Installing IBM Cloud Pak foundational services by using the CLI

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.

   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:v1.25-20231212.144827-CE39CA95B
        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.

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

      apiVersion: v1
      kind: Namespace
      metadata:
        name: <your {{site.data.keyword.cloud_pak_notm}} namespace>
      
      ---
      apiVersion: operators.coreos.com/v1alpha2
      kind: OperatorGroup
      metadata:
        name: operatorgroup
        namespace: <your {{site.data.keyword.cloud_pak_notm}} namespace>
      spec:
        targetNamespaces:
        - <your {{site.data.keyword.cloud_pak_notm}} namespace>
      
      ---
      apiVersion: operators.coreos.com/v1alpha1
      kind: Subscription
      metadata:
        name: ibm-common-service-operator
        namespace: <your {{site.data.keyword.cloud_pak_notm}} namespace>
      spec:
        channel: v3
        installPlanApproval: Automatic
        name: ibm-common-service-operator
        source: ibm-operator-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
      

      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:

• Verify the status of ibm-common-service-operator.

  oc -n <dedicated-namespace> get csv
  

  Following is a sample command and output:

  oc -n common-service 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
  

• 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
  

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

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

  Note: For versions 3.5.x and 3.6.x, if you change the profile to large or medium, you cannot scale down the profile to small after installation. However, you can switch between large and medium, or scale up a profile after installation.

• License: Accept the license to use foundational services by adding spec.license.accept: true in the spec section.

1. Edit the common-service resource.

   oc -n ibm-common-services 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: ibm-common-services
   spec:
     license:
       accept: true
     size: small
   

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.