Configuration Contexts & Schemas¶

Configuration Contexts¶

Sometimes it is desirable to associate additional data with a group of devices or virtual machines to aid in automated configuration. For example, you might want to associate a set of syslog servers for all devices within a particular region. Context data enables the association of extra user-defined data with devices and virtual machines grouped by one or more of the following assignments:

Region
Site
Role
Device type
Platform
Cluster group
Cluster
Tenant group
Tenant
Tag

Context data not specifically assigned to one or more of the above groups is by default associated with all devices and virtual machines.

Configuration contexts may be managed within Nautobot via the UI and/or API; they may also be managed externally to Nautobot in a Git repository if desired.

Hierarchical Rendering¶

Context data is arranged hierarchically, so that data with a higher weight can be entered to override lower-weight data. Multiple instances of data are automatically merged by Nautobot to present a single dictionary for each object.

For example, suppose we want to specify a set of syslog and NTP servers for all devices within a region. We could create a config context instance with a weight of 1000 assigned to the region, with the following JSON data:

{
    "ntp-servers": [
        "172.16.10.22",
        "172.16.10.33"
    ],
    "syslog-servers": [
        "172.16.9.100",
        "172.16.9.101"
    ]
}

But suppose there's a problem at one particular site within this region preventing traffic from reaching the regional syslog server. Devices there need to use a local syslog server instead of the two defined above. We'll create a second config context assigned only to that site with a weight of 2000 and the following data:

{
    "syslog-servers": [
        "192.168.43.107"
    ]
}

When the context data for a device at this site is rendered, the second, higher-weight data overwrite the first, resulting in the following:

{
    "ntp-servers": [
        "172.16.10.22",
        "172.16.10.33"
    ],
    "syslog-servers": [
        "192.168.43.107"
    ]
}

Data from the higher-weight context overwrites conflicting data from the lower-weight context, while the non-conflicting portion of the lower-weight context (the list of NTP servers) is preserved.

Local Context Data¶

Devices and virtual machines may also have a local config context defined. This local context will always take precedence over any separate config context objects which apply to the device/VM. This is useful in situations where we need to call out a specific deviation in the data for a particular object.

Warning

If you find that you're routinely defining local context data for many individual devices or virtual machines, custom fields may offer a more effective solution.

Config Context Schemas¶

Added in version 1.1.0

While config contexts allow for arbitrary data structures to be stored within Nautobot, at scale it is desirable to apply validation constraints to that data to ensure its consistency and to avoid data entry errors. To service this need, Nautobot supports optionally backing config contexts with JSON Schemas for validation. These schema are managed via the config context schema model and are optionally linked to config context instances, in addition to devices and virtual machines for the purpose of validating their local context data.

A JSON Schema is capable of validating the structure, format, and type of your data, and acts as a form of documentation useful in a number of automation use cases.

A config context is linked to a single schema object and thus they are meant to model individual units of the overall context. In this way, they validate each config context object, not the fully rendered context as viewed on a particular device or virtual machine.

When a config context schema is employed on a config or local context, the data therein is validated when the object in question is saved. Should validation against the schema fail, a relevant error message is returned to the user and they are prevented from saving the data until the validation issue has been resolved.

Here is an example JSON Schema which can be used to validate an NTP server config context:

{
    "type": "object",
    "properties": {
        "ntp-servers": {
            "type": "array",
            "minItems": 2,
            "maxItems": 2,
            "items": {
                "type": "string",
                "format": "ipv4"
            }
        }
    },
    "additionalProperties": false
}

This schema would allow a config context with this data to pass:

{
    "ntp-servers": [
        "172.16.10.22",
        "172.16.10.33"
    ]
}

However it would not allow any of these examples to be saved:

{
    "ntp-servers": [
        "172.16.10.22"
    ]
}

{
    "ntp": "172.16.10.22,172.16.10.22"
}

{
    "ntp-servers": [
        "172.16.10.22",
        "172.16.10.33",
        "5.5.4"
    ]
}

For more information on JSON Schemas and specifically type formats for specialized objects like IP addresses, hostnames, and more see the JSON Schema docs.

Note

Config Context Schemas currently support the JSON Schema draft 7 specification.