Configuring Netlify Custom Subdomain Aliases Without Downtime

Configuring Netlify custom subdomain aliases without downtime requires careful planning of your DNS records and SSL/TLS certificate provisioning before you route live traffic. When you map a subdomain like app.example.com or shop.example.com to a Netlify site, you must coordinate your DNS provider's settings with Netlify's domain management panel to prevent broken links and expired certificates. By understanding the underlying mechanics of CNAME records, apex domains, and automated Let's Encrypt validation, you can achieve a seamless transition with zero interruption for your users.

To verify your current DNS state before making any changes, you can use the CNAME Lookup tool to check existing target pointers and ensure no conflicting records exist on your authoritative nameservers.

Preparing Your Netlify Site for a Custom Subdomain

Before touching your DNS provider, you need to inform Netlify which subdomain aliases your site should accept. Netlify handles routing based on the Host header, so it must explicitly recognize the incoming hostname.

Adding the Domain in the Netlify Dashboard

Log in to your Netlify account, navigate to your site dashboard, and go to Site settings > Domain management > Domains. Under the custom domains section, click Add custom domain. Enter your fully qualified domain name, such as app.example.com.

Netlify will immediately check if the domain is already registered elsewhere on their network. If it is unclaimed, Netlify will add it to your site configuration. At this stage, Netlify will flag the domain with a warning indicating that DNS verification is pending or that the SSL certificate cannot be provisioned yet. This is entirely normal because you have not yet pointed your DNS records to Netlify.

Understanding Netlify Domain Types

Netlify supports two primary ways to attach custom names:

• Subdomains (e.g., blog.example.com, docs.example.com): These use CNAME records pointing to your Netlify site's default subdomain (e.g., your-site-name.netlify.app).
• Apex or Root Domains (e.g., example.com): These traditionally require A records or ALIAS/ANAME records, though Netlify provides load-balanced IP addresses for apex configurations.

For subdomain aliases, a CNAME record is always the industry standard and best practice because it decouples your application routing from specific IP addresses.

Step-by-Step DNS Configuration for Zero Downtime

Achieving zero downtime means ensuring that users are never greeted with a "Site Not Found" or an SSL handshake error during the migration. The key is to prepare the destination, create the DNS record with a low Time to Live (TTL), and provision the SSL certificate before shifting heavy traffic.

Step 1: Set a Low TTL

Log in to your DNS provider (such as Cloudflare, Route 53, GoDaddy, or Namecheap) and locate the zone file for `example.com". Note that interface menus may differ slightly depending on your registrar, but you will generally look for "DNS Manager", "Zone Editor", or "Advanced DNS".

If you already have an existing record for app.example.com, lower its TTL (Time to Live) to the minimum allowed value—typically 300 seconds (5 minutes)—at least 24 hours before your planned migration. This ensures that global recursive resolvers flush their caches quickly when you make your final change.

Step 2: Create the CNAME Record

Create or update the DNS record for your subdomain alias:

• Type: CNAME
• Name / Host: app (or app.example.com depending on your provider's input style)
• Value / Target: your-site-name.netlify.app
• TTL: 300 (or Automatic if using an integrated CDN provider)

DNS Record Type	Host / Name	Target / Value	TTL	Purpose
CNAME	app	your-site-name.netlify.app	300	Routes subdomain traffic to Netlify
TXT	_netlify.app	site-verification-token	3600	Optional ownership verification

Step 3: Verify DNS Propagation

Before checking your Netlify dashboard, verify that your new CNAME record has propagated globally using command-line diagnostic tools. Run a dig query targeting a public DNS resolver like Google (8.8.8.8) or Cloudflare (1.1.1.1):

dig CNAME app.example.com @8.8.8.8 +short

If your configuration is correct, the output will return your Netlify site URL:

your-site-name.netlify.app.

You can also use nslookup on Windows PowerShell:

Resolve-DnsName -Name app.example.com -Type CNAME

Once the command returns the correct Netlify target address, your DNS changes have successfully propagated.

Securing Your Subdomain with HTTPS (SSL/TLS)

Netlify automatically provisions free Let's Encrypt SSL certificates for all configured custom domains, but the certificate generation process can only complete successfully after your DNS CNAME record is actively resolving to Netlify.

Provisioning the Certificate

Return to your Netlify site dashboard under Site settings > Domain management > Domains. If your CNAME record is properly configured, click the Verify DNS propagation button if prompted.

Scroll down to the HTTPS section and click Provision certificate. Netlify will initiate an ACME challenge with Let's Encrypt. Because your CNAME record points to Netlify, Netlify's edge servers will successfully respond to the challenge, and a TLS certificate will be issued within a few seconds.

Validating SSL Configuration

Confirm that your SSL certificate is working correctly by testing the secure connection from your terminal using OpenSSL:

openssl s_client -connect app.example.com:443 -servername app.example.com

Look for the certificate details in the output, specifically confirming that the Common Name (CN) or Subject Alternative Name (SAN) matches your subdomain (app.example.com) and that the issuer is Let's Encrypt.

You can also test HTTP-to-HTTPS redirection using curl:

curl -I https://app.example.com

A healthy response will return an HTTP/2 200 OK status code along with security headers like Strict-Transport-Security.

Common Mistakes and How to Fix Them

Even experienced engineers can run into edge cases during domain migrations. Here are the most common pitfalls and their solutions.

1. Conflicting DNS Record Types

A common mistake is attempting to create a CNAME record on a hostname that already possesses an conflicting A record or TXT record. DNS specifications strictly prohibit a CNAME record from coexisting with other records on the exact same label.

• The Fix: Delete any existing A, AAAA, or conflicting records for app.example.com before creating your CNAME record.

2. CAA Record Restrictions

If your domain uses Certification Authority Authorization (CAA) DNS records to restrict which companies can issue SSL certificates for your domain, Let's Encrypt may be blocked from generating your Netlify SSL certificate.

• The Fix: Add a CAA record allowing Let's Encrypt (letsencrypt.org) to issue certificates for your domain, or temporarily remove your CAA records during the initial certificate provisioning phase.

3. Proxying Through Third-Party CDNs

If you manage your DNS in a cloud proxy provider and enable their orange-cloud or proxy feature on the CNAME record, traffic will hit their servers instead of directly reaching Netlify's edge. This breaks Netlify's automated SSL provisioning and domain validation.

• The Fix: Disable the proxy setting (set the record to DNS-only or unproxied) so that the CNAME points directly to your-site-name.netlify.app without interception.

Configuration Checklist

Review this quick checklist before announcing your new subdomain alias to production users:

• Added the custom subdomain (app.example.com) in the Netlify dashboard.
• Lowered the DNS TTL to 300 seconds 24 hours prior to migration.
• Created the CNAME record pointing to your-site-name.netlify.app.
• Verified global DNS propagation using dig or nslookup.
• Provisioned and verified the Let's Encrypt SSL certificate in Netlify.
• Tested HTTPS connectivity, certificate validity, and HTTP redirection using curl and openssl.
• Removed conflicting A, AAAA, or proxy settings on the registrar side.