Set Up a Custom Domain Name for API Gateway by CloudFormation

Yoshihiro ITO
2 min readFeb 21, 2020


Today, I will tell you about how to set up a custom domain name for an API in Amazon API Gateway by using Amazon CloudFormation.

To set up custom domain for an API in API Gateway in management console is a bit tricky. However, using CloudFormation removes its complexity and reduce operational mistakes.

Before introducing CloudFormation templates, please assume the following:

  • The API already exists in API Gateway
  • The domain to be used for a custom domain has been created as a host zone in Route 53
  • An SSL certificate for the domain (or sub-domain) to be used for custom domain has been issued in ACM

And the following value are needed.

  • ID of the API in API Gateway
  • Host Zone ID of the domain hosted in Route 53
  • ARN of SSL certificate issued in ACM

The following YAML is the main template of today’s topic.

When you use this template for setting up custom domain name actually, please run the following command. (e.g. in case using for the custom domain name)


$ aws cloudformation deploy --stack-name <your stack name> \
--template-file path/to/template-file.yml \
--parameter-overrides \
AcmArn=<your ACM arn> \ \
ApiId=<your target api id> \
DomainHostZoneId=<your host zone id of Route 53>

If you want to create only CloudFormation change-set, use --no-execute-changeset option.

This topic is a partial excerpt and translation of the following blog post (my blog in Japanese):

API Gateway のカスタムドメインを CloudFormation で設定してみた —