Continued work on feature docs
This commit is contained in:
jeremystretch
@@ -1,69 +1,34 @@
|
||||
# Configuration Contexts
|
||||
# Context Data
|
||||
|
||||
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 group
|
||||
* Site
|
||||
* Location (devices only)
|
||||
* Device type (devices only)
|
||||
* Role
|
||||
* Platform
|
||||
* Cluster type (VMs only)
|
||||
* Cluster group (VMs only)
|
||||
* Cluster (VMs only)
|
||||
* Tenant group
|
||||
* Tenant
|
||||
* Tag
|
||||
|
||||
## 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 NetBox 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:
|
||||
|
||||
```json
|
||||
{
|
||||
"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:
|
||||
Configuration context data (or "config contexts" for short) is a powerful feature that enables users to define arbitrary data that applies to device and virtual machines based on certain characteristics. For example, suppose you want to define syslog servers for devices assigned to sites within a particular region. In NetBox, you can create a config context instance containing this data and apply it to the desired region. All devices within this region will now include this data when fetched via an API.
|
||||
|
||||
```json
|
||||
{
|
||||
"syslog-servers": [
|
||||
"192.168.43.107"
|
||||
"192.168.43.107",
|
||||
"192.168.48.112"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
When the context data for a device at this site is rendered, the second, higher-weight data overwrite the first, resulting in the following:
|
||||
While this is handy on its own, the real power of context data stems from its ability to be merged and overridden using multiple instances. For example, perhaps you need to define _different_ syslog servers within the region for a particular device role. You can create a second config context with the appropriate data and a higher weight, and apply it to the desired role. This will override the lower-weight data that applies to the entire region. As you can imagine, this flexibility can cater to many complex use cases.
|
||||
|
||||
```json
|
||||
{
|
||||
"ntp-servers": [
|
||||
"172.16.10.22",
|
||||
"172.16.10.33"
|
||||
],
|
||||
"syslog-servers": [
|
||||
"192.168.43.107"
|
||||
]
|
||||
}
|
||||
```
|
||||
There are no restrictions around what data can be stored in a configuration context, so long as it can be expressed in JSON. Additionally, each device and VM may have local context data defined: This data is stored directly on the assigned object, and applies to it only. This is a convenient way for "attaching" miscellaneous data to a single device or VM as needed.
|
||||
|
||||
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.
|
||||
Config contexts can be computed for objects based on the following criteria:
|
||||
|
||||
## 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.
|
||||
| Type | Devices | Virtual Machines |
|
||||
|---------------|------------------|------------------|
|
||||
| Region | :material-check: | :material-check: |
|
||||
| Site group | :material-check: | :material-check: |
|
||||
| Site | :material-check: | :material-check: |
|
||||
| Location | :material-check: | |
|
||||
| Device type | :material-check: | |
|
||||
| Role | :material-check: | :material-check: |
|
||||
| Platform | :material-check: | :material-check: |
|
||||
| Cluster type | | :material-check: |
|
||||
| Cluster group | | :material-check: |
|
||||
| Cluster | | :material-check: |
|
||||
| Tenant group | :material-check: | :material-check: |
|
||||
| Tenant | :material-check: | :material-check: |
|
||||
| Tag | :material-check: | :material-check: |
|
||||
|
||||
Reference in New Issue
Block a user