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 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 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 is deployed into the same namespace as your IBM Cloud Pak deployment by default.

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

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

If you are using License Service, see Installing License Service.
If you are using License Service Reporter, see Installing License Service Reporter with the CLI.
If you are using the foundational services certificate manager, see Installing IBM Cert Manager with the CLI.

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:0b46a3ec66622dd4a96d96243602a21d7a29cd854f67a876ad745ec524337a1f
   updateStrategy:
     registryPoll:
       interval: 45m

Note: You can create the Cloud Native PostgreSQL CatalogSource only by applying the image with the digest value that refers to the appropriate case bundle that is based on the Cloud Native PostgreSQL version.

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

(optional) IBM Business Team Service catalog source, create this catalog source if you are using this service.

Create a YAML file named bts-operator-catalog.yaml with the following definition:

 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

Create the IBM Business Team Service catalog source.
```
 oc apply -f bts-operator-catalog.yaml
```

(optional) IBM Automation Flink catalog source, create this catalog source if you are using this service.

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

 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: 45m

Create the IBM Automation Flink catalog source.
```
 oc apply -f flink-catalog.yaml
```

(optional) IBM Automation Elastic catalog source, create this catalog source if you are using this service.

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

 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

Create the IBM Automation Elastic catalog source.

 oc apply -f ibm-elastic-operator-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 opencloud-operators -o jsonpath="{.status.connectionState.lastObservedState}"

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

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

 oc -n openshift-marketplace get catalogsource bts-operator -o jsonpath="{.status.connectionState.lastObservedState}"

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

 oc -n openshift-marketplace get catalogsource ibm-elastic-operator-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.

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.6
  installPlanApproval: Automatic
  name: ibm-common-service-operator
  source: opencloud-operators
  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 License Service, see Installing License Service.
If you are using License Service Reporter, see Installing License Service Reporter with the CLI.
If you are using the foundational services certificate manager, see Install the IBM Cert Manager Operator.

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

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:
1. Excluding the following community CatalogSource: certified-operators, community-operators, redhat-marketplace, redhat-operators, ibm-cp-automation-foundation-catalog, operatorhubio-catalog
2. CatalogSources in operator namespace (private CatalogSource) have a higher priority than those in other namespaces (global CatalogSource).
3. CatalogSources with higher .spec.priority values will be picked up first.
4. 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.

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.6.0             IBM Cloud Pak foundational services            v4.6.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-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>

Add bindings to access a service. This step is optional. For more information, see Accessing the services.
If you are installing Cloud Native PostgreSQL, 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.