Primeiros passos com o Endpoints para Kubernetes com ESP

Como configurar o Endpoints

O bookstore-grpc exemplo contém os arquivos que você precisa copiar localmente e configurar.

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

Consulte Como configurar o Endpoints para mais informações.

Implantar a configuração do Endpoints

Para implantar a configuração do Endpoints, use o comando gcloud endpoints services deploy. Esse comando usa a Service Infrastructure, a plataforma de serviços fundamentais do Google. Ela é usada pelo Endpoints e por outros serviços para criar e gerenciar APIs e serviços.

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 o Google Cloud CLI:

   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

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:

• Depois de implantar a configuração do Endpoints, acesse a página Endpoints 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 criar credenciais para o serviço

Para fornecer gerenciamento da API, o ESP e o ESPv2 exigem os serviços do Service Infrastructure. Para chamá-los, o ESP e o ESPv2 precisam usar tokens de acesso. Quando você implanta o ESP ou o ESPv2 nos ambientes do Google Cloud, como o GKE ou o Compute Engine, o ESP e o ESPv2 recebem tokens de acesso por meio do serviço de metadados do Google Cloud.

Ao implantar o ESP ou o ESPv2 em um ambiente que não seja do Google Cloud, como seu computador local, um cluster do Kubernetes local ou outro provedor em nuvem, é preciso fornecer um arquivo JSON da conta de serviço que contenha uma chave privada. O ESP e o ESPv2 usam a conta de serviço para gerar tokens de acesso e chamar os serviços necessários para gerenciar a API.

É possível usar o console ou a Google Cloud CLI Para criar a conta de serviço e o arquivo de chave privada:

Adicione os papéis necessários do IAM:

Nesta seção, descrevemos os recursos do IAM que o ESP e o ESPv2 usam, além dos papéis do IAM necessários para que a conta de serviço anexada acesse esses recursos.

Configuração do serviço de endpoint

O ESP e o ESPv2 chamam o Service Control, que usa a configuração do serviço do endpoint. A configuração do serviço do endpoint é um recurso do IAM, e o ESP e o ESPv2 precisam do papel Controlador de serviço para acessá-lo.

O papel do IAM está na configuração do serviço do endpoint, não no projeto. Os projetos podem ter várias configurações de serviço de endpoint.

Use o comando gcloud a seguir para adicionar o papel à conta de serviço anexada na configuração do serviço do endpoint.

gcloud endpoints services add-iam-policy-binding SERVICE_NAME \
  --member serviceAccount:SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com \
  --role roles/servicemanagement.serviceController

Em que
* SERVICE_NAME é o nome do serviço do endpoint
* SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com é a conta de serviço anexada.

Cloud Trace

O ESP e o ESPv2 chamam o serviço Cloud Trace para exportar o Trace para um projeto. Esse projeto é chamado de projeto de rastreamento. No ESP, o projeto de rastreamento e o projeto que tem a configuração do serviço de endpoint são os mesmos. No ESPv2, o projeto de rastreamento pode ser especificado pela sinalização --tracing_project_id e assume como padrão o projeto de implantação.

O ESP e o ESPv2 exigem o papel Agente do Cloud Trace para ativar o Cloud Trace.

Use o seguinte comando gcloud para adicionar o papel à conta de serviço anexada:

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

Em que
* TRACING_PROJECT_ID é o ID do projeto de rastreamento
. * SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID,iam.gserviceaccount.com é a conta de serviço anexada. Para mais informações, consulte O que são funções e permissões?

Consulte gcloud iam service-accounts para mais informações sobre os comandos.

Implantar o back-end da API

Até aqui, você implantou a configuração do serviço no Service Management, mas não o código que disponibilizará o back-end da API. Nesta seção, veja como implantar contêineres predefinidos da API de amostra e ESP no Kubernetes.

Como fornecer as credenciais de serviço ao ESP

O ESP, que é executado dentro de um contêiner, precisa acessar as credenciais armazenadas localmente no arquivo service-account-creds.json. Para que o ESP tenha acesso às credenciais, crie um secret do Kubernetes e ative-o como um volume do Kubernetes.

Para criar o secret do Kubernetes e ativar o volume:

1. Se você usou o console do Google Cloud para criar a conta de serviço, renomeie o arquivo JSON para service-account-creds.json. Mova-o para o mesmo diretório em que os arquivos api_descriptor.pb e api_config.yaml estão localizados.

2. Crie um secret do Kubernetes com as credenciais da conta de serviço:

    kubectl create secret generic service-account-creds
         --from-file=service-account-creds.json

   Caso consiga, verá a mensagem secret "service-account-creds" created.

O arquivo de manifesto de implantação usado para implantar a API e o ESP no Kubernetes já contém o volume secret, conforme mostrado nas duas seções do arquivo a seguir:

volumes:
  - name: service-account-creds
    secret:
      secretName: service-account-creds

volumeMounts:
  - mountPath: /etc/nginx/creds
    name: service-account-creds
    readOnly: true

Como configurar o nome do serviço e iniciar o serviço

O ESP precisa saber o nome do serviço para encontrar a configuração implantada anteriormente usando o comando gcloud endpoints services deploy.

Para configurar o nome do serviço e iniciá-lo:

1. Salve uma cópia do arquivo de manifesto de implantação, k8s-grpc-bookstore.yaml, para o mesmo diretório service-account-creds.json.

2. Abra k8s-grpc-bookstore.yaml e substitua SERVICE_NAME pelo nome do serviço do Endpoints. Este é o mesmo nome configurado no campo name do arquivo api_config.yaml.

   containers:
     - name: esp
       image: gcr.io/endpoints-release/endpoints-runtime:1
       args: [
         "--http2_port=9000",
         "--service=SERVICE_NAME",
         "--rollout_strategy=managed",
         "--backend=grpc://127.0.0.1:8000",
         "--service_account_key=/etc/nginx/creds/service-account-creds.json"
       ]

   A opção --rollout_strategy=managed configura o ESP para usar a implantação mais recente da configuração do serviço. Quando você especifica essa opção, até 5 minutos depois de implantar uma nova configuração de serviço, o ESP detecta a alteração e começa a usá-la automaticamente. Recomendamos especificar essa opção em vez de um ID de configuração específico para uso do ESP. Para mais detalhes sobre os argumentos do ESP, consulte Opções de inicialização do ESP.

3. Inicie o serviço para implantá-lo no Kubernetes:

   kubectl create -f k8s-grpc-bookstore.yaml

   Se for exibida uma mensagem de erro parecida com esta:

   The connection to the server localhost:8080 was refused - did you specify the right host or port?

   Isso indica que kubectl não está configurado corretamente. Consulte Configurar kubectl para mais informações.

Como buscar 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, conforme usado ao enviar solicitações para a API de exemplo.

   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
   

   • Veja os gráficos de atividade da API na página Endpoints > Serviços.
     

     Ir para a página Serviços do Endpoints

     Pode levar alguns instantes até a solicitação aparecer nos gráficos.

   • Verifique os registros de solicitações da API na página "Explorador de registros".
     

     Acessar a página Análise de registros

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

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