How do I troubleshoot API Gateway public custom domain name configuration issues?

Resolution

To troubleshoot API Gateway public custom domain name configuration issues, use the AWSSupport-TroubleshootAPIGatewayCustomDomainConfig runbook. This runbook checks that the public custom domain name is set up in API Gateway with correct configurations for the DNS record and API mappings. If the runbook checks fail, then review the troubleshooting recommendations in the runbook outputs.

Note: This runbook supports public custom domains that are set with the default routing mode API mappings only. This runbook doesn't support custom domains that are set with the routing modes for routing rules or private custom domains.

Prerequisites

Before you start the AWSSupport-TroubleshootAPIGatewayCustomDomainConfig runbook, make sure that your AWS Identify and Access Management (IAM) user or role has 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

Run the AWSSupport-TroubleshootAPIGatewayCustomDomainConfig runbook

Complete the following steps:

1. Open the AWSSupport-TroubleshootAPIGatewayCustomDomainConfig runbook in your AWS Region.
2. Choose Execute automation.
3. For Input parameters, enter the following values:
   AutomationAssumeRole (optional): The Amazon Resource Name (ARN) of the IAM role that allows the automation to perform the actions on your behalf. If you don't specify a role, then the automation uses the permissions of the user that starts the runbook.
   DomainName: Your API's custom domain name.
   ApiId: Your API's ID.
   DNSServerIp (optional): A DNS server to resolve the custom domain name. If you don't specify the value, then the runbook uses AWS DNS Server.
   HostedZoneId (optional): The ID for the public hosted zone that contains the DNS record for the custom domain name. If you don't use Amazon Route 53 for DNS, then leave the HostedZoneId blank.
4. Choose Execute. The automation initiates.
5. Review the Outputs section for detailed results.

The runbook validates the following configurations:

• The custom domain name exists in API Gateway.
• A mappings exist between the custom domain name and any APIs.
• A DNS record exists for the custom domain name.
• The DNS record points to the correct target.

If the runbook checks run successfully, then the output shows the custom domain name's configuration details. If the runbook check fails, then review the troubleshooting recommendations.

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 mappings don't exist:

" 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 doesn't point 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."

Related information

AWS Support Automation Workflows (SAW)

Custom domain name for public REST APIs in API Gateway

Tutorial: Create and invoke a custom domain name for private APIs

How can I set up a public custom domain name for my API Gateway API?