Installing IBM Cloud Pak foundational services in multiple namespaces

You can install multiple foundational services instances in your cluster.

Multiple foundational services instances capability is supported. See the following sections before you use this capability:

• Requirements and limitations
• Planning your installation

The IBM Cloud Pak foundational services operator, including the Operand Deployment Lifecycle Manager and all of the foundational services, by default, are installed only in the ibm-common-services namespace. If you want to install multiple foundational services instances in other namespaces, create the common-service-maps configmap in the kube-public namespace, and update it with the IBM Cloud Paks® and foundational services namespace information.

Requirements and limitations

• Each instance of foundational services can be a different version, starting from version 3.19.9.
• Multiple foundational services instances capability is available only with a fresh installation of foundational services version 3.19.9 and later, and not with an upgrade to version 3.19.9 or later.
• You can install multiple foundational services instances only if you are installing them for the first time in your cluster. You cannot migrate foundational services to another namespace by updating the configmap if they are already installed in your cluster.
• License Service Reporter does not support multiple instances capability.
• The Cloud Pak Platform (zen-cpp-operator) operator does not support multiple instances capability.
• When there are multiple instances of foundational services, each instance has its own ibmcloud-cluster-info ConfigMap in its own instance namespace.
  • If it is a cluster-shared single instance, this ConfigMap is copied to the kube-public namespace from its original instance namespace.
  • If the cluster has multiple foundational services instances, no ibmcloud-cluster-info ConfigMap will be copied from the original instance namespace to the kube-public namespace. Otherwise, ibmcloud-cluster-info ConfigMap in kube-public namespace will be overwritten by each other.

Planning your installation

• Plan the number of foundational services instances that you need in your cluster. You might need multiple instances if your IBM Cloud Pak requires or recommends it. See the following scenarios:

  • You plan to install multiple IBM Cloud Paks in your cluster. Some might need dedicated instances of foundational services. Follow the installation instructions of each IBM Cloud Pak to install the foundational services instances.

  • Your IBM Cloud Pak might need a separate instance for each environment. For example, to configure a different identity provider for each department.

• Create or update the common-service-maps configmap before you start the multiple instances installation.

Preparing your cluster

You must prepare your cluster to meet the requirements for the number of foundational services instances that you are installing. For more details on the requirements of one instance of foundational services, see the following topics:

• Hardware requirements and recommendations
• Cluster permissions
• Configuration options

Creating the configmap

Important: You must create or update the common-service-maps configmap before you start installing your IBM Cloud Paks and foundational services instances.

You can create the common-service-maps configmap by using the OpenShift cluster console or the command-line interface (CLI). In the configmap, you can map the IBM Cloud Pak and its foundational services instance in the namespaceMapping section.

Following descriptions provide more details on the configmap parameters:

• The controlNamespace is a shared namespace for deploying cluster-scope resources.
  • This namespace must not be the same as any IBM Cloud Pak or foundational services instance namespace.
  • You cannot change this namespace after you install foundational services.

• The requested-from-namespace is your IBM Cloud Pak namespace. You must map this namespace to only one foundational services instance.

  Important: You must install your IBM Cloud Pak in the namespace that you specify in the requested-from-namespace section.

• The map-to-common-service-namespace is the namespace where foundational services are installed.

• If you plan to install one foundational services instance for multiple IBM Cloud Paks, specify multiple IBM Cloud Pak namespaces in the requested-from-namespace section. Specify the foundational services namespace in the map-to-common-service-namespace section. See the following example:

    - requested-from-namespace:
      - cp4d
      - cp4mcm
      map-to-common-service-namespace: common-service-1
  

• If you plan to install a dedicated foundational services instance for an IBM Cloud Pak, specify the IBM Cloud Pak namespace in the requested-from-namespace section, and the foundational services namespace in the map-to-common-service-namespace section. See the following example:

    - requested-from-namespace:
      - cp4i
      map-to-common-service-namespace: cp4i-fs
  

Create the configmap by using the OpenShift cluster console

You must complete these tasks from your OpenShift cluster console.

1. Log in to your OpenShift cluster console.
2. Click the plus icon. You see the Import YAML dialog box.

3. Paste the following configmap definition into the dialog box and replace the namespace value with your custom namespaces.

    apiVersion: v1
    kind: ConfigMap
    metadata:
      name: common-service-maps
      namespace: kube-public
    data:
      common-service-maps.yaml: |
        controlNamespace: cs-control
        namespaceMapping:
        - requested-from-namespace:
          - <IBM Cloud Pak-1-namespace>
          map-to-common-service-namespace: <foundational services-namespace-1>
        - requested-from-namespace:
          - <IBM Cloud Pak-2-namespace>
          map-to-common-service-namespace: <foundational services-namespace-2>
   

4. Click Create. The common-service-maps configmap is created in the kube-public namespace.

Create the configmap by using the command-line interface (CLI)

You must complete these tasks from your OpenShift cluster node.

1. Log in to the cluster by using the oc login command.

2. Create a YAML file named common-service-maps.yaml with the following definition:

    apiVersion: v1
    kind: ConfigMap
    metadata:
      name: common-service-maps
      namespace: kube-public
    data:
      common-service-maps.yaml: |
        controlNamespace: cs-control
        namespaceMapping:
        - requested-from-namespace:
          - <IBM Cloud Pak-1-namespace>
          map-to-common-service-namespace: <foundational services-namespace-1>
        - requested-from-namespace:
          - <IBM Cloud Pak-2-namespace>
          map-to-common-service-namespace: <foundational services-namespace-2>
   

3. Create the configmap.

    oc apply -f common-service-maps.yaml
   

The common-service-maps configmap is created in the kube-public namespace.

Editing the configmap

You can change the namespace mapping after you install foundational services. However, the following conditions apply:

• After you start installing your IBM Cloud Pak and the foundational services instance, you cannot remove the requested-from-namespace or change the map-to-common-service-namespace. However, you can add a namespace to the requested-from-namespace list.
• If you uninstall a foundational services instance, you can remove the IBM Cloud Pak namespaces mapping. You can map these IBM Cloud Pak namespaces to another foundational services instance.

What's next

Install foundational services.

Important: In each foundational services instance namespace that you add in the common-service-maps configmap, you must complete the following tasks:

1. Install the IBM Cloud Pak operator in each requested-from-namespace namespace.
2. Update the CommonService custom resource (CR) with the hardware profile and configurations of individual services.
   • If you have a cluster-scoped operator in the controlNamespace, it picks the largest hardware profile across all the CommonService custom resources in the cluster, and sets it as the hardware profile for the cluster. For example, the License Service and Certificate Manager operators.
   • If you have a namespace-scoped operator, it sets the hardware profile based on the CommonService custom resource in the namespace.
3. Create an OperandRequest with the services that you want to install in the foundational services instance.

You can install the following services in multiple namespaces:

• Identity Management (ibm-im-operator)
• Common Web UI (ibm-idp-config-ui-operator)
• Certificate Manager (ibm-cert-manager-operator)
• Events (ibm-events-operator)
• Cloudctl (ibm-platform-api-operator)
• License Service (ibm-licensing-operator)
• MongoDB (ibm-im-mongodb-operator)
• Platform UI (ibm-platformui-operator)

Note: Even though you install multiple instances of the License Service or Certificate Manager service, only one instance each is installed in the cluster. Irrespective of where you create the OperandRequest, these two services are installed in the namespace that you specify as the controlNamespace parameter value in the common-service-maps configmap. The largest configured resources limits (CPU and memory) of these services across the cluster are applied to the instances that are in the controlNamespace.