AppsConfiguration ManagerGolden ConfigurationsCLI Golden Configurations

JSON Golden Configurations

Golden Configurations can also be used to evaluate the compliance of services that use adapters to communicate with Itential Platform. To do this, Configuration Manager queries those adapters and grades their responses.

Because adapters communicate in JSON format, they can only be managed by Golden Configurations of the JSON OS type. JSON Golden Configurations follow many of the same conventions as CLI Golden Configurations. As such, this guide will only cover the Golden Configuration elements that differ when working with JSON data.

How JSON Golden Configurations work

Every node in a JSON Golden Configuration also has an associated baseline configuration, though it behaves slightly differently than when working with devices. It consists of:

  • Lines of JSON data that mimic the expected adapter response
  • Rules that determine how those lines are interpreted (whether the line should be present or absent from the response)

Once an adapter task (represented in JSON Golden Configurations as a task instance) has been added to a node, you can run compliance checks against it. The adapter task is executed, and the response received from it is compared to the node’s baseline configuration. A compliance report is then generated from this comparison.

JSON Golden Configuration

JSON configuration options

The configuration that task instances must be compliant with is created on the Configuration tab. JSON configurations function similarly to CLI configurations—type the JSON data you would like to verify incoming responses against into the text editor, then define any needed rules. However, there are some key differences.

In JSON configurations, rules are defined on a line-by-line basis using the JSON Configuration Options modal. To open the modal, right-click on the line you would like to edit. The selected line, or path, is displayed at the top of the modal in JSONPath dot notation.

JSON Configuration Options modal

For example, if you selected line 15 from the configuration snippet below, the path would be displayed as vpcs[1].interfaces:

1{
2  "interfaces": [],
3  "vpcs": [
4    {
5      "vpcId": "none"
6    },
7    {
8      "vpcId": "test",
9      "sysNtp": [
10        "13.202.18.187",
11        "129.135.229.181",
12        "47.132.55.37",
13        "13.79.253.232"
14      ],
15      "interfaces": [
16        {
17          "name": "1.1",
18          "ifIndex": "48",
19          "mac-address": "00:10:58:81:34:c2",
20          "A": [],
21          "hello": "A"
22        },
23        {
24          "name": "1.2",
25          "ifIndex": "65",
26          "mac-address": "00:21:27:42:12:d3",
27          "A": []
28        }
29      ]
30    }
31  ]
32}

Tabs

Different tabs are made available on the modal depending on the context of the path:

  • The Rules tab is always available
  • The Key Validation tab is only available if the path references a key-value pair
  • The Array Operations tab is only available if the path is at the root of (opens or closes) an array

The rules provided by these tabs are also contextual. For example, even if the Rules tab is currently available, it will not display rules that are irrelevant to the current path.

The JSON Configuration Options modal was introduced in version 2023.1 of Itential Platform. It was much simplified compared to its current iteration, featuring only the functionality of the Rules and Key Validation tabs. In the 2023.2 version, Array Operations were introduced and the modal was split into three tabs.

Rules tab

The Rules tab provides general-purpose rules that can be applied to most paths.

RuleDescription
EvaluationDetermines whether the path should be required in responses, disallowed from responses, or ignored (not graded in compliance reports)
Violation SeverityDetermines the weight given to violations of the defined evaluation rule (Error is the most severe, Info is the least severe)
Identifier KeyOnly available if the path opens (or closes) an array of objects (selects the key that will be used to match incoming array objects to their definition in the configuration; this is sometimes required due to the unpredictable nature of array ordering; any key that appears in all objects of an array and has a primitive value may be used as the identifier key; largely used in conjunction with array operation rules)

Key Validation tab

The Key Validation tab provides rules that determine how key-value pairs are interpreted in the current path. In practice, these rules are only used when the path is an array of objects. In such scenarios, these rules can evaluate keys that should (or should not) appear in every object of the array.

RuleDescription
Object KeyEnables key validation and determines whether the key referenced by the path should be required or disallowed in responses
Check every keyOnly available if key validation is enabled (checks all parallel objects in the path for the referenced key)
Check every valueOnly available if key validation is enabled and the referenced key has a primitive value (searches all parallel objects in the path for the referenced key, then checks the value of the key; when enabled, type the value the incoming responses should be verified against into the Value field)

Array Operations tab

The Array Operations tab provides rules that determine how the array referenced by the current path is interpreted.

If the current path references an array of objects, an identifier key must be set via the Rules tab. All rules defined on the Array Operations tab will only affect the identifier key.

RuleDescription
UniquenessEnsures there are no duplicate elements in the array
Treat Object as an ArrayAny incoming objects are wrapped in an array
OrderingOnly available if uniqueness is being enforced
- Strict ensures that all array indexes in the response are received in the order defined by the configuration
- Loose acts similarly to strict, but allows indexes not defined in the configuration to be present at any point in the response
RestrictionsDetermines which array indexes are expected in the response
- At least these items ensures that the response contains all indexes defined in the configuration, but does not restrict other indexes from being present
- Exactly these items ensures that the response only contains the indexes defined in the configuration
- None of these items ensures that none of the indexes defined in the configuration are present in the response
Operations SeverityDetermines the weight given to violations of rules defined on the Array Operations tab (Error is the most severe, Info is the least severe)

Reporting key

By default, noncompliant objects present in an array are designated by index value. For example, if an object at the second index of an array named vpcs is noncompliant, it will be referred to by the path vpcs[1]. However, because index values are not always static, it can sometimes be challenging to locate the noncompliant object.

To address this issue, you may use the value of an object key as a reporting identifier:

1

Add reporting key

Click the + Reporting Key button near the top of the modal. A text input field will appear.

2

Enter key name

Enter the key you would like to use as an identifier into the text input field.

3

Save

Click the Save Keys button.

Itential recommends that you use a key that appears in every array object and has a unique value across all array objects.

Variable and regular expression support

To prevent syntax errors, different delimiters are used in JSON configurations to define variables than in CLI configurations.

To utilize variables in a JSON configuration, use the $_ _$ delimiters. In the following example, the value of "vpcName" will be replaced by the variable value:

1{
2    "vpcName": "$_varName_$"
3}

Regular expressions can be utilized in a similar manner by using the $/ /$ delimiters. For example, to ensure that the value of "deviceName" begins with Itential:

1{
2    "deviceName": "$/Itential.*/$"
3}

Manage task instances

Once your baseline configuration has been defined, you can use it to measure the compliance of any applicable task instances. All operations related to task instances are performed from the Manage tab.

Create a task instance

1

Open Add Adapter Task modal

Select the Add Task (+) button from the toolbar at the top of the Manage tab. The Add Adapter Task modal will appear.

Add Adapter Task modal
2

Select adapter and task

  • Select an adapter from the list on the right side of the modal. All related adapter tasks will be displayed.
  • Click the adapter task that you would like to run compliance checks against.
3

Add task

Click the Add (+) button at the bottom of the modal.

4

Define parameters

After clicking Add (+), the parameters dialog will appear. Define the following for the adapter task:

  • A unique (within the node) instance name
  • Any parameters required to execute the task
Adding an adapter task
5

Submit

After all required parameters have been defined, click the Submit button located at the bottom of the dialog to create the task instance.

Run compliance

To run a compliance check against a task instance:

1

Open task menu

Click the menu button (⋮) of the task you would like to run a compliance check against.

2

Run compliance

Select Run Compliance (▶) from the menu that appears.

Run compliance
3

View compliance report

Once the compliance process has finished running, select the View Compliance menu option to display the Compliance and Reporting window.

Compliance report