使用 AWS CLI apigatewayv2 create-vpc-link 为 HTTP API 创建 VPC Link 完整指南【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli导读本文以 AWS CLI 官方示例 create-vpc-link.rst 为核心骨架系统讲解如何通过aws apigatewayv2 create-vpc-link命令为 API Gateway HTTP API 创建 VPC Link私有网络连接并完整覆盖配套的查询、更新、删除与集成使用流程。读完本文你将掌握 VPC Link 的完整生命周期管理命令、每个参数与输出字段的准确含义、VPC Link 在 HTTP API 私有集成中的接线方式以及底层 API 模型service-2.json对状态机与字段约束的权威定义。什么是 VPC Link为什么 HTTP API 需要它VPC Link 是 API Gateway 提供的一种网络连接资源。它把 API Gateway 与用户 VPCVirtual Private Cloud虚拟私有云内部署的、没有公网 IP 的私有资源例如 Application Load Balancer、NLB、ECS 服务或 EC2 实例安全地打通。当你的 HTTP API 需要代理转发到 VPC 内的后端时集成类型必须选择VPC_LINK并引用一个已经创建好的 VPC Link 作为连接通道从而避免让私有后端暴露到公网。在 AWS CLI 的 HTTP APIapigatewayv2命令体系中VPC Link 相关的命令共有五个完整覆盖资源的创建与生命周期管理命令作用示例文档create-vpc-link创建 VPC Linkcreate-vpc-link.rstget-vpc-link查询单个 VPC Link 详情get-vpc-link.rstget-vpc-links分页列出当前账号下的全部 VPC Linkget-vpc-links.rstupdate-vpc-link更新 VPC Link仅能改名update-vpc-link.rstdelete-vpc-link删除 VPC Linkdelete-vpc-link.rst创建 VPC Link 的前提条件在执行create-vpc-link之前你需要准备以下资源一个 VPCVPC Link 将关联到该 VPC 内的网络资源。至少一个子网Subnet--subnet-ids是必填参数。API Gateway 会在这些子网中预置弹性网络接口ENI子网必须至少有两个可用区AZ以保证高可用且所在可用区需支持 API Gateway 的服务化集成。安全组Security Group--security-group-ids为选填但生产环境强烈建议显式指定。安全组用于控制 VPC Link 的 ENI 与后端资源之间的流量放行规则。这些子网与安全组 ID 可以通过aws ec2 describe-subnets、aws ec2 describe-security-groups提前获取命令返回的SubnetId与GroupId直接作为本命令的参数值。核心命令create-vpc-link官方示例 create-vpc-link.rst 给出了最直接的创建方式aws apigatewayv2 create-vpc-link \ --name MyVpcLink \ --subnet-ids subnet-aaaa subnet-bbbb \ --security-group-ids sg1234 sg5678对应的成功输出创建后 VPC Link 处于PENDING状态{ CreatedDate: 2020-04-07T00:11:46Z, Name: MyVpcLink, SecurityGroupIds: [ sg1234, sg5678 ], SubnetIds: [ subnet-aaaa, subnet-bbbb ], Tags: {}, VpcLinkId: abcd123, VpcLinkStatus: PENDING, VpcLinkStatusMessage: VPC link is provisioning ENIs, VpcLinkVersion: V2 }参数逐项详解对照仓库中的服务模型定义 service-2.jsonCreateVpcLinkRequest结构各参数的约束如下参数是否必填类型与约束说明--name是字符串长度 1128StringWithLengthBetween1And128VPC Link 的名称用于在控制台与命令中识别资源--subnet-ids是字符串列表SubnetIdList要纳入 VPC Link 的子网 IDAPI Gateway 将在此预置 ENI--security-group-ids否字符串列表SecurityGroupIdListVPC Link 关联的安全组 ID控制到后端流量的访问策略--tags否键值映射Tagsvalue 长度 11600资源标签便于成本分摊与资源管理从模型定义中可以确认SubnetIds与Name是两个必填字段CreateVpcLinkRequest的required列表而安全组与标签均可省略。输出字段解读create-vpc-link返回的就是完整的 VpcLink 资源对象VpcLink结构关键字段含义VpcLinkIdVPC Link 的唯一 ID后续get-vpc-link、update-vpc-link、delete-vpc-link以及集成接线都要以它为标识。VpcLinkStatus当前状态。模型VpcLinkStatus枚举定义了五种状态PENDING、AVAILABLE、DELETING、FAILED、INACTIVE。VpcLinkStatusMessage状态说明。例如示例中的VPC link is provisioning ENIs表示 API Gateway 正在子网中预置弹性网络接口这是PENDING阶段的典型行为。VpcLinkVersionVPC Link 版本。模型VpcLinkVersion枚举当前仅定义了V2一个取值示例输出也返回V2。CreatedDate创建时间戳ISO 8601 格式。注意示例输出中的VpcLinkStatus是PENDING而不是AVAILABLE创建是异步操作返回201表示请求已受理、资源已创建但网络通道仍在预置中。只有状态变为AVAILABLE示例中get-vpc-link返回的状态消息为VPC link is ready to route traffic之后VPC Link 才能被用于真实流量转发。查询 VPC Linkget-vpc-link 与 get-vpc-links查询单个 VPC Link使用 get-vpc-link.rst 中的示例按 ID 查询详情aws apigatewayv2 get-vpc-link \ --vpc-link-id abcd123输出{ CreatedDate: 2020-04-07T00:27:47Z, Name: MyVpcLink, SecurityGroupIds: [ sg1234, sg5678 ], SubnetIds: [ subnet-aaaa, subnet-bbbb ], Tags: {}, VpcLinkId: abcd123, VpcLinkStatus: AVAILABLE, VpcLinkStatusMessage: VPC link is ready to route traffic, VpcLinkVersion: V2 }创建完成后用get-vpc-link轮询状态是常见的运维手法当VpcLinkStatus从PENDING变为AVAILABLE且状态消息变为VPC link is ready to route traffic时说明通道已就绪。若状态变为FAILED可结合VpcLinkStatusMessage的失败原因排查子网可用区、安全组规则或后端配置问题。列出全部 VPC Link支持分页使用 get-vpc-links.rst 中的示例aws apigatewayv2 get-vpc-links输出{ Items: [ { CreatedDate: 2020-04-07T00:27:47Z, Name: MyVpcLink, SecurityGroupIds: [sg1234, sg5678], SubnetIds: [subnet-aaaa, subnet-bbbb], Tags: {}, VpcLinkId: abcd123, VpcLinkStatus: AVAILABLE, VpcLinkStatusMessage: VPC link is ready to route traffic, VpcLinkVersion: V2 }, { CreatedDate: 2020-04-07T00:27:47Z, Name: MyOtherVpcLink, SecurityGroupIds: [sg1234, sg5678], SubnetIds: [subnet-aaaa, subnet-bbbb], Tags: {}, VpcLinkId: abcd456, VpcLinkStatus: AVAILABLE, VpcLinkStatusMessage: VPC link is ready to route traffic, VpcLinkVersion: V2 } ] }从模型定义GetVpcLinksRequest/GetVpcLinksResponse可知该接口支持两个可选分页参数--max-results单次返回的最大元素数量--next-token上一页返回的NextToken用于获取下一页。例如aws apigatewayv2 get-vpc-links \ --max-results 10 \ --next-token 上页返回的NextToken当 VPC Link 数量较多时响应体中的NextToken字段用于翻页NextToken仅在集合非末页时有效。更新 VPC Link注意只能改名与 REST APIapigateway v1的update-vpc-link通过--patch-operations灵活打补丁不同见 apigateway 示例 update-vpc-link.rstHTTP APIapigatewayv2的更新能力非常有限。使用 update-vpc-link.rst 中的示例aws apigatewayv2 update-vpc-link \ --vpc-link-id abcd123 \ --name MyUpdatedVpcLink输出{ CreatedDate: 2020-04-07T00:27:47Z, Name: MyUpdatedVpcLink, SecurityGroupIds: [sg1234, sg5678], SubnetIds: [subnet-aaaa, subnet-bbbb], Tags: {}, VpcLinkId: abcd123, VpcLinkStatus: AVAILABLE, VpcLinkStatusMessage: VPC link is ready to route traffic, VpcLinkVersion: V2 }从模型定义UpdateVpcLinkRequest看该接口的请求体只接受Name一个可变字段VpcLinkId作为 URI 路径参数location: uri定位资源。因此创建完成后不能修改 VPC Link 的子网或安全组如需更换子网或安全组必须删除后重新创建update-vpc-link仅用于重命名这也是官方示例标题 updates the name of a VPC link 的直接含义。删除 VPC Link使用 delete-vpc-link.rst 中的示例aws apigatewayv2 delete-vpc-link \ --vpc-link-id abcd123该命令不产生任何输出This command produces no output.。从模型看DeleteVpcLinkRequest仅包含作为 URI 参数的VpcLinkIdHTTP 层面对应DELETE /v2/vpclinks/{vpcLinkId}返回202表示删除请求已受理、异步执行。删除后该 VPC Link 即不可再被集成引用引用它的既有集成将失效因此建议先解除相关集成的依赖再执行删除。让 VPC Link 真正生效接入 HTTP API 私有集成创建 VPC Link 本身只是准备了一条私有通道真正使用它需要把 HTTP API 的集成Integration接到这条通道上。在 create-integration.rst 中普通集成的--connection-type为INTERNET默认值走公网而私有集成的关键就在于ConnectionType枚举值VPC_LINK。在服务模型 service-2.json 中CreateIntegrationRequest对这两个字段的定义明确写道ConnectionTypeSpecify INTERNET for connections through the public routable internet or VPC_LINK for private connections between API Gateway and resources in a VPC. The default value is INTERNET.ConnectionIdThe ID of the VPC link for a private integration.Supported only for HTTP APIs.因此接入 VPC Link 的典型命令如下aws apigatewayv2 create-integration \ --api-id a1b2c3d4 \ --integration-type HTTP_PROXY \ --connection-type VPC_LINK \ --connection-id abcd123 \ --integration-uri http://internal-alb-1234567890.us-west-2.elb.amazonaws.com \ --payload-format-version 2.0其中--connection-id填的就是前面create-vpc-link返回的VpcLinkId示例中的abcd123。整体链路为HTTP API 路由 → 集成VPC_LINK→ VPC Link → VPC 内的 ALB/NLB/ECS 等私有后端。底层 API 模型与错误处理命令背后的 HTTP 语义从 service-2.json 的operations定义可看到每条 CLI 命令对应的底层 REST 语义操作HTTP 方法与路径成功响应码CreateVpcLinkPOST /v2/vpclinks201GetVpcLinkGET /v2/vpclinks/{vpcLinkId}200GetVpcLinksGET /v2/vpclinks200UpdateVpcLinkPATCH /v2/vpclinks/{vpcLinkId}200DeleteVpcLinkDELETE /v2/vpclinks/{vpcLinkId}202这解释了为什么delete-vpc-link没有输出删除是202 Accepted语义命令返回即代表受理资源销毁异步进行。常见异常模型定义的errors列表给出了各操作可能抛出的两类核心异常BadRequestException请求参数非法例如子网 ID 不存在、名称超长、子网可用区不受支持。创建与列出接口均可能触发。TooManyRequestsException请求频率超过账户/资源的每秒调用限额触发后应退避重试。NotFoundExceptionget-vpc-link、update-vpc-link、delete-vpc-link在传入的VpcLinkId不存在时返回。实践要点与建议轮询状态再使用创建后 VPC Link 先处于PENDING预置 ENI 阶段务必等到AVAILABLE再接入集成否则集成会引用一个未就绪的通道。子网多可用区为 VPC Link 至少选择两个可用区的子网保障高可用单个可用区的子网可能无法满足 API Gateway 的预置要求。安全组规则前置规划VPC Link 的 ENI 安全组需要放行到后端资源如 ALB、NLB 安全组的入站流量且后端安全组要允许来自该 ENI 的流量否则链路通了也无法访问后端。不可变性约束VPC Link 创建后子网与安全组不可修改设计阶段就应确认好网络拓扑避免后期重建。删除前解除依赖删除 VPC Link 前先确认没有 HTTP API 集成仍以VPC_LINK--connection-id引用它避免破坏线上流量。以上所有命令与字段约束均可对照仓库内的 create-vpc-link.rst 等示例文件与 apigatewayv2 服务模型 进行验证可作为日常编写与排障时的权威参考。【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考