Implementar o back-end da API

Esta página explica como implementar o código de back-end da sua API e o proxy de serviço extensível (ESP) no Google Kubernetes Engine e no Compute 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 por proxy para que o Cloud Endpoints possa gerir a sua API.

Pré-requisitos

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

Preparação para a implementação

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 de Docker do ESP que está disponível gratuitamente no Container Registry.

Antes de implementar:

Antes de poder implementar a sua API e ESP no Compute Engine, conclua os seguintes passos:

  1. Crie, configure e inicie a 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 contentor Docker para o código do servidor de back-end.
  4. Envie o contentor para o Artifact Registry} ou outro registo.

  5. Certifique-se de que consegue:

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 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 artigo O que são âmbitos de acesso?.

Antes de implementar:

Com a adição de uma pequena secção ao ficheiro de manifesto de implementação, pode executar a imagem do Docker do ESP nos clusters de contentores juntamente com a sua aplicação em contentores. Antes de poder implementar a sua API com o ESP no GKE, conclua os seguintes passos:

  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 aplicação numa imagem Docker.
    2. Carregue a imagem para um registo.
    3. Crie um cluster de contentores.
    4. Implemente a sua aplicação no cluster.
    5. Exponha a sua aplicação à Internet.

  2. Certifique-se de que consegue:

    • Inicie o servidor da API.
    • Enviar pedidos para a sua API.

Implementar a API e o ESP

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 do contentor 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 seu contentor.
    • Substitua YOUR_PROJECT_ID pelo Google Cloud ID do 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 name do ficheiro 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 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. Execute novamente o comando docker run.

Se especificar --rollout_strategy=managed e a opção --version, o ESP começa com a configuração especificada em --version, mas é 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 demasiado 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. Para reiniciar o ESP, execute o comando docker run.

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.

  2. Abra o ficheiro de manifesto de implementação (denominado deployment.yaml) e adicione o seguinte à secçã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 sua API.

  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 é 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 demasiado 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 --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:

O que se segue?