Migrate to the external-domain service

Who is this for?

This post is for all users of the cdn-route or custom-domain services.

Background

The custom-domain and cdn-route services leverage Let's Encrypt to provision certificates on our users' behalf. Several months ago, Let's Encrypt announced that they're deprecating their v1 API. To work with their new API, we've written a replacement to the cdn-route and custom-domain services, the external-domain service.

We now need to migrate your service instances to the new service to ensure their certificates can continue renewing without issue. To accomplish this, we've written internal tooling to migrate instances automatically without service interruption, but it does require some action on your part to initiate the migration.

What you need to do

The new external-domain service uses a different method of validation with Let's Encrypt. The new method relies on specific DNS records being present for each of your domains. To begin the migration, you need to have configured the following DNS records for each domain on your custom-domain or cdn-route instances.

Create the required records

_acme-challenge record

Create a DNS CNAME or ALIAS record with the name:

_acme-challenge.<DOMAIN>.

and the value:

_acme-challenge.<DOMAIN>.external-domains-production.cloud.gov.

The _acme-challenge.<DOMAIN> record allows us to provision SSL certificates on your behalf.

domain record

Create a DNS CNAME or ALIAS record with the name:

<DOMAIN>.

and the value:

<DOMAIN>.external-domains-production.cloud.gov.

The <DOMAIN> record is responsible for routing the user traffic to your site.

If you already have CNAME, A, and/or AAAA (with ALIAS) record(s) for <DOMAIN>, you should update the value or replace the record to match what is shown above.

Example

For example, if you have a custom-domain service created for example.agency.gov that you want to be migrated to an external-domain service, you would want to create these records:

_acme-challenge record

Create a DNS CNAME or ALIAS record with the name:

_acme-challenge.example.agency.gov.

and the value:

_acme-challenge.example.agency.gov.external-domains-production.cloud.gov.

domain record

Create a DNS CNAME or ALIAS record with the name:

example.agency.gov.

and the value:

example.agency.gov.external-domains-production.cloud.gov.

Please note: If your domain is an "apex domain" or "2nd level domain" (i.e. agency.gov instead of example.agency.gov), then you will need to use an A and AAAA (with ALIAS) record(s) assuming your DNS provider supports it.

Validating DNS before making changes

Updating the DNS record for <DOMAIN> changes how users get to your site. We've made every effort to validate we're prepared for this change, but you should confirm that <DOMAIN>.external-domains-production.cloud.gov currently resolves before making this change.

To confirm that your domain is ready for migration, you can directly compare the outputs of nslookup <DOMAIN> and nslookup <DOMAIN>.external-domains-production.cloud.gov. Using the example of example.agency.gov as the <DOMAIN>, you would compare the output of these commands:

nslookup example.agency.gov
nslookup example.agency.gov.external-domains-production.cloud.gov

If this test fails, STOP and do not update your DNS, and contact support@cloud.gov for assistance.

What to expect

During the migration

The migration will not cause:

• downtime
• interruption to your services
• change in functionality or configuration to your services

During the migration, you may see a new service instance with a name you do not recognize in your space(s). Once started, the migration takes about 30 minutes for cdn-route instances, and less than 15 minutes for custom-domain instances.

During this time, you will be unable to make other modifications to the service instance.

After the migration

After the migration, your service instance(s) will have a new instance ID, so any references to your service instance ID will need to be updated. Additionally, your service instance(s) will be of a different service offering (external-domain) and plan (domain or domain-with-cdn), depending on your current instance type).

Customers that experience issues, or that have questions about this change, can send a request to support@cloud.gov.