Como implantar o back-end da API

Nesta página, você verá como 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.

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:

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:

Google 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 Container 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 Container Registry ou outro registro.
  5. Confira se é possível:

GKE;

Quando você cria um cluster no console do Google Cloud, por padrão, os escopos do 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

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:
    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. 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 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 sua própria rede de contêineres 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 do Google Cloud usado quando você enviou 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 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 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, conhecido como arquivo deployment.yaml, e adicione o seguinte à seção de contêineres:
    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:

A seguir