Converting a single-namespace installation to a multiple-namespaces installation

Important: This content is a technical preview, and should not be relied on in a production environment.

If you installed IBM Cloud Pak foundational services in a single namespace in your cluster (also known as shared-instance mode), and you now want to install foundational services in multiple namespaces (also known as multiple-instance mode), you can run a conversion process to do so.

You can run the conversion process in two ways:

Run a conversion script
Run a conversion job

Before you proceed, familiarize yourself with the multiple foundational services instances capability. See Installing IBM Cloud Pak foundational services in multiple namespaces.

The outcome of this conversion process is entirely determined by what you specify in the common-service-maps configmap. The configmap has the information about the number of instances to be created and their location.

Example common-service-maps configmaps

Following are some examples of what you can specify in the common-service-maps configmap:

Simple conversion

This type of conversion is the supported path.

Example simple conversion common-service-maps configmap:

apiVersion: v1
kind: ConfigMap
metadata:
  name: common-service-maps
  namespace: kube-public
data: 
  common-service-maps.yaml: |
    controlNamespace: cs-control
    namespaceMapping:
    - requested-from-namespace:
      - cloudpakns1
      - cloudpakns2
      - cloudpakns3
      map-to-common-service-namespace: ibm-common-services

The simple conversion configmap specifies that there are (or likely to be) IBM Cloud Pak workloads that run in the namespaces that you specified in the requested-from-namespace section, and that one foundational services instance is running in the namespace that is specified in map-to-common-service-namespace.

Note: The original foundational services instance might already be running in the namespace that is specified in map-to-common-service-namespace.
Only two major changes happen after you run the simple conversion process:

Singleton operators (cert-manager, licensing, and crossplane) are reinstalled in the controlNamespace.
The cluster can now manage more than one instance of foundational services. You can add another instance of foundational services by adding another entry under namespaceMapping, as shown in the following split workload conversion example.

Split workload conversion

This conversion process needs more manual steps.

Example split workload conversion common-service-maps configmap:

apiVersion: v1
kind: ConfigMap
metadata:
  name: common-service-maps
  namespace: kube-public
data: 
  common-service-maps.yaml: |
    controlNamespace: cs-control
    namespaceMapping:
    - requested-from-namespace:
      - cloudpakns1
      map-to-common-service-namespace: ibm-common-services
    - requested-from-namespace:
      - cloudpakns2
      map-to-common-service-namespace: cloudpakns2
    - requested-from-namespace:
      - cloudpakns3
      map-to-common-service-namespace: cloudpakns3

Important: The split workload configmap is only an example. Following are some major caveats to using such a configuration for the conversion process:

The two new instances (cloudpakns2 and cloudpakns3) get fresh installations of foundational services.
No data from the original foundational services installation in the ibm-common-services namespace is copied over to the two new instances.
If workloads exist in cloudpakns2 or cloudpakns3, you might have to restart those pods so that they use the data from the new foundational services instances. Otherwise, the pods might continue to use data from the original foundational services installation.

In the split workload configmap, each entry under namespaceMapping creates an instance of foundational services. To keep it simple, the same namespace is used in the requested-from-namespace and the map-to-common-service-namespace sections. With this configuration, the IBM Cloud Pak workloads and its foundational services instance workloads run in the same namespace. However, this configuration is just an example. The IBM Cloud Pak and its foundational services instance namespaces can be different.

Conversion process

You can run a conversion script or run a conversion job to covert your cluster to a multiple-instances cluster.

Note: Before you convert your cluster, if you want to back up MongoDB, see Back up and restore MongoDB during conversion to a multiple-namespaces installation.

Run a conversion script

Run a script to convert your cluster.

Prerequisites for running the script

Create the common-service-maps configmap. For more information, see Creating the configmap and Example common-service-maps configmaps.
Ensure that all namespaces declared in common-service-maps exist.
Ensure that foundational services are not installed in AllNamespaces mode.
Ensure that the original foundational services instance, which is installed in the default ibm-common-services namespace, is declared in one of the map-to-common-service-namespace entries.
If you have a foundational services operator that runs in the common-service namespace, either remove this namespace or include it in the common-service-maps configmap.

Run the script

After you create the common-service-maps configmap, specify the foundational services namespace in the following command to run the conversion script:

curl -s https://raw.githubusercontent.com/IBM/ibm-common-service-operator/scripts/convert_to_multi_instance.sh | bash -s <foundational services-namespace>

Verify the conversion

The script must not return any errors.

Check the exit code of the script.
```
echo $?
```

Verify that the controlNamespace has the singleton operators (cert-manager, licensing, and crossplane) that you requested for.

Verify the ibm-cert-manager-operator:

oc get sub -n <controlNamespace> | grep ibm-cert-manager-operator

oc get csv -n <controlNamespace> | grep ibm-cert-manager-operator

Verify the ibm-licensing-operator:

oc get sub -n <controlNamespace> | grep ibm-licensing-operator

oc get csv -n <controlNamespace> | grep ibm-licensing-operator

Verify the ibm-crossplane-operator:

oc get sub -n <controlNamespace> | grep ibm-crossplane-operator

oc get csv -n <controlNamespace> | grep ibm-crossplane-operator

Verify that foundational services pods are still running in the original ibm-common-services namespace.
Verify that new foundational services pods are installed or installing in the new map-to-common-service-namespace namespaces.
Verify that IBM Cloud Pak workloads are still properly running.

Run a conversion job

Run a job to convert your cluster.

Note: Before runnning the script or the conversion job, you must specify the foundational services namespace.

Prerequisites for running the job

Create the common-service-maps configmap. For more information, see Creating the configmap and Example common-service-maps configmaps.
Ensure that the original foundational services instance is not installed in AllNamespaces mode.
Ensure that the original foundational services instance, which is installed in the default ibm-common-services namespace, is declared in one of the map-to-common-service-namespace entries.
If you have a foundational services operator that runs in the common-service namespace, either remove this namespace or include it in the common-service-maps configmap.
You must grant the permissions that are required to convert a single-instance cluster to a multiple-instances cluster.

You can use the template that has all the required permissions. You must grant these permissions so that the conversion job and script can successfully convert your cluster to a multiple-instances cluster. The conversion job needs many high-level permissions across namespaces. After the conversion job completes, you can delete the serviceaccount, clusterrole, and clusterrolebinding resources that the permissions template creates.

Complete the following steps to create and apply a file that has the required permissions:

Open an empty file for editing by using any editor. Following is an example command:
```
vi permissions.yaml
```

Paste the following content. In the ServiceAccount and ClusterRoleBinding sections, add the namespace in which foundational services is installed. The default ibm-common-services namespace is used in the following template.

apiVersion: v1
kind: ServiceAccount
metadata:
  name: multi-instance-conversion-sa
  namespace: ibm-common-services 

---

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: multi-instance-conversion-role
rules:
  - apiGroups:
      - ""
      - operators.coreos.com
      - packages.coreos.com
      - operator.ibm.com
      - apps
      - apiextensions.k8s.io
    resources:
      - pods
      - subscriptions
      - clusterserviceversions
      - operandregistries
      - operandconfigs
      - certmanagers
      - ibmlicensings
    verbs:
      - delete
      - list
      - get
  - apiGroups:
      - ""
      - operators.coreos.com
      - packages.coreos.com
      - operator.ibm.com
      - apps
      - apiextensions.k8s.io
    resources:
      - configmaps
      - namespaces
      - commonservices 
      - customresourcedefinitions
      - ibmlicenseservicereporters
    verbs:
      - get
      - list
  - apiGroups:
      - ""
      - operators.coreos.com
      - packages.coreos.com
      - operator.ibm.com
      - apps
      - apiextensions.k8s.io
    resources:
      - operatorgroups
      - subscriptions
    verbs:
      - create
      - get
      - list
  - apiGroups:
      - ""
      - operators.coreos.com
      - packages.coreos.com
      - operator.ibm.com
      - apps
      - apiextensions.k8s.io
    resources:
      - deployments
      - deployments/scale 
    verbs:
      - update
      - patch
      - get
      - list

---

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: multi-instance-conversion-rolebinding
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: multi-instance-conversion-role
subjects:
- kind: ServiceAccount
  name: multi-instance-conversion-sa
  namespace: ibm-common-services

Save the file.
Apply the file.
```
oc apply -f permissions.yaml
```

Create the job

You can create a job that runs the script to convert your cluster to a multiple-instances cluster.

Creating the job is optional. You can directly run the conversion script. However, if you create a job, you can track the conversion progress.

Complete these steps to create the job:

Open an empty file for editing by using any editor. Following is an example command:
```
vi convert-job
```

Paste the following content. Specify the foundational services namespace in the curl -s https://raw.githubusercontent.com/IBM/ibm-common-service-operator/scripts/convert_to_multi_instance.sh | bash -s <foundational services-namespace> command.

apiVersion: batch/v1
kind: Job
metadata:
  name: multi-instance-conversion
  namespace: ibm-common-services
  labels:
    app: multi-instance-conversion
spec:
  template:
    spec:
      serviceAccountName: multi-instance-conversion-sa
      containers:
      - name: multi-instance-conversion
        image: icr.io/cpopen/cpfs/multi-instance-conversion
        imagePullPolicy: Always
        command:
        - /bin/sh
        - -c
        - |
          echo "Downloading convert_to_multi_instance.sh from repo and running it..."
          curl -s https://raw.githubusercontent.com/IBM/ibm-common-service-operator/scripts/convert_to_multi_instance.sh | bash -s <foundational services-namespace>
      restartPolicy: Never
      backOffLimit: 2

Save the file.
Apply the file.
```
oc apply -f convert-job
```

The conversion job starts and runs the conversion script.

You can track the progress from your OpenShift console.

Click Workloads > Pods.
Search for multi-instance-conversion to see the pod name.
Click the pod name.
Select the Logs tab to see the logs from the conversion script.

To track the progress from the command-line interface (CLI), run these commands:

Get the conversion pod name.

oc get pod -n ibm-common-services | grep multi-instance-conversion

View the logs.

oc logs <multi-instance-conversion-pod-name>

Verify the status

Verify the status of the pods and operators.

Verify that the controlNamespace has the singleton operators (cert-manager, licensing, and crossplane) that you requested for.

Verify the ibm-cert-manager-operator:

oc get sub -n <controlNamespace> | grep ibm-cert-manager-operator

oc get csv -n <controlNamespace> | grep ibm-cert-manager-operator

Verify the ibm-licensing-operator:

oc get sub -n <controlNamespace> | grep ibm-licensing-operator

oc get csv -n <controlNamespace> | grep ibm-licensing-operator

Verify the ibm-crossplane-operator:

oc get sub -n <controlNamespace> | grep ibm-crossplane-operator

oc get csv -n <controlNamespace> | grep ibm-crossplane-operator

Verify that foundational services pods are still running in the original ibm-common-services namespace.
Verify that new foundational services pods are installed or installing in the new map-to-common-service-namespace namespaces.
Verify that IBM Cloud Pak workloads are still properly running.

Note: If you want to restore MongoDB from an earlier backup, you can do so now restore. See Restore MongoDB.