Connect to private resources in your VPC using VPC Lattice

Amazon Bedrock AgentCore supports private connectivity to resources hosted inside your AWS VPC or on-premises environments connected to your VPC, such as private MCP servers, internal REST APIs, or databases, without exposing those services to the public internet.

Private connectivity is established using Amazon VPC Lattice resource gateways and resource configurations. For details on the two supported modes (managed and self-managed Lattice), see Supported VPC egress modes.

Key concepts

Supported Amazon Bedrock AgentCore services

The following Amazon Bedrock AgentCore services support VPC egress with VPC Lattice:

Supported VPC egress modes

Amazon Bedrock AgentCore supports two modes for configuring VPC Lattice connectivity:

The following table summarizes the key differences:

For VPC Lattice pricing details, see Amazon VPC Lattice pricing.

Option 1: Managed Lattice

With managed Lattice, you provide your VPC, subnet, and optional security group information. AgentCore handles the creation and lifecycle management of the VPC Lattice resource gateway and resource configuration on your behalf, and does not require you to have VPC Lattice permissions in your own IAM policies.

AgentCore uses the AWSServiceRoleForBedrockAgentCoreGatewayNetwork service-linked role to create and manage VPC Lattice resource gateways in your account. This role is created automatically the first time you create a gateway target with a managed private endpoint. For more information about this role, see Gateway service-linked role.

Prerequisites

Before creating a gateway target with a managed private endpoint, ensure the following:

Create a target with a managed private endpoint

To create a resource with a managed private endpoint, include the privateEndpoint.managedLatticeResource block in your create request.

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

The managedLatticeResource block accepts the following fields:

View managed resources

After the resource is created, call the relevant Get API (for example, GetGatewayTarget) to view the managed VPC Lattice resources that AgentCore created on your behalf. These are returned in the privateEndpointManagedResources field of the response:

{
  ...
  "status": "READY",
  "privateEndpoint": {
    "managedLatticeResource": {
      "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"
    }
  ]
}

The resourceGatewayArn is the ARN of the VPC Lattice resource gateway that AgentCore created in your account. AgentCore manages the full lifecycle of this resource: it reuses the same resource gateway for targets with matching VPC and subnet configurations, and deletes it when it is no longer used by any targets.

Option 2: Self-managed Lattice

With self-managed Lattice, you create and manage the VPC Lattice resource gateway and resource configuration yourself, then provide the resource configuration identifier to AgentCore. Use this option if you already have VPC Lattice resources configured, need to share a resource configuration across multiple services, or require control over the Lattice resource lifecycle.

Prerequisites

Before creating a gateway target with a self-managed private endpoint, complete the following steps:

Your IAM principal also needs the following permissions to allow AgentCore to associate the resource configuration with the AgentCore service network on your behalf:

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

Create a target with a self-managed private endpoint

To create a resource with a self-managed private endpoint, include the privateEndpoint.selfManagedLatticeResource block in your create request:

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

The resourceConfigurationIdentifier can be either the ARN or the ID of the VPC Lattice resource configuration. AgentCore uses your credentials (via Forward Access Sessions) to associate the resource configuration with the AgentCore service network.

After the resource is created, the Get API response includes the resourceAssociationArn in the privateEndpointManagedResources field. If you create multiple resources pointing to the same resource configuration, AgentCore automatically reuses the existing service network resource association.

Cross-account private resources

You can connect AgentCore to private resources in a different AWS account than the account that owns the gateway. This is a common pattern for platform teams that manage centralized gateways while individual service teams own the private resources.

The resource owner account must share the VPC Lattice resource configuration with the gateway owner account using AWS RAM. The gateway owner account then provides the shared resource configuration identifier when creating the gateway target.

The following steps summarize the cross-account setup:

Workaround for private DNS support: routing domain

Amazon VPC Lattice requires that the domain used in a resource configuration be publicly resolvable. If your private endpoint uses a domain that is only resolvable within your VPC (for example, a private hosted zone in Route 53), you must use the routingDomain field.

When using a routing domain, the domain you specify for your target (in the MCP endpoint URL or OpenAPI server URL) should be the actual private DNS name of your resource - i.e. the name that is resolvable within your VPC. The routingDomain is a separate, publicly resolvable domain that AgentCore uses only to set up the VPC Lattice resource configuration. At invocation time, AgentCore routes traffic through the routing domain but sends requests with the private DNS name as the TLS SNI hostname, so your resource receives requests addressed to its actual private domain.

The routing domain can be any publicly resolvable domain that routes to your private resource within the VPC — including any existing component in your architecture that already has a publicly resolvable DNS name. Common options include:

The following steps describe the traffic flow when a routing domain is used:

Example: Private API Gateway with VPCE routing domain

The following example shows how to create a gateway target for a private API Gateway using its VPCE domain as the routing domain. The target URL is the private API Gateway hostname, and the routingDomain is the VPCE DNS name:

{
  "name": "my-private-apigw-target",
  "privateEndpoint": {
    "managedLatticeResource": {
      "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>"
      }
    }
  }
}

Workaround for private certificates: ALB

VPC egress requires your target endpoint to have a publicly trusted TLS certificate. If your private resource uses a certificate issued by a private certificate authority (CA), the recommended workaround is to place an internal Application Load Balancer (ALB) in front of your resource.

The following steps describe the traffic flow:

Step 1: Request a public ACM certificate

Request a public certificate from ACM for a domain you own. This domain will be used as the target URL. For instructions, see Request a public certificate in the AWS Certificate Manager User Guide.

Step 2: Create an internal ALB

Create an internal Application Load Balancer in the same VPC as your private resource. For instructions, see Create an Application Load Balancer in the Elastic Load Balancing User Guide. Ensure you set the scheme to internal.

Step 3: Create an IP-based target group

Create a target group with target type ip that points to your private resource's IP address on port 443 (HTTPS), and register your private resource as a target. For instructions, see Create a target group in the Elastic Load Balancing User Guide.

Step 4: Create an HTTPS listener with host header transform

Create an HTTPS listener on port 443 using the public ACM certificate. Add a listener rule that transforms the Host header from the public domain to the private resource's domain before forwarding.

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}]
    }
  }]'

Then modify the listener rule to add the host header transform:

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"]
    }
  }]'

Step 5: Configure the private endpoint

Use the ALB DNS name as the routingDomain and the public cert domain as the target URL.

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

The target URL in your target configuration should use https://my-server.my-company.com (the public cert domain), not the private domain.

Service-linked role for VPC egress

When you create a gateway target with a managed private endpoint (managedLatticeResource), AgentCore uses the AWSServiceRoleForBedrockAgentCoreGatewayNetwork service-linked role to create and manage VPC Lattice resource gateways in your account. This role is created automatically the first time you create a managed private endpoint target, provided your IAM principal has the required iam:CreateServiceLinkedRole permission.

The service-linked role has the following key characteristics:

For the full policy document and instructions for creating, editing, and deleting this role, see Gateway service-linked role.

Target status and troubleshooting

After you create a resource with a private endpoint, the resource goes through a CREATING state while AgentCore sets up the VPC Lattice resources and establishes the service network association. You can monitor the status by calling the relevant Get API (for example, GetGatewayTarget) and checking the status and statusReasons fields.

The following table describes common status values and their meanings:

The following table describes common issues and their solutions:

Limitations and considerations

Be aware of the following limitations during the public preview of VPC egress for AgentCore: