Use patch dictionaries (BETA)
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.
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 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.
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, XL Deploy will parse them in the order that they are listed in the Environment properties page.
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, XL Deploy uses an “all or nothing” approach - if one of the activators is not satisfied, the patch will not be applied to the file.
A patch entry contains the actual instruction to modify a JSON or YAML file to add, replace or remove a value within it. 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.
The patch dictionary wizard lets you select a sample JSON or YAML file from an existing deployment package in XL 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.
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
- We will use the
myconfig.jsonfile 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.
You must first enable the JSON patch dictionary in order to use it. To enable a JSON patch dictionary:
- Add a plugin:
- Add the
xld-patch-dictionary-core libto the
The JSON patch dictionary option should now be visible in the tree context menu of the XL Deploy CI explorer under:
Environments > New > patch > JsonPatchDictionary
To create a JSON patch dictionary:
- Navigate to Environments, click and select New > patch > JsonPatchDictionary
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.
myconfig.jsonfile exists as a deployable in the MySampleApp application. In the Packages field, select Applications/MySampleApp/1.0. XL Deploy will look for all JSON and YAML files found in this location and present them as samples that you can select.
- Click Next. The Activation rules page displays.
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.jsonis found and displayed.
The values we want to be able to patch when deploying our application are
persistentVolumeReclaimPolicy. First we need to create an activator based on the
kind being equal to
PersistentVolume. To do this:
Click on the
kindline. 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
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).
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).
- Click the
storageline in the Sample section.
- In the Patch with section, change the value from
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.
- Click the
- In the Patch with section, change the
- Click Update patch entry.
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.
- Click Save and Close.
You can now associate MyPatchDictionary with MyProdEnvironment and deploy MyApp to the MyProdEnvironment.
- Double-click the MyProdEnvironment and click Edit properties.
In the Common section, next to Patch Dictionaries, find and select MyPatchDictionary.
- Click Save and Close.
Expand the MyApp application. Click the next to the 1.0 package and select Deploy.
On the Select Environment page, select MyProdEnvironment and click Continue.
The Configure page displays.
- On the Configure page, click Preview and expand the steps in the Preview column.
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:
storagevalue is changed from its original value of
persistentVolumeReclaimPolicyvalue is changed from its original value of
- Click Deploy. The MyApp/1.0 application package is deployed to MyProdEnvironment with the patched values.