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.
- Prerequisites
- Creating the catalog sources
- Creating a namespace for foundational services
- Installing the operators from OperatorHub
- Setting the hardware profile and accepting the licenses
- Configuring namespace permissions
- Configuring the services
- Creating the entitled registry secret
- Installing foundational services in your cluster
- Accessing the foundational services console
For postinstallation options, see Enabling or disabling foundational services after installation.
Prerequisites
-
An OpenShift Container Platform cluster must be installed. For the supported OpenShift Container Platform versions, see Supported OpenShift versions and platforms.
-
Certificate Manager service must be installed. You can install any certificate manager service. See the following options:
Creating the catalog sources
Create catalog sources that you need for foundational services installation. Repeat these steps for each catalog source.
- Log in to your cluster console.
- Click the plus icon. You see the Import YAML dialog box.
- Create the catalog source by pasting the catalog source definition provided later.
- Click Create. The catalog source is created.
- 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:
-
Foundational services catalog source definition. Create this catalog source.
apiVersion: operators.coreos.com/v1alpha1 kind: CatalogSource metadata: name: opencloud-operators namespace: openshift-marketplace spec: displayName: IBMCS Operators publisher: IBM sourceType: grpc image: icr.io/cpopen/ibm-common-service-catalog:4.9 updateStrategy: registryPoll: interval: 45m
-
If you are using License Service, see Installing License Service.
-
If you are using License Service Reporter, see Installing License Service Reporter with the OpenShift console.
-
If you are using the foundational services certificate manager, see Installing IBM Cert Manager with the OpenShift console.
-
Cloud Native PostgreSQL catalog source definition. Create this catalog source.
apiVersion: operators.coreos.com/v1alpha1 kind: CatalogSource metadata: name: cloud-native-postgresql-catalog namespace: openshift-marketplace spec: displayName: Cloud Native PostgreSQL Catalog publisher: IBM sourceType: grpc image: icr.io/cpopen/ibm-cpd-cloud-native-postgresql-operator-catalog@sha256:0b46a3ec66622dd4a96d96243602a21d7a29cd854f67a876ad745ec524337a1f updateStrategy: registryPoll: interval: 45m
Note: You can only create the Cloud Native PostgreSQL CatalogSource by applying the image with digest value that refers to the appropriate case bundle based on the Cloud Native PostgreSQL version.
-
IBM Business Team Service catalog source definition (optional): Create this catalog source if you are using this service.
apiVersion: operators.coreos.com/v1alpha1 kind: CatalogSource metadata: name: bts-operator namespace: openshift-marketplace spec: displayName: BTS Operator publisher: IBM sourceType: grpc image: icr.io/cpopen/ibm-bts-operator-catalog:latest updateStrategy: registryPoll: interval: 5m
-
IBM Automation Flink catalog source definition (optional): Create this catalog source if you are using this service.
apiVersion: operators.coreos.com/v1alpha1 kind: CatalogSource metadata: name: flink-catalog namespace: openshift-marketplace spec: displayName: Flink SC2 catalog image: icr.io/cpopen/ibm-opencontent-flink-operator-catalog:sc2 publisher: IBM sourceType: grpc updateStrategy: registryPoll: interval: 5m
-
IBM Automation Elastic catalog source definition (optional): Create this catalog source if you are using this service.
apiVersion: operators.coreos.com/v1alpha1 kind: CatalogSource metadata: name: ibm-elastic-operator-catalog namespace: openshift-marketplace spec: displayName: ibm-elastic-operator-catalog image: icr.io/cpopen/ibm-cs-elastic-operator-catalog:latest publisher: IBM Content sourceType: grpc updateStrategy: registryPoll: interval: 45m
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:
- From your Red Hat OpenShift cluster console, 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.
Installing the operators from OperatorHub
Complete these tasks from your Red Hat® OpenShift® cluster console > Project: All Projects > Operators > OperatorHub page.
-
If you are using License Service, see Installing License Service.
-
If you are using License Service Reporter, see Installing License Service Reporter with the OpenShift console.
-
If you are using the foundational services certificate manager, see Installing IBM Cert Manager with the OpenShift console.
-
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.- 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 Update Channel to the
v4.9
version. - Set Installation Mode to
A specific namespace on the cluster
. Select your IBM Cloud Pak namespace from the Installed Namespace drop-down list. - Set Update approval to
Automatic
. - Click Install.
See the following notes:
-
You can set the approval strategy to either
Automatic
orManual
, as required. By default, the approval strategy is set toAutomatic
, which automatically installs or upgrades the operator when a new version is available. If you set the strategy toManual
, 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 toManual
. For more information, see Approval strategy.
- In the All Items field, enter
After a few minutes, you can see all the operators on the Installed Operators page.
Setting the hardware profile and accepting the licenses
-
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 tostarter
,small
,medium
,production
, orlarge
, if required. -
You can scale up a profile anytime after installation. If you change the profile to
large
ormedium
, you cannot scale down the profile tosmall
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 amedium
orlarge (production)
profile, and then you attempt to scale down to sizesmall
, the profile remains asmedium
. You can be able to scale down tosmall
only if there is no other Cloud Pak withmedium
orlarge (production)
size. You can be able to scale down to starterset (starter) profile with threecommon-service-db
replicasets. -
If you are using the foundational services certificate manager service, see Setting the hardware profile and accepting the license.
- The default profile is
-
License: Accept the licenses for the following services by adding
spec.license.accept: true
in thespec
section.
Complete the following steps:
- From the navigation pane, click Home > Search.
- From the Project drop-down list, select
foundational-services
. - From the Resources drop-down list, select
CommonService
. - Click the
common-service
resource. - Select the YAML tab.
-
Update the
spec.size
parameter to set the hardware profile, and update thespec.license.accept
parameter fromfalse
totrue
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
-
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.
-
Obtain the entitlement key that is assigned to your ID.
- Log in to Container Software Library by using the IBMid and password that are associated with the entitled software.
- In the Entitlement keys section, click Copy key to copy the entitlement key to the clipboard.
- Copy the key to a safe place. You need the key to create your pull secret.
-
(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
-
Log in to your OpenShift Container Platform cluster by using the
oc login
command. -
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 .
- <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:
-
Extract the current pull secret that is in the
openshift-config
namespace:oc extract secret/pull-secret -n openshift-config --keys=.dockerconfigjson --to=. --confirm
-
Convert the extracted pull secret by using
jq
command-line JSON processor. To installjq
, see jq command-line JSON processor .cat .dockerconfigjson | jq . > .dockerconfigjson.orig mv .dockerconfigjson.orig .dockerconfigjson
-
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
-
Make the following edits to the
.dockerconfigjson
file: In theauths
section, addcp.icr.io
to the existing list of objects. Replaceauth_string
with the base64 value that you got in the previous step. Important: You must enter the value ofauth_string
as a single, long string. If you insert any line returns, you get an error.{ "auths": { "cp.icr.io" : { "auth": "auth_string" } } }
-
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:
- 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.
-
OperatorConfig is for internal management of the operators.
NOTE: When the
sourceName
is not explicitly specified for an operator in the OperandRegistry, the Operand Deployment Lifecycle Manager (ODLM) looks for the available CatalogSource of an operator when creating the subscription:-
Excluding the following community CatalogSource:
certified-operators
,community-operators
,redhat-marketplace
,redhat-operators
,ibm-cp-automation-foundation-catalog
,operatorhubio-catalog
-
CatalogSources in operator namespace (private CatalogSource) have a higher priority than those in other namespaces (global CatalogSource).
-
CatalogSources with higher
.spec.priority
values will be picked up first. -
If both CatalogSources have the same namespace and priority, the CatalogSources are sorted based on their names in lexicographical order.
-
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.
-
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.
-
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
andOperandConfig
.- If you do not specify any namespace, the
Operand Deployment Lifecycle Manager
looks for theOperandRegistry
andOperandConfig
in the same namespace where you are creating theOperandRequest
. That is,foundational-services
. - If you specify a namespace, the
Operand Deployment Lifecycle Manager
looks for theOperandRegistry
andOperandConfig
in the namespace that you specified.
- If you do not specify any namespace, the
-
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.
-
On the Create OperandRequest page, select YAML View.
-
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 - name: ibm-elasticsearch-operator - name: ibm-events-operator registry: common-service
Note: You can create the
OperandRequest
in any namespace. If you are creating theOperandRequest
in a different namespace than whereOperandRegistry
andOperandConfig
custom resources are, change thenamespace:
parameter value to the namespace from where you are creating theOperandRequest
. And, add theregistryNamespace: <your-foundational-services-namespace>
in theOperandRequest
. 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>
-
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. -
Add bindings to access a service. This step is optional. For more information, see Accessing the services.
-
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
- From the navigation pane, click Home > Overview. The cluster status is displayed.
- Click Operators on the status card. The operator statuses are displayed.
- Click View all. All the operators that are installed in the cluster are displayed.
-
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.
- Ensure that you are in the
foundational-services
namespace. - Select the Operators > Installed Operators > Operand Deployment Lifecycle Manager > OperandRequest tab.
- Edit the
OperandRequest
instance. You can enable a service by adding it into thespec.requests.operands
list, or disable a service by removing it from thespec.requests.operands
list. - Update the YAML file with your changes and click Save.