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.

Ensure that the Mac OS or Linux machine where you will run the commands meets the appropriate requirements for your environment:

Requirements for the machine Cluster is connected to the internet Cluster is air-gapped
Can connect to the cluster.
Is connected to the internet.  
Has the oc command-line interface.

You can download the appropriate client tools for your operating system from OKD. Ensure that the version is compatible with the version of Red Hat OpenShift on your cluster.

Has the Cloud Pak for Data command-line interface.

See Obtaining the installation files. Use the same version of the command-line interface each time you run the commands.

Has the updated repo.yaml file in the same directory as the Cloud Pak for Data command-line interface.

See Obtaining the installation files.

 
Has the cpd-Operating_System-workspace directory, which contains the required files.

See Preparing for air-gapped installations.

 

Ensure that you have the following information from your Red Hat OpenShift cluster administrator:

Required information Description
OpenShift_URL:port The URL and port number to use when logging in to your Red Hat OpenShift cluster.

Ensure that you have the appropriate credentials to log into the cluster using oc login.

Value:

Your cluster administrator should tell you whether your cluster is connected to the internet or is air-gapped.

Project The project where the software is currently installed.

Value:

Assembly_version

Needed for air-gapped installations only.

The version of the software that is currently installed.

Value:

Registry_location The location to store the updated images on the registry server.

If you are patching the software when you are connected to the internet, ensure that you have the appropriate credentials to push images to the registry server.

Value:

Guidance for Red Hat OpenShift registry users:
  • This is the external route to the location in the registry. The default external route is:
    docker-registry-default.9.87.654.321.nip.io/project

    Where default.9.87.654.321.nip.io is your public IP address.

  • When you specify a value for the Registry_location variable, ensure that you include the project name.
Registry_from_cluster The location from which pods on the cluster can pull images.

Value:

Guidance for Red Hat OpenShift registry users:
  • This is the internal name of the registry service. The default service name is:
    docker-registry.default.svc:5000/project
  • When you specify a value for the Registry_from_cluster variable, ensure that you include the project name.

Ensure that you have the information about the patch that you plan to install. For details, see Available patches.

Important: Some patches have prerequisite patches because they have dependencies on another service or on a set of shared, common services. If the patch details 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:
oc describe cpdinstall cr-cpdinstall | grep "Patch Name:" | sort | uniq | cut -d: -f2

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

About this task

If you apply a patch to a service that has multiple service instances, all of the service instances are patched.

Procedure

To apply a patch:

Run the appropriate cpd patch command for your environment.
Tip: For a list of all available options, enter the command: ./cpd-Operating_System --help.
  • To apply patches on a cluster that can connect to the internet:
    Important: If a patch has prerequisite patches, install the patches in the order listed. Repeat the following steps for each patch.
    1. Change to the directory where you placed the Cloud Pak for Data command-line interface and the repo.yaml file.
    2. Log in to your Red Hat OpenShift cluster as a project administrator:
      oc login OpenShift_URL:port
    3. Run the following command to patch the service:
      ./cpd-Operating_System 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
      

      Replace the following values:

      Variable Replace with
      Operating_System For Linux, specify linux. For Mac OS, specify darwin.
      Assembly_name Specify the assembly name of the software. This information is included in the patch description.
      Important: If you are installing a common core service patch, specify the assembly name of the service that requires the common core service patch.

      For example, if you are applying the common core service patch as a prerequisite for Watson™ Knowledge Catalog, specify wkc.

      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 apply patches on an air-gapped cluster:
    Important: If a patch has prerequisite patches, install the patches in the order listed. Repeat the following steps for each patch.
    1. On a machine that can connect to the internet, change to the directory where you extracted the Cloud Pak for Data installation command-line interface.
    2. Run the following command to download the patch to your local machine:
      ./cpd-Operating_System patch --repo ./repo.yaml \
      --assembly Assembly_name \
      --version Assembly_version \
      --patch-name Patch_name \
      --action download

      Replace the following values:

      Variable Replace with
      Operating_System For Linux, specify linux. For Mac OS, specify darwin.
      Assembly_name Specify the assembly name of the software. This information is included in the patch description.
      Assembly_version Specify the version of the software that is currently installed.
      Patch_name Specify the name of the patch that you want to install. This information is included in the patch description.
    3. Transfer the following items to a machine that can connect to the cluster and to the registry server:
      • The cpd-Operating_System-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.
    4. From the machine that can connect to the cluster, run the following command to push the images to the registry server:
      ./cpd-Operating_System 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

      Replace the following values:

      Variable Replace with
      Operating_System For Linux, specify linux. For Mac OS, specify darwin.
      Project Specify the project (namespace) where the software that you want to patch is deployed.
      Image_directory_location The location of the cpd-Operating_System-workspace directory.
      Assembly_name Specify the assembly name of the software. This information is included in the patch description.
      Important: If you are installing a common core service patch, specify the assembly name of the service that requires the common core service patch.

      For example, if you are applying the common core service patch as a prerequisite for Watson Knowledge Catalog, specify wkc.

      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.