Installing IBM Cloud Pak foundational services by using the OpenShift console

You can use the IBM Cloud Pak foundational services operator to install foundational services in your cluster. Use the following procedure to install foundational services version 3.23.x.

The IBM Cloud Pak foundational services operator, including the Operand Deployment Lifecycle Manager and all of the foundational services, by default, are installed in the ibm-common-services namespace. If you want to install the Operand Deployment Lifecycle Manager and foundational services in any other namespace, create a configmap with the namespace information. For more information, see Installing IBM Cloud Pak foundational services in a custom namespace. The Operand Deployment Lifecycle Manager watches all of the namespaces in the cluster. The IBM Cloud Pak foundational services operator manages the lifecycle of all foundational services operators. For more information about the foundational services that are available and their Operator names and versions, see foundational services Operators and versions.

See the following notes:

• If the foundational services that you are using are included as part of an IBM Cloud Pak® deployment, you do not have to manually deploy the IBM Cloud Pak foundational services operator. The IBM Cloud Pak foundational services operator is deployed into the same namespace as your IBM Cloud Pak operator and it bootstraps the installation into the ibm-common-services namespace.
• The following instructions are for installing foundational services by using the OpenShift Container Platform console. If you want to use the command-line interface (CLI), see Installing IBM Cloud Pak foundational services by using the CLI.

Installation steps

1. Prerequisites
2. Installing the IBM Cloud Pak foundational services operator
3. Setting the hardware profile and accepting the license
4. Installing foundational services in your cluster
   1. Configuring the services
   2. Configuring namespace permissions
   3. Creating the entitled registry secret
   4. Creating the OperandRequest instance
      • Creating the OperandRequest instance by using the Form View
      • Creating the OperandRequest instance by using the YAML View
   5. Installing network policies for foundational services
5. Verifying the installation
6. Accessing the console
   • Console username and password

Post-installation options

• Enabling or disabling foundational services after installation

Reference

• Foundational services installation scenarios when multiple IBM Cloud Paks are installed in your cluster
• Foundational services operators and versions

1. Prerequisites

An OpenShift Container Platform cluster must be installed. For the supported OpenShift Container Platform versions, see Supported OpenShift versions and platforms.

2. Installing the foundational services operator

You must complete these tasks from your OpenShift cluster console to install the latest version of foundational services operator.

1. Create the foundational services catalog source.

   Note: Creating catalog source in a private namespace is not supported. The only supported scenario is to create the catalog source in the openshift-marketplace namespace.

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

   3. Create the IBM Cloud Pak foundational services CatalogSource.

      Note: The OperatorSource is deprecated in foundational services version 3.5.x and is not automatically updated. The CatalogSource opencloud-operators is deprecated in foundational services version 3.8.0.

      To create the CatalogSource, paste the following definition in the YAML dialog box:

      apiVersion: operators.coreos.com/v1alpha1
      kind: CatalogSource
      metadata:
        name: ibm-operator-catalog
        namespace: openshift-marketplace
      spec:
        displayName: ibm-operator-catalog
        publisher: IBM Content
        sourceType: grpc
        image: icr.io/cpopen/ibm-operator-catalog@sha256:ef0641b95201580d19a59b86560e4390ecbbb9f5866d9eea5073bb355eafa0b4
        updateStrategy:
          registryPoll:
            interval: 45m
      

      See the following notes:

      • For foundational services version 3.23, the CatalogSource image tag is icr.io/cpopen/ibm-operator-catalog@sha256:ef0641b95201580d19a59b86560e4390ecbbb9f5866d9eea5073bb355eafa0b4.
      • You can use the image tag for version 3.23 if you want to pin the CatalogSource to a particular version. If you pin the CatalogSource to a version, it will not be updated and will prevent foundational services from automatically upgrading when a new version is available.

   4. Click Create. The catalog source ibm-operator-catalog is created.

   5. Verify that the source container is running.

      oc -n openshift-marketplace get pod | grep ibm-operator-catalog
      

2. Ensure that your IBM Cloud Pak® namespace exists in your cluster. The namespace is needed for the IBM Cloud Pak foundational services operator. Usually, the IBM Cloud Pak foundational services operator is automatically installed in your IBM Cloud Pak namespace when you install your IBM Cloud Pak. If you see the operator in your IBM Cloud Pak namespace, you do not need to manually install it. The Operand Deployment Lifecycle Manager and the foundational services are then, by default, installed in the ibm-common-services namespace. Note: If you want to install the Operand Deployment Lifecycle Manager and the foundational services in a custom namespace, you must create a configmap before you install your IBM Cloud Pak. For more information, see Installing IBM Cloud Pak foundational services in a custom namespace.

   • If you need to create a namespace, complete the following steps:
   • From the navigation pane, click Home > Projects. The Projects page is displayed.
   • Click Create Project. A Create Project area is displayed.
   • Enter details of the namespace that you are creating. You can specify your IBM Cloud Pak namespace as the name.

   • Click Create. The namespace for your IBM Cloud Pak foundational services operator is created.

   • If the IBM Cloud Pak foundational services operator is not already installed in your IBM Cloud Pak namespace, install it now:

   • From the navigation pane, click Operators > OperatorHub. The OperatorHub page is displayed.

   • In the All Items field, enter IBM Cloud Pak foundational services. The IBM Cloud Pak foundational services operator is displayed.
   • Click the IBM Cloud Pak foundational services tile. The IBM Cloud Pak foundational services window is displayed.
   • Click Install. You see the Install Operator page.
   • Set Installation Mode to your IBM Cloud Pak namespace.
   • Set Update Channel to the v3.23 version.

   • Set Approval Strategy to Automatic.

     See the following notes:

     • Starting from version 3.8.x, you can decide on the approval strategy by setting the approval strategy to either Automatic or Manual, as required. By default, the approval strategy is set to Automatic, which automatically installs or upgrades the operator when a new version is available. If you set the strategy to Manual, the operator is not automatically installed or upgraded. Instead, you get an install plan that needs to be manually approved before an upgrade.
     • When you set the approval strategy for the IBM Cloud Pak foundational services operator, it applies to all foundational services that are installed with this operator.
     • If you install the IBM Cloud Pak foundational services operator in a namespace where another operator is installed with the installPlanApproval: Manual set in its subscription, then the foundational services operator inherits the setting: the approval plan for the IBM Cloud Pak foundational services operator is automatically set to Manual. For more information, see Approval strategy.

   • Click Install. After a few minutes, the IBM Cloud Pak foundational services operator and the Operand Deployment Lifecycle Manager operator are installed, and you can see these operators on the Installed Operators page.

The IBM Cloud Pak foundational services operator creates the ibm-common-services namespace, or the custom namespace that you specified in the configmap, and installs the Operand Deployment Lifecycle Manager operator and the IBM NamespaceScope Operator in the namespace.

Optionally, configure the foundational services webhook. For more information, see IBM Cloud Pak foundational services webhook.

3. Setting the hardware profile and accepting the license

• Hardware profile: Set the hardware requirements profile based on the workloads in your cluster. For more information about the profiles, see Hardware requirements and recommendations for foundational services.

  • The default profile is starterset. You can change the profile to starter, small, medium, production, or large, if required.
  • You can scale up a profile anytime after installation. If you change the profile to large or medium, you cannot scale down the profile to small after installation. However, scaling down a profile can be done only if no other Cloud Pak has requested for a larger (production) size. For example, if you install with a medium profile and another Cloud Pak specifies a medium or large (production) profile, and then you attempt to scale down to size small, the profile remains as medium. You can be able to scale down to small only if there is no other Cloud Pak with medium or large (production) size. You can be able to scale down to starterset (starter) profile with 3 MongoDB replicasets.

• License: Accept the license to use foundational services by adding spec.license.accept: true in the spec section.

Complete the following steps:

1. From the navigation pane, click Home > Search.
2. From the Project drop-down list, select ibm-common-services.
3. From the Resources drop-down list, select CommonService.
4. Click the common-service resource.
5. Select the YAML tab.

6. Update the spec.size parameter to set the hardware profile, and add the spec.license.accept: true parameter to accept the license.

     apiVersion: operator.ibm.com/v3
     kind: CommonService
     metadata:
       name: common-service
       namespace: ibm-common-services
     spec:
       license:
         accept: true
       size: small
   

7. Click Save.

4. Installing foundational services in your cluster

1. From the navigation pane, click Operators > Installed Operators.
2. From the Project drop-down list, select the ibm-common-services namespace. You see the IBM Cloud Pak foundational services operator and the Operand Deployment Lifecycle Manager operator. Note: You must install and configure foundational services in the ibm-common-services namespace.

The IBM Cloud Pak foundational services operator provides the CommonService custom resource. If required, you can customize the service definitions by editing the custom resource. For more information, see Configuring foundational services by using the CommonService custom resource.

The Operand Deployment Lifecycle Manager provides the following APIs:

- **OperandConfig** includes all the services that are available for you to install in your cluster.
- **OperandRegistry** is for internal management of the services.
- **OperandRequest** is the API where you add the services that you want to install in your cluster.
- **OperandBindInfo** is the API that manages secrets and configmaps between namespaces.

Operand Deployment Lifecycle Manager creates the OperandRegistry, OperandConfig, and OperandBindInfo instances by default. You must manually create the OperandRequest instance to specify the services that you want to install in your cluster.

Complete the following steps to configure the services and create the OperandRequest:

a. Configuring the services

Before you create the OperandRequest instance, complete the configurations that are required for the foundational services that you are installing. For more information, see Configuring foundational services by using the CommonService custom resource. Note: The ibm-iam-operator creates a default cluster administrator by the name admin during installation. If you already have a user by the name admin in your cluster, you must set the defaultAdminUser parameter before you install foundational services. This setting is to avoid your admin user from being removed if you uninstall foundational services later. For more information about setting this parameter, see Changing the default admin username.

b. Configuring namespace permissions

You can authorize the foundational services operators to manage service workload across namespaces. For more information, see Authorizing foundational services to perform operations on workloads in a namespace.

c. Creating the entitled registry secret

You need to create the entitled registry secret only if you are installing Cloud Native PostgreSQL or IBM User Data Services in your cluster.

To create the entitled registry secret, complete these steps. You must create the secret in the namespace where you are installing the foundational services. The default namespace is ibm-common-services. Note: If you want all the pods in your cluster to be able to pull images from the entitled registry, skip these steps and complete the steps in the Adding a global pull secret section.

1. Obtain the entitlement key that is assigned to your ID.

   1. Log in to Container Software Library by using the IBMid and password that are associated with the entitled software.
   2. In the Entitlement keys section, click Copy key to copy the entitlement key to the clipboard.
   3. Copy the key to a safe place. You need the key to create your pull secret.

   4. (Optional) Verify the validity of the key by logging in to the IBM Entitled Registry by using a container tool.

      docker login cp.icr.io --username cp --password entitlement_key
      

2. Log in to your OpenShift Container Platform cluster by using the oc login command.

3. Create a Docker registry secret named ibm-entitlement-key and add the pull secret to the namespace where you are installing foundational services.

     oc create secret docker-registry ibm-entitlement-key \
       --docker-username=cp \
       --docker-password=<entitlement_key> \
       --docker-server=cp.icr.io \
       --namespace=<target_namespace>
   

   These are the variables that you need to designate:

   • <entitlement_key> is the value of your entitlement key that you copied earlier from Container Software Library .
   • <target_namespace> is the namespace where you are installing foundational services in your cluster. The default namespace that you can use here is ibm-common-services.

Adding a global pull secret

If you want all the pods in your cluster to be able to pull images from the entitled registry, update the pull secret that is in the openshift-config namespace with the Docker account and entitlement key information.

Complete the following steps to update the pull secret:

1. Extract the current pull secret that is in the openshift-config namespace:

    oc extract secret/pull-secret -n openshift-config --keys=.dockerconfigjson --to=. --confirm
   

2. Convert the extracted pull secret by using jq command-line JSON processor. To install jq, see jq command-line JSON processor .

    cat .dockerconfigjson | jq . >  .dockerconfigjson.orig
    mv .dockerconfigjson.orig .dockerconfigjson
   

3. Convert your entitlement key to base64. Replace entitlement_key with the value of your entitlement key that you copied earlier from Container Software Library . Copy the base64 value to a safe location.

    echo "cp:entitlement_key" | base64
   

4. Make the following edits to the .dockerconfigjson file: In the auths section, add cp.icr.io to the existing list of objects. Replace auth_string with the base64 value that you got in the previous step. Important: You must enter the value of auth_string as a single, long string. If there are any line returns, you get an error.

    {
       "auths": {
          "cp.icr.io" : {
             "auth": "auth_string"
          }
       }
    }
   

5. Upload the updated pull secret to the openshift-config namespace:

    oc set data secret/pull-secret -n openshift-config --from-file=.dockerconfigjson
   

After the pull secret successfully uploads, you see the following message:

secret/pull-secret data updated

The update restarts all the nodes in your cluster. Use the following command to monitor the status of the nodes. Wait until all nodes show the status as UPDATED: True.

watch -n 3 oc get machineconfigpool

d. Creating the OperandRequest instance

To create the instance, click Operand Deployment Lifecycle Manager, select the OperandRequest tab, and click Create OperandRequest. On the Create OperandRequest page, select a configuration mode: Form View or YAML View.

Note: Installation by using the Form View is available only in OpenShift version 4.5 or later clusters.

• The Form View provides a simple installation option. However, not all configuration options are supported in the Form View. For example, you cannot add the bindings configuration.

• The YAML View provides a YAML editor that you can use for installing the foundational services. The editor supports all configuration options.

Creating the OperandRequest instance by using the Form View

Complete the following steps to use the form to create the OperandRequest instance. The Create OperandRequest page uses the Form View by default.

1. Provide the following parameters on the form:

   • Name: A name for your OperandRequest instance.
   • Requests: Expand the Requests drawer to specify the list of foundational services that you want to install in your cluster.
   • Operands - Expand the Operands drawer. In the name field, specify the operator name of the service that you want to install in your cluster. For the foundational services operator names, see Foundational services operators and versions. Click Add operand to add as many service operators as you need.
   • registry - Name of the OperandRegistry. Use common-service.
   • description - (Optional) Provide a description of your request.
   • registryNamespace - (Optional) Namespace of the OperandRegistry and OperandConfig.
     • If you do not specify any namespace, the Operand Deployment Lifecycle Manager looks for the OperandRegistry and OperandConfig in the same namespace where you are creating the OperandRequest. That is, ibm-common-services.
     • If you specify a namespace, the Operand Deployment Lifecycle Manager looks for the OperandRegistry and OperandConfig in the namespace that you specified.

2. Click Create.

You can see the list of services that are installed in your cluster on the Operators > Installed Operators page.

Creating the OperandRequest instance by using the YAML View

Complete the following steps to use the YAML to create the OperandRequest instance.

1. On the Create OperandRequest page, select YAML View.

2. Paste the following content in the YAML editor:

     apiVersion: operator.ibm.com/v1alpha1
     kind: OperandRequest
     metadata:
       name: common-service
       namespace: ibm-common-services
       labels:
         app.kubernetes.io/instance: operand-deployment-lifecycle-manager
         app.kubernetes.io/managed-by: operand-deployment-lifecycle-manager
         app.kubernetes.io/name: odlm
     spec:
       requests:
         - operands:
             - name: ibm-cert-manager-operator
             - name: ibm-mongodb-operator
             - name: ibm-iam-operator
             - name: ibm-monitoring-grafana-operator
             - name: ibm-healthcheck-operator
             - name: ibm-management-ingress-operator
             - name: ibm-licensing-operator
             - name: ibm-commonui-operator
             - name: ibm-events-operator
             - name: ibm-ingress-nginx-operator(deprecated)
             - name: ibm-auditlogging-operator
             - name: ibm-platform-api-operator
             - name: ibm-zen-operator
             - name: ibm-db2u-operator
             - name: cloud-native-postgresql
             - name: ibm-user-data-services-operator
             - name: ibm-zen-cpp-operator
             - name: ibm-bts-operator
           registry: common-service
   

   Note: You can create the OperandRequest in any namespace. If you are creating the OperandRequest in a different namespace than where OperandRegistry and OperandConfig custom resources are, change the namespace: parameter value to the namespace from where you are creating the OperandRequest. And, add the registryNamespace: ibm-common-services in the OperandRequest. See the following example:

     apiVersion: operator.ibm.com/v1alpha1
     kind: OperandRequest
     metadata:
       name: common-service
       namespace: <OperandRequest namespace>
     spec:
       requests:
         - operands:
             - name: ibm-cert-manager-operator
              .
              .
              .
           registry: common-service
           registryNamespace: ibm-common-services
   

3. In the spec.requests.operands section, retain the operator names of the services that you want to install in your cluster. You can remove the services that you do not want. For a list of foundational services that you can install, see IBM Cloud Pak foundational services operators and versions.

4. Add bindings to access a service. This step is optional. For more information, see Accessing the services.

5. Click Create.

You can see the list of services that are installed in your cluster on the Operators > Installed Operators page.

e. Installing network policies for foundational services

To install network policies, see Installing network policies for foundational services.

5. Verifying the installation

Check operator status

1. From the navigation pane, click Home > Overview. The cluster status is displayed.
2. Click Operators on the status card. The operator statuses are displayed.
3. Click View all. All the operators that are installed in the cluster are displayed.

4. Check the status of the foundational services operators. All operators must be in the Succeeded status.

   Note: If your operator does not show the Succeeded status, see Operator shows Pending status in a namespace.

Check pod status

To verify the installation, check whether all the pods in the foundational services namespace are running. By default, the namespace is ibm-common-services. You can check from the console by clicking Workloads > Pods under ibm-common-services project. You can also check with the CLI by running the following command:

oc get pods -n ibm-common-services

You can also use the following command to verify whether the foundational services are successfully installed:

oc -n ibm-common-services get csv

6. Accessing the console

Get the URL to access the console.

• Administration panel without the zen-cpp-operator extension installed

  You can get the IBM Cloud Pak console route for accessing the Administration panel by running the following command:

  oc get route -n ibm-common-services cp-console -o jsonpath='{.spec.host}' && echo
  

  The response is your <https://<cluster_address>. <cluster_address> is the IBM Cloud Pak console route.

  Following is a sample output:

  cp-console.apps.mycluster.mydomain.com
  

  Based on the example output, your console URL would be https://cp-console.apps.mycluster.mydomain.com.

• Administration panel with the zen-cpp-operator extension installed

  You can get the Cloud Pak Platform route for accessing the common landing page by running the following command:

  oc get route -n ibm-common-services cpd -o jsonpath='{.spec.host}' && echo
  

  The response is your <https://<cluster_address>. <cluster_address> is the Cloud Pak Platform route.

  Following is a sample output:

  cpd.apps.mycluster.mydomain.com
  

  To access the landing page, go to the following URL: <https://<cpd_address>/zen/#/homepage

  Based on the example output, your Cloud Pak Platform URL would be https://cpd.apps.mycluster.mydomain.com/zen/#/homepage.

Console username and password

The default username to access the console is admin. You can get the default username by running the following command:

oc -n ibm-common-services get secret platform-auth-idp-credentials -o jsonpath='{.data.admin_username}' | base64 -d && echo

You can get the password for the default username by running the following command:

oc -n ibm-common-services get secret platform-auth-idp-credentials -o jsonpath='{.data.admin_password}' | base64 -d

Following is a sample output:

EwK9dj9fwPZHyHTyu9TyIgh9klZSzVsA

Based on the example output, you would use EwK9dj9fwPZHyHTyu9TyIgh9klZSzVsA as the password.

You can change the default password at any time. For more information, see Changing the cluster administrator password.

Note: Any user with access to the ibm-common-services namespace can retrieve this password since it is stored in a secret in the ibm-common-services namespace. To minimize password exposure, allow limited users to access the ibm-common-services namespace.

Accessing Business Teams Service UI

Navigate to http://<cpd_host>/teamserver/ui to access the UI where the cpd-host is the cpd route. To obtain the cpd route, run the following command:

oc get route cpd

Log in with a user with a role that has the Administrate business teams permission. For more information, see Business Teams Service Authorization.

Enabling or disabling foundational services after installation

After you create an instance of the OperandRequest, you must use the same instance to enable or disable foundational services.

1. Ensure that you are in the ibm-common-services namespace.
2. Select the Operators > Installed Operators > Operand Deployment Lifecycle Manager > OperandRequest tab.
3. Edit the OperandRequest instance. You can enable a service by adding it into the spec.requests.operands list or disable a service by removing it from the spec.requests.operands list.
4. Update the YAML file with your changes and click Save.

Foundational services installation scenarios when multiple IBM Cloud Paks are installed in your cluster

If you install more than one IBM Cloud Pak in your cluster, and the IBM Cloud Paks have services in common, then the service installation ensures that the higher service version is retained in the cluster. Consider the following example scenarios:

• You installed IBM Cloud Pak 1 in your cluster, and you installed ServiceA Version 1.0 in IBM Cloud Pak 1. If you now install IBM Cloud Pak 2 with ServiceA Version 1.1, the ServiceA is automatically upgraded to Version 1.1 in your cluster.

• You installed IBM Cloud Pak 1 in your cluster, and you installed ServiceA Version 1.1 in IBM Cloud Pak 1. If you now install IBM Cloud Pak 2 with ServiceA Version 1.0, the ServiceA is retained at Version 1.1 in your cluster.

• You installed ServiceA Version 1.0 by using the Operator Lifecycle Manager (OLM). You then install an IBM Cloud Pak with a set of services that includes ServiceA Version 1.1.

  • If the foundational services installer finds that ServiceA is installed in the cluster but not by using the IBM Cloud Pak foundational services operator, the installer does not install ServiceA. You must manually install or upgrade to the required version.
  • The IBM Cloud Pak foundational services operator does not verify or manage any custom operator that you installed in your cluster. It manages only the operators that are in the OperandRegistry.

Foundational services operators and versions

In Table 1. Versions of operators that need to be manually installed and Table 2. Versions of operators that are automatically installed, following representations are used:

• NA means Not Applicable
• IV means Independent Version
• Operator version in 3.16.x means the operator version in installer version 3.16.x

Manually installed operators

You can install the following foundational services by using the IBM Cloud Pak foundational services operator:

Note: Some services depend on other services. When you install a service, the service operator also installs the dependencies. However, for a foundational service that you are installing, you must ensure that all its dependencies are installed. For more information, see Dependencies of the IBM Cloud Pak foundational services.

Automatically installed operators

The following operators are automatically installed when you install foundational services: