Docs

Deviation Rules (preview)

Write a YAML rule file that decides, per deviation, whether NetBox Assurance applies it to NetBox or holds it for review.

Deviation rules decide which deviations NetBox Assurance applies to NetBox automatically and which ones wait for review. You write the rules in one YAML file. The Diode reconciler reads the file when it starts.

Before you begin

  • You need NetBox Enterprise 2.5.0 or later, with the NetBox Assurance entitlement. Without the entitlement, the Diode reconciler silently ignores the rule file.
  • Auto apply ingested entities to NetBox must be off. When it is on, NetBox Assurance applies every deviation without review, and the Admin Console hides the Deviation rules (preview) field. When it is off and there are no rules, NetBox Assurance holds every deviation for review, except for the rules that match the conditions.

A first rule file

This file applies changes to devices with the tag branch and holds every other deviation for review:

version: 1
rules:
  - name: branch-devices
    action: apply
    object_types:
      - dcim.device
    related_object_types: []
    tag:
      name: branch
  - name: everything-else
    action: review
    object_types:
      - "*"
  • A serial number update on a device with the tag branch is applied by branch-devices.
  • A serial number update on a device without the tag is held by everything-else.
  • A description update on an interface of a branch device is held. branch-devices matches only deviations whose root object is a device. See What a rule matches.
  • A branch device that moves to a site that is not in NetBox is held, because related_object_types: [] allows no related changes, so the deviation cannot create the site.

The sections below explain these results. Examples has more rule files, and Rule file reference describes every key.

How NetBox Assurance decides

NetBox Assurance plans each deviation. Then it reads the rules in file order:

  1. It skips each rule that has enabled: false.
  2. The first rule that matches decides the action. NetBox Assurance ignores the rules after it.
  3. If no rule matches, NetBox Assurance holds the deviation for review.
actionResult
applyNetBox Assurance applies the deviation to NetBox. If the apply succeeds, the deviation gets the status Applied.
reviewNetBox Assurance holds the deviation with the status Active. You apply, ignore, or rediff it in NetBox Assurance.

The first match wins

Put specific rules before general rules. A rule with object_types: ["*"] and no other limits matches every deviation that the rules above it did not match, so the rules below it never run. For an apply rule, no other limits means related_object_types: ["*"], no operations, and no conditions. NetBox Assurance does not warn you about a rule that it cannot reach.

One check runs before the rules. If a deviation only creates custom field definitions, and none of them is required or has a default value, NetBox Assurance applies it without reading the rules. Deviations whose data uses those custom fields still go through the rules, and they can be applied because the custom fields now exist. A deviation that also creates something else, such as a new choice set for a custom field, goes through the rules.

What a rule matches

A deviation is one ingested object, the root object, and all the related objects that the plan changes for it. For example, an IP address payload names its interface and its device. If the interface description is also different from NetBox, the deviation contains two changes: a create of the IP address, which is the root object, and an update of the interface, which is a related change.

  • A rule matches the root object type only. object_types compares the type of the root object, such as ipam.ipaddress. A rule for dcim.interface does not match an IP address deviation, even when that deviation also changes an interface.
  • A deviation applies as one unit. You cannot apply part of a deviation.
  • A related object that NetBox already holds with the same values is not a change. It does not count against related_object_types or operations.
  • A second object of the root type is a related change. For example, an interface payload that creates a new parent interface has one related dcim.interface change.
  • An update of an object that the same deviation creates counts as a create.

Apply rules and review rules read a deviation differently:

Apply ruleReview rule
ReadsThe root object and every related change.The root object only. It ignores related changes.
related_object_typesRequired. The type of each related change must be in this list.Not allowed.
operationsEach change, root and related, must be in this list.The changes to the root object must be in this list.

The difference is intentional: an apply rule writes to NetBox, so it must allow every change in the deviation. A review rule holds the whole deviation, so it describes only the root object. If the deviation does not change the root object, operations does not stop a review rule from matching.

Examples

These examples assume a NetBox instance with:

  • Branch router br042-rtr01 at site Branch 042, with the tag branch.
  • Data center switch dc1-core01 at site DC1, with the tag core and without the tag branch. Site DC1 has the tag datacenter.
  • Lab switch lab-sw01, with the device custom field environment set to lab.

The results assume Diode NetBox plugin 1.19.0 or later. With an older plugin, a rule that needs a tag set only in NetBox does not match.

Review by default, apply exceptions

Discovery keeps branch offices current without review. Data center changes wait for an engineer.

version: 1
rules:
  - name: branch-devices
    action: apply
    object_types:
      - dcim.device
    related_object_types: []
    tag:
      name: branch
  - name: branch-interfaces
    action: apply
    object_types:
      - dcim.interface
    related_object_types:
      - dcim.device
    tag:
      name: branch
      scope: parent_device
  - name: branch-new-ip-addresses
    action: apply
    object_types:
      - ipam.ipaddress
    operations:
      - create
    related_object_types: []
    tag:
      name: branch
      scope: parent_device
  - name: everything-else
    action: review
    object_types:
      - "*"
DeviationResultWhy
Serial number update on br042-rtr01Appliedbranch-devices
Serial number update on dc1-core01Heldeverything-else. The device does not have the tag branch.
br042-rtr01 moves to a site that is not in NetBoxHeldeverything-else. The plan creates a dcim.site, and branch-devices allows no related changes.
Description update on interface Gi0/0/1 of br042-rtr01Appliedbranch-interfaces
Description update on Gi0/0/1 and serial number update on br042-rtr01 in one payloadAppliedbranch-interfaces. The rule allows related dcim.device changes.
New IP address 10.42.0.1/30 on Gi0/0/1Appliedbranch-new-ip-addresses
New IP address 10.42.0.1/30 whose payload also changes the Gi0/0/1 descriptionHeldeverything-else. The root object type is ipam.ipaddress, so branch-interfaces does not match. branch-new-ip-addresses allows no related changes.
Status update on an existing IP address of Gi0/0/1Heldeverything-else. branch-new-ip-addresses allows create only.

The everything-else rule is optional, because a deviation that matches no rule is held. It makes the default visible in the file.

Apply by default, review exceptions

Discovery updates NetBox without review. New sites and new prefixes are planning decisions, and core devices are under change control, so these wait for an engineer.

version: 1
rules:
  - name: hold-new-sites
    action: review
    object_types:
      - dcim.site
    operations:
      - create
  - name: hold-new-prefixes
    action: review
    object_types:
      - ipam.prefix
    operations:
      - create
  - name: hold-core-devices
    action: review
    object_types:
      - dcim.device
    tag:
      name: core
  - name: everything
    action: apply
    object_types:
      - "*"
    related_object_types:
      - "*"
DeviationResultWhy
New site Branch 043Heldhold-new-sites
New site Branch 043 in a new regionHeldhold-new-sites. A review rule ignores the related region create.
Description update on site Branch 042Appliedeverything
New prefix 10.42.0.0/24Heldhold-new-prefixes
Serial number update on dc1-core01Heldhold-core-devices
Description update on interface Eth1/1 of dc1-core01Appliedeverything. The root object is an interface, so hold-core-devices does not match.
New device br043-rtr01 whose payload creates site Branch 043Appliedeverything. The root object is a device, so hold-new-sites does not match.

A review rule cannot hold an object that arrives inside the payload of another object type. To hold a new site that arrives in a device payload, replace "*" in related_object_types of the everything rule with the related types that you allow, and leave out dcim.site.

Rule order

Uplinks carry traffic for the whole branch, so changes to uplink interfaces wait for review, even on branch routers.

version: 1
rules:
  - name: hold-uplinks
    action: review
    object_types:
      - dcim.interface
    tag:
      name: uplink
  - name: branch-interfaces
    action: apply
    object_types:
      - dcim.interface
    related_object_types: []
    tag:
      name: branch
      scope: parent_device
DeviationResultWhy
Update on interface Gi0/0/1 of br042-rtr01, tagged uplinkHeldhold-uplinks matches first.
Update on interface Gi0/1/0 of br042-rtr01, not tagged uplinkAppliedbranch-interfaces
Update on interface Eth1/1 of dc1-core01HeldNo rule matches.

If you swap the two rules, branch-interfaces applies the change to Gi0/0/1. If you set enabled: false on hold-uplinks, the result is the same.

Custom field on the parent device

Changes to lab switches do not need review. The device custom field environment identifies them.

version: 1
rules:
  - name: lab-interfaces
    action: apply
    object_types:
      - dcim.interface
    related_object_types:
      - dcim.device
    custom_field:
      name: environment
      equals: lab
      scope: parent_device
DeviationResultWhy
Interface update on lab-sw01. The payload does not send environment.Appliedlab-interfaces reads lab from NetBox.
Interface update on lab-sw01. The payload sends environment: production.HeldThe payload value replaces the NetBox value.
Interface update on a device without environmentHeldNo rule matches.

Field path scope

Interface changes at data center sites wait for review. All other changes are applied.

version: 1
rules:
  - name: hold-datacenter-interfaces
    action: review
    object_types:
      - dcim.interface
    tag:
      name: datacenter
      scope: device.site
  - name: everything
    action: apply
    object_types:
      - "*"
    related_object_types:
      - "*"
DeviationResultWhy
Update on interface Eth1/1 of dc1-core01. The payload sends site DC1 without tags.Heldhold-datacenter-interfaces reads the tag datacenter from NetBox.
Update on interface Gi0/0/1 of br042-rtr01Appliedeverything. Site Branch 042 does not have the tag datacenter.
Update on interface Eth1/1 of dc1-core01. The payload device has no site.Appliedeverything. The scope does not resolve, so hold-datacenter-interfaces does not match.

Validate a rule file

Validate the file before you deploy it. Download the JSON Schema: deviation-rules.schema.json.

  • In your editor: put this line at the top of the rule file, with the path to the schema. Editors with a YAML language server, such as VS Code with the YAML extension, then show errors as you type.

    # yaml-language-server: $schema=deviation-rules.schema.json
  • On the command line: run check-jsonschema:

    uvx check-jsonschema --schemafile deviation-rules.schema.json rules.yaml

The schema checks the structure of the file. It does not check that rule names are unique, that each object type exists, or that each field path scope exists. The Diode reconciler checks these when it starts.

Set the rules

Admin Console

  1. Open the Admin Console at https://<your-cluster-host-or-ip>:30000/ and select the Config tab.
  2. In the Diode section, turn off Auto apply ingested entities to NetBox.
  3. Select Show Advanced Diode Settings.
  4. Paste the full rule file into Deviation rules (preview).
  5. Save the configuration and deploy it.

The Deviation rules (preview) field appears only when the license has the NetBox Assurance entitlement and Auto apply ingested entities to NetBox is off. The rules stay in force when you collapse the advanced settings. When you turn on Auto apply ingested entities to NetBox, the Admin Console keeps the rule text but does not use it. If you turn the setting off again, those rules apply again. Clear the field first if you do not want them.

When you deploy a change to the field and the operator accepts the file, the Diode reconciler restarts and reads the new file. To stop using rules, clear the field and deploy. NetBox Assurance then holds every deviation for review again, except new custom field definitions.

NetBoxEnterprise resource

Put the rule file in spec.diode.config.reconciler.deviationRules as a string. Set spec.diode.config.reconciler.autoApplyChangesets to false. If you leave autoApplyChangesets out, it is true. While deviationRules is set and autoApplyChangesets is true, the operator does not reconcile the resource: no part of the change deploys, and the resource status gives the error.

spec:
  diode:
    config:
      reconciler:
        autoApplyChangesets: false
        deviationRules: |
          version: 1
          rules:
            - name: everything-else
              action: review
              object_types:
                - "*"

For a Helm install, put the same fields under netboxEnterprise.spec in your values file.

When NetBox Enterprise refuses a file

Two checks run in sequence:

  1. The operator checks the shape. The text must be a YAML mapping with an unquoted version. For version: 1, rules, if present, must be a list, and each rule must have a unique, non-empty name. If a check fails, the operator keeps the last rule file that it accepted, or no file, and the Diode reconciler does not restart. The rest of the change deploys. The Admin Console deploy succeeds and does not show the refusal. To see the reason, run kubectl describe netboxenterprise -n <namespace>. The DeviationRulesRefused condition and a Warning event give it.
  2. The Diode reconciler checks the full file when it starts. If the file is not valid, the reconciler exits and restarts in a loop. Its pod log shows failed to load deviation rules and the reason, and the Admin Console shows the application as not ready. Reconciler pods are replaced one at a time, so with two or more replicas the other pods can continue to run the previous rules. Do not rely on this: a pod that restarts for any reason reads the new file and fails too. Correct the file, or clear the field, and deploy again.

For the problems that the Diode reconciler refuses, see Files the reconciler refuses.

Find out why a deviation was applied or held

The Diode reconciler log shows each decision:

  • At the INFO level, the deviation rule applies message names the rule that applied each deviation. It does not say why the rules before it did not match.
  • At the DEBUG level, a deviation held for review message is logged for each held deviation. It gives the review rule that held it (if any), the changes in the deviation, and why each enabled rule before the decision did not match

The log does not show the custom field definitions that are applied before the rules.

To set the DEBUG level, add LOGGING_LEVEL=DEBUG to Reconciler extra env vars in the Admin Console. For a Helm install, set spec.diode.config.reconciler.logLevel to DEBUG in the NetBoxEnterprise resource. On an Admin Console install, Enable Debug Logging sets logLevel on each deploy.

This reason means that branch-devices did not match because the plan creates a site:

branch-devices: related change create dcim.site not in related_object_types []; add dcim.site, or "*" for any, to apply it with the deviation

Limits

  • The rules decide when NetBox Assurance plans a deviation. A new rule file does not change the deviations that are already held for review.
  • A changed rule file takes effect only after the Diode reconciler restarts.
  • A deviation applies as one unit. For example, an interface update inside an IP address deviation is applied or held with the IP address.
  • A review rule reads the root object only. With a catch-all apply rule that has related_object_types: ["*"], an object that arrives inside the payload of another object is applied. See Apply by default, review exceptions.
  • Conditions trust the tags and custom field values that the payload sends. Anyone with Diode credentials can send a tag or a custom field value that meets an apply rule. The rules decide which changes from a trusted source need review. They do not protect NetBox from a source that you do not trust.
  • A deviation that a rule applies has the status Active for a short time before it is applied.
  • NetBox Assurance plans the deviation again when it applies it. If NetBox changes in that time, the applied changes can be different from the changes that the rule read.
  • NetBox Assurance records the rule name only on deviations that a rule applied.

Rule file reference

Keys

This rule uses every key:

version: 1
rules:
  - name: branch-monitored-interfaces
    enabled: true
    action: apply
    object_types:
      - dcim.interface
    operations:
      - create
      - update
    related_object_types:
      - dcim.device
    tag:
      name: branch
      scope: parent_device
    custom_field:
      name: monitored
      equals: true

It applies a new or changed interface when its device has the tag branch and the interface has the custom field monitored set to true. The deviation can also create or update the device. It cannot change other objects.

KeyRequiredValue
versionYes1.
rulesNoThe rules, in evaluation order. An empty or missing list holds every deviation for review, except new custom field definitions.
nameYesA unique name. NetBox Assurance records it on each deviation that the rule applies, and the Diode reconciler writes it to its log. The Assurance UI does not show it.
enabledNotrue (default) or false. NetBox Assurance skips a rule with false. The reconciler still checks that a disabled rule is valid.
actionYesapply or review.
object_typesYesThe root object types that the rule matches, such as dcim.device. "*" matches all types.
operationsNocreate, update, or both. If you leave it out, both are allowed. Do not write an empty list.
related_object_typesApply rules: yes. Review rules: not allowed.The types that related changes can have. [] allows no related changes. "*" allows all types.
tagNoA tag condition. See Tag condition.
custom_fieldNoA custom field condition. See Custom field condition.

Object types use the NetBox app_label.model format, such as dcim.site, dcim.device, dcim.interface, ipam.prefix, ipam.ipaddress, and extras.tag.

All the conditions in one rule must hold. To match one condition or another, write two rules. A rule can have one tag condition and one custom_field condition.

Tag condition

tag:
  name: branch
  slug: branch
  scope: parent_device

Give name, slug, or both. If you give both, a match on either one is sufficient. The match is exact and case sensitive.

The condition reads the tags that the object will have after the deviation is applied. Diode adds the payload tags to the tags that NetBox already holds, so the condition holds when the payload sends the tag or when NetBox already has the tag on the object. A tag that is set only in NetBox counts with Diode NetBox plugin 1.19.0 or later. See When a condition cannot be decided.

When a payload sends a tag that does not exist in NetBox yet, the plan creates it. That create is a related extras.tag change. To let an apply rule create the tag, add extras.tag to related_object_types.

Custom field condition

custom_field:
  name: environment
  equals: lab
  scope: parent_device

Without equals, the condition holds when the custom field has a value that is not empty. An integer 0 and a boolean false are values.

With equals, the condition holds when the custom field has that value. You can write numbers and booleans without quotes, such as equals: 42 or equals: true. For a multiple selection custom field, the condition holds when the selection contains the value. Write dates as 2026-11-03 and date-times in UTC in RFC 3339 format, such as 2026-11-03T10:00:00Z. Text comparison is exact and case sensitive. equals does not work with object, multiple object, or JSON custom fields.

The condition reads the value that NetBox will hold after the deviation is applied. If the payload sends the custom field, the payload value is used. If the payload does not send it, the current NetBox value is used.

Scope

scope tells a tag or custom_field condition which object to read.

scopeObject that the condition reads
object (default)The root object.
parent_deviceThe device that the root object belongs to. This works for interfaces, console ports, console server ports, power ports, power outlets, front ports, rear ports, device bays, module bays, modules, inventory items, and virtual device contexts. For IP addresses and MAC addresses, it is the device of the assigned interface. A device is its own parent device. Objects on a virtual machine do not have a parent device.
A field pathThe object at a dotted path of fields in the payload, such as device.site, assigned_object_interface.device, or vrf. A path can follow single object fields only, not lists.

A scope is exact. If the scoped object does not have the tag, the condition does not hold, even when the root object has the tag.

The payload must contain the scoped object

A condition does not hold when the payload does not contain the object that its scope names. For example, scope: device.site does not hold for an interface payload whose device has no site. A review rule then does not match, and a later apply rule can apply the deviation. The same applies to parent_device on an object type that has no parent device, such as dcim.site.

When a condition cannot be decided

A condition is undecided when the payload contains the scoped object without the tag or custom field, and NetBox Assurance cannot read the value that NetBox holds for that object. For example, the plan does not name the object. Or a tag is set only in NetBox and the Diode NetBox plugin is older than 1.19.0, which does not give the names of those tags. Then:

  • An apply rule with an undecided condition does not match. NetBox Assurance reads the next rule.
  • A review rule with an undecided condition matches and holds the deviation.

An undecided condition never makes its own rule apply a deviation. A later apply rule can still apply it.

A condition whose scoped object is not in the payload is not undecided. It does not hold, for apply rules and review rules alike. See Scope.

Files the reconciler refuses

The Diode reconciler refuses a file that has one of these problems:

  • No version, or a version other than 1. Write version: 1 without quotes.
  • An unknown key, for example operation instead of operations.
  • A rule without name, or two rules with the same name.
  • A rule without action or object_types, or an unknown action or object type.
  • An operation other than create or update. Diode does not delete objects, so delete is not allowed.
  • An apply rule without related_object_types.
  • A review rule with related_object_types.
  • A tag without name or slug, or a custom_field without name.
  • A field path scope that does not exist on an object type of the rule. With "*", the path must exist on at least one object type.
  • Any of these problems in a rule with enabled: false. The reconciler also checks disabled rules.

The reconciler reads only the first YAML document in the file. It ignores everything after a --- separator, without an error.

On this page