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.

  1. Prerequisites
  2. Creating the catalog sources
  3. Installing the operators
  4. Setting the hardware profile and accepting the license
  5. Configuring namespace permissions
  6. 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.

  1. Log in to the cluster by using the oc login command.

  2. Create the following catalog sources.

    • Foundational services catalog source

      1. 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
        
      2. Create the foundational services catalog source.

        oc apply -f opencloud-operators.yaml
        
      • Licensing service catalog source

        1. 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.2.0
             publisher: IBM
             sourceType: grpc
             image: icr.io/cpopen/ibm-licensing-catalog
             updateStrategy:
               registryPoll:
                 interval: 45m
          
        2. 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

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

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

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

See the following notes:

Complete these steps to install the resources:

  1. 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.2
       installPlanApproval: Automatic
       name: ibm-common-service-operator
       source: opencloud-operators
       sourceNamespace: openshift-marketplace
    
     ---
    
     apiVersion: v1
     kind: Namespace
     metadata:
       name: ibm-licensing
    
     ---
     apiVersion: operators.coreos.com/v1alpha2
     kind: OperatorGroup
     metadata:
       name: operatorgroup
       namespace: ibm-licensing
     spec:
       targetNamespaces:
       - ibm-licensing
    
     ---
     apiVersion: operators.coreos.com/v1alpha1
     kind: Subscription
     metadata:
       name: ibm-licensing-operator-app
       namespace: ibm-licensing
     spec:
       channel: v4.2
       installPlanApproval: Automatic
       name: ibm-licensing-operator-app
       source: ibm-licensing-catalog
       sourceNamespace: openshift-marketplace
    
  2. 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
    
  3. 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.2             IBM Cloud Pak foundational services            4.2       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

Complete these steps:

  1. Edit the common-service resource.

     oc -n <your-foundational-services-namespace> edit commonservice common-service
    
  2. 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
  1. 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>
    
  2. Add bindings to access a service. This step is optional. For more information, see Accessing the services.

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

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