Installing IBM Cloud Pak foundational services by using the CLI

You can use the command-line interface (CLI) to install IBM Cloud Pak foundational services in your cluster.

The IBM Cloud Pak foundational services operator installs IBM Cloud Pak foundational services in your cluster.

The IBM Cloud Pak foundational services operator, including the Operand Deployment Lifecycle Manager and all foundational services, by default, are installed in the <foundational-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 namespaces in the cluster. The IBM Cloud Pak foundational services operator 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 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 bootstraps the installation into the <foundational-services> namespace.

Prerequisites
Creating the catalog sources
Installing the operators
Setting the hardware profile and accepting the license
Configuring namespace permissions
Installing foundational services in your cluster

Prerequisites

For more information, see Prerequisites.

Creating the catalog sources

Create catalog sources that you need for foundational services installation.

Create the following catalog sources.

Foundational services catalog source

Create a YAML file named opencloud-operators.yaml with the following definition:

 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.1
   updateStrategy:
     registryPoll:
       interval: 45m

Create the foundational services catalog source.
```
 oc apply -f opencloud-operators.yaml
```

Licensing service catalog source

Create a YAML file named ibm-licensing-catalog.yaml with the following definition:

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

Create the licensing service catalog source.
```
 oc apply -f ibm-licensing-catalog.yaml
```

If you are using the foundational services certificate manager service, see Create cert-manager catalog source.

CloudNative PostgreSQL catalog source

Create a YAML file named cloud-native-catalog.yaml with the following definition:

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

Create the CloudNative PostgreSQL catalog source.
```
 oc apply -f cloud-native-catalog.yaml
```

It might take up to a minute for the catalog sources to be created.

Verify that all the catalog sources are created.

 oc -n openshift-marketplace get catalogsource ibm-common-service-catalog -o jsonpath="{.status.connectionState.lastObservedState}"

 oc -n openshift-marketplace get catalogsource ibm-licensing-catalog -o jsonpath="{.status.connectionState.lastObservedState}"

 oc -n openshift-marketplace get catalogsource ibm-cert-manager-catalog -o jsonpath="{.status.connectionState.lastObservedState}"

 oc -n openshift-marketplace get catalogsource cloud-native-postgresql-catalog -o jsonpath="{.status.connectionState.lastObservedState}"

Following is the expected output:

 READY

Installing the IBM Common Service Operator

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.

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 your IBM Cloud Pak namespace exists in your cluster, and you installed your IBM Cloud Pak but you don't see the IBM Cloud Pak foundational services operator in your IBM Cloud Pak namespace, then you need to create only the subscription for the IBM Cloud Pak foundational services operator. You do not need to create a namespace and OperatorGroup.
If your IBM Cloud Pak namespace does not exist in your cluster, then you need to create a namespace for your IBM Cloud Pak, and a OperatorGroup and subscription for the IBM Cloud Pak foundational services operator. In the Subscription definition, specify your IBM Cloud Pak namespace as the namespace parameter value.

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

Complete these steps to install the resources:

Create a YAML file named def.yaml with the resources definitions that you need.

 apiVersion: v1
 kind: Namespace
 metadata:
   name: <your IBM Cloud Pak namespace>

 ---
 apiVersion: operators.coreos.com/v1alpha2
 kind: OperatorGroup
 metadata:
   name: operatorgroup
   namespace: <your IBM Cloud Pak namespace>
 spec:
   targetNamespaces:
   - <your IBM Cloud Pak namespace>

 ---
 apiVersion: operators.coreos.com/v1alpha1
 kind: Subscription
 metadata:
   name: ibm-common-service-operator
   namespace: <your IBM Cloud Pak namespace>
 spec:
   channel: v4.1
   installPlanApproval: Automatic
   name: ibm-common-service-operator
   source: opencloud-operators
   sourceNamespace: openshift-marketplace

 ---
 apiVersion: operators.coreos.com/v1alpha1
 kind: Subscription
 metadata:
   name: ibm-licensing-operator
   namespace: ibm-licensing
 spec:
   channel: v4.1
   installPlanApproval: Automatic
   name: ibm-licensing-operator
   source: ibm-licensing-catalog
   sourceNamespace: openshift-marketplace

Create the resources that you specified in the definition file.

 oc apply -f def.yaml

Following is a sample output:

 namespace/cloud-pak-1 created
 operatorgroup.operators.coreos.com/operatorgroup created
 subscription.operators.coreos.com/ibm-common-service-operator created

If you are using the foundational services certificate manager service, see Install the IBM Cert Manager Operator.

After a few minutes, the operators are installed.

The IBM Cloud Pak foundational services operator creates the <foundational-services> namespace, or the custom namespace that you specified in the configmap, and installs the Operand Deployment Lifecycle Manager Operator in the namespace. The IBM Cloud Pak foundational services operator creates 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 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.

You can verify the status of the operators by running the following commands:

oc -n <operator-namespace> get csv

Following is a sample command and output:

oc -n <your IBM Cloud Pak&reg; namespace> get csv

NAME                                          DISPLAY                                       VERSION   REPLACES                                      PHASE
ibm-common-service-operator.v4.1.0             IBM Cloud Pak foundational services            4.1.0       ibm-common-service-operator.v3.23.0            Succeeded

Verify whether the CustomResourceDefinitions (CRDs) are created.

oc get crd | grep operandrequest

Following is a sample output:

NAME                               CREATED AT
operandrequests.operator.ibm.com   2020-09-18T10:10:22Z

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 small, medium, or large, if required.
- If you are using the foundational services certificate manager service, see Setting the hardware profile and accepting the license.
License: Accept the license to use foundational services by adding spec.license.accept: true in the spec section.

Complete these steps:

Edit the common-service resource.

 oc -n <your-foundational-services-namespace> edit commonservice common-service

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: <your-foundational-services-namespace>
 spec:
   license:
     accept: true
   size: starterset

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.

Installing foundational services in your cluster

You must create the OperandRequest to specify the services that you want to install in your cluster.

Before you install the foundational services by creating 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-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.

To edit the CommonService custom resource, run this command:

oc -n <your-foundational-services-namespace> edit commonservice common-service

Create a operand-request.yaml file with the following definition. Specify only the services that you want to install in your cluster. Remove the service entries (operands) that you do not want to install.

For a list of foundational services that you can install, see IBM Cloud Pak foundational services Operators and versions.

 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-user-data-services-operator
         - name: ibm-bts-operator
         - name: ibm-automation-flink
         - name: ibm-automation-elastic
         - 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>

Add bindings to access a service. This step is optional. For more information, see Accessing the services.
If you are installing Cloud Native PostgreSQL or IBM User Data Services Operator in your cluster, you need to create the entitled registry secret. For the steps to create the entitled registry secret, see Creating the entitled registry secret.
Create the OperandRequest instance.
```
 oc apply -f operand-request.yaml
```

To verify the installation, see Verifying the installation.

To access the console, see Accessing the console.