Best practice: Setting up install variables
${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.
- 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.
|
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.
|
PROJECT_CPD_OPS |
The Red Hat OpenShift project where the
Cloud Pak for Data software operators are installed.
|
PROJECT_CATSRC |
The Red Hat OpenShift project where the
catalog sources are installed.
|
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.)
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.
|
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.
- The software does not support a
version
entry in the custom resource. For example, the Voice Gateway service does not support aversion
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.
- 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 aversion
entry in the custom resource, the service will be automatically upgraded when the operator is upgraded.
Variable | Description |
---|---|
APPROVAL_TYPE |
The type of approval that is required to create and update operators.
|
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.
|
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.
|
IBM_ENTITLEMENT_USER |
The username for accessing Cloud Pak for Data
software images.
|
IBM_ENTITLEMENT_SERVER |
The container registry where the Cloud Pak for Data software images are hosted.
|
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.
- 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
- 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
- Create catalog sources
- Mirror software images to a private container registry
- 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.
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.
|
OFFLINEDIR_CPFS |
The directory where you will store the CASE packages for the IBM Cloud Pak
foundational services software.
|
PATH_CASE_REPO |
The repository where the CASE packages are hosted.
|
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).
|
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.
Variable | What to specify |
---|---|
PRIVATE_REGISTRY_LOCATION |
The 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.
|
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:
|
PRIVATE_REGISTRY_PULL_USER |
The username of a user who has the required privileges to pull images from the
private container registry.
|
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:
|
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.
- 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.
Variable | What to specify |
---|---|
INTERMEDIARY_REGISTRY_HOST |
The location of the intermediary container registry. The intermediary container registry is
hosted locally.
|
INTERMEDIARY_REGISTRY_PORT |
The port to use for the intermediary container registry on the local host.
|
INTERMEDIARY_REGISTRY_LOCATION |
The host and port of the intermediary container registry. The script automatically
concatenates the values that you specify for |
INTERMEDIARY_REGISTRY_USER |
The username that you will use to authenticate to the intermediary container registry.
|
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:
|