Updating your environment variables script (Upgrading from Version 5.2 to Version 5.4)

The commands for upgrading IBM® Software Hub use variables with the format ${VARIABLE_NAME}. Ensure that your environment variables script includes the correct information for the instance of IBM Software Hub that you want to upgrade.

Upgrade phase

Updating your client workstation
Collecting required information
Preparing to run an upgrade in a restricted network
Preparing to run an upgrade from a private container registry
Upgrading prerequisite software
Upgrading shared cluster components
Preparing to upgrade an instance
Upgrading an instance
Setting up IBM Software Hub

Who needs to complete this task?

Operations team The IBM Software Hub operations team should work with the cluster administrator to compile information about the cluster where IBM Software Hub is installed.

When do you need to complete this task?

Repeat as needed If you have multiple instances of IBM Software Hub on the cluster and you maintain separate scripts for each instance, update the script for each instance that you plan to upgrade.

Editing your environment variables file

Open your existing environment variable shell script in a text editor.
Locate the VERSION entry and specify the version of IBM Software Hub that you want to upgrade to. For example:
```
export VERSION=5.4.0
```
Set or update the PATCH_ID environment variable based on the patch that you want to install:
```
export PATCH_ID=<patch-id>
```
Release ID

5.4.0 0
Set or update the OLM_UTILS_IMAGE environment variable based on your license and your cluster hardware.
Tip: If your cluster pulls images from a private container registry, you will update this environment variable after the image is pushed to the private container registry.
olm-utils-v4
All IBM Software Hub customers are entitled to use the olm-utils-v4 image.
x86-64 clusters
export OLM_UTILS_IMAGE=icr.io/cpopen/cpd/olm-utils-v4:${VERSION}.amd64
ppc64le clusters
export OLM_UTILS_IMAGE=icr.io/cpopen/cpd/olm-utils-v4:${VERSION}.ppc64le
s390x clusters
export OLM_UTILS_IMAGE=icr.io/cpopen/cpd/olm-utils-v4:${VERSION}.s390x
olm-utils-premium-v4
You must purchase the IBM Software Hub Premium Cartridge license to use the olm-utils-premium-v4 image.
x86-64 clusters
export OLM_UTILS_IMAGE=cp.icr.io/cp/cpd/olm-utils-premium-v4:${VERSION}.amd64
ppc64le clusters
export OLM_UTILS_IMAGE=cp.icr.io/cp/cpd/olm-utils-premium-v4:${VERSION}.ppc64le
s390x clusters
export OLM_UTILS_IMAGE=cp.icr.io/cp/cpd/olm-utils-premium-v4:${VERSION}.s390x
Update the Projects section to include the following environment variables. For more information on the appropriate values for the variables in this section, see Projects.
1. Add the PROJECT_CPD_INST_BR_SVC environment variable to your script:
```
export PROJECT_CPD_INST_BR_SVC=<enter your BR orchestration service project>
```
2. If your environment includes the scheduling service, add the PROJECT_SCHEDULING_BR_SVC environment variable to your script:
```
export PROJECT_SCHEDULING_BR_SVC=<enter your scheduling service BR orchestration service project>
```

Release	ID
5.4.0	`0`

Add a new section called Backup and restore to your script. For more information on the appropriate values for the variables in this section, see Backup and restore.

# ------------------------------------------------------------------------------
# Backup and restore 
# ------------------------------------------------------------------------------

export BACKUP_NAME=online-backup-$(date '+%Y%m%d-%H%M%S')
export RESTORE_NAME=${BACKUP_NAME}-restore
export OADP_PROJECT=<enter your OADP project>
# export OADP_VERSION=<OADP-version>
export NODE_AGENT_POD_CPU_LIMIT=500m
export KOPIA_POD_CPU_LIMIT=1
# export PROJECT_FUSION=ibm-spectrum-fusion-ns
# export OADP_PROJECT=ibm-backup-restore
# export PROJECT_PX_ADMIN_NS=No default.
# export PROJECT_NETAPP_TRIDENT_PROTECT=trident-protect
# export NETAPP_TRIDENT_PROTECT_APP_VAULT=<AppVault name>
export BR_OPERATOR_JOB_SA=bros-job-sa
export BR_OPERATOR_SA=bros-sa
# export PROJECT_CPD_INST_OPERATORS_NEW=<project-name>
# export OPERATOR_MAPPING=${PROJECT_CPD_INST_OPERATORS}:${PROJECT_CPD_INST_OPERATORS_NEW}
# export PROJECT_CPD_INST_OPERANDS_NEW=<project-name>
# export OPERAND_MAPPING=${PROJECT_CPD_INST_OPERANDS}:${PROJECT_CPD_INST_OPERANDS_NEW}
# export PROJECT_CPD_INSTANCE_TETHERED_1=<project-name>
# export PROJECT_CPD_INSTANCE_TETHERED_1_NEW=<project-name>
# export TETHER_MAPPING_1=${PROJECT_CPD_INSTANCE_TETHERED_1}:${PROJECT_CPD_INSTANCE_TETHERED_1_NEW}
# export PROJECT_CPD_INSTANCE_TETHERED_2=<project-name>
# export PROJECT_CPD_INSTANCE_TETHERED_2_NEW=<project-name>
# export TETHER_MAPPING_2=${PROJECT_CPD_INSTANCE_TETHERED_2}:${PROJECT_CPD_INSTANCE_TETHERED_2_NEW}
# export RESTORE_PROJECT_MAPPING="${OPERATOR_MAPPING},${OPERAND_MAPPING}"
# export RESTORE_PROJECT_MAPPING="${OPERATOR_MAPPING},${OPERAND_MAPPING},${TETHER_MAPPING_1},${TETHER_MAPPING_2}"

Add a new section called S3 object storage to your script. For more information on the appropriate values for the variables in this section, see S3 object storage.

# ------------------------------------------------------------------------------
# S3 Object Storage
# ------------------------------------------------------------------------------

export S3_URL=<S3-url>
export REGION=<S3-region>
export BUCKET_NAME=<bucket-name>
export BUCKET_PREFIX=<bucket-prefix>
export ACCESS_KEY_ID=<access-key-ID>
export SECRET_ACCESS_KEY=<access-key-secret>

Add a new section called Image pull configuration to your script and add the following environment variables:
1. Add the IMAGE_PULL_SECRET environment variable and set it to the name that you want to use for the namespace-scoped secret that will contain the base64 encoded credentials for pulling images.
  Specify a Kubernetes compliant name that contains only lowercase alphanumeric characters, hyphens (-) or periods (.). The name must start and end with an alphanumeric character.
```
export IMAGE_PULL_SECRET=<pull-secret-name>
```
2. Add the IMAGE_PULL_CREDENTIALS and IMAGE_PULL_PREFIX environment variables based on where your cluster pulls images from:
  IBM Entitled Registry
  If your cluster pulls images from the IBM Entitled Registry, add the following environment variables to your script. Do not modify the export commands:
```
export IMAGE_PULL_CREDENTIALS=$(echo -n "cp:$IBM_ENTITLEMENT_KEY" | base64 -w 0)
export IMAGE_PULL_PREFIX=icr.io
```
  Private container registry
  If your cluster pulls images from a private container registry, add the following environment variables to your script. Do not modify the export commands:
```
export IMAGE_PULL_CREDENTIALS=$(echo -n "$PRIVATE_REGISTRY_PULL_USER:$PRIVATE_REGISTRY_PULL_PASSWORD" | base64 -w 0)
export IMAGE_PULL_PREFIX=${PRIVATE_REGISTRY_LOCATION}
```
Locate the COMPONENTS entry and make the following updates:
1. Add the br_orchestration component after the cpd_platform component. For example:
```
export COMPONENTS=ibm-licensing,scheduler,cpd_platform,br_orchestration,...
```
2. Remove the following components, if applicable:
  - mongodb_cp4d
  - wca_z
  - wca_z_ce
  - wca_z_cg
If you mirror images to a private container registry, and you need to mirror models or optional images that are not included with the service images, add or update the IMAGE_GROUPS environment variable to your script:
```
export IMAGE_GROUPS=<comma-separated-list-of-group-names>
```
A comma-separated list of models or optional images to mirror to your private container registry.
If a component has models or optional images that are not mirrored by default, you must explicitly mirror those images to your private container registry.

For example, if you plan to install watsonx.ai™, you must choose which models to mirror to your private container registry.

For more information, see Determining which models and images to mirror to your private container registry (Upgrading from Version 5.2 to Version 5.4).
Save your changes.
Confirm that the script does not contain any errors. For example, if you named the script cpd_vars.sh, run:
```
bash ./cpd_vars.sh
```

Sourcing the environment variables

You must run the script from a bash prompt before you run the 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
```

Projects

The variables in the Projects section of the script specify where the components that comprise IBM Software Hub are installed.

Need more information about projects? See:

Supported project (namespace) configurations

Variable Description

Variable	Description
`PROJECT_SCHEDULING_BR_SVC`	The project for the IBM Software Hub Backup Restore Orchestration service for the scheduling service. Default value There is no default value. Valid values You can use any Red Hat® OpenShift® project; however, it is strongly recommended that you use `ibm-cpd-scheduler-br-svc`. Do not co-locate the Backup Restore Orchestration service with other software. For example, do not use the same project for the Backup Restore Orchestration service for the scheduling service and for the Backup Restore Orchestration service for an instance of IBM Software Hub.
`PROJECT_INST_BR_SVC`	The project for the IBM Software Hub Backup Restore Orchestration service for an instance of IBM Software Hub. Default value `${PROJECT_CPD_INST_OPERATORS}-br-svc` Valid values You can use any Red Hat OpenShift project; however, it is strongly recommended that you use `${PROJECT_CPD_INST_OPERATORS}-br-svc`. Do not co-locate the Backup Restore Orchestration service with other software. For example, do not use the same project for the Backup Restore Orchestration service for an instance of IBM Software Hub and for the Backup Restore Orchestration service for the scheduling service.

PROJECT_SCHEDULING_BR_SVC

The project for the IBM Software Hub Backup Restore Orchestration service for the scheduling service.

Default value: There is no default value.
Valid values: You can use any Red Hat® OpenShift® project; however, it is strongly recommended that you use ibm-cpd-scheduler-br-svc.
Do not co-locate the Backup Restore Orchestration service with other software. For example, do not use the same project for the Backup Restore Orchestration service for the scheduling service and for the Backup Restore Orchestration service for an instance of IBM Software Hub.

PROJECT_INST_BR_SVC

The project for the IBM Software Hub Backup Restore Orchestration service for an instance of IBM Software Hub.

Default value: ${PROJECT_CPD_INST_OPERATORS}-br-svc
Valid values: You can use any Red Hat OpenShift project; however, it is strongly recommended that you use ${PROJECT_CPD_INST_OPERATORS}-br-svc.
Do not co-locate the Backup Restore Orchestration service with other software. For example, do not use the same project for the Backup Restore Orchestration service for an instance of IBM Software Hub and for the Backup Restore Orchestration service for the scheduling service.

Backup and restore

The variables in the Backup and restore section of the script specify information about:

The OpenShift API for Data Protection (OADP) operator
Third-party backup and restore utilities, if applicable

Need more information about back up and restore? See:

Backup and restore requirements

Variable	Description
`BACKUP_NAME`	The name to use when you create a backup. Default value `online-backup-$(date '+%Y%m%d-%H%M%S')` Valid values The name must: Start and end with an alphanumeric character Contain only alphanumeric characters, hyphens (-), underscores (_) or periods (.) Contain no more than 60 characters
`RESTORE_NAME`	The name to use when you restore IBM Software Hub from a backup. Default value `BACKUP_NAME-restore` Valid values The name must: Start and end with an alphanumeric character Contain only alphanumeric characters, hyphens (-), underscores (_) or periods (.) Contain no more than 60 characters
`OADP_PROJECT`	The OpenShift project where the OADP operator is installed. Default value The default value depends on how you installed the OADP operator. If you installed the operator through Red Hat OpenShift Container Platform, the default value is `openshift-adp`. If you installed the operator by running the default value is `openshift-adp`. If the operator was installed by the IBM Fusion backup and restore service, the default value is `ibm-backup-restore`. Valid values The OpenShift project where the OADP operator is installed.
`OADP_VERSION`	The version of the OADP operator that is installed. The following versions of OADP are supported: Version 1.4 Version 1.5 Ensure that the version of the OpenShift API for Data Protection (OADP) operator is compatible with the version of Red Hat OpenShift Container Platform that you are running. Specify this option if you use one of the following back up and restore utilities: OpenShift API for Data Protection backup and restore utility Portworx disaster recovery (asynchronous data replication) NetApp Trident Protect To use the `OADP_VERSION` variable, you must uncomment the `export` command in the environment variables file. Default value There is no default. Valid values Specify the version with the following format: `v<major-release>.<minor-release>.<patch-release>`. For example: `v1.5.4`
`NODE_AGENT_POD_CPU_LIMIT`	The CPU limit for node-agent pods. Specify this option if you use one of the following back up and restore utilities: OpenShift API for Data Protection backup and restore utility Portworx disaster recovery (asynchronous data replication) NetApp Trident Protect Default value `500m` Valid values Specify an integer or fixed-point number. Include one of the following quantity suffixes: `k`, `M`, `G`, `T`, `P`, `E`. (Alternatively, you can specify a power-of-two equivalent: `ki`, `Mi`, `Gi`, `Ti`, `Pi`, `Ei`. Specify `0` (zero) to remove the limit. Examples: `0`, `100m`, `256Mi`, `1Gi`
`KOPIA_POD_CPU_LIMIT`	The CPU limit for Kopia pods. Specify this option if you use one of the following back up and restore utilities: OpenShift API for Data Protection backup and restore utility Portworx disaster recovery (asynchronous data replication) NetApp Trident Protect Default value `1` Valid values Specify an integer or fixed-point number. Include one of the following quantity suffixes: `k`, `M`, `G`, `T`, `P`, `E`. (Alternatively, you can specify a power-of-two equivalent: `ki`, `Mi`, `Gi`, `Ti`, `Pi`, `Ei`. Specify `0` (zero) to remove the limit. Examples: `0`, `100m`, `256Mi`, `1Gi`
`PROJECT_FUSION`	The OpenShift project where IBM Fusion is installed. This variable is required only if you use the IBM Fusion Backup & Restore service to back up your IBM Software Hub installation. To use the `PROJECT_FUSION` variable, you must uncomment the `export` command in the environment variables file. Default value `ibm-spectrum-fusion-ns` Valid values The OpenShift project where IBM Fusion is installed.
`OADP_PROJECT`	The OpenShift project where the IBM Fusion Backup & Restore service and OADP are installed. This variable is required only if you use the IBM Fusion Backup & Restore service to back up your IBM Software Hub installation. To use the `OADP_PROJECT` variable, you must uncomment the `export` command in the environment variables file. Default value `ibm-backup-restore` Valid values The OpenShift project where the IBM Fusion Backup & Restore service and OADP are installed.
`PROJECT_PX_ADMIN_NS`	The OpenShift project where Portworx Enterprise is installed. This variable is required only if you use Portworx asynchronous data replication to back up your IBM Software Hub installation. To use the `PROJECT_PX_ADMIN_NS` variable, you must uncomment the `export` command in the environment variables file. Default value No default. Valid values The OpenShift project where Portworx Enterprise is installed.
`PROJECT_NETAPP_TRIDENT_PROTECT`	The OpenShift project where NetApp Trident Protect is installed. This variable is required only if you use NetApp Trident Protect to back up your IBM Software Hub installation. To use the `PROJECT_NETAPP_TRIDENT_PROTECT` variable, you must uncomment the `export` command in the environment variables file. Default value `trident-protect` Valid values The OpenShift project where NetApp Trident Protect is installed.
`NETAPP_TRIDENT_PROTECT_APP_VAULT`	The name of the NetApp Trident Protect AppVault where you store the backups for this instance of IBM Software Hub. This variable is required only if you plan to use NetApp Trident Protect to back up your IBM Software Hub installation. To use the `NETAPP_TRIDENT_PROTECT_APP_VAULT` variable, you must uncomment the `export` command in the environment variables file. Default value No default. Valid values The name of the NetApp Trident Protect AppVault where you store the backups for this instance of IBM Software Hub.
`BR_OPERATOR_JOB_SA`	The name to use service account for jobs that are managed by the IBM Software Hub Backup Restore orchestration service. Default value `bros-job-sa` Valid values The name must be a valid DNS subdomain name. The name must: Start and end with an alphanumeric character Contain only lowercase alphanumeric characters, hyphens (-), or periods (.) Contain no more than 235 characters
`BR_OPERATOR_SA`	The name to use for the service account for the IBM Software Hub Backup Restore orchestration service. Default value `bros-sa` Valid values The name must be a valid DNS subdomain name. The name must: Start and end with an alphanumeric character Contain only lowercase alphanumeric characters, hyphens (-), or periods (.) Contain no more than 235 characters
`PROJECT_CPD_INST_OPERATORS_NEW`	If you want to restore IBM Software Hub to a different project, specify the name of the project where you want to restore the IBM Software Hub operators. To use the `PROJECT_CPD_INST_OPERATORS_NEW` variable, you must uncomment the `export` command in the environment variables file. Default value No default. Valid values Specify a valid name for a project. Ensure that the project does not already exist on the cluster. If you specify an existing project, you will encounter errors.
`OPERATOR_MAPPING`	For restore to a different project, map the existing operator project to the project where you want to restore the operators. To use the `OPERATOR_MAPPING` variable, you must uncomment the `export` command in the environment variables file. Default value `${PROJECT_CPD_INST_OPERATORS}:${PROJECT_CPD_INST_OPERATORS_NEW}` Valid values Do not modify the default value.
`PROJECT_CPD_INST_OPERANDS_NEW`	If you want to restore IBM Software Hub to a different project, specify the name of the project where you want to restore the IBM Software Hub operands. To use the `PROJECT_CPD_INST_OPERANDS_NEW` variable, you must uncomment the `export` command in the environment variables file. Default value No default. Valid values Specify a valid name for a project. Ensure that the project does not already exist on the cluster. If you specify an existing project, you will encounter errors.
`OPERAND_MAPPING`	For restore to a different project, map the existing operands project to the project where you want to restore the operands. To use the `OPERAND_MAPPING` variable, you must uncomment the `export` command in the environment variables file. Default value `${PROJECT_CPD_INST_OPERANDS}:${PROJECT_CPD_INST_OPERANDS_NEW}` Valid values Do not modify the default value.
`PROJECT_CPD_INSTANCE_TETHERED_1_NEW`	If you want to restore IBM Software Hub to a different project, specify the name of the project where you want to restore the resources that are in a tethered project. To use the `PROJECT_CPD_INSTANCE_TETHERED_1_NEW` variable, you must uncomment the `export` command in the environment variables file. Default value No default. Valid values Specify a valid name for a project. Ensure that the project does not already exist on the cluster. If you specify an existing project, you will encounter errors.
`TETHER_MAPPING_1`	For restore to a different project, map the existing tethered project to the project where you want to restore the resources in the tethered project. To use the `TETHER_MAPPING_1` variable, you must uncomment the `export` command in the environment variables file. Default value `${PROJECT_CPD_INSTANCE_TETHERED_1}:${PROJECT_CPD_INSTANCE_TETHERED_1_NEW}` Valid values Do not modify the default value.
`PROJECT_CPD_INSTANCE_TETHERED_2_NEW`	If you want to restore IBM Software Hub to a different project, specify the name of the project where you want to restore the resources that are in a tethered project. To use the `PROJECT_CPD_INSTANCE_TETHERED_2_NEW` variable, you must uncomment the `export` command in the environment variables file. If you have additional tethered projects, you can create additional `PROJECT_CPD_INSTANCE_TETHERED_N_NEW` environment variables. Default value No default. Valid values Specify a valid name for a project. Ensure that the project does not already exist on the cluster. If you specify an existing project, you will encounter errors.
`TETHER_MAPPING_2`	For restore to a different project, map the existing tethered project to the project where you want to restore the resources in the tethered project. To use the `TETHER_MAPPING_2` variable, you must uncomment the `export` command in the environment variables file. If you have additional tethered projects, you can create additional `TETHER_MAPPING_N` Default value `${PROJECT_CPD_INSTANCE_TETHERED_2}:${PROJECT_CPD_INSTANCE_TETHERED_2_NEW}` Valid values Do not modify the default value.
`RESTORE_PROJECT_MAPPING`	A list of projects that IBM Software Hub will be restored to. The `RESTORE_PROJECT_MAPPING` environment variable depends on whether your instance includes tethered projects. Instances without tethered projects If your instance does not include tethered projects, uncomment the `RESTORE_PROJECT_MAPPING` entry that includes the following mappings: `${OPERATOR_MAPPING}` `${OPERAND_MAPPING}` Instances with tethered projects If your instance includes tethered projects, uncomment the `RESTORE_PROJECT_MAPPING` entry that includes the following mappings: `${OPERATOR_MAPPING}` `${OPERAND_MAPPING}` `${TETHER_MAPPING_1}` `${TETHER_MAPPING_2}` You can adjust the number of `TETHER_MAPPING_N` variables based on the number of tethered projects that are associated with the instance.

S3 object storage

The variables in the S3 object storage section of the script specify information about the S3 object storage where you store your backups.

Need more information about back up and restore? See:

Backup and restore requirements

Variable	Description
`S3_URL`	The URL of the S3-compatible object storage where you store your backups for this instance of IBM Software Hub If you are using the default port (`80` for HTTP or `443` for HTTPS), omit the port from the URL. Default value There is no default value. Valid values Specify the URL of the object store. If you are using publicly hosted S3 object storage, enter the public endpoint. If you are using a private instance, enter the IP address or private DNS URL. Review the documentation for your S3 object storage for information on valid URLs.
`REGION`	The region where the S3 bucket is located. Default value There is no default value. Valid values Specify the region of the object store. For example: `us-south` `us-gov-east-1` `ap-northeast-2` `me-central-1` Review the documentation for your S3 object storage for a list of valid regions.
`BUCKET_NAME`	The name of the object storage bucket where you store your IBM Software Hub backups. Default value There is no default value. Valid values Specify the name of an existing bucket on your S3 object storage.
`BUCKET_PREFIX`	The bucket prefix that you use for IBM Software Hub backups. Default value There is no default value. Valid values Specify the name of an existing bucket prefix on your S3 object storage.
`ACCESS_KEY_ID`	The access key ID for your S3-compatible object storage. Default value There is no default value. Valid values Specify the access key ID for your S3 object storage. The user associated with the access key must have `write` access to the object store.
`SECRET_ACCESS_KEY`	The access key secret for your S3-compatble object storage. Default value There is no default value. Valid values Specify the access key secret for your S3 object storage. The user associated with the access key must have `write` access to the object store.

What to do next

Now that you've updated the environment variables in your script, you're ready to complete Preparing to run IBM Software Hub upgrade commands in a restricted network (Upgrading from Version 5.2 to Version 5.4).