Updating cp-console hostname and TLS secret

This version of documentation is no longer updated. For the latest information, see the following links:
- Continuous Delivery (CD) documentation
- Support Cycle-2 (SC-2) documentation

You can update the cp-console hostname with the custom hostname and certificates.

Updating cp-console hostname and TLS using the script
- Restore SAML
Updating cp-console hostname using the ibmcloud-cluster-info configmap (no TLS certificate update required)
Reverting the updates
Troubleshooting cp-console hostname issues

Note:

These instructions are for changing only the cp-console route hostname and certificates. This procedure is not applicable for the CPD route, zenservice custom resource (CR), or Platform UI. Review respective IBM Cloud Pak® documentation to update the CPD route. For more information, see IBM Cloud Paks® that use IBM Cloud Pak® foundational services.
From IBM Cloud Pak® foundational services v4.10 and onward, cp-consoles can be removed for the unified console. These instructions are not applicable for an IBM Cloud Pak environment that uses a unified console where the cp-console route is not deployed. Run the oc get route | grep cp-console command, and a cp-console cp-console-ibm-common-services.apps.cluster_hostname.com response indicates that the cp-console exists in the cluster. This procedure is applicable only for the cluster with the cp-console route.

Updating cp-console hostname using the script

You can update the cp-console hostname and certificates using the cs-onprem-tenant-config.sh script. Ensure that you complete the prerequisites before you run the script.

Prerequisites

Keep your new hostname and certificates ready.

Create the custom hostname. If the default Red Hat® OpenShift® Container Platform domain needs a placement change, you can modify its default value.
Make sure that the custom hostname that you configure is resolvable from both inside and outside the Red Hat OpenShift cluster.
Optional: If you are updating the TLS secret, provide new certificates in an unencrypted PEM format. Place the certificates in the installer_scripts directory. For more information, see Download and extract the installer scripts for your CASE bundle.

Note: This step is applicable only if you need to update the certificates. If the certificates change or expire, you must provide new certificates and run the script again to create a secret by using the new certificates.
- ca.crt: Contains the intermediate CA signer certificates and the CA root signer certificate. The file must start with the intermediate CA certificates in order that to lead the root CA.
- tls.crt: Contains only the route server certificate.
  
  Note: The route server certificate passes the TLS verification for the route hostname.
- tls.key: Contains the private key of the route server certificate.
  
  See the following example of PEM encoding that uses header and footer lines for each certificate and private key.
```
-----BEGIN CERTIFICATE-----
(encoded set of characters)
-----END CERTIFICATE-----

-----BEGIN PRIVATE KEY-----
(encoded set of characters)
-----END PRIVATE KEY-----
```

Procedure

Complete the following steps to change the cp-console hostname and certificates of the cp-console route.

Create a cs-onprem-tenant-config.yaml file with the following configmap definition. In the data section, provide your custom hostname. If you are providing new certificates to update the TLS secret, do not change the name of the custom_host_certificate_secret secret in the configmap.
```
apiVersion: v1
kind: ConfigMap
metadata:
  name: cs-onprem-tenant-config
  namespace: <your-foundational-services-namespace>
labels:
  cs_onprem_tenant_config: "true"
data:
  ##comment out or remove this setting if not changing the hostname
  custom_hostname: <your-custom-hostname>
  ##comment out or remove this setting if not changing the certificates
  custom_host_certificate_secret: custom-tls-secret
```
Update the value of the custom_hostname parameter to include the hostname that you want without the https:// protocol, as shown in the following example. The script updates the custom hostname change alone and does not support a domain name change.
```
cp-testcustomhn.apps.o1-849902.cp.fyre.ibm.com
```
Create the cs-onprem-tenant-config configmap.
```
oc apply -f cs-onprem-tenant-config.yaml
```
If your cluster topology has a separate namespace for all operators, identify that namespace and set it as the default namespace. You need to update the $csNamespace and $map_to_common_service_namespace in the script.
1. Get the namespace where you deployed the foundational services.
```
oc get csv -A | grep common-service-operator
```
  The following is the sample output:
```
cp4itest                                           ibm-common-service-operator.v4.11.0            IBM Cloud Pak foundational services    4.11.0            ibm-common-service-operator.v4.10.0            Succeeded
```
  cp4itest is the namespace where foundational services is deployed and v4.11.0 is the CASE version
2. Set the project with the default foundational services namespace.
```
oc project <your-foundational-services-namespace>
```
  The following is the sample command:
```
oc project cp4itest
```

Download and extract the installer scripts for your CASE bundle.

To get the CASE version, run the following command or see IBM: Product CASE to Application Version and search for the installed foundational services version to find the related CASE version.
```
oc get csv -n  "<your-foundational-services-namespace>"  | grep ibm-common-service-operator
```
Run the following command. Replace CASE_VERSION with the foundational services version.
```
export CASE_VERSION=<your foundational services operator version>
```

Next, run the following commands to download the CASE bundle:

wget https://github.com/IBM/cloud-pak/raw/master/repo/case/ibm-cp-common-services/${CASE_VERSION}/ibm-cp-common-services-${CASE_VERSION}.tgz

tar -xvzf ibm-cp-common-services-$CASE_VERSION.tgz

cd ibm-cp-common-services/inventory/ibmCommonServiceOperatorSetup/installer_scripts

Set the following environmental variables in the cs-onprem-tenant-config.sh script. To update the script, you can use the text editor or run one of the following commands in a system editor:
```
   vi cs-onprem-tenant-config.sh
```
```
   sudo nano cs-onprem-tenant-config.sh
```
- $csNamespace - Set the operator namespace of the foundational services. The operator namespace is the control namespace where foundational services is deployed.
- $map_to_common_service_namespace - Set the operand namespace of the foundational services where platform-auth-service-xxx pod is running.
  
  Note: If the operators and operands are in the same namespace, set $map_to_common_service_namespace and $csNamespace with <your-foundational-services-namespace>.
If you are providing new certificates for TLS secret, place the tls.key, tls.crt, and ca.crt files in the installer_scripts directory. Run the script to create the TLS secret with the required certificate files.

To change the hostname and use the selfsigned certificate, see Prerequisites to prepare your cert and tls files.
Run the script from the operator namespace.
```
./cs-onprem-tenant-config.sh
```
If you see the following error, it means that you did not provide the new certificate files for TLS secret in the installer_scripts directory. To resolve the issue, place the certificate files and run the script again.
```
tls.key is not present in current directory, pls keep tls.key, tls.crt and ca.crt files in current directory
```
The script completes the following tasks:
- Uses namespaces from the common_service_maps configmap that is in the kube-public namespace. The common_service_maps` configmap has all the namespaces in a tenant.
- Creates a TLS secret if you provided new certificate files.
- If your cluster topology has a separate namespace for all operators, the script runs the iam-custom-hostname job in that namespace.
- Update the custom hostname in all applicable identity management (IM) components.
Restart the platform-auth service pods to pick up the route change.

(Optional) Restart the Zen operator pod if Zen is installed.

oc get pod -n <your-foundational-services-namespace> | grep ibm-zen-operator

oc delete pod -n <your-foundational-services-namespace> <ibm-zen-operator-pod-name>

(Optional) Restart the usermgmt pods if Zen is installed.
1. Get the usermgmt pod names.
```
oc get pods |grep usermgmt
```
2. Delete the usermgmt pods.
```
oc delete pod <usermgmt-pod-name>
```
(Optional) If you restarted the Zen operator pod and usermgmt pods, wait until these pods restart. Ensure that the pods are in the ready and running status.
```
oc get pods -n <your-foundational-services-namespace> | grep ibm-zen-operator
oc get pods -n <your-foundational-services-namespace>|grep usermgmt
```
If you cannot access the route with the updated custom hostname, see Troubleshooting cp-console hostname issues.

Restore SAML

If you have a SAML configuration, after you change the certificate the Security Assertion Markup Language (SAML) connection breaks. You must update the SAML metadata with the new certificate information to restore the connection. For more information, see Identity and access management migration.

Updating cp-console hostname using the `ibmcloud-cluster-info` configmap (no TLS certificate update required)

You can update the cp-console hostname with the wildcard certificate using the ibmcloud-cluster-info configmap. You cannot change the cp-console hostname that is not configured with the wildcard certificate and cp-console domain name.

The following is the sample wildcard certificate:

An example of wildcard certificate

Note: You cannot update the TLS using the ibmcloud-cluster-info configmap. To update the TLS, see Updating cp-console hostname using the script.

Complete the following steps to update the custom hostname with the ibmcloud-cluster-info configmap:

Update the cluster_address and cluster_endpoint parameters in the ibmcloud-cluster-info configmap.

oc edit cm ibmcloud-cluster-info -n cpfs-data

The following is the sample ibmcloud-cluster-info configmap:

apiVersion: v1
data:
  cluster_address: <hostname>-cpfs-data.apps.ocp415-qb.cp.fyre.ibm.com.              
  cluster_endpoint: https://<hostname>-cpfs-data.apps.ocp415-qb.cp.fyre.ibm.com      
  cluster_kube_apiserver_host: api.ocp415-qb.cp.fyre.ibm.com
  cluster_kube_apiserver_port: "6443"
  cluster_name: mycluster
  cluster_router_http_port: "80"
  cluster_router_https_port: "443"
  im_idmgmt_endpoint: https://platform-identity-management.cpfs-data.svc:4500
  im_idprovider_endpoint: https://platform-identity-provider.cpfs-data.svc:4300
  proxy_address: cp-proxy-cpfs-data.apps.ocp415-qb.cp.fyre.ibm.com
kind: ConfigMap

Replace <hostname> with the custom hostname.

Wait for the IM pods to restart.

platform-auth-service-xxx
platform-identity-management-xxx
platform-identity-provider-xxx

(Optional) Restart Zen pods with the following label if Zen is installed:
```
name=ibm-zen-operator
component=usermgmt
```
1. Get the usermgmt pod names.
```
oc get pods |grep usermgmt
```
2. Delete the usermgmt pods.
```
oc delete pod <usermgmt-pod-name>
```
You can login to cp-console and cpd with the updated hostname after the restart of the Zen pods.

Result

After you run the script, the cp-console route is updated with the new hostname. You can also see the new certificates, if applicable, in your browser when you access the cp-console URL.

To verify that the cp-console route is updated with the new hostname, run the following command:

oc get routes -n <foundational-services-namespace> | grep cp-console

In response, you should get the list of routes with the new hostname.

Reverting the updates

If you need to revert to the previous hostname and certificate, repeat the steps in Procedure by using the previous hostname.

To revert to the default name for cp-console, complete the following steps:

Update the cs-onprem-tenant-config ConfigMap to set the default name in the custom_hostname parameter.

oc -n <your-foundational-services-namespace> edit configmap cs-onprem-tenant-config

apiVersion: v1
kind: ConfigMap
metadata:
  name: cs-onprem-tenant-config
  namespace: $csNamespace
labels:
  cs_onprem_tenant_config: "true"
data:
  ##comment out or remove this setting if not changing the hostname
  custom_hostname: <Default hostname>
  ##comment out or remove this setting if not changing the certificates
  custom_host_certificate_secret: custom-tls-secret

Run the script again.
```
./cs-onprem-tenant-config.sh
```

To restore the default certificates, delete the cp-console route.

oc get route -n <your-foundational-services-namespace>

oc delete route cp-console  -n <your-foundational-services-namespace>

Troubleshooting cp-console hostname issues

If Application is not available error message is displayed in the console when you run the ./cs-onprem-tenant-config.sh script with the custom hostname, see Unable to access the CPD route when you update custom hostname.

Error in console

If the issue still exist, contact IBM Support.