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. Use the following procedure to install IBM Cloud Pak foundational services version 3.23.x.

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 of the foundational services, by default, are installed in the ibm-common-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 of the namespaces in the cluster. The IBM Cloud Pak foundational services operator manages the lifecycle of all foundational services operators. For more information about the foundational services that are available and their Operator names and versions, see IBM Cloud Pak 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 will bootstrap the installation into the ibm-common-services namespace.

  1. Prerequisites
  2. Installing the IBM Cloud Pak foundational services operator
  3. Setting the hardware profile and accepting the license
  4. Installing foundational services in your cluster
  5. Installing network policies for foundational services

1. Prerequisites

An OpenShift Container Platform cluster must be installed. For the supported OpenShift Container Platform versions, see Supported OpenShift versions and platforms.

2. Installing the IBM Common Service Operator

You must complete these tasks from your boot node.

  1. Create the IBM Cloud Pak foundational services catalog source.

    Note: Creating catalog source in a private namespace is not supported. The only supported scenario is to create the catalog source in the openshift-marketplace namespace.

    1. Log in to the cluster by using the oc login command.
    2. Create a YAML file named ibm-operator-catalog.yaml with the following Operator definition:

      apiVersion: operators.coreos.com/v1alpha1
      kind: CatalogSource
      metadata:
        name: ibm-operator-catalog
        namespace: openshift-marketplace
      spec:
        displayName: ibm-operator-catalog
        publisher: IBM Content
        sourceType: grpc
        image: icr.io/cpopen/ibm-operator-catalog@sha256:ef0641b95201580d19a59b86560e4390ecbbb9f5866d9eea5073bb355eafa0b4
        updateStrategy:
          registryPoll:
            interval: 45m
      
    3. Create the operator.

      oc apply -f ibm-operator-catalog.yaml
      

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

    4. Verify that all the operator packages are created.

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

      Following is the expected output:

      READY
      
  2. 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 ibm-common-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:

      • Starting from version 3.8.0, you can decide on the approval strategy by setting the subscription InstallPlanApproval to either Automatic or Manual, if required. By default, the InstallPlanApproval is set to Automatic. If the approval strategy is set to Automatic, the operator is automatically installed or upgraded when a new version is available. If you set the installPlanApproval parameter to Manual, the operator is not automatically installed or upgraded. Instead, you get an install plan that needs to be manually approved.

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

    • 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: v3.23
           installPlanApproval: Automatic
           name: ibm-common-service-operator
           source: ibm-operator-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
      

      After a few minutes, the IBM Cloud Pak foundational services operator and the Operand Deployment Lifecycle Manager operator are installed.

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

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

oc -n <dedicated-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.v3.7.1            IBM Cloud Pak foundational services            3.7.1     ibm-common-service-operator.v3.7.0            Succeeded
oc get crd | grep operandrequest

Following is a sample output:

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

Optionally, configure the IBM Cloud Pak foundational services webhook. For more information, see IBM Cloud Pak foundational services webhook.

3. Setting the hardware profile and accepting the license

4. 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, that is create 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-iam-operator creates a default cluster administrator by the name admin during installation. If you already have a user by the name admin in your cluster, you must set the defaultAdminUser parameter before you install foundational services. This is to avoid your admin 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 ibm-common-services 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: common-service
        namespace: ibm-common-services
      spec:
        requests:
          - operands:
              - name: ibm-cert-manager-operator
              - name: ibm-mongodb-operator
              - name: ibm-iam-operator
              - name: ibm-monitoring-grafana-operator
              - name: ibm-healthcheck-operator
              - name: ibm-management-ingress-operator
              - name: ibm-licensing-operator
              - name: ibm-commonui-operator
              - name: ibm-events-operator
              - name: ibm-ingress-nginx-operator
              - name: ibm-auditlogging-operator
              - name: ibm-platform-api-operator
              - name: ibm-zen-operator
              - name: ibm-db2u-operator
              - name: cloud-native-postgresql
              - name: ibm-user-data-services-operator
              - name: ibm-zen-cpp-operator
              - name: ibm-bts-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: ibm-common-services in the OperandRequest. See the following example:

      apiVersion: operator.ibm.com/v1alpha1
      kind: OperandRequest
      metadata:
        name: common-service
        namespace: <OperandRequest namespace>
      spec:
        requests:
          - operands:
              - name: ibm-cert-manager-operator
               .
               .
               .
            registry: common-service
            registryNamespace: ibm-common-services
    
  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.

5. Installing network policies for foundational services

To install network policies, see Installing network policies for foundational services.