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

Important: You can install foundational services in only one namespace in your cluster.

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.

Prerequisites
Installing the IBM Cloud Pak foundational services operator
Setting the hardware profile
Installing foundational services in your cluster

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.

Create the IBM Cloud Pak foundational services catalog source.

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

Note: The image tag that is used here is for installing version 3.14.2.

 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.20-20211224.114031-815F91F3F
   updateStrategy:
     registryPoll:
       interval: 45m

Create the Operator.
```
oc apply -f ibm-operator-catalog.yaml
```
It might take up to a minute for the operator to be created.

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

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

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

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.

Edit the common-service resource.

oc -n ibm-common-services edit commonservice common-service

Update the spec.size parameter.

  apiVersion: operator.ibm.com/v3
  kind: CommonService
  metadata:
    name: common-service
    namespace: ibm-common-services
  spec:
    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

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-apicatalog
          - name: ibm-zen-cpp-operator
          - name: ibm-bts-operator
          - name: ibm-cloud-databases-redis-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

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. Note: If you are installing the IBM API Catalog service, you must install Cloud Native PostgreSQL in your cluster. The IBM API Catalog service depends on Cloud Native PostgreSQL.
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.

Note: If you installed the IBM API Catalog service, you can view the APIs on the console. For more information, see IBM API Catalog service console.