Esta página explica como implantar o código de back-end da API e as Extensible Service Proxy (ESP) Google Kubernetes Engine, Compute Engine e a App Engine flexível de nuvem.
As etapas da implantação variam de acordo com a plataforma que hospeda sua API, sempre há uma etapa em que você fornece ao ESP nome do serviço e uma opção que configura o ESP para usar a implantação mais recente Configuração de serviço do Cloud Endpoints. Com essas informações, o ESP recebe a configuração do Endpoints da API, e atua como proxy em solicitações e respostas para que ela seja gerenciada pelo Endpoints.
Pré-requisitos
Como ponto de partida, nesta página presume-se que você:
Como se preparar para a implantação
App Engine
Com a inclusão de uma pequena etapa de configuração, descrita nas etapas seguintes, a implantação da API para que ela seja gerenciada pelo Endpoints é semelhante à implantação de qualquer aplicativo no ambiente flexível do App Engine. Siga a documentação do App Engine para:
- Organizar os arquivos de configuração.
- Criar o arquivo de configuração
app.yaml
. - Caso seu aplicativo seja baseado em microsserviços, consulte a documentação Como implantar vários aplicativos de serviços para mais informações sobre como configurar os arquivos
app.yaml
para cada serviço.
Use o comando gcloud app deploy
para implantar a API no App Engine. Ele cria automaticamente uma imagem de contêiner usando o serviço Container Builder e a implanta no ambiente flexível do App Engine.
Antes de implantar:
- O proprietário do projeto do Google Cloud precisa criar o aplicativo do App Engine.
- É necessário verificar se a conta de usuário inclui os privilégios exigidos.
Compute Engine
Para que o Endpoints possa gerenciar a API, é necessário instalar e configurar o ESP e o código do servidor de back-end para a API. Você precisa instalar o Docker na instância de VM do Compute Engine pode executar a imagem do Docker ESP, disponível gratuitamente no Artifact Registry.
Antes de implantar:
Os tópicos a seguir descrevem em linhas gerais as etapas necessárias antes de implantar a API e o ESP no Compute Engine. De modo geral, são todas as etapas normalmente necessárias para executar o código de servidor de back-end no Compute Engine.
- Crie, configure e inicie sua instância de VM. Consulte a documentação do Compute Engine.
- Instale o Docker Enterprise Edition (EE) ou o Docker Community Edition (CE) na sua instância de VM. Consulte Instalar o Docker.
- Crie um contêiner do Docker para seu código de servidor de back-end. Veja a documentação do Cloud Build.
- Envie o contêiner para o Artifact Registry ou outro registro.
- Confira se é possível:
- conectar-se à instância de VM;
- executar a imagem do Docker para iniciar o servidor de back-end na instância VM. Consulte a Referência de execução do Docker;
- enviar solicitações para a API.
GKE;
Quando você cria um cluster no console do Google Cloud, por padrão, os Os escopos OAuth concedidos à conta de serviço do cluster incluem o escopos exigidos pelo Endpoints:
- Service Control: ativado
- Service Management: somente leitura
Ao criar um cluster com o comando gcloud container clusters create
ou um arquivo de configuração de terceiros, especifique os seguintes escopos:
"https://www.googleapis.com/auth/servicecontrol"
"https://www.googleapis.com/auth/service.management.readonly"
Para mais informações, consulte O que são os escopos de acesso?
Antes de implantar:
Com o acréscimo de uma pequena seção ao seu arquivo de manifesto de implantação, é possível executar a imagem do Docker ESP nos seus clusters de contêineres junto com o aplicativo em contêiner. Veja a seguir as etapas gerais que você precisa seguir antes de implantar a API com o ESP para o GKE. De modo geral, são todas as etapas normalmente necessárias para executar o código de servidor de back-end no GKE.
- Implante o aplicativo em contêiner nos clusters do contêiner. As etapas gerais descritas na documentação do GKE são:
- Empacote o app em uma imagem do Docker.
- Faça upload da imagem para um registro.
- Crie um cluster de contêiner.
- Implante o aplicativo no cluster.
- Publique o app na Internet.
- Confira se é possível:
- iniciar o servidor da API;
- enviar solicitações para a API.
Como implantar a API e o ESP
App Engine
Para implantar a API e o ESP no App Engine:
- Solicite o nome do serviço da API. Este é o nome que você especificou no campo
host
do documento da OpenAPI. - Edite o arquivo
app.yaml
e adicione uma seção chamadaendpoints_api_service
que contém o nome do serviço. É possível usar o arquivoapp.yaml
do tutorial como modelo:Java Python Go PHP Ruby NodeJS Substitua
ENDPOINTS-SERVICE-NAME
pelo nome do serviço da API. Por exemplo:endpoints_api_service: name: example-project-12345.appspot.com rollout_strategy: managed
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.Se o aplicativo for baseado em microsserviços, será preciso incluir a seção
endpoints_api_service
em cada arquivoapp.yaml
. - Salve o arquivo
app.yaml
. - Implante o código de back-end e o ESP no App Engine:
gcloud app deploy
Como você adicionou a seção endpoints_api_service
ao arquivo app.yaml
, o comando gcloud app deploy
implanta e configura o ESP em um contêiner separado no ambiente flexível do App Engine. Todo o tráfego de solicitação é roteado pelo ESP, que atua como proxy em solicitações e respostas de e para o contêiner que executa o código de servidor do back-end.
Veja como configurar o ESP para usar um ID de configuração específico, caso seja necessário:
- Na seção
endpoints_api_service
do arquivoapp.yaml
, adicione o campoconfig_id
e configure-o para um ID de configuração específico. - Remova
rollout_strategy: managed
ou definarollout_strategy
comofixed
. A opçãofixed
configura o ESP para usar a configuração de serviço que você especificou emconfig_id
. - Implante novamente a API e o ESP:
gcloud app deploy
Recomendamos não manter o ESP configurado para usar um ID de configuração específico por muito tempo porque, se você implantar uma configuração de serviço atualizada, terá que reiniciar o ESP para usar a nova configuração.
Para remover o ID de configuração específico, siga estas etapas:
- Remova a opção
config_id
do arquivoapp.yaml
. - Adicione a opção
rollout_strategy: managed
. - Emita o comando
gcloud app deploy
.
Ao usar a opção rollout_strategy: managed
, não inclua config_id: YOUR_SERVICE_CONFIG_ID
no arquivo app.yaml
. Caso contrário, gcloud app deploy
falhará e mostrará o seguinte erro:
config_id is forbidden when rollout_strategy is set to "managed".
Ao implantar sua API no ambiente flexível do App Engine pela primeira vez, provavelmente haverá um atraso durante a configuração da máquina virtual (VM, na sigla em inglês) e de outras infraestruturas. Para mais informações, consulte Como garantir uma implantação bem-sucedida na documentação do App Engine.
Compute Engine
Para implantar a API com o ESP no Compute Engine com o Docker, siga estas etapas:
- Conecte-se à instância da VM. Substitua
INSTANCE_NAME
pelo nome da sua instância de VM.gcloud compute ssh INSTANCE_NAME
- Crie uma rede de contêineres própria denominada
esp_net
:sudo docker network create --driver bridge esp_net
- Execute uma instância da imagem do código do servidor de back-end e conecte-a à rede de contêineres
esp_net
:sudo docker run \ --detach \ --name=YOUR_API_CONTAINER_NAME \ --net=esp_net \ gcr.io/YOUR_PROJECT_ID/YOUR_IMAGE:1.0
- Substitua
YOUR_API_CONTAINER_NAME
pelo nome do contêiner. - Substitua
YOUR_PROJECT_ID
pelo ID do projeto do Google Cloud usado quando você enviou a imagem. - Substitua
YOUR_IMAGE
pelo nome da imagem.
- Substitua
- Solicite o nome do serviço da API. Este é o nome que você especificou no campo
host
do documento da OpenAPI. - Execute uma instância da imagem do Docker ESP:
sudo docker run \ --name=esp \ --detach \ --publish=80:8080 \ --net=esp_net \ gcr.io/endpoints-release/endpoints-runtime:1 \ --service=SERVICE_NAME \ --rollout_strategy=managed \ --backend=YOUR_API_CONTAINER_NAME:8080
- Substitua
SERVICE_NAME
pelo nome do serviço. - Substitua
YOUR_API_CONTAINER_NAME
pelo nome do contêiner da API.
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. - Substitua
Veja como configurar o ESP para usar um ID de configuração específico, caso seja necessário:
- Inclua a opção
--version
e defina-a para um ID de configuração específico. - Remova a opção
--rollout_strategy=managed
ou defina--rollout_strategy
comofixed
. A opçãofixed
configura o ESP para usar a configuração de serviço que você especificou em--version
. - Emita o comando
docker run
novamente.
Caso você especifique as opções --rollout_strategy=managed
e --version
, o ESP será iniciado com a configuração especificada em --version
, mas será executado no modo gerenciado e recebendo a configuração mais recente.
Recomendamos não manter o ESP configurado para usar um ID de configuração específico por muito tempo porque, se você implantar uma configuração de serviço atualizada, terá que reiniciar o ESP para usar a nova configuração.
Para remover o ID de configuração específico, siga estas etapas:
- Nas sinalizações ESP de
docker run
, remova a opção--version
. - Adicione a opção
--rollout_strategy=managed
. - Emita o comando
docker run
para reiniciar o ESP.
Veja as opções de inicialização do ESP para conhecer a lista completa de opções que podem ser especificadas ao iniciar o ESP.
GKE
Para implantar o ESP no GKE:
- Confira o nome do serviço da API. Esse é o nome que você especificou no campo
host
do documento da OpenAPI. - Abra o arquivo de manifesto de implantação, referido como
deployment.yaml
abaixo, e adicione o seguinte comando à seção "containers":containers: - name: esp image: gcr.io/endpoints-release/endpoints-runtime:1 args: [ "--http_port=8081", "--backend=127.0.0.1:8080", "--service=SERVICE_NAME", "--rollout_strategy=managed" ]
Substitua
SERVICE_NAME
pelo nome do serviço da API.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. - Inicie o serviço do Kubernetes usando o comando kubectl create:
kubectl create -f deployment.yaml
Veja como configurar o ESP para usar um ID de configuração específico, caso seja necessário:
- No arquivo de manifesto da implantação, adicione a opção
--version
e defina-a para um ID de configuração específico. - Remova
--rollout_strategy=managed
ou defina--rollout_strategy
comofixed
. A opçãofixed
configura o ESP para usar a configuração de serviço que você especificou em--version
. - Inicie o serviço do Kubernetes:
kubectl create -f deployment.yaml
Caso você especifique as opções --rollout_strategy=managed
e --version
, o ESP será iniciado com a configuração especificada em --version
, mas será executado no modo gerenciado e recebendo a configuração mais recente.
Recomendamos não manter o ESP configurado para usar um ID de configuração específico por muito tempo porque, se você implantar uma configuração de serviço atualizada, terá que reiniciar o ESP para usar a nova configuração.
Para remover o ID de configuração específico, siga estas etapas:
- No Arquivo de manifesto de implantação, remova a opção
--version
. - Adicione a variável
--rollout_strategy=managed
. - Inicie o serviço do Kubernetes:
kubectl create -f deployment.yaml
Veja as opções de inicialização do ESP para conhecer a lista completa de opções que podem ser especificadas ao iniciar o ESP.
Como rastrear a atividade da API
Depois de implantar o ESP e o back-end da API, será possível usar ferramentas como curl
ou Postman para enviar solicitações à API. Caso não receba uma resposta bem-sucedida, consulte Como solucionar problemas em erros de resposta.
Após o envio de algumas solicitações, é possível:
Veja os gráficos de atividade da sua API em Endpoints > Serviços.
Ir para a página Serviços do Endpoints
Pode levar alguns instantes até a solicitação aparecer nos gráficos.Veja os registros de solicitações da API na página Cloud Logging.
A seguir
- Como solucionar problemas na implantação do ambiente flexível do App Engine
- Como solucionar problemas do Endpoints no Compute Engine
- Como solucionar problemas do Endpoints no Google Kubernetes Engine