Customizing pods by creating a resource specification injection patch

You can use resource specification injection (RSI) to create patches to customize the pods in your IBM® Software Hub environment.

Who needs to complete this task?

To complete this task, you must be either:

A cluster administrator
An instance administrator

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 IBM Software Hub installation.

Before you begin

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
--include_labels or --select_all_pods
--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.

labels

If you use either of the following options, you can change the pods that the patch applies to:

--include_labels
--exclude_labels

Restriction: You cannot switch between the --include_labels option and the --select_all_pods option.

Tip: If you plan to apply multiple RSI patches to an instance of IBM Software Hub, 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_INST_OPERANDS} 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

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

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

Table 1: Command options

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. IBM Software Hub 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=<description>` Default value No default. Valid values A description.
`--exclude_labels`	Specify a subset of pods to skip based on the labels on the pods. If you specify multiple key-value pairs, the patch will skip any pods that have all of the specified labels. Status Optional. Use this option in combination with the `--include_labels` option or the `--select_all_pods` option. Syntax `--exclude_labels=<comma-separated-key-value-pairs-representing-pod-labels>` Default value No default. Valid values Specify valid pod labels as key-value pairs. Separate the key and the value with a colon. Separate multiple key-value pairs with a comma. For example: `--exclude_labels=key1:value1,key2:value2`
`--include_labels`	Specify which pods the patch will apply to based on the labels on the pods. If you specify multiple key-value pairs, the patch will be applied only to pods that have all of the specified 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 Optional. If you omit this option, you must specify the `--select_all_pods` option. Syntax `--include_labels=<comma-separated-key-value-pairs-representing-pod-labels>` Default value No default. Valid values Specify valid pod labels as key-value pairs. Separate the key and the value with a colon. Separate multiple key-value pairs with a comma. For example: `--include_labels=key1:value1,key2:value2`
`--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, hyphen (-), 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 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 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` Specify this option to add an `init` container to pods. `rsi_pod_side_car_container` Specify this option to add a `sidecar` container to pods.
`--select_all_pods`	Specify whether you want to apply the patch to all of the pods in the operands project and any tethered projects for the instance. Status Optional. If you omit this option, you must specify the `--include_labels` option. Syntax `--select_all_pods=true\|false` Default value `false` If you omit this option, the default value is used. Valid values `false` Do not apply the patch to all of the pods in operands project and any projects that are tethered to the operands project. `true` Apply the patch to all of the pods in operands project and any projects that are tethered to the operands project.
`--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.