Installing IBM Cloud Pak foundational services by using the OpenShift console

You can use the IBM Cloud Pak foundational services operator to install IBM Cloud Pak foundational services in your cluster. Use the following procedure to install IBM Cloud Pak foundational services version 3.12.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 IBM Cloud Pak foundational services Operators and versions.

See the following notes:

• If the IBM Cloud Pak 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 will bootstrap the installation into the ibm-common-services namespace.
• The following instructions are for installing IBM Cloud Pak 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.
• You can install foundational services in only one namespace in your cluster.

Installation steps

1. Prerequisites
2. Installing the IBM Cloud Pak foundational services operator
3. Setting the hardware profile
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. Verifying the installation
6. Accessing the console
   • Console username and password

Post-installation options

• Enabling or disabling foundational services after installation

Reference

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

• IBM Cloud Pak 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 IBM Cloud Pak foundational services operator

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

1. Create the IBM Cloud Pak foundational services catalog source.

   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 source. You need to create a CatalogSource.

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

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

      Note: The image tag that is used in the following definition is for installing foundational services version 3.12.1.

       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:v1.20-20211021.212837-69B421A7C
         updateStrategy:
           registryPoll:
             interval: 45m
      

   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:

     1. From the navigation pane, click Home > Projects. The Projects page is displayed.

     2. Click Create Project. A Create Project area is displayed.

     3. Enter details of the namespace that you are creating. You can specify your IBM Cloud Pak namespace as the name.

     4. 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:

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

     2. In the All Items field, enter IBM Cloud Pak foundational services. The IBM Cloud Pak foundational services operator is displayed.

     3. Click the IBM Cloud Pak foundational services tile. The IBM Cloud Pak foundational services window is displayed.

     4. Click Install. You see the Install Operator page.

     5. Set Installation Mode to your IBM Cloud Pak namespace.

     6. Set Update Channel to the v3 version.

     7. 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, if required. By default, the Approval strategy is set to Automatic. If the Approval strategy is set to Automatic, the operator is automatically installed or upgraded 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 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 installed with this operator.

        • If you install the IBM Cloud Pak foundational services operator in a namespace where another operator is installed that already has the installPlanApproval: Manual set in its subscription, then the IBM Cloud Pak foundational services operator inherits this setting. The approval plan is set to Manual and IBM Cloud Pak foundational services operator cannot be automatically installed or upgraded.

        • For more information, see Approval strategy.

     8. 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 IBM Cloud Pak foundational services webhook. For more information, see IBM Cloud Pak foundational services webhook.

3. Setting the 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 small, medium, or large, if required.

Note: For versions 3.5.x and 3.6.x, if you change the profile to large or medium, you cannot scale down the profile to small after installation. However, you can switch between large and medium, or scale up a profile after installation.

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 CommonServices.

4. Click the common-service resource.

5. Select the YAML tab.

6. Update the spec.size parameter.

     apiVersion: operator.ibm.com/v3
     kind: CommonService
     metadata:
       name: common-service
       namespace: ibm-common-services
     spec:
       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.

3. 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.

4. 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 these steps to configure the services and create the OperandRequest:

1. 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 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.

2. Configuring namespace permissions

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

3. 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 Operator in your cluster.

Note: If you are installing the IBM API Catalog service, you must install Cloud Native PostgreSQL in your cluster. The IBM API Catalog service depends on Cloud Native PostgreSQL.

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. 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>
   

   Here 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.

Follow these 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 will 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

4. 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 these 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 IBM Cloud Pak 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.

     Note: If you are installing the ibm-user-data-services-operator, update the OperandRegistry for the common-service instance and set the channel name to alpha for the ibm-user-data-services section. Alternatively, create a new OperandRegistry instance and add the following content for ibm-user-data-services-operator.

       - channel: alpha
         installPlanApproval: Automatic
         name: ibm-user-data-services-operator
         namespace: ibm-common-services
         packageName: ibm-user-data-services-operator
         scope: public
         sourceName: ibm-operator-catalog
         sourceNamespace: openshift-marketplace
     

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 these 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-apicatalog
             - name: ibm-user-data-services-operator
             - name: ibm-zen-cpp-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
   

1. (Optional) If you are installing the ibm-user-data-services-operator, update the OperandRegistry for the common-service instance and set the channel name to alpha for the ibm-user-data-services section. Alternatively, create a new OperandRegistry instance and add the following content for ibm-user-data-services-operator.

        - channel: alpha
          installPlanApproval: Automatic
          name: ibm-user-data-services-operator
          namespace: ibm-common-services
          packageName: ibm-user-data-services-operator
          scope: public
          sourceName: ibm-operator-catalog
          sourceNamespace: openshift-marketplace
   

2. 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.

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

4. Click Create.

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

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 should be in the Succeeded status.

   Note: If your operator is not in 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. The username and password are defined in the config.yaml file.

• 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 the IBM API Catalog service console

If you installed the IBM API Catalog service, you can view the APIs on the console. For more information, see IBM API Catalog service console.

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 Operand Request instance. You can enable it by adding it into the spec.requests.operands list or disable it by removing it from the spec.requests.operands list.

4. Update the YAML file with your changes and click Save.

Foundational service 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.

IBM Cloud Pak foundational services operators and versions

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 the dependencies are installed. For more information, see Dependencies of the IBM Cloud Pak foundational services.