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). Este tutorial
usa a versão Python da amostra
bookstore-grpc
. Consulte as amostras de gRPC em outras linguagens na seção A seguir.
O tutorial usa imagens de contêiner predefinidas do código de amostra e do ESPv2, 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 Endpoints. - Implante a configuração do Endpoints para criar um serviço dele. Consulte Como implantar a configuração do Endpoints.
- Crie um back-end para exibir 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 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
- 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 porque ele será necessário posteriormente.
- Instale e inicialize a Google Cloud CLI.
- 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: Uma nova guia do navegador será aberta e você precisará escolher 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 pela ID do seu projeto.
Se você tiver outros projetos do Google Cloud e quiser usar
gcloud
para gerenciá-los, consulte Como gerenciar configurações da CLI gcloud. - Instale
kubectl
:gcloud components install kubectl
- 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
. Na nova guia aberta do navegador, escolha uma conta.gcloud auth application-default login
- Siga as etapas no Guia de início rápido do gRPC para Python (em inglês) 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.
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.
- 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 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.
Criar um cluster de contêiner
O cluster precisa de um alias de IP para usar o balanceamento de carga nativo de contêiner. Para criar um cluster de contêiner com um alias de IP para nosso exemplo:
gcloud container clusters create espv2-demo-cluster \ --enable-ip-alias \ --create-subnetwork="" \ --network=default \ --zone=us-central1-a
O comando acima cria um cluster, espv2-demo-cluster
, com uma
sub-rede provisionada automaticamente na zona us-central1-a
.
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
O ESP e o ESPv2 chamam os serviços do Google que usam o IAM para verificar se a identidade da chamada tem permissões suficientes para acessar os recursos do IAM usados. A identidade de chamada é a conta de serviço anexada que implanta o ESP e o ESPv2.
Quando implantada no pod do GKE, a conta de serviço anexada é a conta de serviço do nó. Ela costuma ser a conta de serviço padrão do Compute Engine. Siga esta recomendação de permissão para escolher uma conta de serviço de nó adequada.
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. Esta conta de serviço do Google é a conta de serviço anexada.
Se a conta de serviço anexada for a conta de serviço padrão do Compute Engine do projeto e a configuração do serviço do endpoint for implantada no mesmo projeto, a conta de serviço já deve ter permissões suficientes para acessar os recursos do IAM, então a etapa a seguir pode ser pulada. Caso contrário, adicione os papéis do IAM à conta de serviço anexada.
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?
Como configurar chaves e certificados SSL
O balanceamento de carga nativo do contêiner usa o HTTP2 LB, que precisa ser criptografado por TLS. Isso exigiu a implantação de um certificado TLS na entrada do GKE e no ESPv2. É possível trazer seu próprio certificado ou usar um certificado autoassinado.
Crie um certificado e uma chave autoassinados usando openssl. Verifique se você inseriu o mesmo FQDN
bookstore.endpoints.MY_PROJECT_ID.cloud.goog
quando solicitado por "Nome comum(CN)". Esse nome é usado pelos clientes para verificar o certificado do servidor.openssl req -x509 -nodes -days 365 -newkey rsa:2048 \ -keyout ./server.key -out ./server.crt
Crie um segredo do Kubernetes com o certificado e a chave SSL. O certificado é copiado para dois lugares,
server.crt
etls.crt
, já que o segredo é fornecido para a entrada do GKE e o ESPv2. A entrada do GKE procura o caminho de certificadotls.crt
e o ESPv2 procura o caminho do certificadoserver.crt
.kubectl create secret generic esp-ssl \ --from-file=server.crt=./server.crt --from-file=server.key=./server.key \ --from-file=tls.crt=./server.crt --from-file=tls.key=./server.key
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:
git clone
este repo e abra para editar o arquivo de manifesto de implantação grpc-bookstore.yaml.- Substitua SERVICE_NAME pelo nome do serviço
do Endpoints para o contêiner Ingress e o ESPv2.
Este é o mesmo nome configurado no campo
name
do arquivoapi_config.yaml
.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.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" ]
- Inicie o serviço:
kubectl create -f grpc-bookstore.yaml
Se você receber uma mensagem de erro, consulte Como solucionar problemas de 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.
Veja o endereço IP externo:
kubectl get ingress
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.
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
Criar uma CA raiz para o certificado autoassinado
openssl x509 -in server.crt -out client.pem -outform PEM
Envie uma solicitação à API de amostra:
python bookstore_client.py --host SERVER_IP --port 443 \ --servername bookstore.endpoints.MY_PROJECT_ID.cloud.goog --use_tls true --ca_path=client.pem
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 a API do 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 nos seguintes idiomas: