Upgrading the operator by running a script

To upgrade the operator, a cluster administrator user can run a script to set up the cluster. The administrator needs permission to apply or created custom resource definitions (CRD's) and create namespaces. The deployment script will detect the existing installation version and method and provide a fresh install path for missing operators or upgrade existing.

Before you begin

The upgrade_deployment.py script uses the following utility tools and needs them to be installed on your client machine:

Kubernetes CLI
Python
Helm CLI
ibm-content-cortex-containers repository from GitHub

To install the specified tools that are used by the upgrade_deployment.py script, see topic Preparing a client to connect to the cluster.

About this task

Note: For operator upgrades from V5.5.8 to V26.0.0 on OCP and CNCF platforms, deployments will be migrated to a Helm chart install.

When you run the script the prerequisites validation for the script checks whether the required utility tools like Helm CLI and if the connection to the cluster is successful. It also checks if the required descriptor files exist. If the prerequisites validation fails, the script flags the missing tools and files. The script will detect the current installation of the operators, either being at the correct version, available for fresh install or requiring an upgrade. If an OLM or Yaml based deployment is detected, on upgrade these resources will be cleaned and a Helm based install will proceed. It also gives you the option to install the IBM Content Cortex AI Services operator. For more information about the AI Services operator, see AI Services on container platforms.

After you downloaded the ibm-content-cortex-containers repository, change the directory to the ibm-content-cortex-containers/scripts folder. The script can be run from this location and has the following options:

python3 deploy_operator.py --help

Usage: deploy_operator.py [OPTIONS]

Content Cortex Operator Deployment CLI.

Options:
  --version                      Show version and exit. 
  --install-completion           Install completion for the current shell.
  --show-completion              Show completion for the current shell, to copy it or customize the installation.
  --help                         Show this message and exit.

Customization and Utils:
  --silent     --no-silent       Enable Silent Install (no prompts). [default: no-silent]
  --verbose    --no-verbose      Enable verbose logging. [default: no-verbose]
  --dryrun     --no-dryrun       Perform a dry run [default: no-dryrun]
  --validate   --no-validate     Disable validation of entitlement key or private registry. [default: validate]
  --force      --no-force        Force redeployment even if operators are already at target version. [default: no-force] 

Deployment Method:  
  --use-olm    --no-use-olm      Use OLM (Operator Lifecycle Manager) for deployment instead of Helm. [default: no-use-olm]
  --helm-chart-source            TEXT  Helm chart source: 'github' (default - downloads from GitHub), 'packaged' (local files), 'local' (unpacked charts), 'public' (Helm repo), or 'url'. [default: github]

You can run the script interactively, or supply the configuration file beforehand and run the script as a silent deployment.

When you run the script in interactive mode, you can specify the mode that you want. When you run the script without specifying a mode, it runs in all modes. The following command runs the script interactively:

python3 deploy_operator.py

Tip: Before you run the script in silent mode, make sure that you fill the ./scripts/silent_config/silent_install_deployoperator.toml file and then run the following command:

python3 deploy_operator.py --silent

Procedure

Open a terminal or command prompt and log in to the target cluster as the <cluster-admin> user.
Navigate to the directory where the ibm-content-cortex-containers repository was downloaded:
```
cd ./ibm-content-cortex-containers/scripts
```
Run the following command to install the necessary Python packages from the requirements.txt file:
```
python3 -m pip install -r requirements.txt
```
Run the upgrade deployment script in operator mode to upgrade the ibm-content-operator in your cluster.
- Interactive:
```
python3 deploy_operator
```
- Silent:
  Before you run the script in silent mode, make sure that you fill the ./scripts/silent_config/silent_install_deployoperator.toml file and then run the following command:
```
python3 deploy_operator.py --silent 
```
The prerequisites validation for the script checks whether the required utility tools like Podman or Docker exist and if the connection to the cluster is successful. It also checks if the required descriptor files exist. If the prerequisites validation fails, the script flags the missing tools and files. It also checks whether you want to use a global catalog that is shared across multiple deployments or if you want to use a private catalog for your deployment.
For an interactive operator upgrade, provide the following values:
1. Accept the license.
2. Specify whether the deployment is air-gapped by selecting Y or N.
3. For an online deployment, enter your IBM Entitlement Registry key when the script prompts for it.
4. For an offline deployment, provide your private registry information. This will be validated.
5. Enter your namespace.
6. Review the current installation summary. The script shows which operators are upgraded or installed, including the Content operator, the required License Service and Usage Metering operators, and the optional IBM Content Cortex AI Services operator.
7. Select which operators need to be install or upgraded based on the current state of the namespace.
8. For each operator that has existing custom resource definitions (CRDs), choose how Helm handles the CRDs. To let Helm take ownership of the CRDs for the Content operator, the AI Services operator, License Service, Usage Metering Cluster-Scoped, and Usage Metering operators, accept the recommended ownership option.
9. Proceed with the operator deployment. All operators are installed in parallel and are not dependent on each others install success.
10. The values.yaml files generated to either install or upgrade the helm based deployment will be saved to ./scripts/CCxHelm/<namespace>.
View your install helm chart with the following command.
```
helm list -n <namespace>
```

What to do next

Once the operator is upgraded, and an updated custom resource is applied, the deployment upgrade starts. This can take approximately 20 minutes, and after one reconcile loop completes, you can validate your upgrade. To validate the success of your upgrade, see topic Verifying the upgrade.