Implementar o back-end da API

OpenAPI   |  gRPC

Esta página explica como implementar 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.

Embora os passos de implementação variem consoante a plataforma que aloja a sua API, existe sempre um passo em que fornece ao ESP o nome do serviço e uma opção que configura o ESP para usar a configuração do serviço Cloud Endpoints implementada mais recentemente. Com estas informações, o ESP pode obter a configuração dos pontos finais da sua API, o que permite ao ESP encaminhar pedidos e respostas para que os pontos finais possam gerir a sua API.

Nota: ESP e ESPV2 têm cada um um suporte de ambiente diferente. O ESP só é suportado no ambiente flexível do App Engine e não está disponível no ambiente padrão do App Engine. Por outro lado, o ESPv2 pode ser implementado no GKE e no Kubernetes, mas não suporta o App Engine.

Pré-requisitos

Como ponto de partida, esta página pressupõe que:

• Criou um Google Cloud projeto.
• Pontos finais configurados.
• Implementou a configuração dos Endpoints.

Preparação para a implementação

Ambiente flexível do App Engine

Com a adição de um pequeno passo de configuração (descrito nos passos seguintes), a implementação da sua API para que seja gerida pelos Endpoints é igual à implementação de qualquer aplicação no ambiente flexível do App Engine. Siga a documentação do App Engine para:

• Organize os seus ficheiros de configuração.
• Crie o app.yamlficheiro de configuração
• Se a sua aplicação se basear em microsserviços, consulte a documentação sobre a Implementação de várias aplicações de serviço para obter informações sobre a configuração dos ficheiros app.yaml para cada serviço.

Implementa a sua API no App Engine através do comando gcloud app deploy. Este comando cria automaticamente uma imagem de contentor através do serviço Container Builder e, em seguida, implementa essa imagem no seu ambiente flexível do App Engine.

Antes da implementação:

• O proprietário do Google Cloud projeto tem de criar a aplicação do App Engine.
• Certifique-se de que a sua conta de utilizador inclui os privilégios necessários.

Compute Engine

Para que os Endpoints geram a sua API, tem de instalar e configurar o ESP, bem como o código do servidor de back-end para a sua API. Tem de instalar o Docker na instância de VM do Compute Engine para poder executar a imagem do Docker do ESP que está disponível gratuitamente no Artifact Registry.

Antes da implementação:

Seguem-se os passos gerais que tem de realizar antes de poder implementar a API e o ESP no Compute Engine. Em geral, executa todos os passos que normalmente faria para executar o código do servidor de back-end no Compute Engine.

1. Crie, configure e inicie a 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 o artigo Instale o Docker.
3. Crie um contentor Docker para o código do servidor de back-end. Consulte a documentação do Cloud Build.
4. Envie o contentor para o Artifact Registry ou outro registo.
5. Certifique-se de que consegue:
   • Estabeleça ligação à instância de VM.
   • Execute a imagem do Docker para iniciar o servidor de back-end na instância da VM. Consulte a referência de execução do Docker.
   • Enviar pedidos para a sua API.

GKE

Quando cria um cluster na Google Cloud consola, por predefinição, os âmbitos do OAuth concedidos à conta de serviço do cluster incluem os âmbitos que o Endpoints requer:

• Controlo de serviços: ativado
• Gestão de serviços: só de leitura

Quando cria um cluster através do comando gcloud container clusters create ou através de um ficheiro de configuração de terceiros, certifique-se de que especifica os seguintes âmbitos:

• "https://www.googleapis.com/auth/servicecontrol"
• "https://www.googleapis.com/auth/service.management.readonly"

Para mais informações, consulte O que são âmbitos de acesso?

Antes da implementação:

Com a adição de uma pequena secção ao seu ficheiro de manifesto de implementação, pode executar a imagem do Docker do ESP nos seus clusters de contentores juntamente com a sua aplicação em contentores. Seguem-se os passos gerais que tem de realizar antes de poder implementar a sua API com o ESP no GKE. Em geral, executa todos os passos que normalmente executaria para executar o código do servidor de back-end no GKE.

1. Implemente a sua aplicação contentorizada nos clusters de contentores. Os passos gerais, conforme descrito na documentação do GKE , são:
   1. Empacote a sua app numa imagem do Docker.
   2. Carregue a imagem para um registo.
   3. Crie um cluster de contentores.
   4. Implemente a sua app no cluster.
   5. Exponha a sua app à Internet.
2. Certifique-se de que consegue:
   • Inicie o servidor da API.
   • Enviar pedidos para a sua API.

Implementar a API e o ESP

Ambiente flexível do App Engine

Para implementar a API e o ESP no App Engine:

1. Obtenha o nome do serviço da sua API. Este é o nome que especificou no campo host do seu documento OpenAPI.
2. Edite o ficheiro app.yaml e adicione uma secção denominada endpoints_api_service que contenha o nome do serviço. Pode usar o ficheiro 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

   Ir

   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 sua API.

   Adicione as variáveis de tempo de execução e de ambiente no app.yamlficheiro de configuração.

   Por 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 configuração do serviço implementada mais recente. Quando especifica esta opção, até 5 minutos após implementar uma nova configuração de serviço, o ESP deteta a alteração e começa a usá-la automaticamente. Recomendamos que especifique esta opção em vez de um ID de configuração específico para o ESP usar.

   Se a sua aplicação se basear em microsserviços, tem de incluir a secção endpoints_api_serviceapp.yaml em todos os ficheiros app.yaml.

3. Guarde o ficheiro (ou os ficheiros) app.yaml.
4. Implemente o código de back-end e o ESP no App Engine:

   gcloud app deploy

Uma vez que adicionou a secção endpoints_api_service ao ficheiro app.yaml, o comando gcloud app deploy implementa e configura o ESP num contentor separado do ambiente flexível do App Engine. Todo o tráfego de pedidos é encaminhado através do ESP e este envia pedidos e respostas por proxy para e a partir do contentor que executa o código do servidor de back-end.

Se precisar de configurar o ESP para usar um ID de configuração específico:

1. Na secção endpoints_api_service do ficheiro app.yaml, adicione o campo config_id e defina-o como 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 do serviço que especificou em config_id.
3. Volte a implementar a API e o ESP: gcloud app deploy

Recomendamos que não mantenha o ESP configurado para usar um ID de configuração específico durante muito tempo, porque se implementar uma configuração de serviço atualizada, tem de reiniciar o ESP para usar a nova configuração.

Para remover o ID de configuração específico:

1. Remova a opção config_id do ficheiro app.yaml.
2. Adicione a opção rollout_strategy: managed.
3. Emita o comando gcloud app deploy

Quando usar a opção rollout_strategy: managed, não inclua config_id: YOUR_SERVICE_CONFIG_ID no ficheiro app.yaml. Se o fizer, o gcloud app deploy falha com o seguinte erro:

config_id is forbidden when rollout_strategy is set to "managed".

Quando implementa a sua API no ambiente flexível do App Engine pela primeira vez, pode haver um atraso enquanto a máquina virtual (VM) e outra infraestrutura são configuradas. Para mais informações, consulte o artigo Garantir uma implementação bem-sucedida na documentação do App Engine.

Compute Engine

Para implementar a sua API com o ESP no Compute Engine com o Docker:

1. Estabeleça ligação à sua instância de VM. Substitua INSTANCE_NAME pelo nome da sua instância de VM.

   gcloud compute ssh INSTANCE_NAME

2. Crie a sua própria rede de contentores 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 associe-a à rede de contentores 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 seu contentor.
   • Substitua YOUR_PROJECT_ID pelo ID do Google Cloud projeto que usou quando enviou a imagem.
   • Substitua YOUR_IMAGE pelo nome da sua imagem.
4. Obtenha o nome do serviço da sua API. Este é o nome que especificou no campo host do seu documento OpenAPI.
5. Execute uma instância da imagem do Docker do 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 seu serviço.
   • Substitua YOUR_API_CONTAINER_NAME pelo nome do contentor da API.

   A opção --rollout_strategy=managed configura o ESP para usar a configuração do serviço implementada mais recente. Quando especifica esta opção, até 5 minutos após implementar uma nova configuração de serviço, o ESP deteta a alteração e começa a usá-la automaticamente. Recomendamos que especifique esta opção em vez de um ID de configuração específico para o ESP usar.

Se precisar de configurar o ESP para usar um ID de configuração específico:

1. Inclua a opção --version e defina-a como 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 do serviço que especificou em --version.
3. Emita novamente o comando docker run.

Se especificar --rollout_strategy=managed e a opção --version, o ESP é iniciado com a configuração especificada em --version, mas, em seguida, é executado no modo gerido e obtém a configuração mais recente.

Recomendamos que não mantenha o ESP configurado para usar um ID de configuração específico durante muito tempo, porque se implementar uma configuração de serviço atualizada, tem de reiniciar o ESP para usar a nova configuração.

Para remover o ID de configuração específico:

1. Nas flags ESP para 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.

Consulte as opções de arranque do ESP para ver a lista completa de opções que pode especificar ao iniciar o ESP.

GKE

Para implementar o ESP no GKE:

1. Obtenha o nome do serviço da sua API (o nome que especificou no campo host do seu documento OpenAPI).
2. Abra o ficheiro de manifesto de implementação (denominado ficheiro deployment.yaml) e adicione o seguinte à secção de contentores:

   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 sua API.

   A opção --rollout_strategy=managed" configura o ESP para usar a configuração do serviço implementada mais recente. Quando especifica esta opção, até 5 minutos após implementar uma nova configuração de serviço, o ESP deteta a alteração e começa a usá-la automaticamente. Recomendamos que especifique esta opção em vez de um ID de configuração específico para o ESP usar.

3. Inicie o serviço Kubernetes com o comando kubectl create:

   kubectl create -f deployment.yaml

Se precisar de configurar o ESP para usar um ID de configuração específico:

1. No ficheiro de manifesto de implementação, adicione a opção --version e defina-a como 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 do serviço que especificou em --version.
3. Inicie o serviço do Kubernetes: kubectl create -f deployment.yaml

Se especificar --rollout_strategy=managed e a opção --version, o ESP começa com a configuração especificada em --version, mas, em seguida, é executado no modo gerido e obtém a configuração mais recente.

Recomendamos que não mantenha o ESP configurado para usar um ID de configuração específico durante muito tempo, porque se implementar uma configuração de serviço atualizada, tem de reiniciar o ESP para usar a nova configuração.

Para remover o ID de configuração específico:

1. No ficheiro de manifesto de implementação, remova a opção --version.
2. Adicione o --rollout_strategy=managed.
3. Inicie o serviço do Kubernetes: kubectl create -f deployment.yaml

Consulte as opções de arranque do ESP para ver a lista completa de opções que pode especificar ao iniciar o ESP.

Acompanhamento da atividade da API

Depois de implementar o ESP e o back-end da API, pode usar ferramentas como o curl ou o Postman para enviar pedidos para a sua API. Se não receber uma resposta bem-sucedida, consulte o artigo Resolução de problemas de erros de resposta.

Depois de enviar alguns pedidos, pode:

• Veja os gráficos de atividade da sua API em 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 Cloud Logging.
  

  Aceda à página do Explorador de registos

O que se segue?

• Resolução de problemas da implementação do ambiente flexível do App Engine.
• Resolução de problemas de pontos finais no Compute Engine.
• Resolução de problemas de pontos finais no Google Kubernetes Engine.