Implementação de nomes de domínio personalizados para endpoints privados com o Amazon API Gateway

Este post foi escrito por Heeki Park, arquiteto de soluções principal

O Amazon API Gateway está introduzindo o suporte personalizado de nomes de domínio para endpoints privados da API REST. Os clientes escolhem endpoints privados da API REST quando querem endpoints que só podem ser chamados de dentro do Amazon VPC. Os nomes de domínio personalizados são URLs mais simples e intuitivos que você pode usar com seus aplicativos e, anteriormente, só eram compatíveis com endpoints públicos da API REST. Agora você pode usar nomes de domínio personalizados para mapear para APIs REST privadas e compartilhar esses nomes de domínio personalizados entre contas usando o AWS Resource Access Manager (AWS RAM).

Visão geral da conectividade do API Gateway

Ao considerar a conectividade de rede com o API Gateway, é importante ter em mente dois aspectos: o tipo de integração e o tipo de conectividade. O diagrama a seguir mostra exemplos dessas considerações.

Figura 1: Arquitetura geral

O primeiro aspecto é a distinção entre integrações de front-end e integrações de back-end. As integrações de front-end são como clientes de API, como dispositivos móveis, navegadores da web ou aplicativos clientes, se conectam ao endpoint da API. As integrações de back-end são os serviços de API aos quais seu endpoint do API Gateway solicita, como aplicativos executados em instâncias do Amazon Elastic Compute Cloud (EC2), contêineres do Amazon Elastic Kubernetes Service (EKS) ou do Amazon Elastic Container Service (ECS) ou como funções do AWS Lambda. O segundo aspecto é se essa conectividade é por meio da Internet pública ou por meio de sua VPC privada.

Chamando endpoints privados da API REST

Para enviar solicitações para um endpoint privado da API REST, os clientes devem operar em uma VPC configurada com um endpoint VPC. Depois que um VPC endpoint é configurado, um cliente tem três opções diferentes dentro da VPC para se conectar ao endpoint da API, dependendo de como a VPC e o VPC endpoint estão configurados.

Se o VPC endpoint tiver o DNS privado ativado, o cliente poderá enviar solicitações para a URL padrão do endpoint: https://{api-id}.execute-api. {region} .amazonaws.com/ {stage}. Essas solicitações são resolvidas para o VPC endpoint, que então é roteado para o endpoint apropriado do API Gateway.

Figura 2: VPC endpoint configurado com nomes DNS privados habilitados

Como alternativa, se o VPC endpoint tiver o DNS privado desativado, o cliente poderá enviar solicitações para a URL do VPC endpoint: https://{vpce-id}.execute-api. {region} .amazonaws.com/ {stage}. Um dos cabeçalhos a seguir também precisa ser enviado junto com essa solicitação.

Host: {api-id}. execute-api.us-east-1.amazonaws.com
x-apigw-api-id: {api-id}

Por fim, se o endpoint da VPC tiver o DNS privado desativado e o endpoint da API REST privado estiver associado ao endpoint da VPC, o cliente poderá enviar solicitações para o seguinte URL: https://{api-id}-{vpce-id}.execute-api. {region} .amazonaws.com/ {stage}. Para associar um VPC endpoint a uma API privada, a propriedade a seguir configura essa associação.

      EndpointConfiguration:
        Type: PRIVATE
        VPCEndpointIds:
          - !Ref vpcEndpointId

Você pode ver essa configuração no console, da seguinte forma.

Figura 3: Configuração opcional do VPC endpoint com endpoints privados da API REST

Para simplificar o acesso aos seus endpoints privados da API REST, agora você também pode configurar nomes de domínio personalizados, que funcionam como um URL intuitivo estável para suas APIs privadas.

Implementação de nomes de domínio personalizados para endpoints privados

Antes de configurar um nome de domínio personalizado para seus endpoints privados da API REST, um endpoint VPC para o API Gateway, um certificado do AWS Certificate Manager (ACM), uma zona hospedada privada do Amazon Route 53 e um ou mais endpoints privados da API REST precisam ser configurados.

Depois que esses pré-requisitos forem configurados, um nome de domínio personalizado poderá ser configurado com as seguintes etapas:

Na conta do provedor de API, crie um nome de domínio personalizado e um mapeamento do caminho base.
Na conta do provedor, use a AWS RAM para criar um compartilhamento de recursos para o nome de domínio personalizado. Na conta do consumidor, aceite a solicitação de compartilhamento de recursos. Essa etapa só é necessária se o provedor e o consumidor estiverem em contas diferentes da AWS.
Na conta do consumidor, associe um VPC endpoint ao nome de domínio personalizado.
Na conta do consumidor, crie um alias do Route 53 para mapear o domínio personalizado para o VPC endpoint.

Figura 4: Componentes para configurar um nome de domínio personalizado

Etapa 1: Criar um nome de domínio personalizado privado

Ao configurar um nome de domínio personalizado, uma política baseada em recursos especifica quais consumidores de API podem invocar seu nome de domínio personalizado privado.

Figura 5: Criação de um nome de domínio personalizado privado

Esse é um exemplo de definição do CloudFormation para um nome de domínio personalizado privado.

  DomainName:
    DependsOn: Certificate
    Type: AWS::ApiGateway::DomainNameV2
    Properties:
      CertificateArn: !Ref certificateArn
      DomainName: api.internal.example.com
      EndpointConfiguration:
        Types:
          - PRIVATE
      Policy:
        Fn::ToJsonString:
          Statement:
            - Effect: Deny
              Principal: '*'
              Action: execute-api:Invoke
              Resource:
                - execute-api:/*
              Condition:
                StringNotEquals:
                  aws:SourceVpce: !Ref vpceEndpointId
            - Effect: Allow
              Principal:
                AWS:
                  - '123456789012'
              Action: execute-api:Invoke
              Resource:
                - execute-api:/*
      SecurityPolicy: TLS_1_2

Observe que a diretiva Fn: :toJsonString acima vem da transformação AWS: :LanguageExtensions.

Neste exemplo, a política baseada em recursos nega qualquer solicitação que não venha de um determinado VPC endpoint e só permite invocar solicitações provenientes dessa conta de consumidor (123456789012).

Em seguida, o nome de domínio personalizado privado precisa ser mapeado para um ou mais endpoints privados da API REST nessa conta do provedor. O mapeamento abaixo é um exemplo de mapeamento de uma API REST privada para o nome de domínio personalizado.

  Mapping:
    DependsOn: DomainName
    Type: AWS::ApiGateway::BasePathMappingV2
    Properties:
      BasePath: app1
      DomainName: api.internal.example.com
      DomainNameId: abcde12345
      RestApiId: !Ref apiId
      Stage: !Ref stageName

Neste exemplo, o basePath está definido como app1. Se o Stage estiver definido como dev, o endpoint privado poderá ser acessado via https://api.internal.example.com/app1. O ID do domínio é o identificador do nome de domínio personalizado privado, que você pode obter ao criar o nome de domínio personalizado na etapa 1.

Observe que, com nomes de domínio públicos personalizados, o nome de domínio precisa ser exclusivo na região, pois eles são resolvidos publicamente. Com nomes de domínio personalizados privados, como eles são resolvidos em uma VPC, um nome de domínio personalizado privado com o mesmo nome pode ser criado em contas diferentes. O nome de domínio personalizado privado é então resolvido para o VPC endpoint na VPC dessa conta.

Etapa 2: Compartilhamento do nome de domínio personalizado privado usando AWS RAM

Para que os consumidores da API acessem o nome de domínio personalizado privado de outra conta, o nome de domínio personalizado precisa ser compartilhado com as contas do consumidor usando RAM. Quando a RAM cria o compartilhamento de recursos, ela também cria automaticamente uma política de gerenciamento. A política de gerenciamento concede à conta do consumidor permissão para associar um VPC endpoint ao nome de domínio privado personalizado. No entanto, se o provedor da API e o consumidor da API estiverem na mesma conta, essa etapa com RAM poderá ser ignorada.

Figura 6: Compartilhamento do nome de domínio personalizado privado

A seguinte definição do CloudFormation cria um compartilhamento de recursos na conta do provedor.

  Share:
    Type: AWS::RAM::ResourceShare
    Properties:
      Name: private-custom-domain-name
      Principals: 
        - '123456789012'
      ResourceArns: 
        - 'arn:aws:apigateway:us-east-1:567890123456:/domainnames/api.internal.example.com+abcde12345'

Os “principals” permitidos para o compartilhamento de recursos especificam os IDs da conta do consumidor. O ResourceARNS especifica o ARN do nome de domínio personalizado privado.

Na conta do consumidor, um administrador recebe uma notificação para aceitar o compartilhamento de recursos. Essa solicitação deve ser aceita para permitir que a conta do consumidor veja o nome de domínio personalizado privado. Esse “aperto de mão” (handshaking) atua como um acordo mútuo entre as contas para permitir que o nome de domínio personalizado privado seja exposto da conta do provedor (567890123456) para a conta do consumidor (123456789012). Se as contas do provedor e do consumidor estiverem na mesma organização da AWS, o compartilhamento será aceito automaticamente em nome dos consumidores.

Etapa 3: Associar o nome de domínio personalizado privado a um VPC endpoint

O nome de domínio personalizado privado agora está visível na conta do consumidor. Em seguida, associe o nome de domínio personalizado privado a um VPC endpoint na conta do consumidor e na VPC em que os aplicativos cliente residem.

Figura 7: Associando o nome de domínio personalizado privado a um VPC endpoint

  Association:
    DependsOn: DomainName
    Type: AWS::ApiGateway::DomainNameAccessAssociation
    Properties:
      AccessAssociationSource: vpce-abcdefgh123456789
      AccessAssociationSourceType: VPCE
      DomainNameArn: 'arn:aws:apigateway:us-east-1:567890123456:/domainnames/api.internal.example.com+abcde12345'

O AccessAssociationSource é o ID do VPC endpoint, e o DomainNameArn é o mesmo ARN usado no compartilhamento de recursos de RAM.

Etapa 4: Criar um alias do Route 53 para o nome de domínio personalizado

A etapa final antes de poder testar o nome de domínio personalizado na conta do consumidor é configurar um alias do Route 53. Esse alias é configurado em uma zona hospedada privada associada à VPC em que residem o endpoint da VPC e os aplicativos cliente. O alias resolve o nome de domínio totalmente qualificado (FQDN) para o nome DNS do VPC endpoint.

Figura 8: Criando um alias do Route 53

A seguinte definição do CloudFormation cria esse alias.

  Alias:
    Type: AWS::Route53::RecordSet
    Properties:
      HostedZoneId: !Ref privateZoneId
      Name: api.internal.example.com
      ResourceRecords:
        - vpce-abcdefgh123456789-abcd1234.execute-api.us-east-1.vpce.amazonaws.com
      TTL: 300
      Type: CNAME

Os ResourceRecords apontam para o FQDN do VPC endpoint ao qual nosso nome de domínio personalizado privado está associado. Depois que esse alias for criado, seus aplicativos cliente poderão testar se ele pode enviar solicitações com êxito para o nome de domínio personalizado privado.

Opcional: Limpando os recursos

Se você configurou um ambiente de teste com esses recursos, pode limpar a implantação seguindo as etapas na ordem inversa.

Na conta do consumidor, exclua o alias do Route 53.
Na conta do consumidor, exclua a associação.
Na conta do consumidor e do provedor, remova o compartilhamento de recursos de RAM.
Na conta do provedor, exclua o nome de domínio personalizado e o mapeamento do caminho base.

Conclusão

Nesta postagem, você aprendeu sobre como os clientes podem se conectar a endpoints privados da API REST com o API Gateway. Com nomes de domínio personalizados, seus aplicativos se conectam a URLs estáveis que podem encaminhar solicitações para diversos back-ends de APIs privadas. Além disso, suas equipes de aplicativos podem implantar recursos em contas separadas da AWS de linha de negócios e acessar o nome de domínio personalizado privado como um recurso compartilhado central, usando o compartilhamento de recursos de RAM da AWS. Isso permite que suas equipes de aplicativos criem aplicativos de API seguros e privados e os exponham aos consumidores de API com segurança e em várias contas da AWS.

Para obter mais detalhes, consulte a documentação do API Gateway e confira os padrões com o API Gateway em Serverless Land.

Este blog é uma tradução do conteúdo original em inglês (link aqui).

Biografia do autor

Heeki Park é arquiteto de soluções principal da AWS.

Biografia do tradutor

Daniel Abib é Senior Solution Architect na AWS, com mais de 25 anos trabalhando com gerenciamento de projetos, arquiteturas de soluções escaláveis, desenvolvimento de sistemas e CI/CD, microsserviços, arquitetura Serverless & Containers e segurança. Ele trabalha apoiando clientes corporativos, ajudando-os em sua jornada para a nuvem.

https://www.linkedin.com/in/danielabib/

Biografia do Revisor

Guilherme Gomes é um arquiteto especialista sênior em AI da AWS.

O blog da AWS