Domains and TLS certificates

Overview

Stacktape allows you to connect your custom domain names to some of your resources (Web Service, HTTP API Gateways, Application Load Balancers and Buckets with CDNs).

Connecting a custom domain to the resource does 2 things:

Creates DNS records:
- If you use your custom domain with a resource, Stacktape automatically creates a DNS record (during deploy) pointing the specified domain name to the resource.
Adds TLS certificates
- If the origin resource (HTTP API Gateway, Application Load Balancer or CDN) uses HTTPS protocol, Stacktape takes care of issuing and attaching correct (free, AWS-managed) certificate to the resource. This means, you do not have to deal with TLS termination as it is handled by the connected resource.
- If you want to use your own certificates, you can configure customCertificateArns.

To manage a custom domain, it first needs to be added to your AWS account. This means that a hosted zone (collection of records managed together for a given domain) for your domain exists in your AWS account and your domain registrar's name servers are pointing to it. To learn more, refer to Adding a domain guide.

Under the hood

For managing domains and their DNS records, Stacktape uses AWS Route 53. You can also easily buy domain through Route 53 AWS console. SSL/TLS certificates for domains are generated using AWS Certificate Manager(ACM)(free of charge).

Adding domain

To use domain and its subdomains with your Stacktape resources (Web Services, Hosting Buckets, HTTP Api Gateways, Application Load Balancers and CDNs), your domain's (i.e example.com) DNS records must be in control of your AWS account. This means that the DNS records for the domain must be managed in Route53(AWS DNS Service) hosted zone.

Stacktape offers domain:add command which provides an easy and interactive way of preparing/adding your domain to be used with Stacktape.

During the process of adding domain:

Hosted zone is created in your AWS account (if not already present). If you registered the domain through your AWS account, the hosted zone was already created.
Free TLS certificates are generated for your domain in the chosen region. If you want to connect the domain to your CDN, the certificates also need to be created in the us-east-1 region ("root" region for the "global" CDN resource).

Throughout the whole process, the domain:add command will print information and guide you through the required steps.

After domain is successfully added and prepared to be used with Stacktape, output of the command should look something like this:

(Optional) Enabling domain for SES

During the domain:add command, Stacktape will ask you if you wish to verify your domain for use with SES. This will enable you to send automated emails from you AWS apps from addresses under your domain.

You can decline this option and continue using your domains without any restrictions. If you wish to activate this option sometimes in the future, simply rerun domain:add command.

Migrating existing domain

If you already have a domain which is currently managed by a third-party provider (not AWS), domain:add command will inform you, you need to perform additional steps.

This output means that you need to manually change your domain registrar's name server records to point to the hosted zone created in you AWS account. This can be usually easily done in your domain registrar's console UI (note that it can take up to multiple days until this change is propagated).

Make sure to migrate all your existing DNS records into your new hosted zone before changing name server records!

If your domain is actively in use, you should be careful and refer to this AWS guide before migrating the domain.

Connecting custom domains to other resources

To connect the domain to a supported resource, use the customDomains property.

To learn more, refer to the docs of these resources:

Web Services
Hosting Buckets
HTTP Api Gateways (or with CDN)
Application Load Balancers (or with CDN)
Buckets with CDN

Using subdomains

Stacktape also allows your to configure subdomains. You can connect your domain to any number of resources.

The subdomain can also be interpolated, for example based on the the specified stage.


Copy
resources:
  myHttpApi:
    type: 'http-api-gateway'
    properties:
      customDomains:
        - domainName: $Format('{}.mydomain.com', $Stage())