Conecte-se a recursos privados em sua VPC usando o VPC Lattice

O Amazon Bedrock AgentCore oferece suporte à conectividade privada com recursos hospedados em sua AWS VPC ou em ambientes locais conectados à sua VPC, como servidores MCP privados, APIs REST internas ou bancos de dados, sem expor esses serviços à Internet pública.

A conectividade privada é estabelecida usando gateways de recursos e configurações de recursos do Amazon VPC Lattice. Para obter detalhes sobre os dois modos compatíveis (rede gerenciada e autogerenciada), consulte Modos de saída de VPC compatíveis.

Principais conceitos

Serviços Amazon Bedrock AgentCore compatíveis

Os seguintes AgentCore serviços do Amazon Bedrock oferecem suporte à saída de VPC com o VPC Lattice:

Modos de saída de VPC compatíveis

O Amazon Bedrock AgentCore oferece suporte a dois modos para configurar a conectividade do VPC Lattice:

A tabela a seguir resume as principais diferenças:

Para obter detalhes sobre os preços do VPC Lattice, consulte os preços do Amazon VPC Lattice.

Opção 1: recursos gerenciados de VPC

Com os recursos gerenciados da VPC, você fornece informações sobre a VPC, a sub-rede e o grupo de segurança opcional. AgentCore trata da criação e do gerenciamento do ciclo de vida do gateway de recursos do VPC Lattice e da configuração de recursos em seu nome. O gateway de recursos gerenciados é um invólucro em torno dos ENIs em sua VPC. Você não pode modificar, configurar ou interagir com ele. AgentCore possui todo o seu ciclo de vida, incluindo criação, reutilização e exclusão.

AgentCore usa a função AWSServiceRoleForBedrockAgentCoreGatewayNetwork vinculada ao serviço para criar e gerenciar gateways de recursos do VPC Lattice em sua conta. Essa função é criada automaticamente na primeira vez que você cria um destino de gateway com um endpoint privado gerenciado. Para obter mais informações sobre essa função, consulte Função vinculada ao serviço do Gateway.

Pré-requisitos

Antes de criar um destino de gateway com um endpoint privado gerenciado, verifique o seguinte:

Crie um destino com um endpoint privado gerenciado

Para criar um recurso com um endpoint privado gerenciado, inclua o privateEndpoint.managedVpcResource bloco na sua solicitação de criação.

{
  ...
  "privateEndpoint": {
    "managedVpcResource": {
      "vpcIdentifier": "vpc-0abc123def456",
      "subnetIds": ["subnet-0abc123", "subnet-0def456"],
      "endpointIpAddressType": "IPV4",
      "securityGroupIds": ["sg-0abc123def"]
    }
  },
  ...
}

O managedVpcResource bloco aceita os seguintes campos:

Exibir recursos gerenciados

Depois que o recurso for criado, chame a API Get relevante (por exemplo,GetGatewayTarget) para ver os recursos gerenciados do VPC Lattice AgentCore criados em seu nome. Eles são retornados no privateEndpointManagedResources campo da resposta:

{
  ...
  "status": "READY",
  "privateEndpoint": {
    "managedVpcResource": {
      "vpcIdentifier": "vpc-0abc123def456",
      "subnetIds": ["subnet-0abc123", "subnet-0def456"],
      "endpointIpAddressType": "IPV4",
      "securityGroupIds": ["sg-0abc123def"]
    }
  },
  "privateEndpointManagedResources": [
    {
      "domain": "my-server.internal.example.com",
      "resourceGatewayArn": "arn:aws:vpc-lattice:us-east-1:123456789012:resourcegateway/rgw-abc123"
    }
  ]
}

Esse resourceGatewayArn AgentCore é o ARN do gateway de recursos do VPC Lattice criado em sua conta. AgentCore gerencia todo o ciclo de vida desse recurso: ele reutiliza o mesmo gateway de recursos para destinos com configurações de VPC e sub-rede correspondentes e o exclui quando não é mais usado por nenhum destino.

Opção 2: Self-managed recursos de rede

Com o Lattice autogerenciado, você mesmo cria e gerencia o gateway de recursos e a configuração de recursos do VPC Lattice e, em seguida, fornece o identificador de configuração do recurso a. AgentCore Use essa opção se você já tiver recursos do VPC Lattice configurados, precisar compartilhar uma configuração de recursos entre vários serviços ou precisar de controle sobre o ciclo de vida dos recursos do Lattice.

Pré-requisitos

Antes de criar um destino de gateway com um endpoint privado autogerenciado, conclua as seguintes etapas:

Configurar recursos do VPC Lattice para conectividade autogerenciada

Seu diretor do IAM também precisa das seguintes permissões AgentCore para permitir associar a configuração do recurso à rede AgentCore de serviços em seu nome:

{
"Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "vpc-lattice:GetResourceConfiguration",
        "vpc-lattice:CreateServiceNetworkResourceAssociation",
        "vpc-lattice:GetServiceNetworkResourceAssociation",
        "vpc-lattice:ListServiceNetworkResourceAssociations",
        "vpc-lattice:AssociateViaAWSService"
      ],
      "Resource": "*"
    }
  ]
}

Crie um destino com um endpoint privado autogerenciado

Para criar um recurso com um endpoint privado autogerenciado, inclua o privateEndpoint.selfManagedLatticeResource bloco na sua solicitação de criação:

{
  ...
  "privateEndpoint": {
    "selfManagedLatticeResource": {
      "resourceConfigurationIdentifier": "arn:aws:vpc-lattice:us-east-1:123456789012:resourceconfiguration/rcfg-abc123"
    }
  },
  ...
}

resourceConfigurationIdentifierPode ser o ARN ou o ID da configuração do recurso VPC Lattice. AgentCore usa suas credenciais (por meio de sessões de acesso direto) para associar a configuração do recurso à rede AgentCore de serviços.

Depois que o recurso é criado, a resposta da API Get inclui o resourceAssociationArn no privateEndpointManagedResources campo. Se você criar vários recursos apontando para a mesma configuração de recursos, AgentCore reutilizará automaticamente a associação de recursos de rede de serviços existente.

Cross-account recursos privados

Você pode se AgentCore conectar a recursos privados em uma AWS conta diferente da conta proprietária do gateway. Esse é um padrão comum para equipes de plataforma que gerenciam gateways centralizados, enquanto equipes de serviço individuais possuem os recursos privados.

A conta do proprietário do recurso deve compartilhar a configuração do recurso VPC Lattice com a conta do proprietário do gateway usando RAM. AWS A conta do proprietário do gateway então fornece o identificador de configuração do recurso compartilhado ao criar o destino do gateway.

As etapas a seguir resumem a configuração de várias contas:

Configurar a conectividade privada entre contas

Roteie o tráfego por meio de um domínio intermediário

Você pode usar o routingDomain campo para rotear o tráfego por meio de um componente intermediário, como um VPC endpoint, Application Load Balancer interno ou Network Load Balancer, em vez de diretamente para seu domínio de destino. Isso é útil quando você deseja consolidar vários recursos privados em um único ponto de entrada (por exemplo, rotear vários gateways de API privados por meio de um único VPC endpoint para reduzir o número de configurações de recursos e os custos associados).

Ao usar um domínio de roteamento, o domínio que você especifica para seu destino (na URL do endpoint MCP ou na URL do servidor OpenAPI) deve ser o nome DNS real do seu recurso. routingDomainÉ um domínio separado AgentCore usado para definir a configuração de recursos do VPC Lattice. No momento da invocação, AgentCore roteia o tráfego pelo domínio de roteamento, mas envia solicitações com o domínio de destino real como nome de host TLS SNI, para que seu recurso receba solicitações endereçadas ao domínio real.

O domínio de roteamento pode ser qualquer domínio roteado para seu recurso privado dentro da VPC. As opções comuns incluem:

As etapas a seguir descrevem o fluxo de tráfego quando um domínio de roteamento é usado:

Exemplo: Gateway de API privado com domínio de roteamento VPCE

O exemplo a seguir mostra como criar um destino de gateway para um API Gateway privado usando seu domínio VPCE como domínio de roteamento. O URL de destino é o nome de host privado do API Gateway e o routingDomain nome DNS do VPCE:

{
  "name": "my-private-apigw-target",
  "privateEndpoint": {
    "managedVpcResource": {
      "vpcIdentifier": "vpc-0123456789abcdef0",
      "subnetIds": ["subnet-0123456789abcdef0", "subnet-0abcdef1234567890"],
      "endpointIpAddressType": "IPV4",
      "routingDomain": "<vpce-id>.execute-api.us-east-1.vpce.amazonaws.com"
    }
  },
  "targetConfiguration": {
    "mcp": {
      "openApiSchema": {
        "inlinePayload": "<OpenAPI spec JSON with server URL matching the public certificate domain, for example https://<api-id>.execute-api.<region>.amazonaws.com>"
      }
    }
  }
}

Solução alternativa para certificados privados: ALB

A saída de VPC exige que seu endpoint de destino tenha um certificado TLS publicamente confiável. Se seu recurso privado usa um certificado emitido por uma autoridade de certificação (CA) privada, a solução alternativa recomendada é colocar um Application Load Balancer (ALB) interno na frente do seu recurso.

As etapas a seguir descrevem o fluxo de tráfego:

Etapa 1: Solicitar um certificado público do ACM

Solicite um certificado público do ACM para um domínio que você possui. Esse domínio será usado como URL de destino. Para obter instruções, consulte Solicitar um certificado público no Guia do usuário do AWS Certificate Manager.

Etapa 2: criar um ALB interno

Crie um Application Load Balancer interno na mesma VPC do seu recurso privado. Para obter instruções, consulte Create an Application Load Balancer no Guia do usuário do Elastic Load Balancing. Certifique-se de definir o esquema comointernal.

Etapa 3: criar um IP-based grupo-alvo

Crie um grupo-alvo com o tipo de destino ip que aponte para o endereço IP do seu recurso privado na porta 443 (HTTPS) e registre seu recurso privado como destino. Para obter instruções, consulte Criar um grupo-alvo no Guia do usuário do Elastic Load Balancing.

Etapa 4: criar um ouvinte HTTPS com transformação do cabeçalho do host

Crie um ouvinte HTTPS na porta 443 usando o certificado público do ACM. Adicione uma regra de ouvinte que transforme o cabeçalho Host do domínio público para o domínio do recurso privado antes do encaminhamento.

aws elbv2 create-listener \
  --load-balancer-arn <alb-arn> \
  --protocol HTTPS \
  --port 443 \
  --certificates CertificateArn=<acm-certificate-arn> \
  --default-actions '[{
    "Type": "forward",
    "TargetGroupArn": "<target-group-arn>",
    "ForwardConfig": {
      "TargetGroups": [{"TargetGroupArn": "<target-group-arn>", "Weight": 1}]
    }
  }]'

Em seguida, modifique a regra do ouvinte para adicionar a transformação do cabeçalho do host:

aws elbv2 modify-rule \
  --rule-arn <default-rule-arn> \
  --actions '[{
    "Type": "forward",
    "TargetGroupArn": "<target-group-arn>",
    "ForwardConfig": {
      "TargetGroups": [{"TargetGroupArn": "<target-group-arn>", "Weight": 1}]
    }
  }]' \
  --transforms '[{
    "Type": "host-header",
    "HostHeaderConfig": {
      "Values": ["my-server.my-company.internal"]
    }
  }]'

Etapa 5: configurar o endpoint privado

Use o nome DNS do ALB como o routingDomain e o domínio público do certificado como o URL de destino.

{
  ...
  "privateEndpoint": {
    "managedVpcResource": {
      "vpcIdentifier": "<vpc-id>",
      "subnetIds": ["<subnet-id-1>", "<subnet-id-2>"],
      "endpointIpAddressType": "IPV4",
      "routingDomain": "internal-my-alb-1234567890.us-west-2.elb.amazonaws.com"
    }
  },
  ...
}

O URL de destino em sua configuração de destino deve usar https://my-server.my-company.com (o domínio público do certificado), não o domínio privado.

Service-linked função para saída de VPC

Ao criar um destino de gateway com um endpoint privado gerenciado (managedVpcResource), AgentCore usa a função AWSServiceRoleForBedrockAgentCoreGatewayNetwork vinculada ao serviço para criar e gerenciar gateways de recursos do VPC Lattice em sua conta. Essa função é criada automaticamente na primeira vez que você cria um destino de endpoint privado gerenciado, desde que seu diretor do IAM tenha a iam:CreateServiceLinkedRole permissão necessária.

A função vinculada ao serviço tem as seguintes características principais:

Para obter o documento de política completo e as instruções para criar, editar e excluir essa função, consulte Função vinculada ao serviço do Gateway.

Status do alvo e solução de problemas

Depois de criar um recurso com um endpoint privado, o recurso passa por um CREATING estado enquanto AgentCore configura os recursos do VPC Lattice e estabelece a associação da rede de serviços. Você pode monitorar o status chamando a API Get relevante (por exemplo,GetGatewayTarget) e verificando os status statusReasons campos e.

A tabela a seguir descreve os valores de status comuns e seus significados:

A tabela a seguir descreve problemas comuns e suas soluções:

Limitações e considerações

Esteja ciente das seguintes limitações ao usar a saída de VPC para: AgentCore