You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This library is meant to be a light-weight way to compare structured output from network devices `show` commands. `netcompare` is a python library targeted at intelligently deep diffing structured data objects of json type. In addition, `netcompare` can also provide some basic testing of key/values within a data structure.
3
+
The `jdiff` is a light-weight library to examine structured data. `jdiff` provides an interface to intelligently compare json data objects as well as test for the presence (or absence) of keys, and to examine and compare their values.
4
4
5
-
The library heavily relies on [jmespath](https://jmespath.org/) for traversing the json object and finding the value(s) to be evaluated. More on that later.
5
+
The library heavily relies on [jmespath](https://jmespath.org/) for traversing the json object and finding the value(s) to be evaluated. More on that [here](#customized-jmespath).
6
6
7
-
## Use Case
7
+
## Usage
8
8
9
-
`netcompare` enables an easy and direct way to see the outcome of network configuration or operational status change. The intended usage is to collect structured `show` command output before and after a change window. Prior to closing the change window, the results are compared to help determine if the change was successful as intended and if the network is in an acceptable state. The output can be stored with the change's documentation for easy reference and proof of completion.
9
+
A `jdiff` Check accepts two objects as input: the reference object, and the comparison object. The reference object is used as the intended or accepted state and it's keys and values are compared against the comparison object.
10
+
11
+
`jdiff` does not collect the data for you, it simply works on data passed into it. This allows for maximum flexibility in collecting the data.
12
+
13
+
For instance, the reference state can be collected from the network directly using any method that returns structured data: ansible, napalm, nornir to name a few. You could also choose to generate the reference state from an SoT, such as [Nautobot](https://github.com/nautobot/nautobot/), and have a true intended state.
14
+
15
+
`jdiff` is perfectly suited to work with data gathered from network devices via show commands, Ansible playbooks, as well as in applications such as [Nautobot](https://github.com/nautobot/nautobot/), or [Netbox](https://github.com/netbox-community/netbox). `jdiff` is focused on being the 'plumbing' behind a full network automation validation solution.
16
+
17
+
### Testing data structures
18
+
19
+
Briefly, these tests, or `CheckTypes`, are provided to test the objects, to aide in determining the status of the data.
20
+
21
+
-`exact_match`: the keys and values much match, exactly, between the two objects
22
+
-`tolerance`: the keys must match and the values can differ according to the 'tolerance' value provided
23
+
-`parameter_match`: a reference key and value is provided and it's presence (or absence) is checked in the provided object
24
+
-`regex`: a reference regex pattern is provided and it's presence (or absence) is checked for a match in the provided object
25
+
-`operator`: similar to parameter match, but the reference includes several different possible operators: 'in', 'bool', 'string', and numerical comparison with 'int' and 'float' to check against
26
+
27
+
`CheckTypes` are explained in more detail in the [CheckTypes Explained section](#check-types-explained).
28
+
29
+
30
+
## Workflow
31
+
32
+
||
33
+
|:---:|
34
+
|**`jdiff` workflow**|
35
+
36
+
37
+
1. The reference state object is assembled. The structured data may be collected from:
38
+
39
+
- an SoT
40
+
- Directly from the network using any Automation that returns structured data
41
+
42
+
2. The Network Engineer makes changes to the network, whether it is an upgrade, peering change, or migration.
43
+
3. The comparison state is collected, typically directly from the network, but any method is acceptable.
44
+
4. The reference state is then compared to the current state using the jdiff library.
10
45
11
46
## Library Architecture
12
47
13
-
48
+
||
49
+
|:---:|
50
+
|**`jdiff` architecture**|
14
51
15
52
An instance of `CheckType` object must be created first before passing one of the below check types as an argument:
16
53
17
54
-`exact_match`
18
55
-`tolerance`
19
-
-`parameters`
56
+
-`parameter_match`
20
57
-`regex`
21
58
-`operator`
22
59
@@ -26,7 +63,7 @@ my_check = "exact_match"
26
63
check = CheckType.init(my_check)
27
64
```
28
65
29
-
Next, define a json object as reference data, as well as a JMESPATH expression to extract the value wanted and pass them to `get_value` method. Be aware! `netcompare` works with a customized version of JMESPATH. More on that later.
66
+
Next, define a json object as reference data, as well as a JMESPATH expression to extract the value wanted and pass them to `get_value` method. Be aware! `jdiff` works with a customized version of JMESPATH. More on that [below](#customized-jmespath).
Since `netcompare` works with json objects as data inputs, JMESPATH was the obvious choice for traversing the data and extracting the value(s) to compare.
91
+
Since `jdiff` works with json objects as data inputs, JMESPATH was the obvious choice for traversing the data and extracting the value(s) to compare.
55
92
56
93
However, JMESPATH comes with a limitation where is not possible to define a `key` to which the `value` belongs to.
57
94
@@ -105,7 +142,7 @@ A JMESPATH expression to extract `state` is shown below.
105
142
```
106
143
107
144
How can we understand that `Idle` is relative to peer 7.7.7.7 and `Connected` to peer `10.1.0.0` ?
108
-
We could index the output but that would require some post-processing of the data. For that reason, `netcompare` use a customized version of JMESPATH where it is possible to define a reference key for the value(s) wanted. The reference key must be within `$` sign anchors and defined in a list, together with the value(s):
145
+
We could index the output but that would require some post-processing of the data. For that reason, `jdiff` use a customized version of JMESPATH where it is possible to define a reference key for the value(s) wanted. The reference key must be within `$` sign anchors and defined in a list, together with the value(s):
>>><netcompare.check_types.ExactMatchType object at 0x10ac00f10>
227
+
>>><jdiff.check_types.ExactMatchType object at 0x10ac00f10>
191
228
>>># Extract the wanted value from pre_dat to later compare with post_data. As we want compare all the body (excluding "interfaceStatistics"), we do not need to define any reference key
@@ -219,60 +256,8 @@ Let's see a better way to run `exact_match` for this specific case. Since we are
219
256
```
220
257
Targeting only the `interfaceStatus` key, we would need to define a reference key (in this case `$name$`), we would not define any exclusion list.
221
258
222
-
The anchor logic for the reference key applies to all check-types available in `netcompare`
223
-
259
+
The anchor logic for the reference key applies to all check-types available in `jdiff`
224
260
225
-
### parameter_match
226
-
227
-
parameter_match provides a way to match keys and values in the output with known good values.
228
-
229
-
The test defines key/value pairs known to be the good value - type `dict()` - as well as a mode - `match`, `no-match` - to match or not against the parsed output. The test fails if any status has changed based on what is defined in pre/post. If there are new values not contained in the input/test value, that will not count as a failure.
@@ -358,6 +343,59 @@ Lets have a look to a couple of examples:
358
343
This test can test the tolerance for changing quantities of certain things such as routes, or L2 or L3 neighbors. It could also test actual outputted values such as transmitted light levels for optics.
359
344
360
345
346
+
### Parameter_match
347
+
348
+
parameter_match provides a way to match keys and values in the output with known good values.
349
+
350
+
The test defines key/value pairs known to be the good value - type `dict()` - as well as a mode - `match`, `no-match` - to match or not against the parsed output. The test fails if any status has changed based on what is defined in pre/post. If there are new values not contained in the input/test value, that will not count as a failure.
In network data, this could be a state of bgp neighbors being Established or the connectedness of certain interfaces being up.
397
+
398
+
361
399
### Regex
362
400
363
401
The `regex` check type evaluates data against a python regular expression defined as check-type argument. As per `parameter_match` the option `match`, `no-match`is also supported.
@@ -405,7 +443,7 @@ Let's run an example where we want to check the `burnedInAddress` key has a stri
0 commit comments