{% include "_shared/_delete_tutorial_resources.html" with name="Getting started with gRPC on Kubernetes" %}

Primeiros passos com o gRPC no Kubernetes

Neste tutorial, mostraremos como implantar um exemplo simples do serviço gRPC com o Extensible Service Proxy (ESP) em um cluster do Kubernetes que não esteja sendo executado no Google Cloud Platform (GCP). 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 ESP, que são armazenadas no Google 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 GCP 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 dele. Consulte Como implantar a configuração do Endpoints.
  4. Crie credenciais para o serviço do Endpoints. Consulte Como criar credenciais para o serviço.
  5. Crie um back-end para disponibilizar 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 à API. Consulte Como enviar uma solicitação à API.
  8. Evite cobranças na sua conta do GCP. Consulte Fazer limpeza.

Custos

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

Use a calculadora de preços para gerar uma estimativa de custo com base no uso do projeto. Novos usuários do GCP são 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 mais informações, 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. Selecione ou crie um projeto do Google Cloud Platform.

    Acessar a página Gerenciar recursos

  3. Verifique se o faturamento foi ativado no projeto do Google Cloud Platform.

    Saiba como ativar o faturamento

  4. Anote o código do projeto do GCP, porque será necessário mais tarde.
  5. Instale e inicialize 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 seus dados e serviços no GCP:
    gcloud auth login
    Na nova guia aberta, selecione uma conta.
  8. Defina o projeto padrão como o código do projeto:
    gcloud config set project
        YOUR_PROJECT_ID

    Substitua YOUR_PROJECT_ID pelo ID do projeto do GCP.

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

  9. Instale o kubectl:
    gcloud components install kubectl
  10. Consiga novas credenciais de usuário a serem usadas para o Application Default Credentials. As credenciais do 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.

Como 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 aquivo de serviço .proto:
    1. Salve uma cópia de bookstore.proto a partir 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 um arquivo descritor, api_descriptor.pb, usando o compilador de buffers de protocolo, protoc: Execute o seguinte comando no diretório em que 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 acima, --proto_path está definido para o diretório de trabalho atual. No seu ambiente de compilação gRPC, caso use um diretório diferente para arquivos de entrada .proto, mude --proto_path para que o compilador pesquise no diretório em que você 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 seu arquivo api_config.yaml pelo seu código do projeto do GCP. Por exemplo:
      #
      # Name of the service configuration.
      #
      name: bookstore.endpoints.example-project-12345.cloud.goog
      

      O valor do campo apis.name nesse 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 está definido em bookstore.proto dentro do pacote endpoints.examples.bookstore. O nome da API totalmente qualificado será endpoints.examples.bookstore.Bookstore, exatamente 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

O Endpoints e o ESP exigem, no mínimo, os seguintes serviços:
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 habilita esses serviços obrigatórios. No entanto, o comando gcloud é concluído com sucesso, mas não ativa os serviços obrigató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 GCP atual em que esses serviços foram explicitamente desativados.

Para confirmar que os serviços obrigatórios estão habilitados:

gcloud services list

Se você não encontrar os serviços obrigatórios listados, habilite-os:

gcloud services enable SERVICE_NAME

Substitua SERVICE_NAME pelo nome do serviço a ser ativado.

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

  1. Certifique-se de que 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 usado atualmente pela ferramenta de linha de comando gcloud é o projeto do GCP em que você quer 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 os arquivos de proto descriptor e 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 configuração do serviço é concluída, o Service Management envia o código de configuração e o nome do serviço, semelhante ao seguinte:

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

    No exemplo acima, 2017-02-13r0 é o código 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 Solução de problemas na implantação da configuração do Cloud 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 Service Infrastructure. Para chamá-los, o ESP precisa usar tokens de acesso. Quando implantado nas plataformas do GCP, como o GKE ou o Compute Engine, o ESP recebe tokens de acesso por meio do serviço de metadados do GCP.

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

Use o Console do GCP ou a ferramenta de linha de comando gcloud para criar a conta de serviço e o arquivo de chave privada e para atribuir os seguintes papéis à conta:

Console

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

    Acessar 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. Para exibir os códigos dos projetos do GCP, digite:

    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 seus dados e serviços no GCP:

    gcloud auth login
    

    Se você tiver mais de uma conta, escolha a conta presente no projeto do GCP em que está a API. 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 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 Stackdriver Trace:

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

Consulte gcloud iam service-accounts para saber mais sobre os comandos.

Como 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 executado dentro de um contêiner precisa de acesso às 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 (links em inglês).

Para criar a chave secreta do Kubernetes e ativar o volume:

  1. Se você tiver usado o Console do GCP para criar a conta de serviço, renomeie o arquivo JSON para service-account-creds.json. Mova-o para o mesmo diretório onde 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
    

    Se houver êxito, será exibida 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 da chave secreta, conforme mostrado nas duas seções a seguir do arquivo:

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 seu serviço para encontrar a configuração que você implantou 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 da implantação, k8s-grpc-bookstore.yaml, no mesmo diretório que service-account-creds.json.

  2. Abra k8s-grpc-bookstore.yaml e substitua SERVICE_NAME pelo nome do seu 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"
        ]

    Com a opção --rollout_strategy=managed, você configura o ESP para usar a implantação mais recente da configuração de serviço. Quando essa opção é especificada, a alteração é detectada pelo ESP até um minuto após a implantação de uma nova configuração de serviço e começa a ser usada automaticamente. Recomendamos especificar essa opção em vez de um código 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 a kubectl não foi configurada corretamente. Para saber mais, consulte Configurar o kubectl (em inglês).

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 para EXTERNAL-IP e salve-o em uma variável de ambiente SERVER_IP, conforme usado ao enviar solicitações para a 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
    

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.

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

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Cloud Endpoints com gRPC
Precisa de ajuda? Acesse nossa página de suporte.