Layered Device Configuration with NetBox Config Contexts

Desired Outcome

Centralize per‑device configuration data in NetBox so that automation scripts can pull a single, fully resolved JSON object that reflects global defaults, site‑specific overrides, and device‑role exceptions.

Prerequisites

• NetBox 3.0 or newer, running and accessible over HTTPS.
• Administrative or “Manage Config Contexts” permission on the NetBox instance.
• Existing objects to target: at least one Site, one Device Role, and one Tag (optional).
• An API token with scope extras.config_contexts.read and dcim.devices.read if you plan to use the REST API.

Creating a Base Config Context

1. Navigate to Extras > Config Contexts in the NetBox UI.
2. Click Create to open the context form.
3. Fill in a Name that describes the purpose – e.g., Global‑SNMP‑Defaults.
4. Paste valid JSON into the Data field. For a global SNMP community string and NTP server:

   {
     "snmp_community": "public",
     "ntp_server": "10.0.0.1"
   }

5. Set the Weight to 10 (lower numbers are overridden by higher ones).
6. Under Assignments, choose All Devices to make the context apply everywhere.
7. Click Create. The UI will validate the JSON; any syntax error will be shown as a form error.

Adding Site‑Specific Overrides

1. Repeat the steps above to create a new context named London‑NTP‑Override.
2. Use the following JSON to change the NTP server for London devices:

   {
     "ntp_server": "10.50.0.5"
   }

3. Set Weight to 20.
4. Assign it to the Site object named London.
5. Save the context.

Defining a Device‑Role Exception

1. Create a context called Core‑Switch‑Timeout.
2. JSON payload:

   {
     "domain_timeout": 60
   }

3. Weight: 100.
4. Assign to the Device Role named Core‑Switch.
5. Save.

Verifying the Merge in the UI

Open any device that falls under all three contexts – for example, a core switch in London. In the device detail page, the Config Context section will display the merged JSON:

{
  "snmp_community": "public",
  "ntp_server": "10.50.0.5",
  "domain_timeout": 60
}

Notice that the NTP server comes from the site context (weight 20) and the timeout from the role context (weight 100). The global SNMP community remains unchanged because no higher‑weight context overrides it.

Fetching the Resolved Context via the REST API

Use the device‑specific endpoint to let NetBox perform the merge:

curl -s -H "Authorization: Token YOUR_API_TOKEN" \
  https://netbox.example.com/api/dcim/devices/123/config-context/

Replace 123 with the device ID. The response body will contain a single data object with the merged JSON. Example output:

{
  "data": {
    "snmp_community": "public",
    "ntp_server": "10.50.0.5",
    "domain_timeout": 60
  }
}

When the JSON in any context is invalid, the API returns a 400 Bad Request with details, and the UI will block saving the context.

Audit and Rollback

All context changes are recorded in the NetBox change log. To revert a mistaken value:

1. Navigate to the context’s Change Log tab.
2. Find the event you want to undo and copy the Data snapshot.
3. Edit the context and paste the older JSON.
4. Alternatively, delete the context via the API:

   curl -s -X DELETE \
     -H "Authorization: Token YOUR_API_TOKEN" \
     https://netbox.example.com/api/extras/config-contexts/42/
   

Common Pitfalls and Safeguards

• Do not store plain‑text secrets in config contexts. Use NetBox Secrets with an encrypted backend instead.
• Missing target objects (e.g., a non‑existent site) will silently ignore the context; double‑check assignments before saving.
• Concurrent edits can cause lost updates. Check the change log for recent edits and use optimistic locking if available.

Practical Check‑List

• JSON is valid – try jq . locally before pasting.
• Weight values are intentional – higher numbers win.
• Assignments match existing objects – use the UI picker to avoid typos.
• After creation, verify the merged output in both UI and API.
• Document the context hierarchy in your configuration management repo for future reference.