Applying patches

A Red Hat® OpenShift® project administrator can apply patches on a cluster that is connected to the internet or on an air-gapped cluster.

Before you begin

Required role: To install a patch, you must be an administrator of the project (namespace) where the software is deployed.

In this topic, the term software can be either the Cloud Pak for Data control plane or a service.

Before you apply patches, ensure that:

The machine from which you will run the commands meets the requirements described in Preparing your installation node.
You have the required information about your Red Hat OpenShift cluster, as described in Collecting information about your cluster from your administrator.
You have the information about the patch that you plan to install.

Tip: For a list of all available options, enter the following command:

./cpd-cli patch --help

Procedure

To install patches:

Checking for available patches
Complete the appropriate task to apply patches on your environment:
- Applying patches on clusters connected to the internet
- Applying patches on air-gapped clusters

If needed, you can roll back patches that you've applied.

Checking for available patches

The best way to check for available patches is to review the appropriate Preventive Service Planning document for the software that you want to patch. You can find a list of the Preventive Service Planning documents in Available patches.

The Preventive Service Planning documents are updated when patches are released and contain information about any prerequisite patches you might need to install.

Important: Some patches have prerequisite patches because they have dependencies on another service or on the Cloud Pak for Data common core services. If the patch details in a Preventive Service Planning document list one or more prerequisite patches, you must install the prerequisite patches before you install the service patch. You can run the following command to determine whether any of the prerequisite patches are already installed on the cluster:

cpd-cli status \
--namespace Project \
--patches

You can optionally specify the --assembly Assembly_name flag if you want to get information only about a specific service.

If the prerequisite patch is already installed, it will be listed in the output of the preceding command.

In addition to the Preventive Service Planning documents, you can use the following methods to check for available patches.

Tip: You can run the following command to check for available patches. However, this method does not include information about any prerequisite patches. It is strongly recommended that you review the information about Available patches before you install the patch.

If your cluster is connected to the internet
Run the following command to see all of the available patches for the software that is deployed in a given Red Hat OpenShift project:
```
./cpd-cli status \
--repo ./repo.yaml \
--namespace Project \
--patches \
--available-updates
```
Replace Project with the project (namespace) where the software that you want to patch is deployed.
If your cluster is air-gapped
Review the documents listed in the Available patches.

Applying patches on clusters connected to the internet

Important: If a patch has prerequisite patches, install the patches in the order listed. Repeat the following steps for each patch.

From your installation node:

Change to the directory where you placed the Cloud Pak for Data command-line interface and the repo.yaml file.
Log in to your Red Hat OpenShift cluster as a project administrator:
```
oc login OpenShift_URL:port
```

Run the following command to preview the changes that will be applied when you patch the software:

Important: If you are using the internal Red Hat OpenShift registry and you are using the default self-signed certificate, specify the --insecure-skip-tls-verify flag to prevent x509 errors.

./cpd-cli patch \
--repo ./repo.yaml \
--assembly Assembly_name \
--namespace Project \
--patch-name Patch_name \
--transfer-image-to Registry_location \
--cluster-pull-prefix Registry_from_cluster \
--ask-push-registry-credentials \
--action transfer \
--dry-run

Replace the following values:

Variable	Replace with
`Assembly_name`	Specify the assembly name of the software. This information is included in the patch description.
`Project`	Specify the project (namespace) where the software that you want to patch is deployed.
`Patch_name`	Specify the name of the patch that you want to install. This information is included in the patch description.
`Registry_location`	Use the value specified by your cluster administrator or the value that you used when you installed the software.
`Registry_from_cluster`	Use the value specified by your cluster administrator or the value that you used when you installed the software.

Rerun the previous command without the --dry-run flag to patch the software.

Applying patches on air-gapped clusters

Important: If a patch has prerequisite patches, install the patches in the order listed. Repeat the following steps for each patch.

From your installation node:

Change to the directory where you placed the Cloud Pak for Data command-line interface and the repo.yaml file.

Run the following command to download the patch to your local machine:

./cpd-cli patch \
--repo ./repo.yaml \
--assembly Assembly_name \
--version Assembly_version \
--patch-name Patch_name \
--action download

Replace the following values:

Variable	Replace with
`Assembly_name`	Specify the assembly name of the software. This information is included in the patch description.
`Assembly_version`	The version of the assembly that is currently installed on your cluster.
`Patch_name`	Specify the name of the patch that you want to install. This information is included in the patch description.

Transfer the following items to a machine that can connect to the cluster and to the registry server:
- The cpd-cli-workspace directory. Ensure that the directory structure remains unchanged.
- A copy of the Cloud Pak for Data installation command-line interface. Ensure that the command-line interface is compatible with the machine that you are transferring the files to and that it is the same version as the command-line interface that you ran in the preceding steps.
From the machine that can connect to the cluster, run the following command to preview the changes that will be applied when you patch the software:
Important: If you are using the internal Red Hat OpenShift registry:
- Do not specify the --ask-pull-registry-credentials parameter.
- If you are using the default self-signed certificate, specify the --insecure-skip-tls-verify flag to prevent x509 errors.
```
./cpd-cli patch \
--namespace Project \
--load-from Image_directory_location
--assembly Assembly_name \
--patch-name Patch_name \
--transfer-image-to Registry_location \
--ask-push-registry-credentials \
--action push \
--dry-run
```
Replace the following values:

Variable	Replace with
`Project`	Specify the project (namespace) where the software that you want to patch is deployed.
`Image_directory_location`	The location of the cpd-cli-workspace directory.
`Assembly_name`	Specify the assembly name of the software. This information is included in the patch description.
`Patch_name`	Specify the name of the patch that you want to install. This information is included in the patch description.
`Registry_location`	Use the value specified by your cluster administrator or the value that you used when you installed the software.

Rerun the previous command without the --dry-run flag to patch the software.

Rolling back patches

Whether a patch succeeded or failed, you can revert a service to the state before the patch was applied. You cannot roll back more than one patch.

Tip: For a list of all available options, enter the command:

./cpd-cli patch rollback --help

From your installation node:

Change to the directory where you placed the Cloud Pak for Data command-line interface.
Log in to your Red Hat OpenShift cluster as a project administrator:
```
oc login OpenShift_URL:port
```
List the patches in your project:
```
./cpd-cli status \
--patches \
--namespace Project
```
Replace Project with the project where the patch is installed.

Roll back the patch:

./cpd-cli patch rollback \
--assembly Assembly_name \
--namespace Project \
--patch-name Patch_name \
--cluster-pull-prefix Registry_from_cluster \
--cluster-pull-username=$(oc whoami) \
--cluster-pull-password=$(oc whoami -t)