How to Change the Elastic Runtime System and Apps Domains

Products

Operations Manager

Issue/Introduction

When installing Elastic Runtime, you'll be asked to enter a system domain and an apps domain. The system domain is the domain used for things like the API, Apps Manager and other system provided services. The apps domain is the default domain that will be setup for your developers to use when pushing applications to the environment. More apps domains can be added later via the cli but this is the initial and default (used if no domain is set by a developer) domain.

If you initially configure the domains incorrectly, perhaps due to a data entry error, or if you change your mind about the domains to be used you may need to change them at a later point in time. This article will walk you through the process of changing the domains.

Environment

Resolution

It is possible to change the system and the application domains after the initial deploy. The process to change the system domain is straightforward and consists of logging into Ops Manager, navigating to the Elastic Runtime tile, clicking on the Domains screen, entering the new domain, clicking Save and then Apply Changes. This will push out the new system domain.

The process to change the default applications domain is a bit more complicated and can be found in the documentation here . As mentioned above, additional shared domains can be added using the `cf` cli and the `cf create-shared-domain` as an admin user at any time after the initial install.

The main thing to consider before changing domains is if there will be any overlap with the existing apps domains. To prevent overlap from occurring, the Cloud Controller has logic to check for overlapping domains and will fail preventing it from starting. Unfortunately this logic does not occur in Ops Manager, so instead of getting an error in Ops Manager what you'll see is that the deployment fails on the cloud controller job.

If you need to make a change with the domains and suspect that there could be overlap, for example if you want to swap the system and apps domains, then you need to follow the steps below to apply these changes in a multi-step fashion.

Change the system domain to a new, different domain. This needs to be setup in DNS so that it resolves the same way as your current domain. Apply Changes.
Follow the instructions for changing the apps domain. The new domain needs to be setup in DNS so that it resolves the same way as your current domain. Apply Changes.

At this point, you now have temporary domains in use for your system and apps domains. This means that you can now reconfigure the apps and system domains to use a new set of domains, even if the new domains may have overlapped with the previously configured domains. To complete the change, simply repeat the previous two steps but using your new target system and apps domains.

Impact

There are several things to consider when changing the apps and system domains. Please read the notes below and proceed with caution.

After changing the system domain users will need to run `cf api` again and may also need to update bookmarks for Apps Manager and other services.
Domains cannot overlap or you will see failures when applying changes. Specifically the cloud controller job will fail to start. See the notes in the instructions section for more details.
Changing the apps domain will change the routes used to access apps that are deployed to the platform. Please consider the impact of this before making the change. External resources that attempt to access the applications on your system may need to be updated to reference the new app routes.
If you do not follow the documented instructions for changing the apps domain, you may see smoke tests fail. This happens because the smoke tests run expecting the default domain to be the first domain returned when you run `cf domains`. If you do not follow the documented instructions, in particular the steps that reorder the domains, then you could get into a situation where the domain that the smoke tests expect to be the default is not the default and thus the test fails. If this happens you can disable the smoke test so that Apply Changes completes successfully and then follow the instructions to reorder the domains.

If you have any questions about the process, please contact Broadcom Support.