Setting up installation environment variables

The commands for installing and upgrading IBM® Cloud Pak for Data use variables with the format ${VARIABLE_NAME}. You can create a script to automatically export the appropriate values as environment variables before you run the installation commands. After you source the script, you will be able to copy most install and upgrade commands from the documentation and run them without making any changes.

Installation phase: Setting up a client workstation; Collecting required information; Preparing your cluster; Installing the Cloud Pak for Data platform and services
Who needs to complete this task?: Any users who will run installation or upgrade commands that require information about your environment, such as information about your Red Hat® OpenShift® Container Platform cluster or your private container registry.
When do you need to complete this task?: You should complete this task before you start preparing your cluster.

Before you begin

Before you create the script, consider whether you need to support:

Repeatable deployments across clusters: In this scenario, you can re-use the same script to improve the consistency of deployments across your environments.
Multiple deployments on the same cluster: In this scenario, you can create multiple scripts to simplify the process of managing each instance. Clearly name each script to ensure that you run the correct script before you run the installation or upgrade commands.

Tip: If multiple people are working together to complete the installation, you should share a copy of the appropriate files with each user. Each user can edit the scripts to supply their own credentials and source the script on their own workstation.

Creating an environment variables file

Copy the following example to a text editor on your local file system:

#===============================================================================
# Cloud Pak for Data installation variables
#===============================================================================

# ------------------------------------------------------------------------------
# Cluster
# ------------------------------------------------------------------------------

export OCP_URL=<enter your Red Hat OpenShift Container Platform URL>
export OPENSHIFT_TYPE=<enter your deployment type>
# export OCP_USERNAME=<enter your username>
# export OCP_PASSWORD=<enter your password>
# export OCP_TOKEN=<enter your token>


# ------------------------------------------------------------------------------
# Projects
# ------------------------------------------------------------------------------

export PROJECT_CPFS_OPS=ibm-common-services        
export PROJECT_CPD_OPS=<enter your Cloud Pak for Data operator installation project>
export PROJECT_CATSRC=openshift-marketplace
export PROJECT_CPD_INSTANCE=<enter your Cloud Pak for Data installation project>
# export PROJECT_TETHERED=<enter the tethered project>


# ------------------------------------------------------------------------------
# Storage
# ------------------------------------------------------------------------------

export STG_CLASS_BLOCK=<RWO-storage-class-name>
export STG_CLASS_FILE=<RWX-storage-class-name>

# ------------------------------------------------------------------------------
# IBM Entitled Registry
# ------------------------------------------------------------------------------

export IBM_ENTITLEMENT_KEY=<enter your IBM entitlement API key>


# ------------------------------------------------------------------------------
# Private container registry
# ------------------------------------------------------------------------------
# Set the following variables if you mirror images to a private container registry.
#
# To export these variables, you must uncomment each command in this section.

# export PRIVATE_REGISTRY_LOCATION=<enter the location of your private container registry>
# export PRIVATE_REGISTRY_PUSH_USER=<enter the username of a user that can push to the registry>
# export PRIVATE_REGISTRY_PUSH_PASSWORD=<enter the password of the user that can push to the registry>
# export PRIVATE_REGISTRY_PULL_USER=<enter the username of a user that can pull from the registry>
# export PRIVATE_REGISTRY_PULL_PASSWORD=<enter the password of the user that can pull from the registry>


# ------------------------------------------------------------------------------
# Cloud Pak for Data version
# ------------------------------------------------------------------------------

export VERSION=4.5.3


# ------------------------------------------------------------------------------
# Components
# ------------------------------------------------------------------------------
# Set the following variable if you want to install or upgrade multiple components at the same time.
#
# To export the variable, you must uncomment the command.

# export COMPONENTS=cpfs,scheduler,cpd_platform,<component-ID>

Update each section in the script for your environment. See the following sections to learn about the variables and valid values in each section of the script:
Save the file as a shell script. For example, save the file as cpd_vars.sh.
Confirm that the script does not contain any errors. For example, if you named the script cpd_vars.sh, run:
```
bash ./cpd_vars.sh
```
If you stored passwords in the file, prevent others from reading the file. For example, if you named the script cpd_vars.sh, run:
```
chmod 700 cpd_vars.sh
```

Sourcing the environment variables

Save a copy of the script to your workstation and run it from a bash prompt before you the run installation and upgrade commands. The script exports the environment variables to your command-line session.

Important: You must re-run the script each time you open a new bash prompt.

Change to the directory where you saved the script.
Source the environment variables. For example, if you named the script cpd_vars.sh, run:
```
source ./cpd_vars.sh
```

Cluster

The variables in the Cluster section of the script specify information about your Red Hat OpenShift Container Platform cluster.

Need more information on installing Red Hat OpenShift Container Platform? See:

Installing Red Hat OpenShift Container Platform

Variable	Description
`OCP_URL`	The URL of the Red Hat OpenShift Container Platform server. For example, https://openshift1.example.com:8443. Default value There is no default value. Valid values Specify the URL of your Red Hat OpenShift Container Platform server.
`OPENSHIFT_TYPE`	The type of Red Hat OpenShift Container Platform cluster that you are running. Default value self-managed Valid values aro Specify `aro` if you are running Azure Red Hat OpenShift (ARO), the managed OpenShift offering on Microsoft Azure. roks Specify `roks` if you are running Red Hat OpenShift on IBM Cloud®, the managed OpenShift offering on IBM Cloud. rosa Specify `rosa` if you are running Red Hat OpenShift Service on AWS (ROSA), the managed OpenShift offering on Amazon Web Services. self-managed Specify `self-managed` if you are running self-managed OpenShift on: On-premises infrastructure AWS infrastructure IBM Cloud infrastructure Microsoft Azure infrastructure
`OCP_USERNAME`	The username that you use to authenticate to your cluster. You must have sufficient privileges to complete each installation or upgrade task. This variable is used to run the `cpd-cli manage login-to-ocp` command. The Tip: It is recommended that you prevent other users from reading the contents of the environment variable script by running `chmod 700`. However, if you still have concerns about storing your OpenShift credentials in this file, you can: Enter the credentials directly instead of using the environment variable in the commands. Manually export the credentials before you run the commands. Remember: You must uncomment the `export OCP_USERNAME` command if you want to use this environment variable.
`OCP_PASSWORD`	The password that you use to authenticate to your cluster. Remember: You must uncomment the `export OCP_PASSWORD` command if you want to use this environment variable.
`OCP_TOKEN`	Remember: You must uncomment the `export OCP_TOKEN` command if you want to use this environment variable.

Projects

The variables in the Projects section of the script specify where the components that comprise Cloud Pak for Data are installed.

Need more information about projects? See:

Variable	Description
`PROJECT_CPFS_OPS`	The Red Hat OpenShift project where the IBM Cloud Pak® foundational services operators are installed. Default value `ibm-common-services` Valid values Change the value of `PROJECT_CPFS_OPS` only if you installed the IBM Cloud Pak foundational services in a different project.
`PROJECT_CPD_OPS`	The Red Hat OpenShift project where the Cloud Pak for Data software operators are installed. Default value There is no default value. Valid values The location of the operators depends on the type of installation that you choose: Express installation In an express installation, the Cloud Pak for Data operators are installed in the same project as the IBM Cloud Pak foundational services operators: `ibm-common-services` Specialized installation In a specialized installation, the Cloud Pak for Data operators are installed in a separate project from the IBM Cloud Pak foundational services operators. The recommended project name is `cpd-operators`.
`PROJECT_CATSRC`	The Red Hat OpenShift project where the catalog sources are installed. Default value `openshift-marketplace` Valid values The only supported value is `openshift-marketplace`.
`PROJECT_CPD_INSTANCE`	The Red Hat OpenShift project where the Cloud Pak for Data control plane and services are installed. (The Cloud Pak for Data control plane is installed in a separate project from the operators.) Default value There is no default value. Valid values `cpd-instance` is used as an example, but you can choose a name that works for you. Tip: If you want to install multiple instances of Cloud Pak for Data on your cluster, create a separate script for each instance that you plan to install.
`PROJECT_TETHERED`	A Red Hat OpenShift project that is tethered to the project where the Cloud Pak for Data control plane is installed. This variable is required only if you plan to install a service that supports tethering into a tethered project. Remember: You must uncomment the `export PROJECT_TETHERED` command if you want to use this environment variable. Default value There is no default value. Valid values `cpd-instance-tether` is sometimes used as an example, but you can choose a name that works for you.

Storage

The variables in the Storage section of the script specify the storage classes that the installation should use.

Need more information about storage? See:

Variable Description

Variable	Description
`STG_CLASS_BLOCK`	The name of a block storage class on a supported storage option. Default value There is no default value. Valid values Specify the name of a storage class that points to block storage (storage that supports ReadWriteOnce, also called RWO, access). The following list provides the recommended storage classes for the supported storage options. If you use different storage classes, identify an equivalent storage class on the cluster. OpenShift Data Foundation: `ocs-storagecluster-ceph-rbd` IBM Spectrum® Fusion: `ibm-spectrum-scale-sc` IBM Spectrum Scale Container Native: `ibm-spectrum-scale-sc` Portworx: `portworx-metastoredb-sc` NFS: `managed-nfs-storage` Amazon Elastic Block Store: `gp2-csi` or `gp3-csi` IBM Cloud Block Storage: `ibmc-block-gold`
`STG_CLASS_FILE`	The name of a file storage class on a supported storage option. Default value There is no default value. Valid values Specify the name of a storage class that points to file storage (storage that supports ReadWriteMany, also called RWX, access). The following list provides the recommended storage classes for the supported storage options. If you use different storage classes, identify an equivalent storage class on the cluster. OpenShift Data Foundation: `ocs-storagecluster-cephfs` IBM Spectrum Fusion: `ibm-spectrum-scale-sc` IBM Spectrum Scale Container Native: `ibm-spectrum-scale-sc` Portworx: `portworx-rwx-gp3-sc` NFS: `managed-nfs-storage` Amazon Elastic File System: `efs-nfs-client` IBM Cloud File Storage: `ibmc-file-gold-gid` or `ibm-file-custom-gold-gid`

STG_CLASS_BLOCK

The name of a block storage class on a supported storage option.

Default value

There is no default value.

Valid values

Specify the name of a storage class that points to block storage (storage that supports ReadWriteOnce, also called RWO, access).

The following list provides the recommended storage classes for the supported storage options. If you use different storage classes, identify an equivalent storage class on the cluster.

OpenShift Data Foundation: ocs-storagecluster-ceph-rbd
IBM Spectrum® Fusion: ibm-spectrum-scale-sc
IBM Spectrum Scale Container Native: ibm-spectrum-scale-sc
Portworx: portworx-metastoredb-sc
NFS: managed-nfs-storage
Amazon Elastic Block Store: gp2-csi or gp3-csi
IBM Cloud Block Storage: ibmc-block-gold

STG_CLASS_FILE

The name of a file storage class on a supported storage option.

Default value

There is no default value.

Valid values

Specify the name of a storage class that points to file storage (storage that supports ReadWriteMany, also called RWX, access).

The following list provides the recommended storage classes for the supported storage options. If you use different storage classes, identify an equivalent storage class on the cluster.

OpenShift Data Foundation: ocs-storagecluster-cephfs
IBM Spectrum Fusion: ibm-spectrum-scale-sc
IBM Spectrum Scale Container Native: ibm-spectrum-scale-sc
Portworx: portworx-rwx-gp3-sc
NFS: managed-nfs-storage
Amazon Elastic File System: efs-nfs-client
IBM Cloud File Storage: ibmc-file-gold-gid or ibm-file-custom-gold-gid

IBM Entitled Registry

The variables in the IBM Entitled Registry section of the script enable you to connect to the IBM Entitled Registry and access the Cloud Pak for Data software images that you are entitled to.

Depending on whether you pull images from the IBM Entitled Registry or from a private container registry, the variables might also be used to configure the global image pull secret.

Need more information about the IBM Entitled Registry? See:

Obtaining your IBM entitlement API key

Variable	Description
`IBM_ENTITLEMENT_KEY`	The entitlement API key that is associated with your My IBM account. Default value There is no default value. Valid values Specify your IBM entitlement API key.

Private container registry

It is strongly recommended that you use a private container registry. The variables in the Private container registry section are required only if you mirror images to a private container registry.

The variables in the Private container registry section of the script enable you to mirror images from the IBM Entitled Registry to the private container registry.

Important: If you want to use these variables, you must uncomment each command in the Private container registry section of the script.

Need more information about private container registries? See:

Private container registry requirements

Variable	What to specify
`PRIVATE_REGISTRY_LOCATION`	The location of the private container registry. Default value There is no default value. Valid values Specify the hostname or IP address of the private container registry. Keep the following guidance in mind: Do not specify `http://` or `https://`. If the registry is running on port `80` or `443` you can omit the port. However, if the registry is running on a different port, you must specify the port.
`PRIVATE_REGISTRY_PUSH_USER`	The username of a user who has the required privileges to push images to the private container registry. Default value There is no default value. Valid values Specify a username.
`PRIVATE_REGISTRY_PUSH_PASSWORD`	The password of the user who has the required privileges to push images to the private container registry. Tip: It is recommended that you prevent other users from reading the contents of the environment variable script by running `chmod 700`. However, if you still have concerns about storing passwords in this file, you can: Enter the password directly instead of using the environment variable in the commands. Manually export the password before you run the commands. Default value There is no default value. Valid values Specify the password associated with the username.
`PRIVATE_REGISTRY_PULL_USER`	The username of a user who has the required privileges to pull images from the private container registry. Default value There is no default value. Valid values Specify a username.
`PRIVATE_REGISTRY_PULL_PASSWORD`	The password of the user who has the required privileges to pull images from the private container registry. Tip: It is recommended that you prevent other users from reading the contents of the environment variable script by running `chmod 700`. However, if you still have concerns about storing passwords in this file, you can: Enter the password directly instead of using the environment variable in the commands. Manually export the password before you run the commands. Default value There is no default value. Valid values Specify the password associated with the username.

Cloud Pak for Data version

The variable in the Cloud Pak for Data version section specifies which version of Cloud Pak for Data to install or upgrade to.

Remember: All of the components must be installed at the same version.

Variable	Description
`VERSION`	The version of the Cloud Pak for Data software to install. Default value 4.5.3 Valid values 4.5.0 4.5.1 4.5.2 4.5.3

Components

If you want to install or upgrade multiple components at the same time, you can specify a comma separated list of components. The variable in the Components section is recommended to help you easily specify the list of components.

Important: If you want to use this variable, you must uncomment the command in the Components section of the script.

Variable Description

Variable	Description
`COMPONENTS`	The comma separated list of the components that you want to install or upgrade. Default value By default, the list includes the required and recommended components: `cpfs,scheduler,cpd_platform` You can optionally remove `scheduler` if you don't plan to install Watson™ Machine Learning Accelerator or if you don't plan to use the quota enforcement feature. Important: You must specify `cpfs` and `cpd_platform`. These components are required for all installations. Do not add any components to the comma separated list before `cpfs` or `cpd_platform`. Only add components after the `cpd_platform` entry. This ensures that the components are installed in the correct order. Valid values Review the guidance in Determining which components to install to determine which components to specify.

COMPONENTS

The comma separated list of the components that you want to install or upgrade.

Default value

By default, the list includes the required and recommended components:

cpfs,scheduler,cpd_platform

You can optionally remove scheduler if you don't plan to install Watson™ Machine Learning Accelerator or if you don't plan to use the quota enforcement feature.

Important: You must specify cpfs and cpd_platform. These components are required for all installations.

Do not add any components to the comma separated list before cpfs or cpd_platform. Only add components after the cpd_platform entry. This ensures that the components are installed in the correct order.

Valid values

Review the guidance in Determining which components to install to determine which components to specify.