Implantar o back-end da API

OpenAPI | gRPC

Nesta página, você aprende a implantar o código de back-end da sua API e o Extensible Service Proxy (ESP) no Google Kubernetes Engine, no Compute Engine e no ambiente flexível do App Engine.

As etapas de implantação variam de acordo com a plataforma que hospeda sua API, mas sempre há uma etapa em que você fornece ao ESP o nome do serviço e uma opção que configura o ESP para usar a configuração de serviço do Cloud Endpoints implantada mais recentemente. 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.

Observação: o ESP e o ESPV2 têm suporte a ambientes diferentes. O ESP é compatível apenas com o ambiente flexível do App Engine e não está disponível no ambiente padrão do App Engine. Já o ESPv2 pode ser implantado no GKE e no Kubernetes, mas não é compatível com o App Engine.

Pré-requisitos

Como ponto de partida, nesta página presume-se que você:

• Criou um Google Cloud projeto.
• configurou o Endpoints;
• implantado a configuração do Endpoints.

Como se preparar para a implantação

Ambiente flexível do 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 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 sua instância de VM do Compute Engine para 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.

1. Crie, configure e inicie sua instância de VM. Consulte a documentação do Compute Engine.
2. Instale o Docker Enterprise Edition (EE) ou o Docker Community Edition (CE) na sua instância de VM. Consulte Instalar o Docker.
3. Crie um contêiner do Docker para seu código de servidor de back-end. Veja a documentação do Cloud Build.
4. Envie o contêiner para o Artifact Registry ou outro registro.
5. 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

Ao criar um cluster no console Google Cloud , por padrão, os escopos OAuth concedidos à conta de serviço do cluster incluem os 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.

1. Implante o aplicativo em contêiner nos clusters do contêiner. As etapas gerais descritas na documentação do GKE são:
   1. Empacote o app em uma imagem do Docker.
   2. Faça upload da imagem para um registro.
   3. Crie um cluster de contêiner.
   4. Implante o aplicativo no cluster.
   5. Publique o app na Internet.
2. Confira se é possível:
   • iniciar o servidor da API;
   • enviar solicitações para a API.

Como implantar a API e o ESP

Ambiente flexível do App Engine

Para implantar a API e o ESP no App Engine:

1. Solicite o nome do serviço da API. Este é o nome que você especificou no campo host do documento da OpenAPI.
2. Edite o arquivo app.yaml e adicione uma seção chamada endpoints_api_service que contém o nome do serviço. É possível usar o arquivo app.yaml do tutorial como modelo:
   Java

   endpoints_api_service:
     # The following values are to be replaced by information from the output of
     # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
     name: ENDPOINTS-SERVICE-NAME
     rollout_strategy: managed

   Python

   endpoints_api_service:
     # The following values are to be replaced by information from the output of
     # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
     name: ENDPOINTS-SERVICE-NAME
     rollout_strategy: managed

   Go

   endpoints_api_service:
     # The following values are to be replaced by information from the output of
     # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
     name: ENDPOINTS-SERVICE-NAME
     rollout_strategy: managed

   PHP

   endpoints_api_service:
     # The following values are to be replaced by information from the output of
     # 'gcloud endpoints services deploy openapi-appengine.yaml' command. If you have
     # previously run the deploy command, you can list your existing configuration
     # ids using the 'configs list' command as follows:
     #
     #     gcloud endpoints configs list --service=YOUR-PROJECT-ID.appspot.com
     #
     name: ENDPOINTS-SERVICE-NAME
     rollout_strategy: managed

   Ruby

   endpoints_api_service:
     # The following values are to be replaced by information from the output of
     # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
     name: ENDPOINTS-SERVICE-NAME
     rollout_strategy: managed

   NodeJS

   endpoints_api_service:
     # The following values are to be replaced by information from the output of
     # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
     name: ENDPOINTS-SERVICE-NAME
     rollout_strategy: managed

   Substitua ENDPOINTS-SERVICE-NAME pelo nome do serviço da API.

   Adicione as variáveis de ambiente e de tempo de execução ao arquivo de configuração app.yaml.

   Exemplo:

   runtime: nodejs
   env: flex
   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 arquivo app.yaml.

3. Salve o arquivo app.yaml.
4. 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:

1. Na seção endpoints_api_service do arquivo app.yaml, adicione o campo config_id e configure-o para um ID de configuração específico.
2. Remova rollout_strategy: managed ou defina rollout_strategy como fixed. A opção fixed configura o ESP para usar a configuração de serviço que você especificou em config_id.
3. 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:

1. Remova a opção config_id do arquivo app.yaml.
2. Adicione a opção rollout_strategy: managed.
3. 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:

1. Conecte-se à instância da VM. Substitua INSTANCE_NAME pelo nome da sua instância de VM.

   gcloud compute ssh INSTANCE_NAME

2. Crie uma rede de contêineres própria denominada esp_net:

   sudo docker network create --driver bridge esp_net

3. 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 Google Cloud que você usou ao enviar a imagem.
   • Substitua YOUR_IMAGE pelo nome da imagem.
4. Solicite o nome do serviço da API. Este é o nome que você especificou no campo host do documento da OpenAPI.
5. 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.

Veja como configurar o ESP para usar um ID de configuração específico, caso seja necessário:

1. Inclua a opção --version e defina-a para um ID de configuração específico.
2. Remova a opção --rollout_strategy=managed ou defina --rollout_strategy como fixed. A opção fixed configura o ESP para usar a configuração de serviço que você especificou em --version.
3. 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:

1. Nas sinalizações ESP de docker run, remova a opção --version.
2. Adicione a opção --rollout_strategy=managed.
3. 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:

1. Confira o nome do serviço da API. Esse é o nome que você especificou no campo host do documento da OpenAPI.
2. 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.

3. 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:

1. No arquivo de manifesto da implantação, adicione a opção --version e defina-a para um ID de configuração específico.
2. Remova --rollout_strategy=managed ou defina --rollout_strategy como fixed. A opção fixed configura o ESP para usar a configuração de serviço que você especificou em --version.
3. 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:

1. No Arquivo de manifesto de implantação, remova a opção --version.
2. Adicione a variável --rollout_strategy=managed.
3. 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.
  

  Acessar a página Explorador de registros

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