Applying a Db2 Big SQL patch

A Red Hat® OpenShift® project administrator can apply a Db2® Big SQL patch.

Before you begin

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

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 created a profile, as described in Creating a profile to use the cpd-cli management commands. The profile must be created with a user that was granted access to the Db2 Big SQL instance that you want to patch.
You have the information about the patch that you plan to install, as described in Available patches for Db2 Big SQL for IBM® Cloud Pak for Data.
Recommendation: Back up your Db2 Big SQL service instances.

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

./cpd-cli patch --help

About this task

Applying a patch to Db2 Big SQL involves the following steps.

Patching the Db2 Big SQL service.
Patching Db2 Big SQL instances.
If patching a Db2 Big SQL instance failed, restoring a Db2 Big SQL instance backup.

Procedure

Complete the appropriate steps to apply a Db2 Big SQL patch on your environment:

Applying patches on clusters connected to the internet
Applying patches on air-gapped clusters

Applying patches on clusters connected to the internet

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 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 big-sql \
--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
`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.

To patch the service, rerun the previous command without the --dry-run flag.

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

The Db2 Big SQL service is patched and restarted.

Get the list of Db2 Big SQL instances.

./cpd-cli service-instance list --service-type bigsql --profile profile-name

The following example shows the information that is returned by the command.

[INFO] [<timestamp>] Querying CPD services API for version of addon type of bigsql
----------------------------------------------------------------------------------------------------------------------------------
[INFO] [<timestamp>] The following service instances matches the query criteria:
----------------------------------------------------------------------------------------------------------------------------------
Type                 Instance Name                            ID                   Upgrade Available    Instance Ver.    Addon Version(s)
bigsql               Db2-Big-SQL-1                            1602162794533680     no                   7.1.1            [7.1.1]
----------------------------------------------------------------------------------------------------------------------------------

To patch a Db2 Big SQL instance, run the following command.
Tip: You can patch multiple instances in a single transaction by passing multiple instance IDs separated by commas.
```
./cpd-cli patch \
--repo ./repo.yaml \
--assembly big-sql \
--namespace Project \
--patch-name Patch_name \
--instance-id instance_id \
--transfer-image-to Registry_location \
--cluster-pull-prefix Registry_from_cluster \
--ask-push-registry-credentials \
--action transfer
```
Use the same values that you specified when you patched the service.

The head and worker pods for the Db2 Big SQL instance restart.

Applying patches on air-gapped cluster

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 big-sql \
--version Assembly_version \
--patch-name Patch_name \
--action download

Replace the following values:

Variable	Replace with
`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 service.

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 big-sql \
--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.
`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.

To patch the service, rerun the previous command without the --dry-run flag.

./cpd-cli patch \
--namespace Project \
--load-from Image_directory_location
--assembly big-sql \
--patch-name Patch_name \
--transfer-image-to Registry_location \
--ask-push-registry-credentials \
--action push \

The Db2 Big SQL service is patched and restarted.

Get the list of Db2 Big SQL instances.

./cpd-cli service-instance list --service-type bigsql --profile profile-name

The following example shows the information that is returned by the command.

[INFO] [<timestamp>] Querying CPD services API for version of addon type of bigsql
----------------------------------------------------------------------------------------------------------------------------------
[INFO] [<timestamp>] The following service instances matches the query criteria:
----------------------------------------------------------------------------------------------------------------------------------
Type                 Instance Name                            ID                   Upgrade Available    Instance Ver.    Addon Version(s)
bigsql               Db2-Big-SQL-1                            1602162794533680     no                   7.1.1            [7.1.1]
----------------------------------------------------------------------------------------------------------------------------------

To patch a Db2 Big SQL instance, run the following command.
Tip: You can patch multiple instances in a single transaction by passing multiple instance IDs separated by commas.
```
./cpd-cli patch \
--namespace Project \
--load-from Image_directory_location
--assembly big-sql \
--patch-name Patch_name \
--instance-id instance_id \
--transfer-image-to Registry_location \
--ask-push-registry-credentials \
--action push \
```
Use the same values that you specified when you patched the service.

The head and worker pods for the Db2 Big SQL instance restart.

Restoring a backup in case of failure to patch a Db2 Big SQL instance

If patching a Db2 Big SQL instance failed, you can restore the Db2 Big SQL instance backup that you took before you applied the patch.

On the patched cluster, create a new Db2 Big SQL instance.
Restore the Db2 Big SQL backup on the instance that you just created.

Get the name of the Db2 Big SQL head pod:

head_pod=$(oc get pod -l instance=<instanceid>,app=db2-bigsql,bigsql-node-role=head --no-headers=true -o=custom-columns=NAME:.metadata.name)

Restart Db2 Big SQL:

oc exec -i $head_pod /usr/ibmpacks/IBM-Big_SQL/current/standalone/scripts/bigsql-restart.sh

To test that the restore is successful, run a smoke test.
1. If Db2 Big SQL is connected to a Hadoop cluster, run the following command:
```
oc exec -it $head_pod -- bash -lc '/usr/ibmpacks/IBM-Big_SQL/current/bigsql-cli/bigsql-admin -smoke
```
2. If Db2 Big SQL is connected exclusively to an object store service, run the following command. You must provide the name of a bucket that exists on the storage service.
```
oc exec -it $head_pod -- bash -lc '/usr/ibmpacks/IBM-Big_SQL/current/bigsql-cli/bigsql-admin -smoke -o <bucket-name>
```