DNS management and apex domains

Platform.sh expects you to use CNAME records on your apex domain. But that doesn’t work with some DNS registrars. Learn why they’re recommended and what else you can do.

Why CNAME records? 

Each site on Platform.sh is made up of a set of containers. Platform.sh runs routers for each region to map incoming requests to the appropriate container. For inbound requests to be forwarded to the right container, the requests need to know the IPs of the routers at the time of the request. The IP addresses for the routers in each region are fairly stable but can change in two cases:

  • To up- or downscale a region. Routers are added or removed.
  • For upgrades and maintenance. Routers are taken offline, one at a time, to apply the changes.

The edge hostname’s destination IP addresses are updated automatically should they change.

If a router is being upgraded and its IP changed, two possibilities arise:

  • Your apex domain points to the edge hostname using CNAME/ANAME or ALIAS records. The IP addresses for the routers are updated automatically. You don’t need to do anything. Your website remains online.
  • Your apex domain points to your project’s region using A records. The IP addresses for the routers aren’t updated automatically. Your website appears temporarily offline until you manually update your A records or the router is back from maintenance.

The edge hostname can be retrieved through the CLI or the Console.

Why CNAME records are problematic 

The DNS specification was originally published in 1987, long before name-based HTTP hosting became prevalent. In the multiple RFCs that were written regarding CNAME records, the description of their behavior is rather vague.

It’s generally understood that a CNAME record for an apex domain like example.com:

  • Can only point to an IP address like 192.0.2.1 (an A record).
  • Can’t be used as an alias for another hostname like www.example.com (a CNAME record).

The CNAME record limitation is especially problematic if you want to use an apex domain with any container-based managed hosting service like Platform.sh.

Many registrars allow CNAME records for apex domains. If yours doesn’t, several solutions exist to bypass that limitation.

Handling Apex domains 

Some DNS providers (usually your registrar) don’t allow CNAME records for apex domains. This is one of the limitations to CNAME records.

Check your registrar’s documentation to make sure that CNAME records on apex domains are supported. If your registrar supports them, follow the guide to using such records. If your registrar doesn’t support them, there are a number of ways to handle the limitation.

The recommended approach is to use custom records.

Some DNS providers offer custom, non-standard records (sometimes ANAME or ALIAS records) that you can manage like CNAME records. These nonstandard records make an internal lookup behind the scenes and respond to DNS lookups as if they were A records. As these are nonstandard, their behavior (and quality) can vary and not all DNS registrars offer such a feature.

If you want your site to be accessible at a URL like https://example.com and not only https://www.example.com, this is the best way to do so.

To configure your domain name to point to your project using custom records, follow the instructions on how to set up a custom domain. When you come to configuring your DNS provider, replace the suggested CNAME record with the custom record pointing from your domain to the target.

Examples of such workaround records and providers include:

If your registrar doesn’t support custom records, you can consider using domain forwarding.

If your domain is example.com, domain forwarding redirects all requests from example.com to www.example.com.

To configure your domain name to point to your project using domain forwarding:

  1. Make the www. version of your site the default (canonical) version and configure your app and routes to use the www subdomain as upstream.
  2. Follow the instructions on how to set up a custom domain. When you come to configuring your DNS provider, replace the suggested CNAME record with a record forwarding requests from YOUR_DOMAIN to www.YOUR_DOMAIN.

The following DNS providers are known to support both domain forwarding and advanced DNS configurations:

If your registrar doesn’t support custom records or domain forwarding you can consider using a redirection service.

If your domain is example.com, a redirection service uses an A record to redirect all requests from example.com to www.example.com.

One such redirection service is WWWizer.

To configure your domain name to point to your project using a redirection service:

  1. Make the www. version of your site the default (canonical) version and configure your app and routes to use the www subdomain as upstream.
  2. Follow the instructions on how to set up a custom domain. When you come to configuring your DNS provider, replace the suggested CNAME record with an A record pointing from your domain to the redirection service. For WWWizer, that’s the IP 174.129.25.170.
  3. Ensure that your redirects use the same protocol: http://example.com redirects to http://www.example.com, not to https://www.example.com. Redirects from http to https are handled automatically. Trying to change the protocol and domain in the same redirect causes issues for Let’s Encrypt and prevents the TLS certificate from being issued correctly.

The extra redirect adds a few milliseconds to the first page load.

If your registrar doesn’t support custom records or domain forwarding and you can’t use a redirection service, consider using A records.

Using A records is strongly discouraged and should only be used as a last resort.

Using A records has several limitations:

  • If the IPs change, you need to manually update your configuration. Until you do, the site can appear offline because requests are lost.
  • Directly pointing at the edge routers bypasses their load-balancing functionality. Should one of them go offline for maintenance (as happens periodically for upgrades), about 1/3 of requests to your site are sent to the offline router and are lost, making the site appear offline.

To configure your domain name to point to your project using A records:

  1. Get the IP addresses of your project’s production environment by running dig +short $(platform environment:info edge_hostname).
  2. Follow the instructions on how to set up a custom domain. When you come to configuring your DNS provider, replace the suggested CNAME record with separate A records pointing from your domain to each of the IP addresses from step 1. Incoming DNS lookups pick one of those IP addresses at random to use for the given request (known as round-robin DNS).