Preparing to install foundational services

Before you install, review the following installation requirements.

Existing instance of foundational services in the cluster

If you already have foundational services version 4.0.x installed in the cluster, you must configure the common-service-maps ConfigMap. For more information, see Installing IBM Cloud Pak foundational services in multiple namespaces.

Identifying if foundational services version 4.0.x is installed in the cluster

To identify if you have foundational services version 4.0.x is installed in the cluster, check if the CSV of ibm-common-service-operator is on version 4.x.x by running the following command:

oc get csv -A | grep ibm-common-service-operator

The following example shows the output of the preceding command:

$ oc get csv -A | grep ibm-common-service-operator
cloudpak-control-2                                 ibm-common-service-operator.v4.0.0             IBM Cloud Pak foundational services    4.0.0                                                    Succeeded
cloudpak-control-3                                 ibm-common-service-operator.v4.0.0             IBM Cloud Pak foundational services    4.0.0                                                    Succeeded
cloudpak2-cs3-only                                 ibm-common-service-operator.v3.23.3            IBM Cloud Pak foundational services    3.23.3                                                   Succeeded
cloudpak2-csv3                                     ibm-common-service-operator.v3.19.12           IBM Cloud Pak foundational services    3.19.12   ibm-common-service-operator.v3.19.11           Succeeded
ibm-common-services                                ibm-common-service-operator.v3.19.12           IBM Cloud Pak foundational services    3.19.12                                                  Succeeded

Provisioning storage for installing on Linux on IBM Z and LinuxONE

Before you can install foundational services on Linux on IBM Z and LinuxONE, you need to provision your Red Hat® OpenShift® Container Platform clusters with persistent storage by using Openshift Container Storage (OCS). If you are using Red Hat® OpenShift® Container Platform version 4.6, you can use OCS to provision persistent storage. For more information, see NFS support and configuration in foundational services.

Red Hat® OpenShift® Container Platform cluster

Hardware sizing requirement

For the hardware requirements, see Hardware requirements and recommendations for foundational services.

Version of Red Hat® OpenShift® Container Platform

Red Hat® OpenShift® Container Platform CLI tools

If there are no Red Hat® OpenShift® Container Platform CLI tools on the boot node, you need to download, decompress, and install the Red Hat® OpenShift® Container Platform CLI tools oc from Red Hat® OpenShift® Container Platform client binaries Opens in a new tab.

OpenShift console availability

Available storage class

Ensure that you have a pre-configured storage class in Red Hat® OpenShift® Container Platform that can be used for creating storage for IBM Cloud Pak foundational services. You need persistent storage for some of the service pods.

You can use the following command to get the storage classes that are configured in your cluster. Pick a storage class that provides block storage.

oc get storageclasses

Following is a sample output:

NAME                                  PROVISIONER                     AGE
rook-ceph-block-internal              rook-ceph.rbd.csi.ceph.com      42d
rook-ceph-cephfs-internal (default)   rook-ceph.cephfs.csi.ceph.com   42d
rook-ceph-delete-bucket-internal      ceph.rook.io/bucket             42d

For an OpenShift cluster that runs on IBM Cloud®, ibmc-block-gold is always available. For installing IBM Cloud Pak foundational services on IBM Cloud®, you might need to use the ibmc-block-gold storage class. For more information, see Deciding on the block storage configuration.

oc get sc

Example output:

  NAME                          PROVISIONER         AGE
  default                       ibm.io/ibmc-file    4h
  ibmc-block-bronze (default)   ibm.io/ibmc-block   4h
  ibmc-block-custom             ibm.io/ibmc-block   4h
  ibmc-block-gold               ibm.io/ibmc-block   4h
  ibmc-block-retain-bronze      ibm.io/ibmc-block   4h
  ibmc-block-retain-custom      ibm.io/ibmc-block   4h
  ibmc-block-retain-gold        ibm.io/ibmc-block   4h
  ibmc-block-retain-silver      ibm.io/ibmc-block   4h
  ibmc-block-silver             ibm.io/ibmc-block   4h
  ibmc-file-bronze              ibm.io/ibmc-file    4h
  ibmc-file-custom              ibm.io/ibmc-file    4h
  ibmc-file-gold                ibm.io/ibmc-file    4h
  ibmc-file-retain-bronze       ibm.io/ibmc-file    4h
  ibmc-file-retain-custom       ibm.io/ibmc-file    4h
  ibmc-file-retain-gold         ibm.io/ibmc-file    4h
  ibmc-file-retain-silver       ibm.io/ibmc-file    4h
  ibmc-file-silver              ibm.io/ibmc-file    4h

The default storage class is marked as (default).

The foundational services installer uses the default storage class to install MongoDB and Logging services. If you want to set the default storage class or update the default storage class in your Red Hat® OpenShift® Container Platform, see Change the default StorageClassOpens in a new tab.

The storage class provisioner is defined in the PROVISIONER list. To enable dynamic volume provisioning, see Enabling Dynamic ProvisioningOpens in a new tab.

Using Azure File storage class

To use Azure File storage class with IBM Cloud Pak foundational services on Azure environments, complete the following steps before you create the storage class.

  1. Create a project for installing IBM Cloud Pak foundational services.
  2. Run the following command to retrieve the ssc.uid-range of the project:

    oc describe project <project_name>
    

    In the annotations, find the value of ssc.uid-range and save it. Following is the sample output:

    openshift.io/sa.scc.uid-range: 1000630000/10000
    
  3. When you create the Azure File storage class, set the following MonutOptions:

    mountOptions:
    - dir_mode=0777
    - file_mode=0777
    - uid=<retrieved_uid>
    

    where uid is the initial part of the value of ssc.uid-range that you retrieved in step 2.

    For example:

    mountOptions:
    - dir_mode=0777
    - file_mode=0777
    - uid=1000630000
    

Multiple zones requirement

The following prequisites are applicable if you are installing foundational services in a cluster that has multiple zones.

Storage class

The storage class that you use for the foundational services must have its volumeBindingMode set to WaitForFirstConsumer.

You might need to create your own storage class to set the volumeBindingMode. In the following example, the ibmc-block-gold storage class that is available for clusters on IBM Cloud® is used as a template for creating a custom storage class.

allowVolumeExpansion: true
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  labels:
    app: ibmcloud-block-storage-plugin
  name: ibmc-block-wffc
parameters:
  billingType: hourly
  classVersion: "2"
  fsType: ext4
  iopsPerGB: "10"
  sizeRange: '[20-4000]Gi'
  type: Endurance
provisioner: ibm.io/ibmc-block
reclaimPolicy: Delete
volumeBindingMode: WaitForFirstConsumer

Required Kubernetes labels

In an on-premises, multizone Red Hat OpenShift Container Platform cluster, if you want the foundational services replicas to be equally spread across zones, you must add the following labels to each worker node. For more information, see topology.kubernetes.io/region and topology.kubernetes.io/zone.

Important: If you do not add these two labels, Kubernetes might not equally balance the foundational services across zones.

Configure Red Hat® OpenShift® Container Platform cluster for foundational services

Before you install foundational services, you must configure your Red Hat® OpenShift® Container Platform cluster for services.

Networking

Logging

Elasticsearch

For Elasticsearch, ensure that the vm.max_map_count setting is at least 262144 on all nodes. Run the following command to check:

sudo sysctl -a | grep vm.max_map_count

If the vm.max_map_count setting is not at least 262144, complete these steps to set the value to 262144:

  1. Define a custom resource with the vm.max_map_count set to 262144. See the following example:

    1. Use any editor to create a YAML file.

      vi tuned-cs-es-yaml
      
    2. Add the following content to the YAML file.

      apiVersion: tuned.openshift.io/v1
      kind: Tuned
      metadata:
       name: common-services-es
       namespace: openshift-cluster-node-tuning-operator
      spec:
       profile:
       - data: |
           [sysctl]
           vm.max_map_count=262144
         name: common-services-es
       recommend:
       - priority: 10
         profile: common-services-es
      
  2. Create the custom resource.

    oc create -f <YAML-file-name>
    

    Following command uses the example YAML file.

    oc create -f tuned-cs-es-yaml
    

Control installation of Certificate manager operands

Pre-requisites:

Important:

Certificate manager operator (ibm-cert-manager-operator) installs the following three deployments as part of its operands:

These operands are forked from CNCF cert-manager, and are responsible for managing Certificates. These operands, however, can only be installed on a cluster once. Multiple instances on a cluster cause unexpected behavior, which is an issue when a cluster already has a CNCF cert-manager installed before the installation of foundational services.

Note: The following procedure works for clusters which have a CNCF cert-manager installed with via Helm, YAML files (kubectl apply), or OLM operator.

Steps

Complete the following steps before installing foundational services. These steps will configure ibm-cert-manager-operator to make use of an existing CNCF cert-manager that is already installed, so that no additional operands are installed.

  1. Create the ibm-cpp-config configmap in namespace where foundational services will be installed in.
  2. Add deployCSCertManagerOperands: "false" to the data.

    The following is a sample output:

    kind: ConfigMap
    apiVersion: v1
    metadata:
     name: ibm-cpp-config
     namespace: ibm-common-services
    data:
     deployCSCertManagerOperands: "false"