Newshot

在中心辐射型网络中通过集中检查将 Amazon Bedrock AgentCore Gateway 连接到私有 API

AI summary

在许多企业中,中心网络团队拥有每个 VPC 和子网,且 VPC 之间的所有流量都必须双向经过中央防火墙。通过 Amazon Bedrock AgentCore Gateway 调用内部 REST API 和 MCP 服务器的智能体也必须满足这两项要求。本文介绍一种同时满足这两项要求的模式:网络团队保留对每个子网的所有权,Gateway 与私有 API、MCP 服务器之间的流量双向经过中央防火墙;文中还说明了 Amazon VPC Lattice 资源网关的放置位置、各部分的归属、六项配置决策以及验证该模式有效的检查方法。

Translation(model translation, not the source's own text)

将 Amazon Bedrock AgentCore Gateway 连接到采用中心辐射型网络和集中检查的私有 API

在许多企业中,中央网络团队拥有每个虚拟私有云(VPC)和子网,VPC 之间的每条流量都必须双向经过中央防火墙。通过 Amazon Bedrock AgentCore Gateway(Amazon Bedrock AgentCore 的一项能力)调用内部 REST API 和 Model Context Protocol(MCP)服务器的 agent,也必须满足这两项要求。Amazon Bedrock AgentCore 是一个平台,可用任意框架或模型大规模构建、连接和优化 agent。

本文展示了一种同时满足这两项要求的模式。网络团队保留对每个子网的所有权,Gateway 与你的私有 API 及 MCP 服务器之间的流量双向经过中央防火墙。文中涵盖:Gateway 用于访问私有目标的 Amazon VPC Lattice resource gateway 应放置在何处;各部分由谁拥有;六项配置决策;以及确认该模式可用的检查。

我们在美国东部(弗吉尼亚北部)AWS 区域(us-east-1)构建并测试了该模式,实验环境包含 AWS Organizations 中的三个成员账户和一个管理账户。AWS CloudFormation 模板、测试脚本、测试证据和参考资料(地址规划、完整验证检查、故障排查、配额)都在配套仓库中。请将该模式作为指南,并根据你自己的账户架构进行调整。

本文使用的术语

  • Resource gateway:Amazon VPC Lattice 进入 VPC 的入口:位于你所选子网中的弹性网络接口(ENI)。后端看到的每个连接的源地址就是它的地址。
  • Resource configuration:一个 VPC Lattice 对象,用于指定 resource gateway 后面的一个后端(此处为内部负载均衡器或 VPC 终端节点 DNS 名称和端口)。你可以通过 AWS Resource Access Manager(AWS RAM)将其共享给其他账户。
  • 托管模式和自管理模式:Gateway 目标的两种私有终端节点选项。在托管模式下,AgentCore 会为你创建 resource gateway。在自管理模式下,你自行创建它,并为目标指定 resource configuration。

何时使用该模式

当以下所有条件都成立时,请使用该模式:

  • 一个网络账户拥有每个 VPC、子网和 AWS Transit Gateway 挂载,并通过 AWS RAM 共享应用子网。
  • 检查 VPC 中的中央防火墙必须检查进出每个 VPC 的流量。
  • 应用团队只管理自己的资源和安全组。

否则,表 1 中的某个选项可能更合适。

表 1:其他选项更合适的场景。

你的环境使用
Gateway 账户可以拥有能够访问你的工具的子网托管模式
Gateway 与工具之间的流量不需要中央检查如文档所述的自管理模式
工具可通过公有终端节点访问标准 Gateway 目标

我们还考虑了在 AgentCore 拥有的子网中使用托管模式、在每个工具 VPC 或中央终端节点 VPC 中放置 resource gateway,以及为每个工具配置面向互联网的负载均衡器和 AWS WAF。备选方案说明文档解释了每种方案为何在这些约束下不适用。

集中检查的设计要求

  • 网络账户拥有每个子网。Gateway 和应用账户只能在通过 AWS RAM 共享给它们的子网中构建。
  • VPC 之间的每条流量都双向经过中央防火墙。检查 VPC 中的中央防火墙会检查 Gateway 与你的私有 API 及 MCP 服务器之间的流量。

文章标题:将 Amazon Bedrock AgentCore Gateway 连接到 hub-and-spoke 网络中的私有 API,并实现集中检查

正文: AgentCore Gateway 通过 VPC Lattice 资源网关访问私有目标,而两种私有端点模式对其的放置方式不同。托管模式将其创建在 Gateway 账户中,这适用于该账户可以拥有其运行所在子网的环境。自管理模式(如文档所述)将其放置在可直接访问后端的子网中,这适用于不要求在 Gateway 与工具之间进行检查的环境。此环境同时需要满足这两个条件,因此该模式采用自管理模式,并做了一处更改。网络账户拥有资源网关,并将其放置在通过 AWS Transit Gateway 路由的子网中,这样每个请求和回复都会经过检查 VPC。

解决方案概述

在网络账户中为资源网关提供其自己的 VPC 和子网。不要共享它们,并让后端远离这些子网。通过中转网关路由它们,以便 VPC 之间的每个请求和回复都经过防火墙。通过 AWS RAM 与 AgentCore 账户共享每个后端的一个资源配置。图 1 展示了账户、VPC 和流量路径。

网络账户拥有每个 VPC 和 VPC Lattice 资源网关;流量双向经过中央防火墙
网络账户拥有每个 VPC 和 VPC Lattice 资源网关;流量双向经过中央防火墙

图 1:网络账户拥有每个 VPC 和资源网关。其他账户仅拥有它们放置在共享子网中的内容。实线双向经过防火墙。步骤编号与以下流量路径一致

流量路径

  • 位于没有互联网路由的共享子网中的代理调用 Gateway URL。Gateway 接口端点上的私有 DNS 在代理的 VPC 内解析该 URL。
  • 如果附加了 AWS WAF,则由其评估请求。Gateway 检查其资源策略和入站 JSON Web Token (JWT),然后选择目标和工具。
  • Gateway 获取工具账户的出站 OAuth 令牌,并通过 VPC Lattice 将请求发送到网络账户中的资源网关。
  • 资源网关子网路由到中转网关,中转网关将流量通过检查 VPC 发送到工具账户的内部 Application Load Balancer (ALB) 或 execute-api 端点。(经过防火墙。)
  • ALB 或 Amazon API Gateway 验证令牌,并将请求转发到后端。
  • 响应以相同方式返回。(经过防火墙。)

在没有 AgentCore 账户中的中转网关连接的情况下,Gateway 流量如何进入网络账户的 VPC?创建目标时,AgentCore 将共享资源配置与其自己的 VPC Lattice 服务网络关联。然后 VPC Lattice 将该服务网络的连接传递到您 VPC 中资源网关的网络接口。AWS 负责该跳转,从那里开始,由您的路由和防火墙接管。

此模式不做什么。在采用之前,请对照您的需求检查这些限制:

  • 无有效载荷检查 – 从 Gateway 到 ALB 的流量是端到端 TLS,并使用 Gateway 验证的证书。防火墙看到的是流元数据和 TLS 服务器名称指示 (SNI),而不是有效载荷。请求内容位于 Gateway、AWS WAF 和 ALB 日志中。
  • 部分环节跳过防火墙 – 代理到接口端点的环节以及 Gateway 到资源网关的环节不经过防火墙。AgentCore 向每个身份提供方发出的令牌请求也不经过。
  • 工具处无最终用户身份 – 使用客户端凭证授予时,到达工具的每个调用都携带 Gateway 的客户端身份。要将调用追溯到调用者,请使用 Gateway 应用程序日志中的入站 JWT 声明。

谁拥有什么

表 2:谁创建什么。

一次性在已连接的 ALB 上新增 API新增 ALB 或工具账户
网络团队资源网关及其 VPC、子网和路由。防火墙规则。从工具 VPC 到中转网关的默认路由,用于 ALB 的签名密钥获取。网关接口终端节点和策略。AWS RAM 共享无向共享中添加一个资源配置。如果范围是新的,则添加防火墙规则
工具团队一个 ALB 证书,其主题备用名称与 AgentCore 团队使用的目标主机名匹配在其 ALB 上添加一个监听器规则(带 jwt-validation)一个内部 ALB 和安全组,以及一个用于网关的应用程序客户端(客户端凭证授权,作用域如 tools/invoke)
AgentCore 团队网关、入站授权方、资源策略、可选的 AWS WAF每个 API 或 MCP 服务器一个网关目标一个目标,以及用于新身份提供商的 OAuth 凭证提供程序

现有目标上的新操作或工具不需要新的目标:使用 UpdateGatewayTarget 更新 OpenAPI 规范,或为 MCP 服务器调用 SynchronizeGatewayTargets。存储库的构建顺序列出了每个账户中的步骤以及团队之间传递的值。

前提条件

  • 在 AWS Organizations 中有一个组织,并在 AWS RAM 中启用了资源共享。
  • AWS Command Line Interface (AWS CLI) 2.37.7 或更高版本,或 AWS SDK for Python (Boto3) 1.43.106 或更高版本,用于 certificateConfigurations 参数。
  • 对于创建 Gateway 目标的角色:vpc-lattice:GetResourceConfiguration、vpc-lattice:CreateServiceNetworkResourceAssociation、vpc-lattice:GetServiceNetworkResourceAssociation、vpc-lattice:ListServiceNetworkResourceAssociations 和 vpc-lattice:AssociateViaAWSService,以及 bedrock-agentcore 目标操作。如果你的组织目前不使用 VPC Lattice,请检查你的服务控制策略(SCPs)。
  • 在连接到中转网关的中央检查 VPC 中有一个启用了设备模式的防火墙。

关键设计决策

这些代码片段摘自实验模板,并使用实验的地址规划。RGW_NET 是资源网关子网(10.0.1.0/24–10.0.3.0/24),TOOL_NET 是工具 VPC(10.12.0.0/16),ALB_NET 是其中的 ALB 子网。

决策 1:将资源网关放在网络账户中的专用 VPC 中

在网络账户中为资源网关创建一个专用 VPC,其子网不共享,也没有中央终端节点或后端。将这些子网路由到中转网关。每个信任区域保留一个资源网关。


        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

      

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 将连接交付到资源配的域名。AgentCore 会把目标 URL 的主机名(例如 tools.example.internal)作为 SNI 发送,并用它校验 ALB 证书。证书的使用者备用名称必须与该主机名匹配。该主机名不需要在 DNS 中解析。

对于私有 API Gateway REST API,将一个资源配指向网络账户的 execute-api 接口终端节点。每个 API 的目标使用各自的 URL,并且每个 API 的资源策略都必须通过 aws:SourceVpce 允许该终端节点。在我们的测试中,另一个账户中的第二个 API 通过同一资源配即可工作,网络无需任何改动。

## 决策 3:只放行你需要的流量通过防火墙

你的防火墙需要两条有状态放行规则:从资源网关子网到工具 VPC 的 443 端口,以及从 ALB 子网到身份提供商主机名的 443 端口。基于会话的防火墙会放行已允许流的回包。在实验中我们使用了 AWS Network Firewall,采用严格规则顺序,并将默认动作设为 Drop established 和 Alert established。在这些默认设置下,防火墙会丢弃没有任何规则放行的客户端到服务端数据包,并放行回包,除非有规则将其丢弃。规则顺序说明中解释了这些语义。

      

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;)


        
第一条规则只允许资源网关子网在 443 端口访问工具 VPC。第二条规则允许 ALB 获取其身份提供商的签名密钥(JSON Web Key Set,即 JWKS),且仅限来自 ALB 子网、仅限发往身份提供商主机名。工具 VPC 需要有一条指向中转网关的默认路由,此获取请求才能到达集中式出口。如果你的身份提供商不是 Amazon Cognito,请替换该主机名。在我们的测试中,缺少这条规则时,ALB 返回 HTTP 500,agent 收到 MCP invocation failed。

为了证明回包确实经过防火墙,我们在放行规则之前添加了一条针对回包方向的丢弃规则:

      

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


        
随后工具调用会一直挂起直到超时,防火墙会为 sid 100098 记录 to_client 方向的丢弃。移除该规则后调用恢复。请在你自己的防火墙上运行同样的测试。

## 决策 4:在内部 ALB 或私有 API 上校验工具账户的令牌

工具账户保留自己的身份提供商(实验中为 Amazon Cognito),并为 Gateway 创建一个应用客户端。在通往后端的每条路径上都校验该客户端的令牌。

内部 ALB —— 将监听器的默认动作设为固定响应,并在每条转发规则上添加 jwt-validation 动作。将 client_id 固定为 Gateway 的应用客户端,这样同一用户池中的其他客户端都会被拒绝。

      

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: jwt-validation

Order: 1 JwtValidationConfig: Issuer: !Sub https://cognito-idp.${AWS::Region}.amazonaws.com/${ToolPool} JwksEndpoint: !Sub https://cognito-idp.${AWS::Region}.amazonaws.com/${ToolPool}/.well-known/jwks.json AdditionalClaims:

  • {Format: space-separated-values, Name: scope, Values: [tools/invoke]}
  • {Format: single-string, Name: client_id, Values: [!Ref GatewayAppClient]}
  • Type: forward

Order:

agentcore.create_gateway_target( gatewayIdentifier="<gateway-id>", name="classifier", targetConfiguration={"mcp": {"mcpServer": {"endpoint": "https://tools.example.internal/mcp"}}}, credentialProviderConfigurations=[{ "credentialProviderType": "OAUTH", "credentialProvider": {"oauthCredentialProvider": { "providerArn": "<oauth-provider-arn>", "scopes": ["tools/invoke"], "grantType": "CLIENT_CREDENTIALS"}}}],

通过网络账户通过 AWS RAM 共享

privateEndpoint={"selfManagedLatticeResource": { "resourceConfigurationIdentifier": "<shared-resource-configuration-arn>"}},

信任签发 ALB 证书的私有 CA

certificateConfigurations=[{"secretsManager": {"secretArn": "<ca-secret-arn>"}}], )


        
OpenAPI 目标使用相同的块,只是用 openApiSchema 代替 mcpServer。要轮换 CA,请更新密钥并调用 UpdateGatewayTarget。已打开的连接最多可以继续使用旧的信任材料 15 分钟。

让 Gateway 成为共享资源配置的唯一使用者。AWS RAM 的 AWS 托管权限还授予了 ec2:CreateVpcEndpoint,因此 AgentCore 账户可以通过自己的资源 VPC 端点或服务网络访问后端。客户托管权限无法解决这个问题:AWS RAM 会拒绝其中的 vpc-lattice:AssociateViaAWSService,而没有它 Gateway 目标会失败。改为在 AgentCore 账户上附加 SCP:

      

{"Version": "2012-10-17", "Statement": [ {"Sid": "NoOwnEndpointsToSharedResourceConfigurations", "Effect": "Deny", "Action": "ec2:CreateVpcEndpoint", "Resource": "arn:aws:vpc-lattice:::resourceconfiguration/"}, {"Sid": "ServiceNetworkAssociationsOnlyThroughAwsServices", "Effect": "Deny", "Action": "vpc-lattice:CreateServiceNetworkResourceAssociation", "Resource": "", "Condition": {"BoolIfExists": {"aws:ViaAWSService": "false"}}}]}


        
有了这个 SCP,我们创建资源 VPC 端点及其自己的服务网络关联的尝试被拒绝了,而新的 Gateway 目标仍然达到了 READY 状态。SCP 不适用于管理账户,所以不要在那里运行 AgentCore。在网络账户中,使用匹配 AWS CloudTrail 事件 CreateServiceNetworkResourceAssociationBySharee 的 Amazon EventBridge 规则对意外关联发出告警。

撤销访问时,先删除 Gateway 目标(或服务网络资源关联),然后从共享中移除资源配置。仅从共享中移除不会删除现有的关联。

## 决策 6:私有访问 Gateway,并关闭公共端点

在共享的 agent VPC 中创建 Gateway 接口端点并启用私有 DNS,然后附加一个列出已批准 Gateway 的端点策略。主体必须是 *,因为 Gateway 使用持有者令牌对调用方进行身份验证。Resource 列表才是控制点。

      

{"Version": "2012-10-17", "Statement": [{"Effect": "Allow", "Principal": "*", "Action": "bedrock-agentcore:InvokeGateway", "Resource": ["arn:aws:bedrock-agentcore:us-east-1:<agentcore-account-id>:gateway/<gateway-id>"]}]}

在我们的测试中,通过同一端点调用的第二个 Gateway 返回了 JSON-RPC 错误 -32002 Insufficient permissions,但仍然在其公共端点上做出了响应。

接口端点不会关闭 Gateway 的公共端点。附加一个资源策略,仅当 aws:SourceVpce 是你的端点时才允许 bedrock-agentcore:InvokeGateway,否则拒绝(完整策略在仓库中)。在我们的测试中,应用后约 30 秒,互联网调用返回了 -32002,而端点调用继续正常工作。AWS 指出策略变更最多可能需要 15 分钟。

没有互联网路由的 agent 仍然需要其入站 JWT。为它提供一条通往其身份提供方令牌端点的路径,例如通往中转网关的路由,以及一条作用域类似于决策 3 中 JWKS 规则的防火墙规则。或者,使用私有身份提供方。

在你的环境中验证该模式

在依赖该模式之前,请在你的网络账户的非生产副本中,使用你自己的防火墙运行这些检查。完整的 14 项检查列表、每项检查的运行方式以及我们观察到的结果都在仓库中,同时还附有每一跳的日志来源。

  • 请求来自资源网关 – ALB 访问日志显示源 IP 位于资源网关范围内(或者,如果防火墙应用了源 NAT,则位于防火墙范围内)。
  • 请求穿过防火墙 – 防火墙流日志显示从资源网关地址到工具账户 443 端口的 TLS 流。
  • 回复穿过防火墙 – 在回复方向丢弃规则到位的情况下(决策 3),调用失败,防火墙记录 to_client 丢弃。
  • ALB 和私有 API 是令牌边界 – 没有令牌或使用其他客户端令牌的目标会收到 HTTP 401,且后端不会被调用。
  • 公有 Gateway 端点已关闭 – 附加资源策略后,互联网调用会收到 -32002,而端点调用成功。

如果某项检查失败,或者 agent 收到通用错误,故障排查指南会将每个症状映射到显示原因的日志。

注意事项

  • 成本:每个 VPC Lattice 服务网络资源关联都会产生每小时费用加上数据处理费用。参见 VPC Lattice 定价。按每个目标一个关联来规划。要查看你的目标创建了多少个关联,请比较 GetGatewayTarget 为每个目标返回的 resourceAssociationArn,并优先选择每个 API 或 MCP 服务器一个目标,而不是许多小目标。
  • 到公有端点的流量:有三种调用离开私有路径:ALB 的 JWKS 获取、agent 的入站令牌请求,以及 AgentCore 到每个身份提供方的出站 OAuth 令牌请求。
  • 账户布局和配额:Gateway 工具调用配额既按账户也按网关应用。每个环境使用一个 AgentCore 账户,并在达到限制之前按域或 agent 组拆分网关。VPC Lattice 会关闭空闲连接,因此对长期运行的 MCP 流使用 keepalive。仓库列出了其他配额。
  • 我们测试的范围:我们使用了 AWS Network Firewall,没有源 NAT,且仅限 us-east-1。源 NAT、多区域、私有身份提供方以及 OpenAPI 限制在其他注意事项中有所涵盖。

结论

当你的网络团队拥有每个子网,且 VPC 之间的每条流都必须经过中央防火墙时,将 VPC Lattice 资源网关放在网络账户中,并通过中转网关路由其子网。网络团队只需设置一次入口点,并为每个后端负载均衡器添加一个资源配置。应用团队继续只拥有其负载均衡器、安全组、身份提供方和 Gateway 目标,AWS WAF 从每个工具的公有负载均衡器转移到 Gateway。在依赖该模式之前,请在你自己的环境中运行验证检查。

关于作者

The translation is machine-generated and individual terms may be off. Nothing is rewritten or cut; the original is authoritative.

Published by AWS Machine Learning
This site only summarises and aggregates; copyright stays with the original author. Headlines and summaries follow the source — where they differ, the original wins.
Read the original ↗