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. It can be used 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, it can be used 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 in the API. The App Runner console doesn't support it.

When you associate a custom domain with your service, App Runner provides you with a set of CNAME records to add to your Domain Name System (DNS). Add certificate validation records to your DNS. This way, App Runner can validate that you own or control the domain. 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 to amazon.com. Otherwise, ACM can't verify the domain and successfully create your domain.

Note

For auto-renewal of your custom domain certificates, ensure that you do not delete the certificate validation records from your DNS server. For information on how to resolve issues related to the renewal of the certificate, see Custom domain certificate renewal.

For information about how to resolve CAA errors, see:

• 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

In addition, add DNS target records to your DNS 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). At this point, your custom domain is validated, and App Runner starts routing traffic from this domain to your web application.

Note

If you're using Amazon Route 53 as your DNS provider, you can add a subdomain, but support for adding a root domain isn't available at this time.

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

• A root domain – For example, example.com. You can optionally associate www.example.com too as part of the same operation.

• A subdomain – For example, login.example.com or admin.login.example.com. You can optionally associate the www subdomain too as part of the same operation.

• 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.

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. You must delete the records for this domain from your DNS.

App Runner internally creates certificates that track domain validity. They're stored in AWS Certificate Manager (ACM). App Runner doesn't delete these certificates for seven 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

If you're using Amazon Route 53 as your DNS provider, you can add a subdomain, but support for adding a root domain isn't available at this time.

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. Follow the instructions on the Configure DNS page to start the domain validation process. For more information about DNS validation, see DNS Validation in the AWS Certificate Manager User Guide.

   

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.

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, it returns a CustomDomain object 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. It 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, it returns a CustomDomain object that describes the custom domain that's being disassociated from your service. The object shows a DELETING status.