Managing custom domain names for an App Runner service

When you create an AWS App Runner service, App Runner allocates a domain name for it. This is a subdomain in the awsapprunner.com domain that's owned by App Runner. You can use the domain name to access the web application that's running in your service.

If you own a domain name, you can associate it to your App Runner service. After App Runner validates your new domain, you can use your domain to access your application in addition to the App Runner domain. You can associate up to five custom domains.

Note

You can optionally include the www subdomain of your domain. However, this is currently only supported by the API. The App Runner console doesn't support including www subdomain of your domain.

Associate (link) a custom domain to your service

When you associate a custom domain to your service, you must add the CNAME records and DNS target records to your DNS server. The following sections provide information on CNAME records and DNS target records and how to use them.

CNAME records

When you associate a custom domain with your service, App Runner provides you with a set of CNAME records serve for certificate validation purpose. You must add these CNAME records to your Domain Name System (DNS) server. Add the certificate validation records, provided by App Runner, to your DNS server. This way, App Runner can validate that you own or control the domain.

Note

To auto-renew your custom domain certificates, ensure that you don't delete the certificate validation records from your DNS server. For information about how to resolve issues that are related to the renewal of the certificate, see Custom domain certificate renewal.

App Runner uses ACM to verify the domain. If you're using CAA records in your DNS records, make sure that at least one CAA record references amazon.com. Otherwise, ACM can't verify the domain and successfully create your domain.

If you receive errors related to CAA, see the following links to learn how to resolve them:

• Certification Authority Authorization (CAA) problems

• How do I resolve CAA errors for issuing or renewing an ACM certificate?

• Troubleshooting custom domain names for an App Runner service

DNS target records

Add the DNS target records to your DNS server to target the App Runner domain. Add one record for the custom domain, and another for the www subdomain, if you chose this option. Then, wait for the custom domain status to become Active in the App Runner console. This typically takes several minutes, but might take up to 24—48 hours (1—2 days). When your custom domain is validated, App Runner starts routing traffic from this domain to your web application.

Note

For better compatibility with App Runner services, we recommend that you use Amazon Route 53 as your DNS provider. If you don't use Amazon Route 53 to manage your public DNS records, contact your DNS provider to find out how to add records.

If you're using Amazon Route 53 as your DNS provider, you can add either CNAME or alias record for subdomain. For root domain, ensure that you use the alias record.

You can purchase a domain name from Amazon Route 53 or another provider. To purchase a domain name with Amazon Route 53, see Registering a new domain, in the Amazon Route 53 Developer Guide.

For instructions on how to configure a custom domain in Route 53, see Custom domain names Configure an Amazon Route 53 alias record.

Specify a domain to associate with your App Runner service

You can specify a domain to associate with your App Runner service in the following ways:

• A root domain – DNS has some inherent limitations which might block you from creating CNAME records for the root domain name. For example, if your domain name is example.com, you can create a CNAME record that routes traffic for acme.example.com to your App Runner service. However, you can't create a CNAME record that routes traffic for example.com to your App Runner service. To create a root domain, ensure that you add an alias record.

  An alias record is specific to Route 53 and has the following advantages over CNAME records:

  • Route 53 provides you with more flexibility as alias records can be created for root domain or subdomain. For example, if your domain name is example.com, you can create a record that routes requests for example.com or acme.example.com to your App Runner service.

  • It is more cost efficient. This is because Route 53 doesn't charge for requests that use an alias record to route traffic.

• A subdomain – For example, login.example.com or admin.login.example.com. You can optionally also associate the www subdomain as part of the same operation. You can add either CNAME or alias record for subdomain.

• A wildcard – For example, *.example.com. You can't use the www option in this case. You can specify a wildcard only as the immediate subdomain of a root domain and only on its own. These aren't valid specifications: login*.example.com, *.login.example.com. This wildcard specification associates all immediate subdomains, and doesn't associate the root domain itself. The root domain must be associated in a separate operation.

A more specific domain association overrides a less specific one. For example, login.example.com overrides *.example.com. The certificate and CNAME of the more specific association are used.

The following example shows how you can use multiple custom domain associations:

1. Associate example.com with the home page of your service. Enable the www to associate www.example.com.

2. Associate login.example.com with the login page of your service.

3. Associate *.example.com with a custom "not found" page.

Disassociate (unlink) a custom domain

You can disassociate (unlink) a custom domain from your App Runner service. When you unlink a domain, App Runner stops routing traffic from this domain to your web application.

Note

You must delete the records for the domain you disassociated from your DNS server.

App Runner internally creates certificates that track domain validity. These certificates are stored in AWS Certificate Manager (ACM). App Runner doesn't delete these certificates for 7 days after a domain is disassociated from your service or after the service is deleted.

Manage custom domains

Manage custom domains for your App Runner service using one of the following methods:

Note

For better compatibility with App Runner services, we recommend that you use Amazon Route 53 as your DNS provider. If you don't use Amazon Route 53 to manage your public DNS records, contact your DNS provider to find out how to add records.

If you're using Amazon Route 53 as your DNS provider, you can add either CNAME or alias record for subdomain. For root domain, ensure that you use alias record.

App Runner console

To associate (link) a custom domain using the App Runner console

1. Open the App Runner console, and in the Regions list, select your AWS Region.

2. In the navigation pane, choose Services, and then choose your App Runner service.

   The console displays the service dashboard with a Service overview.

   

3. On the service dashboard page, choose the Custom domains tab.

   The console shows the custom domains that are associated with your service, or No custom domains.

   

4. On the Custom domains tab, choose Link domain.

5. In the Link custom domain dialog, enter a domain name, and then choose Link custom domain.

6. Copy the certificate validation records and DNS target records, and add them to your DNS server. App Runner can then validate that you own or control the domain.

   Note

   To auto-renew your custom domain certificates, make sure not to delete the certificate validation records from your DNS server.

   • For more information about Configure certificate validation, see DNS Validation in the AWS Certificate Manager User Guide.

   • For information about how to Configure DNS target with Amazon Route 53 alias record, see Configure Amazon Route 53 alias record for your target DNS.

   

7. Choose Close

   The console shows the dashboard again. The Custom domains tab has a new tile showing the domain that you just linked in the Pending certificate DNS validation status.

   

8. When the domain status changes to Active, verify that the domain works for routing traffic by browsing to it.

   

To disassociate (unlink) a custom domain using the App Runner console

1. On the Custom domains tab, select the tile for the domain you want to disassociate, and then choose Unlink domain.

2. In the Unlink domain dialog, verify the action by choosing Unlink domain.

   Note

   You must delete the records for the domain that you disassociated from your DNS server.

App Runner API or AWS CLI

To associate a custom domain with your service using the App Runner API or AWS CLI, call the AssociateCustomDomain API action. When the call succeeds, a CustomDomain object is returned that describes the custom domain that's being associated with your service. The object shows a CREATING status and contains a list of CertificateValidationRecord objects. The call also returns the target alias that you can use to configure the DNS target. These are records that you can add to your DNS.

To disassociate a custom domain from your service using the App Runner API or AWS CLI, call the DisassociateCustomDomain API action. When the call succeeds, a CustomDomain object is returned that describes the custom domain that's being disassociated from your service. The object shows a DELETING status.