Use patch dictionaries

This topic provides an overview of the patch dictionary feature and an example scenario that shows how you can use patch dictionaries to manage the substitution of configuration values during application deployment.

Important: Patch dictionaries are only supported for Kubernetes and OpenShift.

Key concepts

Applications are commonly delivered to environments using scripted delivery where each application, environment, and deployment has a unique script in the form of JSON or YAML files. Patch dictionaries are intended to standardize, streamline, and scale scripted delivery of applications to environments that use JSON and YAML-based configuration files.

A patch dictionary contains a set of rules and associated actions that will be performed on these configuration files if those rules are satisfied. Integrating patch dictionaries enables standardization of scripted deployments, supporting "on the fly" injection of unique values during deployment.

Patch dictionaries and regular dictionaries

Patch dictionaries complement placeholders and regular dictionaries, while also providing an additional level of flexibility:

• Both placeholders and regular dictionaries are applied "on the fly" during package deployment. However, with placeholders and regular dictionaries, you need to modify your files beforehand when deploying a package. When using a patch dictionary to modify values, the configuration files can be free of placeholders and do not need manual modification.

• While placeholders are useful for managing the substitution of simple key-value pairs, patch dictionaries enable you to find and inject values into hierarchically-structured JSON or YAML configuration files by specifying your key as a path to search for in the file that reflects the file's structure.

• A patch dictionary that is associated with an environment can add, replace or remove values from JSON or YAML configuration files based on keys and values that it finds, see Use JSON Patch Editor.

While not recommended, you can use patch dictionaries in combination with regular dictionaries. If you do use a combination of regular and patch dictionaries, all placeholders need to be resolved before the actions of a patch dictionary can be applied.

Like regular dictionaries, you can associate one or more patch dictionaries with an environment. If you have more than one patch dictionary listed, Deploy will parse them in the order that they are listed in the Environment properties page.

Activators

A patch dictionary activator acts as a sort of "if" statement in which you can specify the pre-condition to look for that determines if a specific patch dictionary should be applied to a specific file. If a patch dictionary has multiple activators, Deploy uses an "all or nothing" approach - if one of the activators is not satisfied, the patch will not be applied to the file.

Patch entries

A patch entry contains the actual instruction to modify a JSON or YAML file to add, replace or remove a value within it, see Use JSON Patch Editor. The patching is performed on a file if it satisfies the activators. Values and paths that you modify using patch entries do not need to be validated using activators.

Sample file sources

The patch dictionary wizard lets you select a sample JSON or YAML file from an existing deployment package in Deploy, or to create a custom one from scratch.

• From a package: Using a sample file is a convenient way to build your activators and patch entries. The sample file is just what its name implies - a sample. It does not need to be associated with the specific deployment package you intend to patch during deployment and is just used to test and preview the patch dictionary you are defining. The sample can be any JSON or YAML file that has a similar structure as to the configuration file you intend to patch. You select specific lines in a sample configuration file and if it is one or more levels down in the tree structure, it's expressed as a path.

• Custom: You can also build your patch rules manually using the custom sample source type. This may be useful in cases where you do not have an existing configuration file and want to build out the structure that will be used for your actual deployment package.

Example scenario

In this scenario, we want to deploy an application called MyApp to an environment called MyProdEnvironment and use a patch dictionary called MyPatchDictionary to swap out and remove values during the deployment.

• Within the MyApp deployment package, there is an existing JSON configuration file called myconfig.json.

• We will use the myconfig.json file as our sample file, creating activators and patch entries based on values in the file.

• During deployment, when the specified patch values are encountered, the value is properly modified or removed based on the patch entries that you have defined.

Create a patch dictionary

To create a JSON patch dictionary:

1. Navigate to Environments, click and select New > patch > JsonPatchDictionary

2. Type a Name for your patch dictionary. For example, MyPatchDictionary. In Source Type, you can select Packages or Custom:

   • Packages: Lets you to select a JSON or YAML configuration file from an application CI to use as a sample.
   • Custom: Lets you define your own JSON or YAML sample file from scratch.

   For this scenario, we will select Packages as the Source Type and then select a package from the dropdown list that we know includes deployables with values that we want to substitute when we deploy our application.

3. The myconfig.json file exists as a deployable in the MySampleApp application. In the Packages field, select Applications/MySampleApp/1.0. Deploy will look for all JSON and YAML files found in this location and present them as samples that you can select.

   

4. Click Next. The Activation rules page displays.

5. If there is more than one JSON or YAML file in the application package, use the dropdown list to find the one you want to work with. If only a single file exists, its contents are displayed in the Sample section.

   Note: Since YAML files can include multiple documents in a single file (separated using ---), you can select a YAML file and then use the Documents dropdown list to select the specific document within the file.

   In our scenario, a single JSON file called myconfig.json is found and displayed.

   

Configure the patch dictionary

The values we want to be able to patch when deploying our application are storage and persistentVolumeReclaimPolicy. First we need to create an activator based on the kind being equal to PersistentVolume. To do this:

1. Click on the kind line. The Add activator dialog displays.

   

   • Path: Path that identifies files that are eligible for patching.
   • Condition: Choose whether the rule should be applied if only the key is found (Exists) or if the key and value are both found (Equals).
   • Value: Value of the path, which is used to identify files that are eligible for patching when the condition is Equals. This field is empty is the condition is Exists.

   In this case, we want to locate a path (/kind) that has a value equal to PersistentVolume.

2. Click Create activator.

   Note: For a scenario where the key and value provided do not match the value in the sample, the following message displays: You provided some unsupported values. Are you sure that you want to Save and close?. This is simply a warning indicating that the activator would fail for the currently selected sample, but may be useful in troubleshooting patch behavior (for example, if a patch was expected to be applied, but was not).

3. Click Next. The Patch rules page displays.

   The Patch rules page includes a split screen view from which you can select a line item from the Sample section and specify a patching option in Patch with section.

   Patching options include:

   • Replace/edit a value of an object or array with the specified value (the pencil icon). Using this option, you can also add a value to an object or insert it into an array. For an array, the value is inserted before the given index.
   • Remove a value from an object or array (trashcan icon).

4. Click the storage line in the Sample section.

5. In the Patch with section, change the value from 2Gi to 4Gi.

6. Click Update patch entry.

   The new patch entry is added to the Patch entries section and the Sample section is updated to reflect the new value.

   

7. Click the persistentVolumeReclaimPolicy line.

8. In the Patch with section, change the Recycle value to Retain.

9. Click Update patch entry.

10. Click View Differences.

    

    • The myconfig.json side shows the original values from the sample that are impacted by the patch entries.
    • The Patch side shows the new values that were substituted.

11. Click Save and Close.

Associate your patch dictionary with your deployment plan

You can now associate MyPatchDictionary with MyProdEnvironment and deploy MyApp to the MyProdEnvironment.

1. Double-click the MyProdEnvironment and click Edit properties.

2. In the Common section, next to Patch Dictionaries, find and select MyPatchDictionary.

   

3. Click Save and Close.

4. Expand the MyApp application. Click the next to the 1.0 package and select Deploy.

   

5. On the Select Environment page, select MyProdEnvironment and click Continue.

   

   The Configure page displays.

   

6. On the Configure page, click Preview and expand the steps in the Preview column.

7. Double-click the first step under Deploy MyApp 1.0 on MyProdEnvironment. The Step preview page displays. The step includes the patched values configured in the MyPatchDictionary. Specifically:

   • The storage value is changed from its original value of 2Gbi to 4Gbi
   • The persistentVolumeReclaimPolicy value is changed from its original value of Recycle to Retain.

8. Click Deploy. The MyApp/1.0 application package is deployed to MyProdEnvironment with the patched values.