Best practice: Setting up install 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 run the script, you will be able to copy most install and upgrade commands from the documentation and run them without making any changes.

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

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 variables
# ------------------------------------------------------------------------------

export OCP_URL=<enter your Red Hat OpenShift Container Platform URL>


# ------------------------------------------------------------------------------
# Project variables
# ------------------------------------------------------------------------------

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>


# ------------------------------------------------------------------------------
# Operator installation variables
# ------------------------------------------------------------------------------

export APPROVAL_TYPE=Automatic


# ------------------------------------------------------------------------------
# Licenses variables
# ------------------------------------------------------------------------------

export LICENSE_CPD=<enter the license you purchased>

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

export IBM_ENTITLEMENT_KEY=<enter your IBM entitlement API key>
export IBM_ENTITLEMENT_USER=cp
export IBM_ENTITLEMENT_SERVER=cp.icr.io


# ------------------------------------------------------------------------------
# CASE package management variables
# ------------------------------------------------------------------------------

export OFFLINEDIR_CPD=<enter an existing directory>
export OFFLINEDIR_CPFS=<enter an existing directory>
export PATH_CASE_REPO=https://github.com/IBM/cloud-pak/raw/master/repo/case
export USE_SKOPEO=true


# ------------------------------------------------------------------------------
# Private container registry variables
# ------------------------------------------------------------------------------
# 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>


# ------------------------------------------------------------------------------
# Intermediary container registry variables
# ------------------------------------------------------------------------------
# Set the following variables if you use an intermediary container registry to
# mirror images to your private container registry.
#
# To export these variables, you must uncomment each command in this section.

# export INTERMEDIARY_REGISTRY_HOST=localhost
# export INTERMEDIARY_REGISTRY_PORT=<enter the port to use on the localhost>
# INTERMEDIARY_REGISTRY_LOCATION="${INTERMEDIARY_REGISTRY_HOST}:${INTERMEDIARY_REGISTRY_PORT}"
# export INTERMEDIARY_REGISTRY_LOCATION
# export INTERMEDIARY_REGISTRY_USER=<enter the username to authenticate to the registry>
# export INTERMEDIARY_REGISTRY_PASSWORD=<enter the password for the user>

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 variables

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

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.

Project variables

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

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 operator installation architecture that you want to use: 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.

Operator installation variables

The variables in the Operator installation variables section of the script specify how the Cloud Pak for Data operators are installed on your cluster.

What are operator install plans?

When you create an operator subscription, you specify the install plan for the operator. Red Hat OpenShift Container Platform supports the following install plans:

Automatic

If you specify installPlanApproval: Automatic, OpenShift will automatically load newer versions of the operator if they are available. For example, if you mirror images to a private container registry and you set the install plan to automatic, Red Hat OpenShift Container Platform will automatically use the latest version of the operator that is available in the private container registry.

Manual

If you specify installPlanApproval: Manual, OLM creates an update request when a newer version of an operator is available. A cluster administrator must manually approve:

The initial request to create the operator
Subsequent requests to update the operator to a newer version.

Note: An operator manages software. Upgrading the operator does not necessarily impact the version of the software that is running on the cluster. In most cases, the software will not be automatically upgraded even after the operator is upgraded. However, there are exceptions to this rule:

The software does not support a version entry in the custom resource. For example, the Voice Gateway service does not support a version entry in the custom resource, which means that the service is automatically upgraded when you install a newer version of the operator on the cluster.
You choose an automatic install plan when you install or upgrade the services on your cluster. When you choose an automatic upgrade plan, you remove the version entry from the custom resource.

Review the documentation for the services that you plan to install to determine whether:

The services support a version entry
The services support the automatic upgrade

Which operator install plan should I choose?

Use the following guidance to choose an install plan:

Private container registry

When you pull images from a private container registry, you must mirror the images to the registry and update the catalog source before you can upgrade the software.

Use the automatic install plan to simplify the process of managing your environment.
Use the manual install plan to ensure that all aspects of the software remain at the same version until you are ready to upgrade the software.

IBM Entitled Registry

The guidance for the IBM Entitled Registry depends on the type of catalog source that you created:

Catalog source that pulls a specific version of the software from the IBM Entitled Registry

When you create catalog sources that pull a specific version of the software from the IBM Entitled Registry, you must update the catalog source before you can upgrade the software.

Use the automatic install plan to simplify the process of managing your environment.
Use the manual install plan to ensure that all aspects of the software remain at the same version until you are ready to upgrade the software.

Catalog source that automatically pulls the latest version of the software from the IBM Entitled Registry

The IBM Operator Catalog automatically pulls the latest version of the software from the IBM Entitled Registry. The IBM Operator Catalog is refreshed any time any IBM operator is released. OLM handles any updates that it finds in the IBM Operator Catalog (ibm-operator-catalog) automatically.

With this configuration, the manual install plan reduces, but does not eliminate, the likelihood that the software will be updated without your knowledge.

Remember: If a service does not include or support a version entry in the custom resource, the service will be automatically upgraded when the operator is upgraded.

Variable Description

Variable	Description
`APPROVAL_TYPE`	The type of approval that is required to create and update operators. Default value Automatic Valid values Automatic OpenShift will automatically load newer versions of the operator if they are available. Manual OLM creates an update request when a newer version of an operator is available. A cluster administrator must manually approve initial request to create the operator and subsequent requests to update the operator to a newer version. Tip: If you choose this option, you should complete Specifying the install plan for operators that are automatically installed by Operand Deployment Lifecycle Manager after you install the Cloud Pak for Data control plane.

APPROVAL_TYPE

The type of approval that is required to create and update operators.

Default value

Automatic

Valid values

Automatic: OpenShift will automatically load newer versions of the operator if they are available.
Manual: OLM creates an update request when a newer version of an operator is available. A cluster administrator must manually approve initial request to create the operator and subsequent requests to update the operator to a newer version.
Tip: If you choose this option, you should complete Specifying the install plan for operators that are automatically installed by Operand Deployment Lifecycle Manager after you install the Cloud Pak for Data control plane.

Licenses variables

The variables in the Licenses variables section of the script specify which licenses you purchased.

Variable	Description
`LICENSE_CPD`	The IBM Cloud Pak for Data license that you purchased. Default value There is no default value. Valid values Enterprise Specify `Enterprise` if you purchased IBM Cloud Pak for Data Enterprise Edition. Standard Specify `Standard` if you purchased IBM Cloud Pak for Data Standard Edition.

IBM Entitled Registry variables

The variables in the IBM Entitled Registry variables 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.

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.
`IBM_ENTITLEMENT_USER`	The username for accessing Cloud Pak for Data software images. Default value `cp` Valid values `cp`
`IBM_ENTITLEMENT_SERVER`	The container registry where the Cloud Pak for Data software images are hosted. Default value `cp.icr.io` Valid values `cp.icr.io`

CASE package management variables

The variables in the CASE package management variables section of the script specify where the CASE packages are saved.

What are CASE packages?

A Container Application Software for Enterprises (CASE) package is an archive file that describes a containerized component of Cloud Pak for Data.

There are CASE packages for:

IBM Cloud Pak foundational services
IBM Cloud Pak for Data control plane
Each IBM Cloud Pak for Data service
Software dependencies for the control plane and services

Each CASE package includes:

Metadata about the component
An inventory of the container images that are required to deploy the component
References to any software dependencies
The scripts needed to mirror the images to a private container registry

The information in the CASE packages is used when you run the commands to:

Create catalog sources
Mirror software images to a private container registry

Identify the directories where you want to store the CASE packages on your system. Keep the following requirements in mind:

You must specify existing directories with sufficient storage
You must use a persistent directory. Using a persistent directory prevents you from transferring files more than once.
Additionally, if you use a persistent directory, you can run the mirror process multiple times or on a schedule.

Best practice: It is recommended that you store the CASE package for the IBM Cloud Pak foundational services in a separate directory from the CASE packages for Cloud Pak for Data.

If you use a private container registry and plan to install multiple IBM Cloud Paks on your cluster, storing the CASE package for IBM Cloud Pak foundational services in a separate directory helps you manage which images are mirrored to your private container registry.

When you run the command to mirror the images, the command mirrors any updated images in the directory. Using a separate directory ensures that you mirror a specific set of images.

Variable	What to specify
`OFFLINEDIR_CPD`	The directory where you will store the CASE packages for the Cloud Pak for Data software. Best practice: Create separate directories for each refresh and update this environment variable each time that you install a new refresh. For example, $HOME/offline/cpd/4.0.x, where `x` is the refresh number. This approach enables you to keep all of the refresh specific CASE packages, dependent CASE packages, and images together so that you have a consistent, refresh-specific set of assets. Default value There is no default value. Valid values $HOME/offline/cpd is used as an example, but you can choose a directory that works for you. Ensure that you specify an existing directory.
`OFFLINEDIR_CPFS`	The directory where you will store the CASE packages for the IBM Cloud Pak foundational services software. Default value There is no default value. Valid values $HOME/offline/cpfs is used as an example, but you can choose a directory that works for you. Ensure that you specify an existing directory.
`PATH_CASE_REPO`	The repository where the CASE packages are hosted. Default value `https://github.com/IBM/cloud-pak/raw/master/repo/case` Valid values `https://github.com/IBM/cloud-pak/raw/master/repo/case`
`USE_SKOPEO`	The `oc mirror` command has some limitations, which can cause failures when mirroring the Cloud Pak for Data images. You must use the `skopeo` executable to mirror images with the IBM Cloud Pak CLI (cloudctl). Default value `true` Valid values `true`

Private container registry variables

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

If you use an intermediary container registry to mirror images to your private container registry, you must also update the variables in the Intermediary container registry variables section of the script. For details, see Intermediary container registry variables.

The variables in the Private container registry variables 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 variables section of the script.

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 fully qualified location of the private container registry.
`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: In the Creating an environment variables file section, 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 to the `PRIVATE_REGISTRY_PUSH_PASSWORD` variable 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: In the Creating an environment variables file section, 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 to the `PRIVATE_REGISTRY_PULL_PASSWORD` variable before you run the commands. Default value There is no default value. Valid values Specify the password associated with the username.

Intermediary container registry variables

The variables in this section are required only if you use an intermediary container registry to mirror images to your private container registry.

The variables in the Intermediary container registry variables section of the script enable you to:

Set up an intermediary container registry
Mirror images from the IBM Entitled Registry to the intermediary container registry
Mirror images from the intermediary container registry to the private container registry.

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

Variable	What to specify
`INTERMEDIARY_REGISTRY_HOST`	The location of the intermediary container registry. The intermediary container registry is hosted locally. Default value `localhost` Valid values `localhost`
`INTERMEDIARY_REGISTRY_PORT`	The port to use for the intermediary container registry on the local host. Default value There is no default value. Valid values Specify a port that is not currently in use. To avoid conflicts with system ports, choose a port greater than `1024`.
`INTERMEDIARY_REGISTRY_LOCATION`	The host and port of the intermediary container registry. The script automatically concatenates the values that you specify for `INTERMEDIARY_REGISTRY_HOST` and `INTERMEDIARY_REGISTRY_PORT`.
`INTERMEDIARY_REGISTRY_USER`	The username that you will use to authenticate to the intermediary container registry. Default value There is no default value. Valid values Specify a username.
`INTERMEDIARY_REGISTRY_PASSWORD`	The password that you will use to authenticate to the intermediary container registry. Tip: In the Creating an environment variables file section, 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 to the `PRIVATE_REGISTRY_PUSH_PASSWORD` variable before you run the commands. Default value There is no default value. Valid values Specify a password.