Primeiros passos com o gRPC no Kubernetes

Este tutorial mostra como implantar um exemplo simples do serviço gRPC com o Extensible Service Proxy (ESP) em um cluster do Kubernetes que não está em execução no Google Cloud. A versão Python da amostra bookstore-grpc é utilizada neste tutorial. Consulte a seção A seguir para ter acesso a exemplos do gRPC em outras linguagens.

Neste tutorial, são usadas imagens de contêiner predefinidas do código de amostra e do ESP, que são armazenadas 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. Copie e configure arquivos da amostra bookstore-grpc. Consulte Como configurar o Cloud Endpoints.
  3. Implante a configuração do Endpoints para criar um serviço. Consulte Como implantar a configuração do Endpoints.
  4. Criar credenciais para o serviço do Endpoints. Consulte Como criar credenciais para o serviço.
  5. Crie um back-end para exibir a API e implante-a. Consulte Como implantar o back-end da API.
  6. Consiga o endereço IP externo do serviço. Consulte Como conseguir o endereço IP externo do serviço.
  7. Envie uma solicitação para a API. Consulte Como enviar uma solicitação para a API.
  8. Evite cobranças na sua conta do Google Cloud. Consulte Fazer 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

Para acompanhar este tutorial, é preciso ter uma configuração de cluster do Kubernetes ou Minikube. Para saber mais, consulte a Documentação do Kubernetes.

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

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

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

    Acessar a página do seletor de projetos

  3. Verifique se a cobrança está ativada para o seu projeto do Google Cloud. Saiba como confirmar se a cobrança está ativada para o seu projeto.

  4. Anote o ID do projeto do Google Cloud. 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. Verifique se o SDK do Cloud (gcloud) está autorizado a acessar os dados e serviços no Google Cloud:
    gcloud auth login
    Na nova guia aberta, selecione 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 seu projeto do Google Cloud.

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

  9. Instale kubectl:
    gcloud components install kubectl
  10. Consiga novas credenciais de usuário a serem usadas para o Application Default Credentials. As credenciais de usuário são necessárias para autorizar o kubectl.
    gcloud auth application-default login
  11. Na nova guia aberta do navegador, escolha uma conta.
  12. Siga as etapas no 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. 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.

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.

  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.

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 o gerenciamento da API, o ESP precisa dos serviços da Infraestrutura de serviços. Para chamá-los, o ESP precisa usar tokens de acesso. Quando você implanta o ESP em ambientes do Google Cloud, como o GKE ou o Compute Engine, o ESP recebe tokens de acesso por meio do serviço de metadados do Google Cloud.

Quando você implanta o ESP em um ambiente que não é do Google Cloud, como sua área de trabalho 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 ao ESP. O ESP usa a conta de serviço para gerar tokens de acesso e chamar os serviços necessários para gerenciar a API.

Você pode usar o Console do Cloud ou a ferramenta de linha de comando gcloud para criar a conta de serviço e o arquivo de chave privada e atribuir as funções abaixo a essa conta:

Console

  1. No Console do Cloud, abra a página Contas de serviço.

    Acesse a página Contas de serviço

  2. Clique em Selecione um projeto.
  3. Selecione o projeto em que a API foi criada e clique em Abrir.
  4. Clique em + Criar conta de serviço.
  5. No campo Nome da conta de serviço, insira o nome para sua conta de serviço.
  6. Clique em Criar.
  7. Clique em Selecionar um papel e selecione Gerenciamento de serviços > Controlador de serviços.
  8. Clique em + Adicionar outro papel.
  9. Clique em Selecionar um papel e selecione Cloud Trace > Agente do Cloud Trace.
  10. Clique em Continuar.
  11. Clique em + Criar chave.
  12. No painel do lado direito, para o Tipo de chave, use o tipo padrão, JSON.
  13. Clique em Criar.
  14. Na caixa de diálogo, clique em Fechar.
  15. Clique em Concluído.

Esse procedimento cria a conta de serviço e faz o download da chave privada dela como um arquivo JSON.

gcloud

  1. Insira o comando a seguir para exibir os IDs dos seus projetos do Google Cloud:

    gcloud projects list
    
  2. Substitua PROJECT_ID no comando a seguir para definir o projeto que contém sua API como padrão:

    gcloud config set project PROJECT_ID
    
  3. Verifique se o SDK do Cloud (gcloud) está autorizado a acessar dados e serviços no Google Cloud:

    gcloud auth login
    

    Se você tiver mais de uma conta, escolha a conta que está no projeto do Google Cloud em que a API está localizada. Se você executar gcloud auth list, a conta selecionada será mostrada como a ativa para o projeto.

  4. Para criar uma conta de serviço, execute o seguinte comando e substitua SERVICE_ACCOUNT_NAME e My Service Account pelo nome e pelo nome de exibição que você quer usar:

    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
      --display-name "My Service Account"
    

    O comando atribui um endereço de e-mail para a conta de serviço no seguinte formato:

    SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
    

    Esse endereço de e-mail é necessário nos comandos subsequentes.

  5. Crie um arquivo da chave da conta de serviço:

    gcloud iam service-accounts keys create ~/service-account-creds.json \
      --iam-account SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
    
  6. 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
    
  7. 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 sobre os comandos, consulte gcloud iam service-accounts.

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. Caso tenha usado o Console do 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 uma chave secreta 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, realize estas ações:

  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
        

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.

A seguir