How to Configure AWS Custom Domain with ECS Express Mode in CloudFormation

Select Language:

If you’re setting up a REST API using ECS Express Mode and CloudFormation, you might run into a few challenges, especially when it comes to customizing your load balancer or adding a custom domain. Here’s a simple guide to help you get everything working smoothly.

First, you’ll want to create your ECS Express Mode task through a CloudFormation template. Your resource definition might look something like this:

yaml
Resources:
ApiService:
Type: AWS::ECS::ExpressGatewayService
Properties:
ExecutionRoleArn: !GetAtt ApiServiceExecutionRole.Arn
InfrastructureRoleArn: !GetAtt ApiServiceInfrastructureRole.Arn
PrimaryContainer:
Image: !Ref ApiImage

This sets up the core express mode service. To add a custom domain, like pointing your API to api-staging.auto-trust.com, the official guide recommends modifying the load balancer settings in the console. Unfortunately, CloudFormation doesn’t yet support direct configuration of load balancer custom domains for Express Mode services.

However, you can work around this by creating a DNS record manually using Route53. Here’s how you can do that in CloudFormation:

yaml
Resources:
ApiDnsRecord:
Type: AWS::Route53::RecordSet
Properties:
HostedZoneId: ZONEID
Type: CNAME
TTL: 900
Name: api-staging.auto-trust.com
ResourceRecords:

!GetAtt ApiService.Endpoint

Replace ZONEID with your actual hosted zone ID. This setup creates a CNAME record pointing your domain to the API endpoint.

That said, some users have found that Express Mode currently doesn’t support all the features needed for seamless custom domain setup directly through CloudFormation. As noted in a recent blog, support for configuring custom domains in Express Mode is limited right now.

If you need full control over custom domains and load balancer settings, your best bet is to set up a separate Application Load Balancer outside of Express Mode and manage your domain routing there. This approach offers more flexibility but adds some complexity.

In the meantime, keep an eye on AWS updates and community contributions. Many developers are requesting similar features, so support for this may improve soon. Until then, using Route53 records and external load balancers is a reliable way to point your API to custom domains with CloudFormation.