Setting up the cluster by running a script

To install the Cloud Pak capabilities with the Cloud Pak operators, a cluster administrator user can run a script to set up the cluster. They can also run the script in silent mode if set of environment variables are created before the script is run. The administrator must also provide information that they get from the script to a non-administrator user so they can run the deployment script.

Before you begin

Make sure you prepared your cluster with the necessary infrastructure and software. For more information, see Option 1: Preparing your cluster for an online deployment.

About this task

The cluster setup script is one of four core scripts (cluster setup, prerequisites, deployment, and post-install) that are provided to help you install the Cloud Pak capabilities. You must be a cluster administrator to run the setup script. For more information, see Targeted role-based user archetypes.

The cluster setup script identifies or creates a namespace and applies the custom resource definitions (CRD). It then adds the specified user to the ibm-cp4a-operator role, binds the role to the service account, and applies a security context constraint (SCC) for the Cloud Pak.

The script also prompts the administrator to take note of the cluster hostname and a dynamic storage class on the cluster. These names must be provided to the user who runs the deployment script.

Note: You can run the scripts on an amd64/x86 machine that connects to a Linux on Z or a Linux on Power based cluster where the client is running Red Hat (RHEL), or a client to a Linux-based machine or virtual machine that can run Podman. The setup script does not set any parameters in the custom resource (CR). The cluster administrator might be running the script on a different host than the user who later runs the deployment script.

A new installation of Cloud Pak for Business Automation always includes a namespace-scoped instance of foundational services when you use the scripts. The only exception is when the OpenShift Container Platform (OCP) cluster already has an existing IBM Cloud Pak deployment that uses a cluster-scoped instance of foundational services. In this case, the new CP4BA deployment uses the instance in the ibm-common-services namespace. In other words, you cannot have a cluster-scoped and a namespace-scoped foundational services in the same cluster.

Tip: You can check whether a foundational services instance is installed by running the following command:

oc get cm ibm-common-services-status -n kube-public -o yaml

If the output fails to find the configMap, it means that foundational services are not installed. If foundational services are installed, then the output of the command shows the status of the installed foundational services:

apiVersion: v1
data:
  2201s-iamstatus: Ready
  cp4ba-iamstatus: Ready
  iamstatus: Ready
  ibm-common-services-iamstatus: Ready
kind: ConfigMap

To check that the instance is not namespace-scoped, you can look for the common-service-maps configMap.

oc get configmap common-service-maps

If no common-service-maps configMaps are found, then the instance is cluster-scoped.

The namespace-scoped foundational services instance is set up by the cp4a-clusteradmin-setup.sh script by adding a configMap (common-service-maps) on the OpenShift Container Platform (OCP) cluster to define the namespace. It checks for an existing common-service-maps configMap, and if it does not exist it creates it.

It is recommended that if you create the configMap before you run the script, then set the namespace of the foundational services to the target namespace. This namespace can be the same as the Cloud Pak for Business Automation deployment, but does not have to be.

Use the following steps to complete the setup.

Procedure

Download the appropriate repository to a Linux® based machine (RHEL) or a client to a linux-based machine or VM that runs podman natively.

For more information about downloading cert-kubernetes, see Option 1: Preparing your cluster for an online deployment.
Optional: If you want to run the script in silent mode, create the environment variables that are needed for your installation. For more information, see Environment variables for installation in silent mode.

Using the OpenShift CLI:

oc login https://<cluster-ip>:<port> -u <cluster-admin> -p <password>

On ROKS, if you are not already logged in:

oc login --token=<token> --server=https://<cluster-ip>:<port>

Run the cluster setup script from where you downloaded the cert-kubernetes repository, and follow the prompts in the command window if the script is not in silent mode.
```
cd cert-kubernetes/scripts
./cp4a-clusteradmin-setup.sh 
```
Remember: The cert-kubernetes folder is under [PATH_TO_EXTRACTED_FILES]/ibm-cp-automation/inventory/cp4aOperatorSDK/files/deploy/crs.
1. Select the platform type: ROKS (1) or OCP (2).
2. Select the deployment type production.
3. Select Yes if you want to install the CP4BA operator in 'All Namespaces'. The default is No.
4. Enter the name for a new project or an existing project (cp4ba-project) for the target deployment namespace. For more information, see Preparing a namespace for the Cloud Pak operator.
  If an existing CP4BA operator is found in another project on your cluster, confirm that you want to deploy another CP4BA operator in the new project by entering Yes. You must install a CP4BA operator in each namespace where you want to install a CP4BA instance.
5. Enter Yes or No to confirm whether you want to use the images in the IBM Entitlement Registry.
6. If you replied Yes, enter your IBM Entitled Registry key and login credentials (user and password).
  If you want to load the container images to a local registry, then set up the cluster by mirroring the images instead of running the cp4a-clusteradmin-setup.sh script. For more information, see Setting up the cluster by mirroring the container images.
  Tip: If you ran the cp4a-clusteradmin-setup.sh script and you see one or more of the following messages, then make sure that you start Docker or Podman and run the script again.
```
Error saving credentials: error storing credentials
Error: unable to connect
The Entitlement Registry key failed
```
Monitor the operator pods until they show a STATUS of "Running".
```
oc get pod -w
```
Tip: If ibm-cp4a-operator is inactive for some time, you can delete the operator pod and let it reconcile.
To confirm that the operator is stuck, check to see whether the log is providing an output.
```
oc project <namespace of Cloud Pak for Business Automation operator>
NAMESPACE=$(oc project -q)
podname=$(oc get pod -n $NAMESPACE | grep ibm-cp4a-operator | awk '{print $1}')
oc logs $podname -f
```
You can also list the ClusterServiceVersion (CSV) to verify the version of the running operators on your cluster.
```
oc get csv -n $NAMESPACE
```
Note: The version number (22.2.0) of the installed operators corresponds to the channel for Cloud Pak for Business Automation 22.0.2.

Results

When the script is finished, all of the available storage class names are displayed along with the infrastructure node name. Take a note of the following information and provide it to the Cloud Pak admin user as they are needed for the deployment script:

Project name or namespace.
Username to log in to the cluster.

When the common-service-maps configMap is applied to the cluster, each CP4BA deployment uses the foundational services that are defined in the configMap namespace mapping.

For more information about installing multiple IBM Cloud Pak foundational services instances in your cluster, see Installing IBM Cloud Pak foundational services in multiple namespaces.

What to do next

You can see the list of operators that are installed in your cluster on the Operators > Installed Operators page. For more information about foundational services, see IBM Cloud Pak foundational services.

To verify the Common Services installation, check whether all the pods in the target CP4BA deployment namespace are running. Use the following command:

oc get pods -n $NAMESPACE

Change the admin user for IAM

The installation of IBM Cloud Pak foundational services creates an admin user, who is a cluster administrator. To avoid the admin user from being removed when you uninstall foundational services, you can customize the username by adding the defaultAdminUser parameter to the OperandConfig instance in the target namespace. Set a custom name that is not admin.

- name: ibm-iam-operator
  spec:
    authentication:
      config:
        defaultAdminUser: <custom-username>

You can access the common-service instance by using the OpenShift Container Platform console or by using the command-line interface (CLI).

In the console, use the following steps:
1. From the navigation menu, click Operators > Installed Operators > Operand Deployment Lifecycle Manager > OperandConfig.
2. Click the overflow menu icon of the common-service instance, and click Edit OperandConfig.

To use the CLI, run the following command:

oc edit OperandConfig common-service -n <namespace>

Continue to prepare everything that you need for each capability that you want to install in Preparing your chosen capabilities.