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, and manages the lifecycle of all foundational services operators. For more information about the service operator names and versions, see Foundational services operators and versions.

Note: 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 theIBM Cloud Pak foundational services operator. The IBM Cloud Pak foundational services operator is deployed into the same namespace as your IBM Cloud Pak deployment by default.

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.

Complete these tasks from your Red Hat® OpenShift® cluster console to install the latest version of foundational services operator.

  1. Prerequisites
  2. Creating the catalog sources
  3. Creating a namespace for foundational services
  4. Installing the operators from OperatorHub
  5. Setting the hardware profile and accepting the licenses
  6. Configuring namespace permissions
  7. Configuring the services
  8. Creating the entitled registry secret
  9. Installing foundational services in your cluster
    1. Creating the OperandRequest instance
  10. Accessing the foundational services console

For postinstallation options, see Enabling or disabling foundational services after installation.

Prerequisites

Creating the catalog sources

Create catalog sources that you need for foundational services installation. Repeat these steps for each catalog source.

  1. Log in to your cluster console.
  2. Click the plus icon. You see the Import YAML dialog box.
  3. Create the catalog source by pasting the catalog source definition provided later.
  4. Click Create. The catalog source is created.
  5. Verify that the source container is ready. Use the console or the command-line interface (CLI) for verifying. The catalog source pod must have the Running status.
    • On the cluster console, see Project: openshift-marketplace > Workloads > Pods.
    • On the CLI, run the following command:
        oc -n openshift-marketplace get pod

Following are the catalog source definitions:

Creating a namespace for foundational services

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 foundational-services namespace.

If you need to create a namespace, complete the following steps:

  1. From your Red Hat OpenShift cluster console, 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.

Installing the operators from OperatorHub

Complete these tasks from your Red Hat® OpenShift® cluster console > Project: All Projects > Operators > OperatorHub page.

  1. If you are using License Service, see Installing License Service.

  2. If you are using License Service Reporter, see Installing License Service Reporter with the OpenShift console.

  3. If you are using the foundational services certificate manager, see Installing IBM Cert Manager with the OpenShift console.

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

    The IBM Cloud Pak foundational services operator installs the Operand Deployment Lifecycle Manager operator in the namespace.

    1. In the All Items field, enter IBM Cloud Pak foundational services. The IBM Cloud Pak foundational services operator is displayed.
    2. Click the IBM Cloud Pak foundational services tile. The IBM Cloud Pak foundational services window is displayed.
    3. Click Install. You see the Install Operator page.
    4. Set Update Channel to the v4.6 version.
    5. Set Installation Mode to A specific namespace on the cluster. Select your IBM Cloud Pak namespace from the Installed Namespace drop-down list.
    6. Set Update approval to Automatic.
    7. Click Install.

    See the following notes:

    • You can set 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.

After a few minutes, you can see all the operators on the Installed Operators page.

Setting the hardware profile and accepting the licenses

Complete the following steps:

  1. From the navigation pane, click Home > Search.
  2. From the Project drop-down list, select foundational-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 update the spec.license.accept parameter from false to true to accept the license.

    apiVersion: operator.ibm.com/v3
kind: CommonService
metadata:
  name: common-service
  namespace: <your-foundational-services-namespace>
spec:
  license:
    accept: true
  size: starterset

  7. Click Save.

Configuring namespace permissions

For some topologies, you must 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.

Configuring the services

Before you install foundational services, you can customize the configuration of the foundational services that you are installing.

For more information, see Configuring foundational services.

Note: The ibm-im-operator creates a default cluster administrator by the name cpadmin during installation. If you already have a user by the name cpadmin in your cluster, you must set the defaultAdminUser parameter before you install foundational services. This setting is to avoid your cpadmin user from being removed if you uninstall foundational services later. For more information about setting this parameter, see Changing the default admin username.

Creating the entitled registry secret

You need to create the entitled registry secret only if you are installing Business Teams Service and Cloud Native PostgreSQL in your cluster.

To create the entitled registry secret, complete these steps. Create the secret in the namespace where you are installing the foundational services. The default namespace is foundational-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 Opens in a new tab 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>

    You need to designate these variables:

    • <entitlement_key> is the value of your entitlement key that you copied earlier from Container Software Library Opens in a new tab.
    • <target_namespace> is the namespace where you are installing foundational services in your cluster. The default namespace that you can use here is foundational-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 Opens in a new tab.

    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 Opens in a new tab. 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 you insert 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

Installing foundational services in your cluster

From your foundational-services namespace > Operators > Installed Operators page, you see the IBM Cloud Pak foundational services operator and the Operand Deployment Lifecycle Manager operator.

The Operand Deployment Lifecycle Manager provides the following APIs:

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

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.

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, foundational-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: <custom-name-of-operand-request>
  namespace: <your-foundational-services-namespace>
  labels:
    app.kubernetes.io/instance: operand-deployment-lifecycle-manager
    app.kubernetes.io/managed-by: operand-deployment-lifecycle-manager
    app.kubernetes.io/name: operand-deployment-lifecycle-manager
spec:
  requests:
    - operands:
        - name: ibm-im-operator
        - name: ibm-platformui-operator
        - name: cloud-native-postgresql
        - name: ibm-bts-operator
        - name: ibm-opencontent-flink-operator
        - name: ibm-elasticsearch-operator
        - name: ibm-events-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: <your-foundational-services-namespace> in the OperandRequest. See the following example:

    apiVersion: operator.ibm.com/v1alpha1
kind: OperandRequest
metadata:
  name: <custom-name-of-operand-request>
  namespace: <OperandRequest namespace>
spec:
  requests:
    - operands:
        - name: ibm-im-operator
         .
         .
         .
      registry: common-service
      registryNamespace: <your-foundational-services-namespace>

  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.

Verifying the installation

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

Checking pod status

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

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

Use the following command to verify whether the foundational services are successfully installed:

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

Accessing the foundational services console

Retrieve your access URL, username, and password.

Getting the console URL

Get the URL to access the console.

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

oc get route -n <your-foundational-services-namespace> 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.

Getting the console username

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

oc -n <your-foundational-services-namespace> get secret platform-auth-idp-credentials -o jsonpath='{.data.admin_username}' | base64 -d && echo

Getting the password

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

oc -n <your-foundational-services-namespace> get secret platform-auth-idp-credentials -o jsonpath='{.data.admin_password}' | base64 -d &&echo

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 foundational-services namespace can retrieve this password since it is stored in a secret in the foundational-services namespace. To minimize password exposure, allow limited users to access the foundational-services namespace.

Accessing Business Teams Service console

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