使用CloudFormation配置AWS WebSocket API自定义域名时遇证书错误

问题概述 #

配置AWS WebSocket API Gateway自定义域名时，出现证书不匹配错误。已在ACM中创建对应证书，CloudFormation脚本部署成功，但使用wscat连接时提示域名不在证书SAN列表中，且返回的证书序列号与ACM中创建的不一致。

错误信息 #

$ wscat -c ws.example.com
error: Hostname/IP does not match certificate's altnames: Host: ws.example.com. is not in the cert's altnames: DNS:*.execute-api.us-east-1.amazonaws.com

关联CloudFormation配置 #

WebsocketApi:
  Type: AWS::ApiGatewayV2::Api
  Properties:
    Name: !Sub ${Environment}-ips-ws-api
    ProtocolType: WEBSOCKET
    RouteSelectionExpression: $request.body.action
    ApiKeySelectionExpression: $request.header.x-api-key

WebsocketStage:
  Type: AWS::ApiGatewayV2::Stage
  Properties: 
    ApiId: !Ref WebsocketApi
    Description: Websocket Api Stage
    StageName: base
    AutoDeploy: true

WebsocketDomainName:
  Type: AWS::ApiGatewayV2::DomainName
  Properties:
    DomainName: !Ref WebsocketDomain
    DomainNameConfigurations:
      - CertificateArn: !Ref WebsocketCertificateArn
        SecurityPolicy: TLS_1_2
        EndpointType: REGIONAL

WebsocketDomainMapping:
  Type: AWS::ApiGatewayV2::ApiMapping
  Properties:
    ApiId: !Ref WebsocketApi
    ApiMappingKey: base
    DomainName: !Ref WebsocketDomainName
    Stage: !Ref WebsocketStage

WebsocketDnsRecord:
  Type: AWS::Route53::RecordSet
  Properties:
    HostedZoneId: !Ref HostedZoneId
    Name: !Ref WebsocketDomain
    Type: CNAME
    AliasTarget:
      DNSName: !GetAtt WebsocketDomainName.RegionalDomainName
      EvaluateTargetHealth: false
      HostedZoneId: !GetAtt WebsocketDomainName.RegionalHostedZoneId

排查步骤 #

• 确认ACM证书覆盖范围：检查ACM证书是否包含ws.example.com或泛域名*.example.com，且证书区域与API Gateway端点区域匹配（REGIONAL端点需证书在API部署区域，Edge优化端点需证书在us-east-1）。
• 验证DNS解析：使用nslookup ws.example.com或dig ws.example.com确认解析目标为自定义域名的RegionalDomainName（格式如d-xxxxxx.execute-api.us-east-1.amazonaws.com），而非API默认执行域名。
• 检查域名映射状态：在API Gateway控制台自定义域名页面，确认域名映射已关联到正确的base阶段，状态显示为已部署。
• 确认资源创建顺序：检查WebsocketDomainMapping是否依赖WebsocketStage和WebsocketDomainName，必要时手动添加DependsOn属性确保创建顺序正确。

解决方案 #

1. 修正证书区域：若使用REGIONAL端点，确保ACM证书创建在API部署的同一区域；若为Edge优化端点，证书必须在us-east-1区域。
2. 修复DNS记录：确保Route53的AliasTarget正确指向WebsocketDomainName.RegionalDomainName，建议使用Alias记录而非CNAME，避免DNS缓存问题。
3. 重新部署域名映射：更新CloudFormation资源，确认WebsocketDomainMapping的Stage和ApiMappingKey匹配，或在控制台手动重建域名映射，等待10-15分钟部署完成。
4. 清除本地DNS缓存：运行ipconfig /flushdns（Windows）或sudo dscacheutil -flushcache（Mac），避免旧DNS记录导致连接到默认域名。

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