SAW ランブックを使用して API Gateway のカスタムドメイン名のトラブルシューティングを行うにはどうすればよいですか?

所要時間6分

AWSSupport-TroubleshootAPIGatewayCustomDomainConfig AWS Support Automation Workflows (SAW) ランブックを使用して Amazon API Gateway のカスタムドメイン名の設定をトラブルシューティングしたいと考えています。

簡単な説明

AWSSupport-TroubleshootAPIGatewayCustomDomainConfig ランブックには、API Gateway のカスタムドメイン名の設定を検証するためのオートメーションソリューションが用意されています。このランブックでは、API Gateway でカスタムドメイン名が正しい DNS レコードと API マッピングで設定されていることを検証します。

SAW の詳細については、「AWS Support Automation Workflows (SAW)」を参照してください。

解決方法

AWSSupport-TroubleshootAPIGatewayCustomDomainConfig ランブックでは、以下の特徴を検証します:

カスタムドメイン名が API Gateway に存在するかどうか。
カスタムドメイン名と任意の API の間にマッピングが存在するかどうか。
以前のマッピングリストに、カスタムドメイン名と指定した API の間のマッピングが含まれているかどうか。
カスタムドメイン名の既存の DNS レコードがあるかどうか。
DNS レコードが、カスタムドメイン名の作成中に API Gateway によって生成された正しいターゲット値を指しているかどうか。

オートメーションを実行する現在のユーザーまたは引き受ける AWS Identity and Access Management (IAM) サービスロールには、以下のアクセス許可が必要です:

apigateway:GET
iam:ListRoles
iam:PassRole
route53:ListResourceRecordSets
ssm:DescribeAutomationExecutions
ssm:GetAutomationExecution
ssm:DescribeAutomationStepExecutions
ssm:StartAutomationExecution
ssm:DescribeDocument
ssm:GetDocument
ssm:ListDocuments

前提条件

ランブックを実行する前に、IAM のユーザーまたはロールに正しいアクセス許可があることを確認してください。それらのアクセス許可には、特定の AWS Systems Manager のアクセス許可と、本記事内の前出のセクションで説明したサービス固有の追加のアクセス許可が含まれます。

AWSSupport-TroubleshootAPIGatewayCustomDomainConfig オートメーションを実行する

AWSSupport-TroubleshootAPIGatewayCustomDomainConfig ランブックを開きます。
注: このランブックは us-east-1 AWS リージョンにあります。
[オートメーションの実行] を選択します。

入力パラメータに、次の情報を入力します:
- AutomationAssumeRole (オプション): Systems Manager の機能である Automation がユーザーの代わりにアクションを実行できるようにする IAM ロールの Amazon リソースネーム (ARN) を入力します。ロールが指定されない場合、Automation はランブックを起動したユーザーのアクセス許可を使用します。
- DomainName (必須): API のカスタムドメイン名。
- ApiId (必須): API の ID。
- DNSServerIp (オプション): カスタムドメイン名を解決する DNS サーバー。値が指定されない場合は、AWS DNS サーバーが使用されます。
- HostedZoneId (オプション): カスタムドメイン名の DNS レコードを含むパブリックホストゾーンの ID。DNS に Route 53 が使用されていない場合は不要です。
[実行] をクリックします。オートメーションが開始されます。
オートメーションが完了したら、[出力] セクションで詳細な結果を確認します。

ランブックのチェックが正常に実行されると、出力にはカスタムドメイン名の設定の詳細が表示されます。

カスタムドメイン名の設定がランブック内のいずれかのチェックに合格しない場合、ランブックは適切な手順で失敗します。トラブルシューティングの推奨事項については、ランブックの出力を確認してください。

AWSSupport-TroubleshootAPIGatewayCustomDomainConfig ランブックの出力例

設定のチェックが成功した場合の出力例:

{
  "Result": "The custom domain name is configured correctly",
  "DomainDetails": {
    "DomainName": "<<CUSTOM DOMAIN NAME>>",
    "APIGatewayDomainName": "d-XXXXXXXX.execute-api.<<REGION>>.amazonaws.com",
    "Status": "XXXXXX",
    "EndpointType": "XXXXXX"
  },
  "MappingDetails": [
    {
      "API": "XXXXXX",
      "MappingId": "XXXXXX",
      "MappingKey": "XXXXXX",
      "Stage": "XXXXXX",
      "Status": "ApiHasMappings"
    }
  ],
  "DNSDetails": {
    "<<RECORD TYPE>>": [
      "XXX.XXX.XXX.XXX",
      "XXX.XXX.XXX.XXX",
      "XXX.XXX.XXX.XXX"
    ]
  }
}

カスタムドメイン名が API Gateway にない場合の出力例:

" Check (1/5): Check custom domain name exists.
  Status: Failed.

  Troubleshooting Recommendations:
    - Custom domain name: <<CUSTOM DOMAIN NAME>> is not configured in API gateway.
    - Please see the link below for information on how to setup a custom domain for API Gateway:
      > https://aws.amazon.com/jp/premiumsupport/knowledge-center/custom-domain-name-amazon-api-gateway/

    - The remaining checks have not been run at this point hence there may be other errors in the current configuration.
    - After resolving the error above, please check that your custom domain name has:
      > A mapping to the API you are trying to reach
      > A DNS record pointing to the generated API Gateway domain name.

    - You can run this automation again to confirm the changes have been made correctly.
    - More details for this particular error can be found within the individual step details.

  Check (2/5): List mappings.
  Status: Skipped

  Check (3/5): Check mapping exists to API Id: <<API ID>>.
  Status: Skipped

  Check (4/5): Check DNS record exists for custom domain name.
  Status: Skipped

  Check (5/5): Validate DNS record.
  Status: Skipped "

カスタムドメイン名にマッピングがまったくない場合の出力例:

" Check (1/5): Check custom domain name exists.
  Status: Complete

  Check (2/5): List mappings.
  Status: Failed

  Troubleshooting Recommendations:
    - <<CUSTOM DOMAIN NAME>> does not contain any mappings.
    - Please see the documentation to create one here:
      > https://docs.aws.amazon.com/apigateway/latest/developerguide/rest-api-mappings.html

    - The remaining checks have not been run at this point hence there may be other errors in the current configuration.
    - After resolving the error above, please check that your custom domain name has:
      > A mapping to the API you are trying to reach
      > A DNS record pointing to the generated API Gateway domain name.

    - You can run this automation again to confirm the changes have been made correctly.
    - More details for this particular error can be found within the individual step details.

  Check (3/5): Check mapping exists to API Id: <<API ID>>.
  Status: Skipped

  Check (4/5): Check DNS record exists for custom domain name.
  Status: Skipped

  Check (5/5): Validate DNS record.
  Status: Skipped "

カスタムドメイン名が、指定した API ID にマッピングされていない場合の出力例:

" Check (1/5): Check custom domain name exists.
  Status: Complete

  Check (2/5): List mappings.
  Status: Complete

  Check (3/5): Check mapping exists to API Id: <<API ID>>.
  Status: Failed

    Troubleshooting Recommendations:
    - A base path mapping does not exist between API Id: <<API ID>> and custom domain name: <<CUSTOM DOMAIN NAME>>.
    - Please see the documentation to create one here:
      > https://docs.aws.amazon.com/apigateway/latest/developerguide/rest-api-mappings.html

    - The remaining checks have not been run at this point hence there may be other errors in the current configuration.
    - After resolving the error above, please check that your custom domain name has:
      > A mapping to the API you are trying to reach
      > A DNS record pointing to the generated API Gateway domain name.

    - You can run this automation again to confirm the changes have been made correctly.
    - More details for this particular error can be found within the individual step details.

  Check (4/5): Check DNS record exists for custom domain name.
  Status: Not Run

  Check (5/5): Validate DNS record.
  Status: Skipped "

カスタムドメイン名の DNS レコードがない場合の出力例:

" Check (1/5): Check custom domain name exists.
  Status: Complete

  Check (2/5): List mappings.
  Status: Complete

  Check (3/5): Check mapping exists to API Id: <<API ID>>.
  Status: Complete

  Check (4/5): Check DNS record exists for custom domain name.
  Status: Failed

  Troubleshooting Recommendations:
    - There is no DNS record for the custom domain name: <<CUSTOM DOMAIN NAME>> or the domain could not be resolved.
    - Please check your DNS server for a record for this domain and ensure it can be resolved.

    - The remaining checks have not been run at this point hence there may be other errors in the current configuration.
    - After resolving the error above, please check that your custom domain name has:
      > A DNS record pointing to the generated API Gateway domain name.

    - You can run this automation again to confirm the changes have been made correctly.
    - More details for this particular error can be found within the individual step details.


  Check (5/5): Validate DNS record.
  Status: Skipped "

DNS レコードが正しいターゲットを参照していない場合の出力例:

" Check (1/5): Check custom domain name exists.
  Status: Complete

  Check (2/5): List mappings.
  Status: Complete

  Check (3/5): Check mapping exists to API Id: <<API ID>>.
  Status: Complete

  Check (4/5): Check DNS record exists for custom domain name.
  Status: Complete

  Check (5/5): Validate DNS record.
  Status: Failed

  Troubleshooting Recommendations:
    - The DNS record for the custom domain name: <<CUSTOM DOMAIN NAME>> may not be pointing to the correct target.
    - The API Gateway domain name generated for this custom domain name is: <<API GATEWAY DOMAIN NAME>> which should be the target of the DNS record created for the custom domain name.
    - Please check your DNS record for this domain and ensure it is pointing to the API Gateway domain name: <<API GATEWAY DOMAIN NAME>>.

    - After resolving the error above, you can run this automation again to confirm the changes have been made correctly.
    - More details for this particular error can be found within the individual step details."

注: AWS リソースのトラブルシューティング、修正、管理、コスト削減に役立つように、AWS サポートでは AWS が提供する事前定義済みランブックのサブセットを管理しています。ランブックのプレフィックスは AWSSupport- と AWSPremiumSupport- です。