Como implantar o back-end da API

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 e no Compute 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 última configuração de serviço do Cloud Endpoints implantada. 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 Cloud Endpoints.

Pré-requisitos

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

Como se preparar para a implantação

Google Compute Engine

Para que o Endpoints gerencie a API, instale e configure o ESP e o código do servidor de back-end da API. É necessário instalar o Docker na instância de VM do Compute Engine para executar a imagem do Docker do ESP disponível gratuitamente no Container Registry.

Antes de implantar:

Antes de implantar sua API e o ESP no Compute Engine, conclua as etapas a seguir:

  1. Crie, configure e inicie sua instância de VM.
  2. Instale o Docker Enterprise Edition (EE) ou o Docker Community Edition (CE) na sua instância de VM.
  3. Crie um contêiner do Docker para seu código de servidor de back-end.
  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 escopos a seguir:

  • "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 com o aplicativo em contêiner. Antes de implantar sua API com o ESP para o GKE, conclua as etapas a seguir:

  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 aplicativo em uma imagem do Docker.
    2. Faça upload da imagem para um registro.
    3. Crie um cluster de contêiner.
    4. Implante seu aplicativo no cluster.
    5. Exponha seu aplicativo à internet.

  2. Confira se é possível:

    • iniciar o servidor da API;
    • enviar solicitações para a API.

Como implantar a API e o ESP

Google 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
    • 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 name do arquivo YAML de configuração do serviço.

  5. Execute uma instância da imagem do Docker do ESP:

    sudo docker run \
    --detach \
    --name=esp \
    --publish=80:9000 \
    --net=esp_net \
    gcr.io/endpoints-release/endpoints-runtime:1 \
    --service=SERVICE_NAME \
    --rollout_strategy=managed \
    --http2_port=9000 \
    --backend=grpc://YOUR_API_CONTAINER_NAME:8000
    • 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 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 de serviço que você especificou em --version.

  3. Execute o comando docker run novamente.

Se você especificar as opções --rollout_strategy=managed e --version, o ESP será iniciado com a configuração determinada em --version, mas será executado no modo gerenciado e receberá a configuração mais recente.

Recomendamos não manter o ESP configurado para usar um ID de configuração específico por muito tempo. Isso 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:

  1. Nas sinalizações do ESP em docker run, remova a opção --version.

  2. Adicione a opção --rollout_strategy=managed.

  3. Para reiniciar o ESP, execute o comando docker run.

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. Solicite o nome do serviço da API.

  2. Abra o arquivo de manifesto de implantação, chamado de deployment.yaml, e adicione o seguinte à seção containers:

          containers:
      - name: esp
        image: gcr.io/endpoints-release/endpoints-runtime:1
        args: [
          "--http2_port=9000",
          "--service=SERVICE_NAME",
          "--rollout_strategy=managed",
          "--backend=grpc://127.0.0.1:8000"
        ]
        ports:
          - containerPort: 9000

    Substitua SERVICE_NAME pelo nome do serviço da API.

  3. Use o comando kubectl create (em inglês) para iniciar o serviço do Kubernetes:

        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 como um ID de configuração específico.

  2. Remova --rollout_strategy=managed ou defina --rollout_strategy como fixed. A opção fixed define 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

Se você especificar as opções --rollout_strategy=managed e --version, o ESP será iniciado com a configuração determinada em --version, mas será executado no modo gerenciado e receberá a configuração mais recente.

Recomendamos não manter o ESP configurado para usar um ID de configuração específico por muito tempo. Isso 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:

  1. No Arquivo de manifesto de implantação, remova a opção --version.

  2. Adicione --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. Se você não receber uma resposta bem-sucedida, consulte Como solucionar problemas em erros de resposta.

Após o envio de algumas solicitações, é possível fazer o seguinte:

A seguir