Add Custom Domain Support to API Gateway with ACM Certificate

[yuki5155]

Description

We need to add custom domain functionality to our existing API Gateway configuration in our AWS SAM template. This will allow us to use a custom domain name for our API instead of the default AWS-provided URL. Additionally, we'll create an SSL/TLS certificate using AWS Certificate Manager (ACM) within the same template.

Current State

Our current template.yaml file defines an API Gateway (ApiGatewayApi) using AWS SAM, but it doesn't include any custom domain configuration or SSL/TLS certificate.

Proposed Changes

1. Add a new parameter to the template:

   • CustomDomainName: To specify the custom domain name

2. Create new resources in the template:

   • Certificate: To create an ACM certificate for the custom domain
   • ApiGatewayCustomDomain: To set up the custom domain
   • ApiGatewayBasePathMapping: To link the API stage to the custom domain

3. Add new outputs to provide information about the custom domain configuration and certificate

Implementation Details

Here's a snippet of the changes to be made to template.yaml:

Parameters:
  # ... (existing parameters)
  CustomDomainName:
    Type: String
    Description: Custom domain name for the API (e.g., api.example.com)

Resources:
  # ... (existing resources)
  Certificate:
    Type: AWS::CertificateManager::Certificate
    Properties:
      DomainName: !Ref CustomDomainName
      ValidationMethod: DNS

  ApiGatewayCustomDomain:
    Type: AWS::ApiGateway::DomainName
    Properties:
      DomainName: !Ref CustomDomainName
      CertificateArn: !Ref Certificate

  ApiGatewayBasePathMapping:
    Type: AWS::ApiGateway::BasePathMapping
    Properties:
      DomainName: !Ref ApiGatewayCustomDomain
      RestApiId: !Ref ApiGatewayApi
      Stage: Prod

Outputs:
  # ... (existing outputs)
  ApiGatewayCustomDomainName:
    Description: Custom domain name for the API
    Value: !Ref ApiGatewayCustomDomain
  ApiGatewayCustomDomainTarget:
    Description: Target domain name for DNS configuration
    Value: !GetAtt ApiGatewayCustomDomain.DistributionDomainName
  CertificateArn:
    Description: ARN of the created ACM Certificate
    Value: !Ref Certificate

Tasks

• [x] Update template.yaml with new parameter, resources, and outputs
• [x] Update the Makefile to include a custom domain parameter for the sam deploy command
• [x] Test the updated template by deploying to a test environment
• [x] Update deployment documentation to include steps for providing custom domain
• [x] Add instructions for completing DNS validation for the ACM certificate
• [x] Add instructions for configuring DNS settings post-deployment
• [ ] Add API tests
• [ ] update the readme to explain changes of makefile, especially about deploy
• [ ] note changes to CHANGELOG.md

Additional Notes

• The certificate uses DNS validation. When you create the stack, ACM will generate DNS records that you need to add to your domain's DNS configuration to validate ownership of the domain.
• Certificate creation and validation can take some time (sometimes up to 30 minutes or more). Stack creation might seem to hang during this process, but it's normal.
• If the domain validation is not completed within 72 hours, the certificate request will time out, and you'll need to delete the stack and try again.
• Ensure you have the necessary permissions to create ACM certificates in your AWS account.

Deployment Steps

1. Deploy the stack, providing the value for CustomDomainName (e.g., api.example.com).
2. After deployment starts, go to the ACM console and find the newly created certificate.
3. In the certificate details, you'll find the DNS records needed for validation. Add these to your domain's DNS configuration.
4. Wait for the validation to complete and the stack to finish creating.
5. Once done, create a CNAME record for your custom domain pointing to the value of ApiGatewayCustomDomainTarget in the stack outputs.