Skip to content

Domain

Load Balanced Web Service

In Copilot, there are two ways to use custom domains for your Load Balanced Web Service:

  1. Use --domain when creating an application to associate a Route 53 domain in the same account.
  2. Use --import-cert-arns to bring your validated ACM certificates when creating an environment.

Attention

Today, a Route 53 domain name can only be associated when running copilot app init.
If you'd like to update your application with a domain (#3045), you'll need to run copilot app delete to remove the old one before creating a new one with --domain to associate a new domain.

Use app-associated root domain

As mentioned in the Application Guide, you can configure the domain name of your app when running copilot app init --domain.

Default domain name for your service

After deploying your Load Balanced Web Services, by default you can access them publicly via

${SvcName}.${EnvName}.${AppName}.${DomainName}

if you are using an Application Load Balancer, or

${SvcName}-nlb.${EnvName}.${AppName}.${DomainName}

if you are using a Network Load Balancer.

For example, https://kudo.test.coolapp.example.aws or kudo-nlb.test.coolapp.example.aws:443.

Customized domain alias

If you don't like the default domain name Copilot assigns to your service, you can set a custom alias for your service by editing your manifest's alias section. The following snippet sets an alias to your service.

# in copilot/{service name}/manifest.yml
http:
  path: '/'
  alias: example.aws

Similarly, if your service is using a Network Load Balancer, you can specify: 

nlb:
  port: 443/tls
  alias: example-v1.aws

However, since we delegate responsibility for the subdomain to Route 53, the alias you specify must be in one of these three hosted zones:

  • root: ${DomainName}
  • app: ${AppName}.${DomainName}
  • env: ${EnvName}.${AppName}.${DomainName}

What happens under the hood?

Under the hood, Copilot

  • creates a hosted zone in your app account for the new app subdomain ${AppName}.${DomainName}
  • creates another hosted zone in your env account for the new env subdomain ${EnvName}.${AppName}.${DomainName}
  • creates and validates an ACM certificate for the env subdomain
  • associates the certificate with:
    • Your HTTPS listener and redirects HTTP traffic to HTTPS, if the alias is used for the Application Load Balancer (http.alias)
    • Your network load balancer's TLS listener, if the alias is for nlb.alias and TLS termination is enabled.
  • creates an optional A record for your alias

What does it look like?

Use domain in your existing validated certificates

If you own a domain outside of Route53 or for compliance reasons want to use an alias from your existing ACM certificates, you can specify the --import-cert-arns flag when creating the environment to import validated ACM certificates that include the alias. For example:

$ copilot env init --import-cert-arns arn:aws:acm:us-east-1:123456789012:certificate/12345678-1234-1234-1234-123456789012

Then, in your service's manifest, you can either:

  1. Specify the ID of the hosted zone into which Copilot should insert the A record: 
    # in copilot/{service name}/manifest.yml
http:
  path: '/'
  alias: example.aws
  hosted_zone: Z0873220N255IR3MTNR4
  2. Deploy the service without the hosted_zone field, then manually add the DNS name of the Application Load Balancer (ALB) created in that environment as an A record where your alias domain is hosted.

We have an example of Option 2 in our blog posts.

Request-Driven Web Service

You can also add a custom domain for your request-driven web service. Similar to Load Balanced Web Service, you can do so by modifying the alias field in your manifest: 

# in copilot/{service name}/manifest.yml
http:
  path: '/'
  alias: web.example.aws

Likewise, your application should have been associated with the domain (e.g. example.aws) in order for your Request-Driven Web Service to use it.

Info

For now, we support only one-level subdomains such as web.example.aws.

Environment-level domains (e.g. web.${envName}.${appName}.example.aws), application-level domains (e.g. web.${appName}.example.aws), or root domains (i.e. example.aws) are not supported yet. This also means that your subdomain shouldn't collide with your application name.

Under the hood, Copilot:

  • associates the domain with your app runner service
  • creates the domain record as well as the validation records in your root domain's hosted zone