Customizing pods by creating a resource specification injection patch

Important: IBM Cloud Pak® for Data Version 4.6 will reach end of support (EOS) on 31 July, 2025. For more information, see the Discontinuance of service announcement for IBM Cloud Pak for Data Version 4.X.

Upgrade to IBM Software Hub Version 5.1 before IBM Cloud Pak for Data Version 4.6 reaches end of support. For more information, see Upgrading IBM Software Hub in the IBM Software Hub Version 5.1 documentation.

You can use resource specification injection (RSI) to create patches to customize the pods in your Cloud Pak for Data environment.

Who needs to complete this task?: You must be a cluster administrator or project administrator to create RSI patches.
When do you need to complete this task?: Complete this task if you want to create or edit an RSI patch.
Important: Create RSI patches only if you are an advanced user on Red Hat® OpenShift® Container Platform. It is your responsibility to ensure that any patches that you apply to not introduce issues to your Cloud Pak for Data installation.

You can use the cpd-cli manage create-rsi-patch command to create or update patches.

Creating a new patch

If you are creating a new patch, specify the following options:

--cpd_instance_ns
--description
--patch_name
--patch_spec
--patch_type
--selector
--skip_apply
--spec_format
--state

Updating a patch

If you are updating an existing patch, the options that you specify depend on what you are trying to do. At a minimum, you must specify:

--cpd_instance_ns
--patch_name

You can change the following aspects of an existing patch:

--description: You can update the description for the patch.
--patch_spec: You can change the contents of the JSON file that defines the patch.

--state: You can make the patch active or inactive.

--selector: You can change the pods that the patch applies to.

Tip: If you plan to apply multiple RSI patches to an instance of Cloud Pak for Data, it is less disruptive to apply the RSI patches in a batch.

What types of patches can you create?

You can use RSI to:

Add environment variables to pod containers
Add labels to pods
Add annotations to pods
Add fields to the spec section of pods
Add an init container to pods
Add a sidecar container to pods

Best practice: Before you create an RSI patch, inspect the current contents of the pods that you want to patch:

oc get -n=${PROJECT_CPD_INSTANCE} pod <pod-name> -o yaml

Add environment variables to pod containers

To add environment variables to pod containers, you must create an rsi_pod_env_var patch:

--patch_type=rsi_pod_env_var

json example

You can create a JSON file that contains patch operations that should be applied in sequence to the pod containers. In this example, the environment variables will be added to specific pod containers.

Important: To apply the patch to specific pod containers, you must know the container index.

[
    {
        "op":"add",
        "path":"/spec/containers/0/env/-",
        "value":{
            "name":"replicaset-test-env-json-one","value":"replicaset-test-env-json-one"
        }
    },
    {
        "op":"add",
        "path":"/spec/containers/0/env/-",
        "value":{
            "name":"replicaset-test-env-json-two","value":"replicaset-test-env-json-two"
        }
    }
]

The format of your JSON file is json:

--spec_format=json

json-merge example

The json-merge format is not recommended for rsi_pod_env_var patches because the patch replaces the entire env section of the pod spec.

set-env example

You can create a JSON file that contains an array of key-value pairs that define environment variables for all of the pod containers.

[
    {
        "name": "myapp-set-env-name-one",
        "value": "myapp-set-env-value-one"
    },
    {
        "name": "myapp-set-env-name-two",
        "value": "set-env-value-two"
    },
    {
        "name": "myapp-set-env-name-four",
        "value": "myapp-set-env-value-four"
    }
]

The format of your JSON file is set-env:

--spec_format=set-env

Add labels to pods

To add labels to pods, you must create an rsi_pod_label patch:

--patch_type=rsi_pod_label

json example

You can create a JSON file that contains patch operations that should be applied in sequence to the labels in the pod metadata. In this example, the patch adds a new label to the existing labels.

[
    {
        "op":"add",
        "path":"/metadata/labels/zen-metastoredb-label-json-one",
        "value":"zen-metastoredb-label-json-one"
    }
]

The format of your JSON file is json:

--spec_format=json

json-merge example

You can create a JSON file that defines the labels to use in the pod metadata. In this example, the patch overwrites any existing labels and replaces them with the new label.

{
    "metadata":{
        "labels":{
            "zen-metastoredb-label-merge-one": "zen-metastoredb-label-merge-one"
        }
    }
}

The format of your JSON file is json-merge:

--spec_format=json-merge

Add annotations to pods

To add annotations to pods, you must create an rsi_pod_annotation patch:

--patch_type=rsi_pod_annotation

json example

You can create a JSON file that contains patch operations that should be applied in sequence to the annotations in the pod metadata. In this example, the patch adds a new annotation to the existing annotations.

[
    {
        "op":"add",
        "path":"/metadata/annotations/zen-watchdog-anno-json-one",
        "value":"zen-watchdog-anno-json-one"
    }
]

The format of your JSON file is json:

--spec_format=json

json-merge example

You can create a JSON file that defines the annotations to use in the pod metadata. In this example, the patch overwrites any existing annotations and replaces them with the new annotation.

{
    "metadata":{
        "annotations":{
            "zen-watchdog-anno-json-merge-one": "zen-watchdog-anno-json-merge-one"
        }
    }
}

The format of your JSON file is json-merge:

--spec_format=json-merge

Add fields to the spec section of pods

To add fields to the spec section of pods, you must create an rsi_pod_spec patch:

--patch_type=rsi_pod_spec

json example

You can create a JSON file that contains patch operations that should be applied in sequence to the pod spec. In this example, the patch adds a runtime class that specifies the container runtime for all containers in the pod.

[
    {
        "op":"add",
        "path":"/spec/runtimeClassName",
        "value":"selinux"
    }
]

The format of your JSON file is json:

--spec_format=json

json-merge example

You can create a JSON file that defines the parameters to add to the pod spec. In this example, the patch adds a DNS policy or overwrites the existing DNS policy in the pod spec.

{
    "spec":{
        "dnsPolicy": "ClusterFirst"
    }
}

The format of your JSON file is json-merge:

--spec_format=json-merge

Add an init container to pods

4.6.4 or later This option is available in IBM Cloud Pak for Data Version 4.6.6 or later.

To add an init container to pods, you must create an rsi_pod_init_container patch:

--patch_type=rsi_pod_init_container

json example

You can create a JSON file that contains patch operations that should be applied in sequence to the initContainers section of the pod spec. In this example, the patch adds a new init container to the list of existing init containers.

[
   {
      "op":"add",
      "path":"/spec/initContainers",
      "value":[
         {
            "command":[
               "sh",
               "-c",
               "echo The app init"
            ],
            "image":"busybox:1.28",
            "name":"init-svr"
         }
      ]
   }
]

The format of your JSON file is json:

--spec_format=json

json-merge example

You can create a JSON file that defines the parameters to use in the initContainers section of the pod spec. In this example, the patch overrides any existing init containers and replaces them with a new init container.

{
    "spec":{
        "initContainers":[
            {
                "command":["sh","-c","echo The app init"],
                "image":"busybox:1.28",
                "name":"init-svr"
            }
        ]
    }
}

The format of your JSON file is json-merge:

--spec_format=json-merge

Add a sidecar container to pods

4.6.4 or later This option is available in IBM Cloud Pak for Data Version 4.6.6 or later.

To add a sidecar container to pods, you must create an rsi_pod_side_car_container patch:

--patch_type= rsi_pod_side_car_container

json example

You can create a JSON file that contains patch operations that should be applied in sequence to the containers section of the pod spec. In this example, the patch adds a new sidecar container to the list of existing containers.

[
    {
        "op":"add",
        "path":"/spec/containers/-1",
        "value":{ 
            "command":["sh","-c","echo \"The app sidecar\"  \u0026\u0026 sleep 3600 "], 
            "image":"busybox:1.28", 
            "name":"sidecar"
        }
    }
]

The format of your JSON file is json:

--spec_format=json

json-merge example: The json-merge format is not recommended for rsi_pod_env_var patches because the patch replaces the entire containers section of the pod spec.

Options reference

The following table provides detailed information about the options that you can specify for the cpd-cli manage create-rsi-patch command.

Option	Description
`--cpd_instance_ns`	The project (namespace) where you want to create or update the patch. If there are any projects tethered to this project, the patch will also apply to the tethered projects. Status Required. Syntax `--cpd_instance_ns=<project-name>` Default value No default. User-defined. Valid values The name of the project where you want to create the RSI feature. Cloud Pak for Data must be installed in this project.
`--description`	The description for the patch. Use the description to describe the purpose and intent of the patch. Status Optional. Syntax `--description=<patch-description>` Default value No default. Valid values A description.
`--patch_name`	The name of the patch to create or update. Status Required. Syntax `--patch_name=<patch-name>` Default value No default. User defined. Valid values The name must adhere to the following rules: Be 50 characters or less. Contain only lowercase alphanumeric characters, hypyen (-), or period (.). Start and end with an alphanumeric character.
`--patch_spec`	The JSON file that contains the patch. Save the file in the `cpd-cli-workspace/olm-utils-workspace/work/rsi/` directory. Status Required to create a new patch. Syntax `--patch_spec=/tmp/work/rsi/<patch-spec-JSON-file>` Default value No default. Valid values Specify the name of the JSON file in the `cpd-cli-workspace/olm-utils-workspace/work/rsi/` with the format: `/tmp/work/rsi/<file-name.json>`
`--patch_type`	The type of patch to create. Status Required to create a new patch. Syntax `--patch_type=rsi_pod_env_var\|rsi_pod_label\|rsi_pod_annotation\|` `rsi_pod_spec\|rsi_pod_init_container\| rsi_pod_side_car_container` Default value No default. Valid values rsi_pod_env_var Specify this option to add environment variables to pod containers. rsi_pod_label Specify this option to add labels to pods. rsi_pod_annotation Specify this option to add annotations to pods. rsi_pod_spec Specify this option to add fields to the `spec` section of pods. rsi_pod_init_container 4.6.4 or later This option is available in IBM Cloud Pak for Data Version 4.6.6 or later. Specify this option to add an `init` container to pods. rsi_pod_side_car_container 4.6.4 or later This option is available in IBM Cloud Pak for Data Version 4.6.6 or later. Specify this option to add a `sidecar` container to pods.
`--selector`	Specify which pods the patch will apply to by specifying one or more pod labels. If you specify multiple labels, the patch will apply to pods with all of the labels. For example, if you specify `app.kubernetes.io/component:zen-core,component:zen-core`, the patch will apply to any pods with both of these labels, even if they have additional labels. Status Required to create a new patch. Syntax `--selector=<comma-separated-key-value-pairs-representing-the-match-labels>` Default value No default. Valid values Specify one or more valid pod label from your cluster. Separate multiple labels as a comma-separated list.
`--skip_apply`	Specify whether the RSI webhook waits to apply the patch or whether it applies the patch immediately. Status Optional. Syntax `--skip_apply=true\|false` Default value false If you omit this option, the default value is used. Valid values false Force the webhook to apply the patch immediately. true Wait for the patch to be applied. The patch will be applied the next time the RSI cronjob runs or when you run the `apply-rsi-patches` command, whichever occurs first.
`--spec_format`	The format of the patch spec JSON file. Status Optional. Syntax `--spec_format=json\|json-merge\|set-env` Default value json-merge If you omit this option, the default value is used. Valid values json Specify `json` if the `--patch_spec` JSON file contains a JSON array of patch operations that should be applied in sequence. For example: `[{"op":"add","path":"/metadata/labels/label-1","value":"value-1"}]` Ensure that `json` patches follow the JavaScript Object Notation (JSON) Patch (RFC 6902) standard. json-merge Specify `json-merge` if the `--patch_spec` JSON file contains a JSON pod spec path. For example: `{"metadata":{"labels":{"label-1": "value-1"}}}` Ensure that `json` patches follow the JSON Merge Patch (RFC 7386) standard. set-env Specify `set-env` if the `--patch_spec` JSON file contains a JSON array of key-value pairs. For example: `[{"name": "env-var-1","value": "env-var-value-1"}]` Restriction: This option applies only if you are creating an `rsi_pod_env_var` patch.
`--state`	Specify whether the patch can be applied by the RSI webhook. Status Optional. Syntax `--state=active\|inactive` Default value active If you omit this option, the default value is used. Valid values active Specify `active` to enable the webhook to apply the patch. inactive Specify `inactive` to prevent the webhook from applying the patch.
`-v` `-vv` `-vvv`	Display verbose output. Options are listed from least verbose to the most verbose. Status Optional. Syntax Verbose output `-v` Very verbose output `-vv` Most verbose output `-vvv` Default value Not applicable. Valid values Not applicable.