Neste tutorial, mostramos 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. O tutorial usa a versão Python da amostra
bookstore-grpc
. 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 Artifact 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. Em todas elas, é necessário que as solicitações para a API sejam enviadas com sucesso.
- Configure um projeto do Google Cloud e faça o download do software necessário. Consulte Antes de começar.
- Copie e configure arquivos da amostra
bookstore-grpc
. Consulte Como configurar o Cloud Endpoints. - Implante a configuração do Endpoints para criar um serviço dele. Consulte Como implantar a configuração do Endpoints.
- Crie credenciais para o serviço do Endpoints. Consulte Como criar credenciais para o serviço.
- Crie um back-end para disponibilizar a API e implante-a. Consulte Como implantar o back-end da API.
- Consiga o endereço IP externo do serviço. Consulte Como conseguir o endereço IP externo do serviço.
- Envie uma solicitação para a API. Consulte Como enviar uma solicitação para a API.
- Evite cobranças na sua conta do Google Cloud. Consulte Fazer limpeza.
Custos
Neste documento, você usará 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.
Ao concluir as tarefas descritas neste documento, é possível evitar o faturamento contínuo excluindo os recursos criados. Saiba mais em 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.
- Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
- Anote o ID do projeto do Google Cloud. Ele será necessário posteriormente.
- Instale e inicialize a CLI gcloud.
- Atualize a CLI gcloud e instale os componentes do Endpoints.
gcloud components update
- Verifique se a Google Cloud CLI (
gcloud
) está autorizada a acessar seus dados e serviços no Google Cloud: Na nova guia aberta, selecione uma conta.gcloud auth login
- 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 Como CLI gcloud do gcloud. - Instale
kubectl
:gcloud components install kubectl
- 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
- Na nova guia aberta do navegador, escolha uma conta.
- 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.
- Crie um arquivo descritor protobuf autocontido a partir do seu arquivo de serviço
.proto
:- Salve uma cópia de
bookstore.proto
do repositório de exemplo. Esse arquivo define a API do serviço Bookstore. - Crie o seguinte diretório:
mkdir generated_pb2
- Crie o arquivo de descritor,
api_descriptor.pb
, usando o compilador de buffers de protocoloprotoc
. Execute o seguinte comando no diretório onde você salvoubookstore.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 salvoubookstore.proto
.
- Salve uma cópia de
- Crie um arquivo YAML de configuração da API gRPC:
- Salve uma cópia do arquivo
api_config.yaml
. Esse arquivo define a configuração da API gRPC do serviço Bookstore. - 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 embookstore.proto
dentro do pacoteendpoints.examples.bookstore
. O nome da API totalmente qualificado éendpoints.examples.bookstore.Bookstore
, assim como aparece no arquivoapi_config.yaml
.apis: - name: endpoints.examples.bookstore.Bookstore
- Salve uma cópia do arquivo
Para saber mais, consulte Como configurar o Endpoints.
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.
- Verifique se você está no diretório onde os arquivos
api_descriptor.pb
eapi_config.yaml
estão localizados. - 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
- 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 ebookstore.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 |
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
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 de 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 camponame
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.
Use o console do Google Cloud ou a Google Cloud CLI para criar a conta de serviço e o arquivo de chave privada:
Console
- No console do Google Cloud, abra a página Contas de serviço .
- Clique em Selecione um projeto.
- Selecione o projeto em que a API foi criada e clique em Abrir.
- Clique em + Criar conta de serviço.
- No campo Nome da conta de serviço, insira o nome para sua conta de serviço.
- Clique em Criar
- Clique em Continuar.
- Clique em Concluído.
- Clique no endereço de e-mail da conta de serviço recém-criada.
- Clique em Chaves.
- Clique em Adicionar chave e em Criar nova chave.
Clique em Criar. O download de um arquivo de chave JSON é feito no seu computador.
Armazene o arquivo de chave com segurança, porque ele pode ser usado para autenticar como sua conta de serviço. Mova e renomeie esse arquivo como quiser.
Clique em Fechar.
gcloud
Insira o comando a seguir para exibir os IDs dos seus projetos do Google Cloud:
gcloud projects list
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
Verifique se a Google Cloud CLI (
gcloud
) está autorizada a acessar dados e serviços no Google Cloud:gcloud auth login
Se você tiver mais de uma conta, escolha a que está no projeto do Google Cloud e que contém a API. Se você executar
gcloud auth list
, a conta selecionada será mostrada como a ativa para o projeto.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.
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
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:
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 arquivosapi_descriptor.pb
eapi_config.yaml
estão localizados.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:
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:
Salve uma cópia do arquivo de manifesto de implantação,
k8s-grpc-bookstore.yaml
, para o mesmo diretórioservice-account-creds.json
.Abra
k8s-grpc-bookstore.yaml
e substitua SERVICE_NAME pelo nome do serviço do Endpoints. Este é o mesmo nome configurado no camponame
do arquivoapi_config.yaml
.A opção
--rollout_strategy=managed
configura o ESP para usar a configuração mais recente do serviço implantado. 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.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 Configurarkubectl
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.
Veja o endereço IP externo:
kubectl get service
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.
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
Altere o diretório de trabalho:
cd python-docs-samples/endpoints/bookstore-grpc/
Instale as dependências:
pip install virtualenv
virtualenv env
source env/bin/activate
python -m pip install -r requirements.txt
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".
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.
Limpar
Para evitar cobranças na sua conta do Google Cloud pelos recursos usados no tutorial, exclua o projeto que os contém ou mantenha o projeto e exclua os recursos individuais.
Exclua a API:
gcloud endpoints services delete SERVICE_NAME
Substitua SERVICE_NAME pelo nome da API.
Exclua o cluster do GKE:
gcloud container clusters delete NAME --zone ZONE
A seguir
- Descubra como configurar sua API gRPC do Cloud Endpoints.
- Configure o DNS:
- Consulte a amostra do Bookstore no GitHub para saber mais. Tanto o cliente quanto o servidor estão disponíveis em Python e Java (links em inglês).
- A amostra
getting-started-grpc
está disponível no GitHub nas seguintes linguagens: