hiw3c 日报精选
AWS ML Blog RSS 全文

将亚马逊Bedrock AgentCore网关连接到中心化检查的Hub-and-Spoke网络中的私有API。

原文标题 · Connect Amazon Bedrock AgentCore Gateway to private APIs in a hub-and-spoke network with centralized inspection

许多企业采用集中式网络模型:一个账户拥有所有VPC,中央防火墙检查所有流量。本篇文章介绍一种经过验证的模式,用于在该模型中将亚马逊Bedrock AgentCore网关与私有API及MCP服务器连接,其中网络账户中包含VPC Lattice资源网关,因此每一次跳转均通过防火墙。

来源:AWS ML Blog · aws.amazon.com

正文为英文,可一键机器翻译(仅首次需要等待)

In many enterprises, a central network team owns every virtual private cloud (VPC) and subnet, and every flow between VPCs must pass a central firewall in both directions. Agents that call internal REST APIs and Model Context Protocol (MCP) servers through Amazon Bedrock AgentCore Gateway, a capability of Amazon Bedrock AgentCore, must meet the same two requirements. Amazon Bedrock AgentCore is a platform to build, connect, and optimize agents at scale, with any framework or model.

This post shows a pattern that meets both requirements. The network team keeps ownership of every subnet, and traffic between the Gateway and your private APIs and MCP servers crosses the central firewall in both directions. It covers where to place the Amazon VPC Lattice resource gateway that the Gateway uses to reach private targets. It also covers who owns each piece, six configuration decisions, and the checks that confirm the pattern works.

We built and tested the pattern in the US East (N. Virginia) AWS Region (us-east-1), in a lab with three member accounts and a management account in AWS Organizations. The AWS CloudFormation templates, test scripts, test evidence, and reference material (address plan, full validation checks, troubleshooting, quotas) are in the companion repository. Use the pattern as a guideline and adjust it to your own account architecture.

Terms used in this post

  • Resource gateway: The Amazon VPC Lattice entry point into a VPC: elastic network interfaces (ENIs) in subnets you choose. Backends see its addresses as the source of each connection.
  • Resource configuration: A VPC Lattice object that names one backend (here, an internal load balancer or VPC endpoint DNS name and port) behind a resource gateway. You can share it with other accounts through AWS Resource Access Manager (AWS RAM).
  • Managed mode and self-managed mode: The two private endpoint options for Gateway targets. In managed mode, AgentCore creates the resource gateway for you. In self-managed mode, you create it and give the target a resource configuration.

When to use this pattern

Use this pattern when all of the following are true:

  • A network account owns every VPC, subnet, and AWS Transit Gateway attachment, and shares application subnets through AWS RAM.
  • A central firewall in an inspection VPC must inspect traffic entering and leaving every VPC.
  • Application teams manage only their own resources and security groups.

Otherwise, one of the options in Table 1 fits better.

Table 1: When another option fits better.

Your environment Use
The Gateway account can own subnets that reach your tools Managed mode
Traffic between the Gateway and the tools doesn’t need central inspection Self-managed mode, as documented
Tools are reachable on public endpoints A standard Gateway target

We also considered managed mode in subnets that AgentCore owns, a resource gateway in each tool VPC or in the central endpoints VPC, and internet-facing load balancers with AWS WAF per tool. The alternatives write-up explains why each falls short under these constraints.

Design requirements for centralized inspection

  • The network account owns every subnet. The Gateway and application accounts build only in subnets shared to them through AWS RAM.
  • Every flow between VPCs crosses the central firewall, in both directions. The central firewall in the inspection VPC inspects the traffic between the Gateway and your private APIs and MCP servers.

AgentCore Gateway reaches private targets through a VPC Lattice resource gateway, and the two private endpoint modes place it differently. Managed mode creates it in the Gateway account, which fits environments where that account can own the subnets it runs in. Self-managed mode, as documented, places it in subnets with direct access to the backend, which fits environments that do not require inspection between the Gateway and the tool. This environment needs both conditions at once, so the pattern uses self-managed mode with one change. The network account owns the resource gateway and places it in subnets routed through AWS Transit Gateway, so every request and reply passes the inspection VPC.

Solution overview

Give the resource gateway its own VPC and subnets in the network account. Don’t share them, and keep backends out of them. Route them through the transit gateway so every request and reply between VPCs crosses the firewall. Share one resource configuration per backend with the AgentCore account through AWS RAM. Figure 1 shows the accounts, VPCs, and traffic path.

Network account owns every VPC and the VPC Lattice resource gateway; traffic crosses the central firewall in both directions

Figure 1: The network account owns every VPC and the resource gateway. The other accounts own only what they place in shared subnets. Solid lines cross the firewall in both directions. Step numbers match the following traffic path

Traffic path

  1. The agent, in a shared subnet with no internet route, calls the Gateway URL. Private DNS on the Gateway interface endpoint resolves it inside the agent’s VPC.
  2. AWS WAF, if attached, evaluates the request. The Gateway checks its resource policy and the inbound JSON Web Token (JWT), then picks the target and tool.
  3. The Gateway gets an outbound OAuth token for the tool account and sends the request through VPC Lattice to the resource gateway in the network account.
  4. The resource gateway subnets route to the transit gateway, which sends the traffic through the inspection VPC to the tool account’s internal Application Load Balancer (ALB) or execute-api endpoint. (Crosses the firewall.)
  5. The ALB or Amazon API Gateway validates the token and forwards the request to the backend.
  6. The response returns the same way. (Crosses the firewall.)

How does Gateway traffic enter the network account’s VPC without a transit gateway attachment in the AgentCore account? When you create a target, AgentCore associates the shared resource configuration with its own VPC Lattice service network. VPC Lattice then delivers connections from that service network to the resource gateway’s network interfaces in your VPC. AWS operates that hop, and from there your routes and firewall take over.

What this pattern doesn’t do. Check these limits against your requirements before you adopt it:

  • No payload inspection – Traffic is TLS end to end from the Gateway to the ALB, with a certificate the Gateway validates. The firewall sees flow metadata and the TLS Server Name Indication (SNI), not payloads. Request content is in the Gateway, AWS WAF, and ALB logs.
  • Some legs skip the firewall – The agent-to-interface-endpoint leg and the Gateway-to-resource-gateway leg don’t cross it. Neither do the token requests that AgentCore makes to each identity provider.
  • No end-user identity at the tool – With the client credentials grant, every call that reaches the tool carries the Gateway’s client identity. To trace a call to a caller, use the inbound JWT claims in the Gateway application logs.

Who owns what

Table 2: Who creates what.

One time New API on a connected ALB New ALB or tool account
Network team Resource gateway and its VPC, subnets, and routes. Firewall rules. A default route from the tool VPC to the transit gateway for the ALB’s signing-key fetch. Gateway interface endpoint and policy. AWS RAM share Nothing One resource configuration added to the share. A firewall rule if the range is new
Tool team An ALB certificate whose subject alternative name matches the target host name that the AgentCore team uses A listener rule (with jwt-validation) on their ALB An internal ALB and security group, and an app client for the Gateway (client credentials grant, with a scope such as tools/invoke)
AgentCore team Gateway, inbound authorizer, resource policy, optional AWS WAF One Gateway target per API or MCP server A target, plus an OAuth credential provider for a new identity provider

A new operation or tool on an existing target needs no new target: update the OpenAPI spec with UpdateGatewayTarget, or call SynchronizeGatewayTargets for an MCP server. The repository’s build order lists the steps in each account and the values the teams pass to each other.

Prerequisites

  • An organization in AWS Organizations with resource sharing in AWS RAM enabled.
  • AWS Command Line Interface (AWS CLI) 2.37.7 or later, or the AWS SDK for Python (Boto3) 1.43.106 or later, for the certificateConfigurations parameter.
  • For the role that creates Gateway targets: vpc-lattice:GetResourceConfiguration, vpc-lattice:CreateServiceNetworkResourceAssociation, vpc-lattice:GetServiceNetworkResourceAssociation, vpc-lattice:ListServiceNetworkResourceAssociations, and vpc-lattice:AssociateViaAWSService, plus the bedrock-agentcore target actions. Check your service control policies (SCPs) if your organization doesn’t use VPC Lattice today.
  • A firewall in a central inspection VPC attached to the transit gateway with appliance mode enabled.

Key design decisions

The snippets are excerpts from the lab templates and use the lab’s address plan. RGW_NET is the resource gateway subnets (10.0.1.0/24–10.0.3.0/24), TOOL_NET is the tool VPC (10.12.0.0/16), and ALB_NET is the ALB subnets in it.

Decision 1: Put the resource gateway in a dedicated VPC in the network account

Create a dedicated VPC in the network account for the resource gateway, with subnets you don’t share and no central endpoints or backends. Route those subnets to the transit gateway. Keep one resource gateway per trust zone.

ResourceGateway:
  Type: AWS::VpcLattice::ResourceGateway
  Properties:
    Name: hub-resource-gateway
    VpcIdentifier: !Ref ResourceGatewayVpc
    SubnetIds: [!Ref RgwSubnetA, !Ref RgwSubnetB, !Ref RgwSubnetC]
    SecurityGroupIds: [!Ref RgwSg]          # egress 443 to application ranges only
    IpAddressType: IPV4

RgwRouteToTgw:
  Type: AWS::EC2::Route
  Properties:
    RouteTableId: !Ref RgwRouteTable
    DestinationCidrBlock: 10.0.0.0/8        # internal ranges go to the transit gateway
    TransitGatewayId: !Ref Tgw

Used only with AgentCore, the resource gateway consumes one IP address per subnet, so small subnets are enough. Two settings can’t be changed after creation, Ipv4AddressesPerEni and ResourceConfigDnsResolution, so choose them up front. Use Availability Zone IDs that VPC Lattice and your AgentCore features support. The lab layout lists them for us-east-1.

Decision 2: Create one resource configuration per load balancer, and share it through AWS RAM

Point the resource configuration at the internal ALB DNS name and share it with the AgentCore account. Don’t start the name with rcfg-, which VPC Lattice reserves.

ToolsResourceConfig:
  Type: AWS::VpcLattice::ResourceConfiguration
  Properties:
    Name: tools-account-a
    ResourceConfigurationType: SINGLE
    ResourceGatewayId: !Ref ResourceGateway
    ProtocolType: TCP
    PortRanges: ["443"]
    ResourceConfigurationDefinition:
      DnsResource:
        DomainName: internal-tools-alb-1234567890.us-east-1.elb.amazonaws.com
        IpAddressType: IPV4

ShareToAgentCore:
  Type: AWS::RAM::ResourceShare
  Properties:
    Name: agentcore-resource-configs
    AllowExternalPrincipals: false
    Principals: ["<agentcore-account-id>"]
    ResourceArns: [!GetAtt ToolsResourceConfig.Arn]

VPC Lattice delivers the connection to the resource configuration’s domain. AgentCore sends the target URL’s host name (for example tools.example.internal) as the SNI and checks the ALB certificate against it. The certificate’s subject alternative name must match that host name. The host name doesn’t need to resolve in DNS.

For private API Gateway REST APIs, point one resource configuration at the network account’s execute-api interface endpoint. Each API’s target uses its own URL, and each API’s resource policy must allow that endpoint through aws:SourceVpce. In our tests, a second API in another account worked through the same resource configuration with no network change.

Decision 3: Pass only the flows you need through the firewall

Your firewall needs two stateful allows: from the resource gateway subnets to the tool VPC on port 443, and from the ALB subnets to the identity provider’s host name on port 443. Session-based firewalls pass replies of an allowed flow. In the lab we used AWS Network Firewall with strict rule order and the default actions Drop established and Alert established. With these defaults, the firewall drops client-to-server packets that no rule passes, and lets replies through unless a rule drops them. The rule-order notes explain the semantics.

# Policy: RuleOrder STRICT_ORDER, StatefulDefaultActions [aws:drop_established, aws:alert_established]
pass tcp $RGW_NET any -> $TOOL_NET 443 (msg:"resource gateway to tool VPC"; flow:to_server; sid:100001; rev:4;)
pass tls $ALB_NET any -> any 443 (msg:"ALB to identity provider JWKS"; tls.sni; content:"cognito-idp.us-east-1.amazonaws.com"; nocase; startswith; endswith; flow:to_server; sid:100010; rev:2;)

The first rule allows only the resource gateway subnets to reach the tool VPC on port 443. The second allows the ALB to fetch its identity provider’s signing keys (JSON Web Key Set, or JWKS), only from the ALB subnets and only to the identity provider’s host name. The tool VPC needs a default route to the transit gateway for this fetch to reach central egress. If your identity provider isn’t Amazon Cognito, replace the host name. Without this rule, in our tests, the ALB returned HTTP 500 and the agent received MCP invocation failed.

To prove replies cross the firewall, we added a drop rule for the reply direction preceding the pass rule:

drop tcp $TOOL_NET 443 -> $RGW_NET any (msg:"PROOF return path blocked"; flow:to_client; sid:100098; rev:2;)

Tool calls then hung until timeout, and the firewall logged to_client drops for sid 100098. Removing the rule restored the calls. Run the same test on your own firewall.

Decision 4: Validate the tool account’s token on the internal ALB or private API

The tool account keeps its own identity provider (Amazon Cognito in the lab) and creates an app client for the Gateway. Validate that client’s token on every path to the backend.

Internal ALB – Make the listener’s default action a fixed response, and put a jwt-validation action on every rule that forwards. Pin client_id to the Gateway’s app client so that other clients in the same user pool are rejected.

McpRule:
  Type: AWS::ElasticLoadBalancingV2::ListenerRule
  Properties:
    ListenerArn: !Ref Listener                # default action: fixed-response 404
    Priority: 10
    Conditions: [{Field: path-pattern, PathPatternConfig: {Values: [/mcp]}}]
    Actions:
      - Type