diff --git a/docs/additional-features/context-data.md b/docs/additional-features/context-data.md deleted file mode 100644 index 432203f92..000000000 --- a/docs/additional-features/context-data.md +++ /dev/null @@ -1,3 +0,0 @@ -# Context Data - -{!docs/models/extras/configcontext.md!} diff --git a/docs/additional-features/tags.md b/docs/additional-features/tags.md deleted file mode 100644 index 0609524f4..000000000 --- a/docs/additional-features/tags.md +++ /dev/null @@ -1,3 +0,0 @@ -# Tagging - -{!docs/models/extras/tag.md!} diff --git a/docs/models/extras/configcontext.md b/docs/models/extras/configcontext.md index 380e631d8..af81cfbf9 100644 --- a/docs/models/extras/configcontext.md +++ b/docs/models/extras/configcontext.md @@ -1,5 +1,65 @@ # Configuration Contexts -Sometimes it is desirable to associate arbitrary data with a group of devices to aid in their configuration. For example, you might want to associate a set of syslog servers for all devices at a particular site. Context data enables the association of arbitrary data to devices and virtual machines grouped by region, site, role, platform, and/or tenant. Context data is arranged hierarchically, so that data with a higher weight can be entered to override more general lower-weight data. Multiple instances of data are automatically merged by NetBox to present a single dictionary for each object. +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: -Devices and Virtual Machines may also have a local config context defined. This local context will always overwrite the rendered config context objects for the Device/VM. This is useful in situations were the device requires a one-off value different from the rest of the environment. +* Region +* Site +* Role +* Platform +* Cluster group +* Cluster +* 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: + +```json +{ + "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: + +```json +{ + "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. diff --git a/docs/models/extras/tag.md b/docs/models/extras/tag.md index f94957616..29cc8b757 100644 --- a/docs/models/extras/tag.md +++ b/docs/models/extras/tag.md @@ -1,24 +1,20 @@ # Tags -Tags are free-form text labels which can be applied to a variety of objects within NetBox. Tags are created on-demand as they are assigned to objects. Use commas to separate tags when adding multiple tags to an object (for example: `Inventoried, Monitored`). Use double quotes around a multi-word tag when adding only one tag, e.g. `"Core Switch"`. +Tags are user-defined labels which can be applied to a variety of objects within NetBox. They can be used to establish dimensions of organization beyond the relationships built into NetBox. For example, you might create a tag to identify a particular ownership or condition across several types of objects. -Each tag has a label and a URL-friendly slug. For example, the slug for a tag named "Dunder Mifflin, Inc." would be `dunder-mifflin-inc`. The slug is generated automatically and makes tags easier to work with as URL parameters. +Each tag has a label, color, and a URL-friendly slug. For example, the slug for a tag named "Dunder Mifflin, Inc." would be `dunder-mifflin-inc`. The slug is generated automatically and makes tags easier to work with as URL parameters. Each tag can also be assigned a description indicating its purpose. Objects can be filtered by the tags they have applied. For example, the following API request will retrieve all devices tagged as "monitored": -``` +```no-highlight GET /api/dcim/devices/?tag=monitored ``` -Tags are included in the API representation of an object as a list of plain strings: +The `tag` filter can be specified multiple times to match only objects which have _all_ of the specified tags assigned: +```no-highlight +GET /api/dcim/devices/?tag=monitored&tag=deprecated ``` -{ - ... - "tags": [ - "Core Switch", - "Monitored" - ], - ... -} -``` + +!!! note + Tags have changed substantially in NetBox v2.9. They are no longer created on-demand when editing an object, and their representation in the REST API now includes a complete depiction of the tag rather than only its label. diff --git a/mkdocs.yml b/mkdocs.yml index 091a3af5c..9de863b4c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -44,7 +44,7 @@ nav: - Additional Features: - Caching: 'additional-features/caching.md' - Change Logging: 'additional-features/change-logging.md' - - Context Data: 'additional-features/context-data.md' + - Context Data: 'models/extras/configcontext.md' - Custom Fields: 'additional-features/custom-fields.md' - Custom Links: 'additional-features/custom-links.md' - Custom Scripts: 'additional-features/custom-scripts.md' @@ -53,7 +53,7 @@ nav: - NAPALM: 'additional-features/napalm.md' - Prometheus Metrics: 'additional-features/prometheus-metrics.md' - Reports: 'additional-features/reports.md' - - Tags: 'additional-features/tags.md' + - Tags: 'models/extras/tag.md' - Webhooks: 'additional-features/webhooks.md' - Plugins: - Using Plugins: 'plugins/index.md'