Step-by-Step Guide to Changing Domain Names from OpenShift 3.9 (ocp6) to ocp7

Requirement

In a customer's OpenShift 3.9 cluster that is ready for production, a domain name change is required; the author first validated the process in a personal test environment, documenting the steps and pitfalls while migrating from ocp6 to ocp7.

Modification Methods

Two ways to change the domain:

Edit /etc/origin/master/master-config.yaml on the master node (routingConfig subdomain).

Edit /etc/ansible/hosts on the deploy node (openshift_master_default_subdomain).

First Modification Method

On each master node, modify /etc/origin/master/master-config.yaml , changing apps.test.ocp6.com to apps.test.ocp7.com (if multiple masters, update all).

routingConfig:
  subdomain: apps.test.ocp7.com

Restart the master services:

systemctl restart atomic-openshift-master-api.service atomic-openshift-master-controllers.service

Verify current routes (still showing ocp6) and then update them. Routes can be edited directly or recreated.

[[email protected] ~]# oc get route --all-namespaces
NAMESPACE        NAME                HOST/PORT                                 PATH   SERVICES          PORT   TERMINATION   WILDCARD
default          docker-registry     docker-registry-default.apps.test.ocp6.com          docker-registry
passthrough   None
default          registry-console    registry-console-default.apps.test.ocp6.com          registry-console
passthrough   None
jenkins          jenkins             jenkins-jenkins.apps.test.ocp6.com                jenkins
edge/Redirect None
logging          logging-kibana      kibana.apps.test.ocp6.com                         logging-kibana
reencrypt/Redirect None
openshift-infra  hawkular-metrics    hawkular-metrics.apps.test.ocp6.com             hawkular-metrics
reencrypt   None

Update the route for each service. The first approach is to edit the existing route via the web console, e.g., change the hostname of registry-console to the new ocp7 domain and save.

Add a host entry on the local machine for the new route:

172.16.37.43 registry-console-default.apps.test.ocp7.com

Edit the OAuth client cockpit-oauth-client on any master node to include the new URL (or add a new client). Example edit command and resulting YAML snippet are shown.

[[email protected] ~]# oc edit oauthclient cockpit-oauth-client
oauthclient "cockpit-oauth-client" edited
[...]
redirectURIs:
- https://registry-console-default.apps.test.ocp6.com
- https://registry-console-default.apps.test.ocp7.com

After these changes, the new domain can be accessed.

Second Modification Method

To avoid mistakes, recreate the route with a new name. Copy all settings from the original route (including certificates) but use the new hostname. This can be done via the web console or the CLI.

Using the CLI, export the existing route to a YAML file, modify the host field, and recreate it:

[[email protected] ~]# oc get route registry-console -o yaml > registry-console-2.yaml
[edit registry-console-2.yaml to set host to apps.test.ocp7.com]
[[email protected] ~]# oc create -f registry-console-2.yaml

Finally, update the OAuth client URLs to point to the new domain.

Additional Pitfalls

When using the first method, every route must be manually updated and the corresponding OAuth client files must be edited; otherwise access errors occur (shown in screenshot).

The OpenShift web console ConfigMap must be updated to reference the new domain (ocp7) when using the first method; the second method updates it automatically.

When using the second method, the Kibana OAuth client is updated automatically, but the registry-console OAuth client must be updated manually.

Jenkins Page Redirection Issue

If Jenkins is deployed inside OpenShift, clicking pipeline logs may still redirect to the old Jenkins domain. Deleting and recreating the pipeline after preserving its content resolves the issue.

Red Hat case suggests setting JENKINS_ROOT_URL via the deployment YAML, but the provided fix did not work for the author.

Is your jenkins instance deployed inside OpenShift using the Jenkins template or is it an external Jenkins instance? If it is deployed on OpenShift and configured from the Jenkins template, you should be able to set the JENKINS_ROOT_URL by navigating to the Deployments > jenkins > Actions > Edit YAML and adding a new environment variable and setting its value to your Jenkins domain name.