为私有API Gateway配置静态公网CNAME并解决访问及TLS问题

问题原因分析 #

核心问题来自两点：

1. TLS证书不匹配：API Gateway默认TLS证书仅覆盖execute-api.<region>.amazonaws.com域名，自定义CNAME不在证书的SAN（Subject Alternative Name）列表中，导致客户端抛出证书验证错误。
2. Host头校验失败：Private API Gateway会校验请求Host头是否匹配其原生动态域名（${api-id}-${vpc-endpoint-id}.execute-api.<region>.amazonaws.com），自定义CNAME的Host头会被拒绝，因此即使跳过证书校验，也会返回Forbidden或Missing Authentication Token。

可行解决方案：配置API Gateway自定义域名 #

这是最直接满足需求的原生方案，无需额外中间层，客户端使用自定义静态域名即可安全访问，无需指定额外Header。具体步骤如下：

1. 准备TLS证书

   • 在AWS Certificate Manager（ACM）中申请或导入对应自定义域名endpoint.sub.domain.com的证书，证书必须部署在API Gateway所在的AWS区域。

2. 配置API Gateway自定义域名

   • 进入API Gateway控制台，选择「自定义域名」页面，点击「创建」：
     • 域名输入endpoint.sub.domain.com，选择刚才准备的ACM证书；
     • 端点类型选择Regional（适配Private API关联VPC Endpoint的场景，避免Edge-optimized带来的公网路由冗余）；
     • 配置基础路径映射：将路径（如/或业务路径）映射到目标API Gateway实例和对应的阶段（${var.stage}）。
   • 完成配置后，AWS会生成一个API Gateway目标域名（格式类似d-xxxxxxxx.execute-api.<region>.amazonaws.com）。

3. 更新Route53记录

   • 在Route53公网托管区sub.domain.com中，将CNAME记录endpoint.sub.domain.com的目标改为上述API Gateway生成的自定义域名目标地址，而非原API的动态域名。

4. 验证访问

   • 等待DNS解析生效后，直接通过curl https://endpoint.sub.domain.com/${var.stage}/${var.path}访问，此时证书验证通过，API Gateway会正确识别自定义域名的Host头，返回正常响应。

备选方案评估 #

• 服务器302重定向：不符合纯DNS实现的需求，且重定向会改变请求方法（POST请求转为GET），无法适配所有业务场景，排除。
• 配置CloudFront：可行但冗余。需将CloudFront源指向原API Gateway URL，配置自定义证书并在缓存行为中强制设置Host头为原API域名。此方案增加额外CDN层，带来复杂度和成本上升，仅适合需要CDN缓存、WAF等额外能力的场景，否则没必要采用。
• Route53/API Gateway DNS配置：即上述自定义域名方案，是原生、轻量的最优解，完全满足需求。
• 启用VPC私有DNS：会导致VPC内DNS解析强制指向VPC Endpoint，破坏公网API Gateway的访问能力，且多云网络客户端可能不在同一VPC，无法解析私有DNS，排除。

内容的提问来源于stack exchange，提问作者Joshua