Este tutorial mostra como implementar um exemplo simples de serviço gRPC com o Extensible Service Proxy V2 (ESPv2) no Google Kubernetes Engine (GKE). Este tutorial
usa a versão Python do exemplo
bookstore-grpc
. Consulte a secção
O que se segue para ver exemplos de gRPC noutros
idiomas.
O tutorial usa imagens de contentores pré-criadas do código de exemplo e do ESPv2, que estão armazenadas no Artifact Registry. Se não tiver familiaridade com os contentores, consulte o seguinte para mais informações:
Para uma vista geral do Cloud Endpoints, consulte os artigos Acerca dos Endpoints e Arquitetura dos Endpoints.
Objetivos
Use a seguinte lista de tarefas de alto nível à medida que avança no tutorial. Todas as tarefas são necessárias para enviar pedidos com êxito para a API.
- Configure um Google Cloud projeto e transfira o software necessário. Consulte a secção Antes de começar.
- Copie e configure ficheiros do exemplo
bookstore-grpc
. Consulte o artigo Configurar pontos finais. - Implemente a configuração do Endpoints para criar um serviço do Endpoints. Consulte o artigo Implementar a configuração dos Endpoints.
- Crie um back-end para publicar a API e implemente a API. Consulte o artigo Implementar o back-end da API.
- Obtenha o endereço IP externo do serviço. Consulte o artigo Determinar o endereço IP externo do serviço.
- Envie um pedido para a API. Consulte o artigo Enviar um pedido para a API.
- Evite incorrer em cobranças na sua conta Google Cloud . Consulte Limpar.
Custos
Neste documento, usa os seguintes componentes faturáveis do Google Cloud:
Para gerar uma estimativa de custos com base na sua utilização projetada,
use a calculadora de preços.
Quando terminar as tarefas descritas neste documento, pode evitar a faturação contínua eliminando os recursos que criou. Para mais informações, consulte o artigo Limpe.
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.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator
(
roles/resourcemanager.projectCreator
), which contains theresourcemanager.projects.create
permission. Learn how to grant roles.
-
Verify 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.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator
(
roles/resourcemanager.projectCreator
), which contains theresourcemanager.projects.create
permission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
- Tome nota do Google Cloud ID do projeto, uma vez que é necessário mais tarde.
- Instale e inicialize a CLI Google Cloud.
- Atualize a CLI gcloud e instale os componentes do Endpoints.
gcloud components update
- Certifique-se de que a CLI do Google Cloud (
gcloud
) está autorizada a aceder aos seus dados e serviços em Google Cloud: É aberto um novo separador do navegador e é-lhe pedido que escolha uma conta.gcloud auth login
- Defina o projeto predefinido para o ID do seu projeto.
gcloud config set project YOUR_PROJECT_ID
Substitua YOUR_PROJECT_ID pelo ID do seu projeto.
Se tiver outros Google Cloud projetos e quiser usar
gcloud
para os gerir, consulte Gerir configurações da CLI gcloud. - Instale
kubectl
:gcloud components install kubectl
- Adquirir novas credenciais de utilizador para usar como credenciais predefinidas da aplicação. As credenciais do utilizador são necessárias para autorizar
kubectl
. No novo separador do navegador apresentado, escolha uma conta.gcloud auth application-default login
- Siga os passos no guia de início rápido do gRPC Python para instalar o gRPC e as ferramentas gRPC.
Configurar pontos finais
O exemplo bookstore-grpc
contém os ficheiros que tem de copiar localmente e configurar.
- Crie um ficheiro de descritor protobuf autónomo a partir do ficheiro
.proto
do seu serviço:- Guarde uma cópia de
bookstore.proto
do repositório de exemplo. Este ficheiro define a API do serviço Bookstore. - Crie o seguinte diretório:
mkdir generated_pb2
- Crie o ficheiro de descritor,
api_descriptor.pb
, usando o compilador de buffers de protocoloprotoc
. Execute o seguinte comando no diretório onde guardoubookstore.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 seu ambiente de compilação gRPC, se usar um diretório diferente para os ficheiros de entrada, altere--proto_path
para que o compilador pesquise o diretório onde guardoubookstore.proto
..proto
- Guarde uma cópia de
- Crie um ficheiro YAML de configuração da API gRPC:
- Guarde uma cópia do
api_config.yaml
ficheiro. Este ficheiro define a configuração da API gRPC para o serviço Bookstore. - Substitua MY_PROJECT_ID no ficheiro
api_config.yaml
pelo ID do projeto. Google Cloud Por exemplo:# # Name of the service configuration. # name: bookstore.endpoints.example-project-12345.cloud.goog
Tenha em atenção que o valor do campo
apis.name
neste ficheiro corresponde exatamente ao nome da API totalmente qualificado do ficheiro.proto
. Caso contrário, a implementação não funciona. O serviço Bookstore está definido embookstore.proto
no pacoteendpoints.examples.bookstore
. O nome da API totalmente qualificado éendpoints.examples.bookstore.Bookstore
, tal como aparece no ficheiroapi_config.yaml
.apis: - name: endpoints.examples.bookstore.Bookstore
- Guarde uma cópia do
Consulte o artigo Configurar pontos finais para mais informações.
Implementar a configuração dos pontos finais
Para implementar a configuração do Endpoints, use o comando
gcloud endpoints services deploy
. Este comando usa a
gestão de serviços
para criar um serviço gerido.
- Certifique-se de que está no diretório onde se encontram os ficheiros
api_descriptor.pb
eapi_config.yaml
. - Confirme que o projeto predefinido que a ferramenta de linha de comandos
gcloud
está a usar atualmente é o projeto Google Cloud no qual quer implementar a configuração do Endpoints. Valide o ID do projeto devolvido pelo seguinte comando para se certificar de que o serviço não é criado no projeto errado.gcloud config list project
Se precisar de alterar o projeto predefinido, execute o seguinte comando:
gcloud config set project YOUR_PROJECT_ID
- Implemente o ficheiro
proto descriptor
e o ficheiro de configuração através da CLI do Google Cloud:gcloud endpoints services deploy api_descriptor.pb api_config.yaml
À medida que cria e configura o serviço, o Service Management envia informações para o terminal. Quando a implementação estiver concluída, é apresentada uma mensagem semelhante à seguinte:
Service Configuration [CONFIG_ID] uploaded for service [bookstore.endpoints.example-project.cloud.goog]
CONFIG_ID é o ID exclusivo da configuração do serviço Endpoints criado pela implementação. Por 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 ID de configuração do serviço consiste numa indicação de data/hora seguida de um número de revisão. Se implementar novamente a configuração dos Endpoints no mesmo dia, o número de revisão é incrementado no ID de configuração do serviço.
A verificar os serviços necessários
No mínimo, os pontos finais e o ESP requerem a ativação dos seguintes serviços Google:Nome | Título |
---|---|
servicemanagement.googleapis.com |
Service Management API |
servicecontrol.googleapis.com |
Service Control API |
Na maioria dos casos, o comando gcloud endpoints services deploy
ativa estes serviços obrigatórios. No entanto, o comando gcloud
é concluído com êxito, mas não ativa os serviços necessários nas seguintes circunstâncias:
Se usou uma aplicação de terceiros, como o Terraform, e não incluiu estes serviços.
Implementou a configuração do Endpoints numGoogle Cloud projeto existente no qual estes serviços foram explicitamente desativados.
Use o seguinte comando para confirmar que os serviços necessários estão ativados:
gcloud services list
Se não vir os serviços necessários listados, ative-os:
gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com
Ative também o serviço Endpoints:
gcloud services enable ENDPOINTS_SERVICE_NAME
Para determinar o ENDPOINTS_SERVICE_NAME, pode:
Após implementar a configuração do Endpoints, aceda à página Endpoints na Cloud Console. A lista de ENDPOINTS_SERVICE_NAME possíveis é apresentada na coluna Nome do serviço.
Para a OpenAPI, o ENDPOINTS_SERVICE_NAME é o que especificou no campo
host
da sua especificação OpenAPI. Para o gRPC, o ENDPOINTS_SERVICE_NAME é o que especificou no camponame
da sua configuração de pontos finais gRPC.
Para mais informações sobre os comandos gcloud
, consulte os
serviços gcloud
.
Se receber uma mensagem de erro, consulte o artigo Resolução de problemas da implementação da configuração de pontos finais.
Consulte o artigo Implementar a configuração dos Endpoints para ver informações adicionais.
Implementar o back-end da API
Até agora, implementou a configuração do serviço na gestão de serviços, mas ainda não implementou o código que publica o back-end da API. Esta secção explica como criar um cluster do GKE para alojar o back-end da API e implementar a API.
Criar um cluster de contentores
O cluster precisa de um alias de IP para usar o balanceamento de carga nativa do contentor. Para criar um cluster de contentores com um alias de IP para o 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 aprovisionada automaticamente na zona us-central1-a
.
A autenticar kubectl
no cluster de contentores
Para usar kubectl
para criar e gerir recursos de cluster, tem de obter
credenciais de cluster e disponibilizá-las ao kubectl
. Para tal, execute o seguinte comando, substituindo NAME pelo nome do novo cluster e ZONE pela respetiva zona do cluster.
gcloud container clusters get-credentials NAME --zone ZONE
A verificar as autorizações necessárias
O ESP e o ESPv2 chamam os serviços Google que usam o IAM para verificar se a identidade de chamada tem autorizações suficientes para aceder aos recursos do IAM usados. A identidade de chamada é a conta de serviço anexada que implementa o ESP e o ESPv2.
Quando implementada no pod do GKE, a conta de serviço anexada é a conta de serviço do nó. Normalmente, é a conta de serviço predefinida do Compute Engine. Siga esta recomendação de autorização para escolher uma conta de serviço de nó adequada.
Se for usada a identidade de carga de trabalho, pode ser usada uma conta de serviço separada da conta de serviço do nó para comunicar com os serviços Google. Pode criar uma conta de serviço do Kubernetes para o pod executar o ESP e o ESPv2, criar uma conta de serviço Google e associar a conta de serviço do Kubernetes à conta de serviço Google.
Siga estes passos para associar uma conta de serviço do Kubernetes a uma conta de serviço Google. Esta conta de serviço Google é a conta de serviço anexada.
Se a conta de serviço anexada for a conta de serviço predefinida do Compute Engine do projeto e a configuração do serviço de ponto final for implementada no mesmo projeto, a conta de serviço deve ter autorizações suficientes para aceder aos recursos de IAM. Por isso, pode ignorar o passo de configuração das funções de IAM. Caso contrário, devem ser adicionadas as seguintes funções do IAM à conta de serviço anexada.
Adicione as funções IAM necessárias:
Esta secção descreve os recursos do IAM usados pelo ESP e pelo ESPv2, bem como as funções do IAM necessárias para que a conta de serviço anexada aceda a estes recursos.
Configuração do serviço de ponto final
O ESP e o ESPv2 chamam o Service Control, que usa a configuração do serviço de endpoint. A configuração do serviço de ponto final é um recurso do IAM, e o ESP e o ESPv2 precisam da função Service Controller para aceder a ele.
A função IAM está na configuração do serviço de ponto final e não no projeto. Um projeto pode ter várias configurações de serviços de pontos finais.
Use o seguinte comando gcloud para adicionar a função à conta de serviço anexada para a configuração do serviço de ponto final.
gcloud endpoints services add-iam-policy-binding SERVICE_NAME \ --member serviceAccount:SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com \ --role roles/servicemanagement.serviceController
Onde
* SERVICE_NAME
é o nome do serviço de ponto final
* 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 rastreio para um projeto. Este projeto é denominado projeto de rastreio. No ESP, o projeto de rastreio e o projeto que detém a configuração do serviço de ponto final são os mesmos. No ESPv2, o projeto de rastreio pode ser especificado através da flag --tracing_project_id
e é predefinido como o projeto de implementação.
O ESP e o ESPv2 requerem a função Agente do Cloud Trace para ativar o Cloud Trace.
Use o seguinte comando gcloud para adicionar a função à 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
Onde
* TRACING_PROJECT_ID é o ID do projeto de rastreio
* SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com
é a conta de serviço anexada.
Para mais informações, consulte o artigo
O que são funções e autorizações?
Configurar as chaves e os certificados SSL
O equilíbrio de carga nativo do contentor usa o HTTP2 LB, que tem de ser encriptado com TLS. Isto exigiu a implementação de um certificado TLS no GKE Ingress e no ESPv2. Pode usar o seu próprio certificado ou um certificado autoassinado.
Crie um certificado e uma chave autoassinados através do openssl. Certifique-se de que introduziu o mesmo FQDN
bookstore.endpoints.MY_PROJECT_ID.cloud.goog
quando lhe foi pedido o "Nome comum(CN)". Este nome é usado pelos clientes para validar 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 a sua chave e certificado SSL. Tenha em atenção que o certificado é copiado para dois locais,
server.crt
etls.crt
, uma vez que o segredo é fornecido ao GKE Ingress e ao ESPv2. O GKE ingress procura o caminho do 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
Implementar a API de exemplo e o ESPv2 no cluster
Para implementar o serviço gRPC de exemplo no cluster para que os clientes o possam usar:
git clone
este repositório e abra-o para editar o ficheiro de manifesto de implementação grpc-bookstore.yaml.- Substitua SERVICE_NAME pelo nome do seu serviço de
endpoints para entrada e contentor ESPv2.
Este é o mesmo nome que configurou no campo
name
do ficheiroapi_config.yaml
.A opção
--rollout_strategy=managed
configura o ESPv2 para usar a configuração do serviço implementada mais recente. Quando especifica esta opção, no prazo de um minuto após implementar uma nova configuração de serviço, o ESPv2 deteta a alteração e começa a usá-la automaticamente. Recomendamos que especifique esta opção em vez de fornecer um ID de configuração específico para o ESPv2 usar. Para mais detalhes sobre os argumentos do ESPv2, consulte as opções de arranque do ESPv2.Por 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" ]
Implementar configurações de serviços nos Endpoints
Se executar uma grande frota de Endpoints (mais de 100) no mesmo projeto do Google Cloud, recomendamos que monte a configuração do serviço para o contentor em vez de usar a flag
--rollout_strategy=managed
para extrair a configuração do serviço da API Service Management.A API Service Management tem uma quota predefinida. Se uma grande frota de proxies ESPv2 usar
Siga os passos abaixo para montar a configuração do serviço:--rollout_strategy=managed
, todos vão sondar a configuração de serviço mais recente. A frota pode exceder a quota e, assim, causar falhas na atualização da configuração do serviço.- Transfira a configuração JSON do serviço.
- Crie um recurso de mapa de configuração do Kubernetes a partir da configuração JSON.
- Monte o recurso do mapa de configuração no contentor e use a flag
--service_config_path
para especificar o caminho do ficheiro de configuração.
curl -o "/tmp/service_config.json" -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://servicemanagement.googleapis.com/v1/services/SERVICE/configs/CONFIG_ID?view=FULL"
kubectl create configmap service-config-configmap \ --from-file=service_config.json:/tmp/service_config.json
Por exemplo:
containers: - args: - --listener_port=8081 - --backend=http://127.0.0.1:8080 - --service_json_path=/etc/espv2_config/service_config.json - --healthz=/healthz image: gcr.io/endpoints-release/endpoints-runtime:2 name: esp ports: - containerPort: 8081 protocol: TCP volumeMounts: - mountPath: /etc/espv2_config name: service-config-volume volumes: - configMap: defaultMode: 420 name: service-config-configmap name: service-config-volume
- Inicie o serviço:
kubectl create -f grpc-bookstore.yaml
Se receber uma mensagem de erro, consulte o artigo Resolução de problemas de pontos finais no GKE.
Obter o endereço IP externo do serviço
Precisa do endereço IP externo do serviço para enviar pedidos para a API de exemplo. Depois de iniciar o serviço no contentor, pode demorar alguns minutos até que o endereço IP externo esteja pronto.
Ver o endereço IP externo:
kubectl get ingress
Tome nota do valor de
EXTERNAL-IP
e guarde-o numa variável de ambiente SERVER_IP. O endereço IP externo é usado para enviar pedidos para a API de exemplo.export SERVER_IP=YOUR_EXTERNAL_IP
Enviar um pedido para a API
Para enviar pedidos para a API de exemplo, pode usar um cliente gRPC de exemplo escrito em Python.
Clone o repositório Git onde o código do cliente gRPC está alojado:
git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git
Altere o diretório de trabalho:
cd python-docs-samples/endpoints/bookstore-grpc/
Instalar dependências:
pip install virtualenv
virtualenv env
source env/bin/activate
python -m pip install -r requirements.txt
Crie uma CA de raiz para o certificado autoassinado
openssl x509 -in server.crt -out client.pem -outform PEM
Envie um pedido para a API de exemplo:
python bookstore_client.py --host SERVER_IP --port 443 \ --servername bookstore.endpoints.MY_PROJECT_ID.cloud.goog --use_tls true --ca_path=client.pem
Consulte os gráficos de atividade da sua API na página Endpoints > Serviços.
Aceda à página Serviços de pontos finais
Pode demorar alguns momentos até que o pedido se reflita nos gráficos.
Consulte os registos de pedidos da sua API na página do Explorador de registos.
Se não receber uma resposta bem-sucedida, consulte o artigo Resolução de problemas de erros de resposta.
Acabou de implementar e testar uma API no Endpoints!
Limpar
Para evitar incorrer em custos na sua conta do Google Cloud pelos recursos usados neste tutorial, elimine o projeto que contém os recursos ou mantenha o projeto e elimine os recursos individuais.
Elimine a API:
gcloud endpoints services delete SERVICE_NAME
Substitua SERVICE_NAME pelo nome da sua API.
Elimine o cluster do GKE:
gcloud container clusters delete NAME --zone ZONE