How to Migrate a Custom Domain Between Global Accounts

[dragomir_anachkov]

Introduction

If you need to migrate the custom domain setup for one of your applications from one global account (A) to another global account (B) within the same region, the following steps will help guide you through this process.

Note: Before we continue, bear in mind that this article covers the custom domain configuration valid for the SAP BTP, Neo environment. If you want to learn more about the SAP Custom Domain service in the SAP BTP, Cloud Foundry environment, see Configuring Application URLs.

Now let’s take a look at the following example: A company has already configured a custom domain for one of its applications in the Europe (Rot) region. At some point in time, that company decides to move the custom domain configuration of that application from the global account that they're currently using, to another global account, both of which are located in the same region - Europe (Rot).

Note: All custom domain related data used in this article is for testing and demonstration purposes only.

 

Before the Migration

Here’s an example of what the original custom domain setup might look like before the migration:

• Subaccount name: ab123c4d5 (part of global account A in the Europe (Rot) region)
• SSL host name: beforemigration (accessible on host EU1234.ssl.ondemand.com)

You can obtain the SSL host name by listing all SSL hosts in a global account:

neo list-ssl-hosts −−host eu1.hana.ondemand.com −−user <username> −−password <password> −−account ab123c4d5

See list-ssl-hosts.

If you want to list the attributes of a specific SSL host, run:

neo set-ssl-host −−host eu1.hana.ondemand.com −−user <username> −−password <password> −−account ab123c4d5 −−name beforemigration

See set-ssl-host.

Here's an example of the set-ssl-host command's output:

Name : beforemigration
Host : EU1234.ssl.ondemand.com
Certificate : before_migration_cert
Supported protocols : TLSV1_2

• Certificate name: before_migration_cert

You can obtain the name of the certificate by running:

neo list-domain-certificates −−host eu1.hana.ondemand.com −−user <username> −−password <password> −−account ab123c4d5

A sample list-domain-certificates output:

Certificates for subaccount 'ab123c4d5': 1. Account quota: 1
---------------------------------------------------------------------
before_migration_cert CSR generated on SAP Cloud Platform: yes
Subject: CN=www.mycompany.com
Validity: 08-02-2029

See list-domain-certificates.

• Custom domain mapping: the custom domain www.mycompany.com is mapped to ab123c4d5myapp.hana.ondemand.com

You can list any custom domain mappings by running the list-custom-domain-mappings command:

neo list-custom-domain-mappings −−host eu1.hana.ondemand.com −−user <username> −−password <password> −−account ab123c4d5

See list-custom-domain-mappings.

After the Migration

Now that we have taken a good look at the original custom domain setup, let’s see how the company owner can migrate it to another global account in the same region.

Here’s an example of the desirable state of the new custom domain setup in the new global account:

• Subaccount name: ef567g8h9 (part of global account B in the Europe (Rot) region)
• SSL host name: aftermigration
• Certificate name: after_migration_cert
• Custom domain mapping: www.mycompany.com to be mapped to ef123g4h5myapp.hana.ondemand.com

Here’s what you need to do to achieve a similar custom domain configuration. These steps follow the standard end-to-end process for configuring a custom domain in the SAP BTP, Neo environment:

1. Create the SSL host:

neo create-ssl-host −−account ef567g8h9 −−user mymail@example.com −−host eu1.hana.ondemand.com −−name aftermigration

See create-ssl-host.

The output should state that the aftermigration SSL host can now be accessed on host EU5678.ssl.ondemand.com. You’ll need this host in step 9 when you update the DNS records.

2. Generate the certificate signing request (CSR):

neo generate-csr −−account ef567g8h9 −−user mymail@example.com −−host eu1.hana.ondemand.com −−name after_migration_cert −−certificate−distinguished−name "C=GB,O=MyCompany,CN= www.mycompany.com,E=admin@example.com"

Don’t forget to add the custom domain as a common name (CN) value of the −−certificate−distinguished−name parameter: CN= www.mycompany.com

See generate-csr.

3. Send the CSR to your certificate authority (CA) to get it signed.

4. Upload the certificate signed by your CA:

neo upload-domain-certificate −−account ef567g8h9 −−user mymail@example.com −−host eu1.hana.ondemand.com −−name after_migration_cert −−location ./certificate.pub

When you upload the signed certificate, make sure it is placed at the beginning of the file before any other intermediate certificates, if any.

See upload-domain-certificate.

5. Bind the after_migration_cert certificate to the aftermigration SSL host:

neo bind-domain-certificate −−account ef567g8h9 −−user mymail@example.com −−host eu1.hana.ondemand.com −−ssl−host aftermigration −−certificate after_migration_cert

See bind-domain-certificate.

6. Start the new application in subaccount ef567g8h9 via the SAP BTP cockpit or the console client and copy the application URL, because you'll need it in step 8. In this example, the application URL is ef567g8h9myapp.hana.ondemand.com.

7. Remove the previous custom domain mapping by running:

neo remove-custom-domain −−account ab123c4d5 −−user mymail@example.com −−host eu1.hana.ondemand.com −−custom−domain www.mycompany.com −−ssl−host beforemigration

See remove-custom-domain.

8. Configure the new custom domain mapping:

neo add-custom-domain −−account ef567g8h9 −−user mymail@example.com −−host eu1.hana.ondemand.com −−custom−domain www.mycompany.com −−application−url ef567g8h9myapp.hana.ondemand.com −−ssl−host aftermigration

See add-custom-domain.

(!) Caution: Bear in mind that updating the DNS record will cause downtime. The downtime can take from several minutes up to several hours depending on the geographic location.

9. Finally, navigate to your dashboard for managing DNS records and switch the DNS record to point to the new EU5678.ssl.ondemand.com host. This is the new host that you acquired in step 1 from the output of the create-ssl-host command.

According to the DNS record before the migration, the custom domain www.mycompany.com was previously pointing to EU1234.ssl.ondemand.com. After the migration is over, make sure that the new DNS record is pointing to the new SSL host, in this case - EU5678.ssl.ondemand.com.

Remove the Old Setup

When you feel confident that the new custom domain configuration is up and running, you can remove the artifacts related to the old custom domain setup. If you don't delete the old custom domain artifacts, you'll still have to pay for them.

To remove the old setup, execute these commands in the following order:

1. Remove the trusted CA configurations from the old SSL host, if any, with set-ssl-host and the −−ca−bundle <bundle_name>:none parameter.

2. Unbind the domain certificate with unbind-domain-certificate.

3. Remove all custom domain mappings with remove-custom-domain.

4. Remove all certificates with delete-domain-certificates and trusted CAs with remove-ca.

5. Remove the old SSL host with delete-ssl-host.

If you encounter any problems, report an incident and assign it to the BC-NEO-INFR component.

Conclusion

This process is somewhat convoluted, so make sure that you pay attention to the parameter values. One small mistake could make the difference between failure and success. If something isn't working as expected, feel free to share it with us in the comments section below.