Modelo de implantação do gateway de API

Sobre os componentes da API

Uma API definida no gateway de API consiste em dois componentes principais:

  1. Configuração da API: a configuração da API criada quando você faz o upload de uma definição de API. Você cria a definição da API como uma especificação OpenAPI. Se a API gerencia serviços gRPC no Cloud Run, é possível definir a API com uma definição e configuração de serviço gRPC.

    Sempre que você fizer o upload de uma definição de API, o gateway de API cria uma nova configuração de API. Ou seja, você pode criar uma configuração de API, mas não será possível modificá-la depois. Se você editar a definição da API na especificação OpenAPI ou no serviço gRPC e fazer upload da definição da API editada, criará uma nova configuração de API.

  2. Gateway: um proxy escalonável, de alto desempenho e baseado no Envoy que hospeda a configuração da API implantada. A implantação de uma configuração de API em um gateway cria o URL externo que seus clientes usam para acessar a API.

A imagem a seguir mostra esses componentes:

A definição da API no painel "Gateway de API" mostra três componentes de configuração de API e três componentes de gateway.

Sobre a implantação de uma configuração de API em um gateway

Implante uma configuração de API em um gateway para tornar a API acessível aos clientes de API:

Em três APIs de amostra, uma configuração de API é implantada em um gateway, tornando as APIs acessíveis aos clientes da API.

Um gateway:

  • é implantada em uma região específica do GCP; Uma região é uma região geográfica específica no GCP em que você pode implantar recursos.

  • É preciso hospedar uma configuração de API. Não é possível criar um gateway vazio, ou seja, um gateway sem configuração de API. No entanto, depois que um gateway é criado, você pode atualizá-lo para substituir uma configuração de API por outra.

  • Só é possível hospedar uma única configuração de API. Não é possível implantar várias configurações de API no mesmo gateway.

Em seguida, gerencie cada gateway implantado separadamente. Para cada gateway, é possível:

  • Iniciar/parar/excluir o gateway
  • Veja registros e métricas
  • Visualizar informações de trace

Como escolher uma região do GCP

Cada gateway é implantado em uma região geográfica específica no GCP. A API Gateway é compatível com as seguintes regiões do GCP para implantação:

  • asia-northeast1
  • australia-southeast1
  • europe-west1
  • europe-west2
  • us-east1
  • us-east4
  • us-central1
  • us-west2
  • us-west3
  • us-west4

Como definir o endpoint da configuração da API implantada

Quando você implanta uma configuração de API em um gateway, o gateway de API cria um URL exclusivo para o gateway no domínio gateway.dev. Seus clientes de API usam um URL no formulário abaixo para acessar a configuração de API implantada:

https://GATEWAY_ID-HASH.REGION_CODE.gateway.dev

em que GATEWAY_ID é o nome do gateway, HASH é o código hash exclusivo gerado quando você implantou a API e REGION_CODE é o código da região do GCP onde você implantou o gateway.

Exemplo:

my-gateway-a12bcd345e67f89g0h.uc.gateway.dev

Como configurar uma conta de serviço para implantar configurações da API

Uma configuração de API implantada em um gateway é executada com as permissões associadas aos papéis concedidos à conta de serviço usada para criar a configuração da API. Portanto, você normalmente define uma conta de serviço separada para criar configurações de API. Essa conta é atribuída somente aos papéis necessários para acessar o serviço de back-end. Assim, é possível limitar as permissões associadas à configuração da API.

Além dos papéis necessários para acessar o serviço de back-end, a conta de serviço precisa receber as seguintes permissões:

  • A permissão iam.serviceAccounts.actAs; Essa permissão está incluída no papel de Usuário da conta de serviço.

  • As permissões necessárias para acessar seu serviço de back-end. Por exemplo, se o back-end for implementado como uma função do Cloud, a conta de serviço precisará ser atribuída pelo menos à função do Chamador do Cloud Functions. Para um back-end do Cloud Run, o papel é Chamador do Cloud Run. Ao limitar as permissões associadas à configuração da API, você pode proteger melhor seus sistemas de back-end.

Consulte Como configurar o ambiente de desenvolvimento para saber mais.

Sobre a escala a zero

O gateway de API é um serviço de escalonamento a zero. Isso significa que, quando não houver tráfego, todas as instâncias serão excluídas. Quando o tráfego aumenta, novas instâncias são criadas sob demanda para manipular a carga. O escalonamento vertical é controlado automaticamente pelo GCP. não é necessário configurá-lo ou gerenciá-lo.

Como usar um balanceador de carga

Cada gateway implantado em uma região contém um balanceador de carga integrado para gerenciar as solicitações do cliente à API implantada no gateway. Não é necessário criar um balanceador de carga separado para cada gateway.

Você precisa criar um balanceador de carga ao implantar a mesma API em gateways localizados em regiões diferentes. Em seguida, o balanceador de carga direciona solicitações de API para as diferentes regiões. Consulte Como implantar uma API em várias regiões abaixo para saber mais.

Como configurar o acesso SSL a uma API

O gateway de API é compatível com acesso HTTPS a uma API implantada em um gateway. Como as APIs são implantadas no domínio gateway.dev, o Google cria e gerencia o certificado SSL no balanceador de carga integrado ao gateway. Não é necessário criar ou fazer upload do seu próprio certificado.

Como configurar um servidor de nomes de domínio

Por padrão, os clientes de API fazem solicitações para um domínio gateway.dev para acessar uma API implantada, conforme mostrado acima.

Os nomes de domínio personalizados são para o gateway de API quando usados em conjunto com o balanceamento de carga HTTP(S) para o gateway de APIPREVIEW. Para personalizar o nome do domínio, crie um balanceador de carga que use seu nome de domínio personalizado e direcione as solicitações para o domínio gateway.dev da API implantada. Para mais informações, consulte Usar um domínio personalizado com gateway de API.

Como implantar várias configurações de API na mesma API

Só é possível implantar uma única configuração de API em um gateway. No entanto, é possível implantar várias configurações de API em vários gateways na mesma API.

Nesta seção, descrevemos dois cenários em que você pode implantar várias configurações de API em vários gateways em uma única API.

Como implantar configurações da API em vários gateways na mesma região

Ao criar uma API, os desenvolvedores geralmente criam ambientes de desenvolvimento, preparação e produção, em que:

  • O ambiente de desenvolvimento é usado pelos desenvolvedores para criar a API.
  • O ambiente staging é usado para testar a API em preparação para uma versão de produção.
  • O ambiente de produção é onde seus clientes de API externos têm permissão para acessar a API.

Para dar suporte a esse tipo de ambiente de desenvolvimento, defina várias configurações de API. Por exemplo, é possível ter várias configurações de API atualmente em desenvolvimento, uma configuração de API em teste no momento e uma configuração de API atualmente implantada na produção.

A API Gateway permite criar várias configurações de API em uma única API e implantar cada configuração de API em um gateway diferente:

Na API 1, três configurações de API chamadas API Config Dev, API Config Stage e API Config Prod são implantadas em três gateways respectivos.

Neste exemplo, você tem três configurações diferentes de API: dev, stage e prod. Em seguida, implante cada configuração de API em um gateway diferente, em que cada gateway define o próprio URL de endpoint exclusivo.

Como implantar uma configuração de API em várias regiões

Muitas vezes, uma API é implantada em várias regiões do GCP. A implantação em várias regiões oferece várias vantagens, incluindo redução da latência de solicitações porque as solicitações são direcionadas para uma API em execução em uma região geograficamente próxima ao cliente, bem como maior confiabilidade porque uma falha em uma região não afeta as APIs em execução em outras regiões.

Para implantar uma API em várias regiões, implante uma configuração de API em um gateway em cada região. Cada configuração de API é específica da região implantada porque precisa fazer referência ao serviço de back-end nessa região.

Na imagem a seguir, as APIs 1 e 2 são implantadas em uma única região, e a API 3 é implantada em várias regiões:

As APIs 1 e 2 são implantadas nas regiões 1, e 3 nas regiões 1, 2 e 3 usando um balanceador de carga.

Neste exemplo, cada configuração de API implantada em um gateway para a API 3 tem um endpoint de URL exclusivo, no formato:

https://my-gateway1-a12bcd345e67f89g0h.uc.gateway.dev
https://my-gateway2-b12cde345f67g89h0i.en.gateway.dev
https://my-gateway3-c12bde345g67h89i0j.uw.gateway.dev

Em seguida, configure um balanceador de carga usando o balanceamento de carga HTTP(S) para o gateway de APIPREVIEW a fim de processar solicitações para a API e encaminhar a solicitação para a região apropriada. Para mais informações, consulte Como criar implantações multirregionais para o gateway de API.

Como atualizar uma API

É possível atualizar uma API implantada editando a definição dela na especificação OpenAPI e, em seguida, fazendo o upload da especificação. O upload de uma nova especificação cria uma nova configuração de API.

O gateway de API é compatível com um modelo de atualização sem inatividade. Isso significa que a API continua processando solicitações durante a implantação da configuração da API atualizada. No entanto, há um período de tempo em que a nova configuração de API está sendo implantada quando algumas solicitações ainda podem ser manipuladas pela versão anterior da configuração da API.

Se você implantou a configuração da API em várias regiões e gateways, é necessário implantar novamente a configuração atualizada da API em cada região.

A seguir