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.

You can install patches from the same machine that you used to install the Cloud Pak for Data software and services. If you are using a different machine, ensure that machine meets the requirements for your environment.

  • Machine requirements

    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 Red Hat OpenShift:

    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:
  • To determine the external route to the registry, run the appropriate command for your environment:
    • OpenShift 3.11:
      oc get route/docker-registry -n default --template {{.spec.host}}

      The command returns a route similar to docker-registry-default.apps.my_cluster_address

      Append the project name to the route. For example:
      docker-registry-default.apps.my_cluster_address/project
    • OpenShift 4.5:
      oc get route/default-route -n openshift-image-registry --template='{{ .spec.host }}'

      The command returns a route similar to default-route-openshift-image-registry.apps.my_cluster_address.

      Append the project name to the route. For example:
      default-route-openshift-image-registry.apps.my_cluster_address/project
  • 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:
    • OpenShift 3.11:
      docker-registry.default.svc:5000/project
    • OpenShift 4.5:
      image-registry.openshift-image-registry.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:
cpd-Operating_System status --namespace Project --patches

You can optionally specify the --assembly 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.

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-Operating_System status --repo ./repo.yaml \
    --namespace Project \
    --patches \
    --available-updates
    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.
  • If your cluster is air-gapped

    Review the documents listed in the Available patches.

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 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-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 \
      --dry-run

      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.
    4. Rerun the previous command without the --dry-run flag to patch the software.
    5. If you are patching a service and you have service instances associated with the service, you must patch all of the instances to the same version as the service.
      1. Run the following command to see the list of service instances:
        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-Operating_System serviceinstance --list \
        --namespace Project \
        --assembly Assembly_name
      2. Run the following command to patch all of the service instances:
        ./cpd-Operating_System patch serviceinstances \
        --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 \
        --all

        Use the same values that you specified when you patched the service.

  • 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.
      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.

      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. 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-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 \
      --dry-run

      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.
      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.
    5. Rerun the previous command without the --dry-run flag to patch the software.
    6. If you are patching a service and you have service instances associated with the service, you must patch all of the instances to the same version as the service.
      1. Run the following command to see the list of service instances:
        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-Operating_System serviceinstance --list \
        --namespace Project \
        --assembly Assembly_name
      2. Run the following command to patch all of the service instances:
        ./cpd-Operating_System patch service instances \
        --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 \
        --all

        Use the same values that you specified when you patched the service.