How can I use a SAW runbook to troubleshoot my custom domain name in API Gateway?

Short description

The AWSSupport-TroubleshootAPIGatewayCustomDomainConfig runbook provides an automated solution to verify your custom domain name configuration in API Gateway. This runbook verifies that the custom domain name is set up in API Gateway with correct configurations for the DNS record and API mappings.

For more information on SAW, see AWS Support Automation Workflows (SAW).

Resolution

The AWSSupport-TroubleshootAPIGatewayCustomDomainConfig runbook validates the following characteristics:

• Whether the custom domain name exists in API Gateway.
• Whether mappings exist between the custom domain name and any APIs.
• Whether the previous mappings list contains a mapping between the custom domain name and the specified APIs.
• Whether there's an existing DNS record for the custom domain name.
• Whether the DNS record points to the correct target value as generated by API Gateway during the creation of the custom domain name.

The current user or assumed AWS Identity and Access Management (IAM) service role that runs the automation must have the following permissions:

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

Prerequisites

Before running the runbook, make sure that your IAM user or role has the correct permissions. These permissions include specific AWS Systems Manager permissions and the additional services-specific permissions covered in earlier sections of this article.

Run the AWSSupport-TroubleshootAPIGatewayCustomDomainConfig automation

1. Open the AWSSupport-TroubleshootAPIGatewayCustomDomainConfig runbook.
   Note: The runbook is in the us-east-1 AWS Region.

2. Select Execute automation.

   For input parameters, enter the following:

   • AutomationAssumeRole (optional): The Amazon Resource Name (ARN) of the IAM role that allows Automation, a capability of Systems Manager, to perform the actions on your behalf. If no role is specified, then Automation uses the permissions of the user that starts the runbook.
   • DomainName (required): Your API's custom domain name.
   • ApiId (required): Your API's ID.
   • DNSServerIp (optional): A DNS server to resolve the custom domain name. When the value isn't specified, AWS DNS Server is used.
   • HostedZoneId (optional): The ID for the public hosted zone that contains the DNS record for the custom domain name. This isn't required when Route 53 isn't used for DNS.

3. Select Execute. The automation initiates.

4. After the automation finishes, review the Outputs section for detailed results.

   If the runbook checks run successfully, then your output shows the custom domain name's configuration details.

   If the custom domain name's configuration doesn't pass one of the checks within the runbook, then the runbook fails at the appropriate step. Troubleshooting recommendations are available in the runbook's output.

Example outputs for the AWSSupport-TroubleshootAPIGatewayCustomDomainConfig runbook

Example output for successful configuration checks:

{
  "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"
    ]
  }
}

Example output for when the custom domain name isn't in 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/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 "

Example output for when the custom domain name has no mappings at all:

" 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 "

Example output for when the custom domain name has no mapping to the specified 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 "

Example output for when there's no DNS record for the custom domain name:

" 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 "

Example output for when the DNS record isn't pointing to the correct target:

" 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."

Note: To help you troubleshoot, remediate, manage, and reduce costs on your AWS resources, AWS Support maintains a subset of the AWS provided predefined runbooks. The runbook prefixes are AWSSupport- and AWSPremiumSupport-.

Related information

Run an automation

Setting up Automation