Primeiros passos com o Endpoints para GKE com ESPv2

Neste tutorial, você aprende a implantar um exemplo simples do serviço gRPC com o Extensible Service Proxy V2 (ESPv2) no Google Kubernetes Engine (GKE). A versão Python da amostra bookstore-grpc é utilizada neste tutorial. Consulte as amostras de gRPC em outras linguagens na seção A seguir.

Neste tutorial, são usadas imagens de contêiner predefinidas do código de amostra e do ESPv2, armazenados no Container Registry. Se você não está familiarizado com os contêineres, consulte as páginas a seguir para saber mais:

Para uma visão geral do Cloud Endpoints, consulte Sobre o Endpoints e Arquitetura do Endpoints.

Objetivos

Ao seguir o tutorial, use a lista detalhada de tarefas abaixo. Para enviar solicitações à API, é necessário concluir todas as tarefas.

  1. Configure um projeto do Google Cloud e faça o download do software necessário. Consulte Antes de começar.
  2. Copiar e configurar arquivos da amostra bookstore-grpc. Consulte Como configurar o Endpoints.
  3. Implantar a configuração do Endpoints para criar um serviço dele. Consulte Como implantar a configuração do Endpoints.
  4. Crie um back-end para exibir a API e implante-a. Consulte Como implantar o back-end da API.
  5. Consiga o endereço IP externo do serviço. Consulte Como conseguir o endereço IP externo do serviço.
  6. Envie uma solicitação para a API. Consulte Como enviar uma solicitação para a API.
  7. Evite cobranças na sua conta do Google Cloud. Consulte Limpeza.

Custos

Neste tutorial, usamos os seguintes componentes faturáveis do Google Cloud:

Para gerar uma estimativa de custo baseada na projeção de uso deste tutorial, use a calculadora de preços. Novos usuários do Google Cloud podem ser qualificados para uma avaliação gratuita.

Ao concluir este tutorial, exclua os recursos criados para evitar o faturamento contínuo. Para mais informações, consulte Como fazer a limpeza.

Antes de começar

  1. Faça login na sua conta do Google.

    Se você ainda não tiver uma, inscreva-se.

  2. No Console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

    Acessar a página do seletor de projetos

  3. Verifique se o faturamento está ativado para seu projeto na nuvem. Saiba como confirmar se o faturamento está ativado para o projeto.

  4. Anote o ID do projeto do Google Cloud porque ele será necessário posteriormente.
  5. Instale e inicie o SDK do Cloud.
  6. Atualize o SDK do Cloud e instale os componentes do Endpoints.
    gcloud components update
  7. Certifique-se de que o Cloud SDK (gcloud) esteja autorizado a acessar seus dados e serviços no Google Cloud:
    gcloud auth login
    Uma nova guia do navegador será aberta e você precisará escolher uma conta.
  8. Defina o projeto padrão como o ID do projeto.
    gcloud config set project YOUR_PROJECT_ID

    Substitua YOUR_PROJECT_ID pelo ID do projeto.

    Se você tiver outros projetos do Google Cloud e quiser usar gcloud para gerenciá-los, consulte Como gerenciar configurações do Cloud SDK.

  9. Instale kubectl:
    gcloud components install kubectl
  10. Consiga novas credenciais de usuário a serem usadas como credenciais padrão do aplicativo. As credenciais do usuário são necessárias para autorizar kubectl.
    gcloud auth application-default login
    Na nova guia aberta do navegador, escolha uma conta.
  11. Siga as etapas no Guia de início rápido do gRPC em Python para instalar o gRPC e as ferramentas dele.

Configurar o Endpoints

A amostra bookstore-grpc contém os arquivos necessários para fazer cópias locais e configurações.

  1. Crie um arquivo descritor protobuf autocontido a partir do seu arquivo de serviço .proto:
    1. Salve uma cópia de bookstore.proto do repositório de exemplo. Esse arquivo define a API do serviço Bookstore.
    2. Crie o seguinte diretório: mkdir generated_pb2
    3. Crie o arquivo de descritor, api_descriptor.pb, usando o compilador de buffers de protocolo protoc. Execute o seguinte comando no diretório onde você salvou bookstore.proto:
      python -m grpc_tools.protoc \
          --include_imports \
          --include_source_info \
          --proto_path=. \
          --descriptor_set_out=api_descriptor.pb \
          --python_out=generated_pb2 \
          --grpc_python_out=generated_pb2 \
          bookstore.proto
      

      No comando anterior, --proto_path está definido como o diretório de trabalho atual. No ambiente da versão do gRPC, caso você use um diretório diferente para arquivos de entrada .proto, mude --proto_path para que o compilador pesquise o diretório em que salvou bookstore.proto.

  2. Crie um arquivo YAML de configuração da API gRPC:
    1. Salve uma cópia do arquivo api_config.yaml. Esse arquivo define a configuração da API gRPC do serviço Bookstore.
    2. Substitua MY_PROJECT_ID no arquivo api_config.yaml pelo ID do projeto do Google Cloud. Exemplo:
      #
      # Name of the service configuration.
      #
      name: bookstore.endpoints.example-project-12345.cloud.goog
      

      Observe que o valor do campo apis.name neste arquivo corresponde exatamente ao nome da API totalmente qualificado do arquivo .proto; caso contrário, a implantação não funcionará. O serviço Bookstore é definido em bookstore.proto dentro do pacote endpoints.examples.bookstore. O nome da API totalmente qualificado é endpoints.examples.bookstore.Bookstore, assim como aparece no arquivo api_config.yaml.

      apis:
        - name: endpoints.examples.bookstore.Bookstore
      

Para saber mais, consulte Como configurar o Endpoints.

Como implantar a configuração do Endpoints

Para implantar a configuração do Endpoints, use o comando gcloud endpoints services deploy. Ele utiliza o Service Management para criar um serviço gerenciado.

  1. Verifique se você está no diretório onde os arquivos api_descriptor.pb e api_config.yaml estão localizados.
  2. Confirme se o projeto padrão que a ferramenta de linha de comando gcloud está usando no momento é o projeto do Google Cloud em que você pretende implantar a configuração do Endpoints. Valide o código do projeto retornado do comando a seguir para garantir que o serviço não seja criado no projeto incorreto.
    gcloud config list project
    

    Se você precisar alterar o projeto padrão, execute o comando:

    gcloud config set project YOUR_PROJECT_ID
    
  3. Implante o arquivo proto descriptor e o arquivo de configuração usando a ferramenta de linha de comando gcloud:
    gcloud endpoints services deploy api_descriptor.pb api_config.yaml
    

    Durante a criação e a configuração do serviço, o Service Management envia informações ao terminal. Quando a implantação for concluída, uma mensagem parecida com esta será exibida:

    Service Configuration [CONFIG_ID] uploaded for service [bookstore.endpoints.example-project.cloud.goog]

    CONFIG_ID é o ID exclusivo de configuração de serviço do Endpoints criado pela implantação. Exemplo:

    Service Configuration [2017-02-13r0] uploaded for service [bookstore.endpoints.example-project.cloud.goog]
    

    No exemplo anterior, 2017-02-13r0 é o ID de configuração do serviço e bookstore.endpoints.example-project.cloud.goog é o nome do serviço. O código de configuração do serviço consiste em um carimbo de data e um número de revisão. Se você implantar novamente a configuração do Endpoints no mesmo dia, o número de revisão será alterado no código da configuração do serviço.

Como verificar os serviços obrigatórios

No mínimo, o Endpoints e o ESP exigem a ativação dos seguintes serviços do Google:
Nome Título
servicemanagement.googleapis.com API Service Management
servicecontrol.googleapis.com API Service Control
endpoints.googleapis.com Google Cloud Endpoints

Na maioria dos casos, o comando gcloud endpoints services deploy ativa os serviços necessários. No entanto, o comando gcloud é concluído com êxito, mas não ativa os serviços necessários nas seguintes circunstâncias:

  • Você usou um aplicativo de terceiros, como o Terraform, e não incluiu esses serviços.

  • Você implantou a configuração do Endpoints em um projeto do Google Cloud existente, em que esses serviços foram desativados explicitamente.

Use o seguinte comando para confirmar se os serviços necessários estão ativados:

gcloud services list

Se você não encontrar os serviços necessários listados, ative-os:

gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com
gcloud services enable endpoints.googleapis.com

Ative também seu serviço do Endpoints:

gcloud services enable ENDPOINTS_SERVICE_NAME

Para determinar o ENDPOINTS_SERVICE_NAME, é possível:

  • Após implantar a configuração do Endpoints, acesse a página Pontos de extremidade no Console do Cloud. A lista de ENDPOINTS_SERVICE_NAME possíveis é mostrada na coluna Nome do serviço.

  • Para a OpenAPI, o ENDPOINTS_SERVICE_NAME é o que você especificou no campo host da especificação do OpenAPI. Para gRPC, o ENDPOINTS_SERVICE_NAME é o que você especificou no campo name da configuração do gRPC Endpoints.

Para mais informações sobre os comandos gcloud, consulte serviços gcloud.

Se você receber uma mensagem de erro, consulte Como solucionar problemas de implantação na configuração do Endpoints.

Para mais informações, consulte Como implantar a configuração do Endpoints.

Como implantar o back-end da API

Até agora, você implantou a configuração do serviço no Service Management, mas não o código que exibe o back-end da API. Nesta seção, você aprenderá a criar um cluster do GKE para hospedar o back-end da API e implantá-la.

Como criar um cluster de contêiner

Para criar um cluster de contêiner de exemplo:

  1. No Console do Google Cloud, acesse a página de clusters do Kubernetes.

    Acessar a página de clusters do Kubernetes

  2. Clique em Criar cluster.
  3. Aceite as configurações padrão e clique em Criar. Anote a zona e o nome do cluster. Eles serão necessários mais adiante neste tutorial.

Como autenticar kubectl no cluster de contêiner

Para criar e gerenciar recursos do cluster com kubectl, é preciso ter credenciais do cluster disponíveis para kubectl. Para isso, execute o comando a seguir, substituindo NAME pelo nome do novo cluster e ZONE pela zona do cluster.

gcloud container clusters get-credentials NAME --zone ZONE

Como verificar as permissões necessárias

Siga esta recomendação de permissão para escolher uma conta de serviço de nó adequada como identidade para se comunicar com os serviços do Google. O ESP e o ESPv2 precisam se comunicar com o Google ServiceController e com o Stackdriver. Também são necessários papéis de IAM adicionais para a conta de serviço do nó que executa o ESP e o ESPv2.

Se a conta de serviço do nó não for a do Compute Engine, siga a próxima etapa para adicionar os papéis necessários do IAM:

Adicione os papéis necessários do IAM:

Os papéis do IAM a seguir são necessários para a conta de serviço usada para ESP e ESPv2.

Para adicionar os papéis de IAM do controlador de serviço e do Cloud Trace à conta de serviço:

Console

  1. No Console do Cloud, selecione o projeto em que sua conta de serviço foi criada.
  2. Abrir a página IAM/Iam.

    Acessar a página do IAM/Iam

    . A página deve listar todos os membros do IAM, incluindo todas as contas de serviço.
  3. Selecione sua conta de serviço e clique em Editar PIN à direita.
  4. Você verá um painel permissão para edição.
  5. Clique em Adicionar outro papel.
  6. Clique em Selecionar um papel e selecione Gerenciamento de serviços > Controlador de serviços.
  7. Clique em + Adicionar outro papel.
  8. Clique em Selecionar um papel e selecione Cloud Trace > Agente do Cloud Trace.
  9. Clique em Save.
  10. Agora você verá os papéis Controlador de serviços e Agente do Cloud Trace na coluna papel da conta de serviço na página do IAM.

gcloud

  1. Adicione o papel de Controlador de serviço:

    gcloud projects add-iam-policy-binding PROJECT_ID \
            --member serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
            --role roles/servicemanagement.serviceController
  2. Adicione o papel de Agente do Cloud Trace para ativar o Cloud Trace:

    gcloud projects add-iam-policy-binding PROJECT_ID \
            --member serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
            --role roles/cloudtrace.agent

Para mais informações, consulte O que são funções e permissões?

Identidade da carga de trabalho

Se a Identidade da carga de trabalho for usada, uma conta de serviço separada diferente da conta de serviço do nó poderá ser usada para falar com os serviços do Google. É possível criar uma conta de serviço do Kubernetes para o pod executar o ESP e o ESPv2. Além disso, você pode criar uma conta de serviço do Google e associá-la à do Kubernetes.

Siga estas etapas para associar uma conta de serviço do Kubernetes a uma conta de serviço do Google.

A conta de serviço do Google precisa ter os papéis do IAM exigidos acima. Caso contrário, siga a etapa adicionar papéis obrigatórios do IAM para adicioná-los.

Como implantar a API de amostra e o ESPv2 no cluster

Veja como implantar o exemplo do serviço do gRPC no cluster a ser usado pelos clientes:

  1. git clone este repo e abra para editar o arquivo de manifesto de implantação grpc-bookstore.yaml.
  2. Substitua SERVICE_NAME pelo nome do serviço do Endpoints. Este é o mesmo nome configurado no campo name do arquivo api_config.yaml.
    spec:
      containers:
      - name: esp
        image: gcr.io/endpoints-release/endpoints-runtime:2
        args: [
          "--listener_port=9000",
          "--service=SERVICE_NAME",
          "--rollout_strategy=managed",
          "--backend=grpc://127.0.0.1:8000"
        ]
        ports:
          - containerPort: 9000
      - name: bookstore
        image: gcr.io/endpointsv2/python-grpc-bookstore-server:1
        ports:
          - containerPort: 8000

    A opção --rollout_strategy=managed configura o ESPv2 para usar a implantação mais recente da configuração do serviço. Ao especificar essa opção, a alteração é detectada pelo ESPv2 em até um minuto após a implantação de uma nova configuração do serviço e começa a ser usada automaticamente. Recomendamos especificar essa opção em vez de fornecer um ID de configuração específico para o ESPv2. Para mais detalhes sobre os argumentos do ESPv2, consulte Opções de inicialização do ESPv2.

    Por exemplo:

        spec:
          containers:
          - name: esp
            image: gcr.io/endpoints-release/endpoints-runtime:2
            args: [
              "--listener_port=9000",
              "--service=bookstore.endpoints.example-project-12345.cloud.goog",
              "--rollout_strategy=managed",
              "--backend=grpc://127.0.0.1:8000"
            ]
    
  3. Inicie o serviço:
    kubectl create -f grpc-bookstore.yaml
    

Se você receber uma mensagem de erro, consulte Como solucionar problemas do Endpoints no GKE.

Como conseguir o endereço IP externo do serviço

É necessário o endereço IP externo do serviço para enviar solicitações à API de amostra. Pode demorar alguns minutos depois de iniciar o serviço no contêiner antes que o endereço IP externo esteja pronto.

  1. Veja o endereço IP externo:

    kubectl get service

  2. Anote o valor de EXTERNAL-IP e salve-o em uma variável de ambiente SERVER_IP. O endereço IP externo é usado para enviar solicitações à API de amostra.

    export SERVER_IP=YOUR_EXTERNAL_IP
    

Como enviar uma solicitação à API

Para enviar solicitações à API de amostra, use um cliente gRPC de amostra escrito em Python.

  1. Clone o repositório do Git onde o código do cliente gRPC está hospedado:

    git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git
       

  2. Altere o diretório de trabalho:

    cd python-docs-samples/endpoints/bookstore-grpc/
      

  3. Instale as dependências:

    pip install virtualenv
    virtualenv env
    source env/bin/activate
    python -m pip install -r requirements.txt
    

  4. Envie uma solicitação à API de amostra:

    python bookstore_client.py --host SERVER_IP --port 80
    

Caso não receba uma resposta bem-sucedida, consulte Como solucionar problemas em erros de resposta.

Você acaba de implantar e testar uma API no Endpoints.

Como fazer a limpeza

Para evitar cobranças dos recursos usados neste tutorial na sua conta do Google Cloud Platform:

  1. Exclua a API:

    gcloud endpoints services delete SERVICE_NAME
    

    Substitua SERVICE_NAME pelo nome da API.

  2. Exclua o cluster do GKE:

    gcloud container clusters delete NAME --zone ZONE
    

A seguir

  • Descubra como configurar sua API gRPC do Cloud Endpoints.
  • Consulte a amostra do Bookstore no GitHub para saber mais. Tanto o cliente quanto o servidor estão disponíveis em Python e em Java (links em inglês).
  • A amostra getting-started-grpc está disponível no GitHub nas seguintes linguagens: