Last Reviewed: February 03, 2023

Cloudflare Domain Configuration

Learn how to point your domain to a Pantheon site using Cloudflare

Edit this page on GitHub Report an issue with this doc

You can use Cloudflare for DNS only or stack it as a CDN on top of Pantheon's Global CDN. We recommend using Cloudflare for DNS only. If you have a paid Cloudflare plan to use features like their WAF or have custom Cloudflare configurations (e.g. many page rules) you'd like to keep, however, then ensure you follow the guide below to enforce HTTPS to prevent any issues.

Before You Begin

Be sure that you have a:

Domain name using Cloudflare to host DNS
Paid Pantheon plan
Domain connected to the target Pantheon environment (typically Live)

Locate Pantheon's DNS Values

Go to the Site Dashboard and select the target environment (typically Live) then click Domains / HTTPS.
Click the DNS Recommendations button next to the www domain and copy the A and AAAA values (e.g. 23.185.0.2, 2620:12a:8000::2).
Login to your Cloudflare account in a new tab before you continue.

Pre-Provision SSL Certificate on Cloudflare (optional)

Though optional, pre-provisioning Let's Encrypt SSL certificates ahead of a planned launch can prevent a gap in SSL service immediately after updating DNS on launch date.

Click DNS on the Cloudflare menu bar.
Click + Add record and then select TXT from the Type drop-down menu.
Enter the TXT Name/Host in the Name field and the TXT Value in the Content field.
You can find both values in the Live environment of your Pantheon Site Dashboard under Domains/HTTPS for that domain.
Select your desired Time to Live (TTL) and then click Save.
Go to the Site Dashboard.
Navigate to the Live environment and click Domains/HTTPS.
Click the details button next to the domain and then click the Verify Ownership button.
The process to provision certificates will begin after domain ownership is verified, and you will receive the following notice:
```
HTTPS
Your DNS configuration is correct, and certificate provisioning is queued to start for this domain.
```
Both the bare domain and the www domain will be accessible over HTTPS after the HTTPS status turns green (which may take up to an hour):
```
HTTPS

Let’s Encrypt certificate deployed to Pantheon’s Global CDN. Certificate renews automatically with no additional cost.
```
Repeat the steps above for all domains (www and non-www).

Configure DNS Records on Cloudflare

Option 1: Use Cloudflare for DNS Only (Recommended)

This configuration routes traffic to Pantheon's Global CDN exclusively. Unless you're paying for advanced Cloudflare features or if you have custom configurations (e.g. many page rules) you'd like to keep, turn off Cloudflare's CDN so that only DNS hosting services are used:

Example DNS only

Click DNS on the Cloudflare menu bar.
Click + Add record.
Select A from the Type drop-down menu.
Enter www in the Name field and paste the IP address value provided by Pantheon (e.g. 23.185.0.2) in the IPv4 field.
Select a desired Time to Live (TTL).
Learn More
Time to Live (TTL)
The TTL dictates the lifespan of a DNS record; a shorter time means less time to wait until the changes go into effect. TTLs are always set in seconds with a few common ones being 86400 (24 hours), 43200 (12 hours), and 3600 (1 hour).
When you make a change to the TTL of an existing record, you need to wait for the old TTL time to pass - that is, if it had been set to 86400, you would need to wait a full 24 hours for the new setting to begin propagating everywhere.
Disable Cloudflare's CDN by clicking the cloud icon (should be gray, not orange).
Click on Save.
Cloudflare Page Rules will not work when Cloudflare is used for DNS only. Instead, redirects are handled by adding redirect logic to the WordPress wp-config.php file or the Drupal settings.php file. See Configure Redirects for more information.

Repeat the steps above to create an A record for the bare domain, using @ as the Name and the same IP address, then repeat again for the AAAA records.

Option 2: Use Cloudflare's CDN stacked on top of Pantheon's Global CDN

You can configure Cloudflare's CDN as an additional layer on Pantheon's Global CDN service. You must use this option if you have a Front-End site.

Select SSL/TLS from the Cloudflare menu bar and set SSL mode to Full (Strict).
Navigate to the Edge Certificates page on the sub-menu and enable Always Use HTTPS
Scroll down and enable Automatic HTTPS Rewrites
Remove existing redirects configured via PHP in settings.php or wp-config.php that you no longer need, and update any still required to point to the domain managed by Cloudflare. You can also set the Primary Domain from the Site Dashboard.
Proceed with DNS configuration as described in Option 1, but make sure the cloud is toggled orange, not gray:

Restrict Content Based on Geographic Location

If you're using Cloudflare's IP Geolocation feature, you will need to read the CF-IPCountry header and set Vary: CF-IPCountry on all responses.

Access to the /.well-known Path Is Needed

If you're using Cloudflare's services to control or block traffic, an exception must be made for the /.well-known path in Cloudflare's config. If the /.well-known path is not accessible, Lets Encrypt may not be able to issue a certificate.

Cache Invalidation Best Practices

Cloudflare allows you to turn on caching. However, no cache invalidation hook is fired when you make content changes if you have Cloudflare caching turned on. This means that Cloudflare will be unaware of your changes and persist with stale cache.

We recommend that you turn off Cloudflare caching until the pantheon_advanced_page_cache module/plugin is extended to send API calls to Cloudflare.

CAA Records (Optional)

A CAA Record specifies which certificate authority (CA) can issue HTTPS certificates for a domain.

Click DNS on the Cloudflare menu bar.
Click + Add record.
Select CAA from the Type drop-down menu.
Enter the bare domain (example.com) in the Name field.
Keep the Only allow specific hostnames tag selected. If you are not stacking Cloudflare's CDN with the Pantheon Global CDN, enter letsencrypt.org as the value:
If you are using Cloudflare's CDN, they will automatically add CAA records for their CA providers when Universal SSL is enabled. Do not add a record for letsencrypt.org in this case.
Select desired Time to Live (TTL).
Learn More
Time to Live (TTL)
The TTL dictates the lifespan of a DNS record; a shorter time means less time to wait until the changes go into effect. TTLs are always set in seconds with a few common ones being 86400 (24 hours), 43200 (12 hours), and 3600 (1 hour).
When you make a change to the TTL of an existing record, you need to wait for the old TTL time to pass - that is, if it had been set to 86400, you would need to wait a full 24 hours for the new setting to be in place everywhere.
Click Add Record. Your record should look similar to the following once it has been created:
Repeat this process for the www subdomain.