Config drift & sync with Ansible / Terraform¶
Danbyte is the source of truth. You describe how a device should be configured in Danbyte; an external runner (Ansible, Terraform, Nornir, …) reads the actual config off the real device and hands it back; Danbyte renders the intended config from your data, diffs the two, and shows drift vs in sync on the device's Config tab and the tenant drift board.
Credentials never live in Danbyte
The runner holds the device credentials. Danbyte stores only intent and the reported state - a Danbyte breach can never reconfigure your fleet.
Where do I click? (orientation)¶
Most of the confusion is "this is configured where?". Every piece is one of these five spots in the Danbyte UI - the How automation works panel on the Integrations → Automation targets page shows the same map in-app:
| To… | Go to |
|---|---|
| Define what the config should be | Customize → Config contexts + Export templates |
| Connect the system that runs your playbooks | Integrations → Automation targets |
| Fire a deploy for one device | a device → Config tab → Deploy |
| See past dispatches (read-only history) | Integrations → Deploy runs |
| Turn the scheduled drift check on/off | Admin → Settings |
Guided setup
First time? Integrations → Automation targets → Guided setup walks you through connecting a target (AWX/AAP, a webhook, or a Danbyte script) in three steps and tells you what to do next. It creates the exact same target as the manual form.
The Deploy runs page is just history
Deploy runs is a read-only log of "Danbyte handed off to a runner at 14:32, got a 200 back" - like the audit log, nothing is editable there. To change how a deploy is dispatched, edit its automation target.
The automation-target page¶
Click a target's name in Integrations → Automation targets to open it (the Edit button is still there, next to Test):
| Tab | What's on it |
|---|---|
| Overview | Kind, enabled, endpoint (or the script, for a script target), AWX job-template id, TLS verification, whether a credential is stored, auto-deploy-on-change, the object types it can deploy, the number of runs, and any extra vars. |
| Runs | Every dispatch Danbyte handed to this target, newest first - the same rows as Deploy runs, pre-filtered (GET /api/deploy-runs/?target=<id>), with the same Retry on a failed run. |
| Journal | Your notes on this target. |
| Change log | Every create/edit/delete of the target itself - see Change log. |
The stored AWX bearer token / webhook signing secret is never shown here. It is write-only on the API, so the page can only report whether one is set - to change it, edit the target and type a new one.
Bulk changes on the target list¶
Tick rows in Integrations → Automation targets - with the change or
delete grant - to reveal the bulk bar:
- Enable and Disable switch every selected target on or off.
- Export downloads the selected targets as CSV, Excel or JSON, without the token.
- Edit sets Enabled and Auto on change. The endpoint, kind and token stay per target.
- Delete first shows what would happen, then deletes the targets; their past runs stay in Deploy runs.
POST /api/automation-targets/bulk-update/ needs automationtarget.change
({ids, fields} with enabled, auto_on_change);
POST /api/automation-targets/bulk-delete/ needs automationtarget.delete.
What lives where¶
Two systems, on purpose - Danbyte does not run Ansible:
| Danbyte | The runner (Ansible / Terraform) | |
|---|---|---|
| Role | Source of truth + drift dashboard | The hands that touch devices |
| Holds | Intent (config contexts, export templates) + reported state | Device credentials (SSH keys, secrets) |
| Touches devices | Never | Yes - over SSH / API |
| Lives | Your Danbyte server | A box you control (a runner host, CI, AWX) |
| You click here | Customize → Config contexts / Export templates; the device Config tab | A cron job / pipeline - outside Danbyte |
The "via ansible" on a drift result is just the source label the runner
stamped on its report - it tells you who reported, not that Danbyte ran
anything. Ansible talks to Danbyte over the API like any other client.
Changing a value is a one-place edit
To change a device's NTP server (or DNS, domain, an IP …) you edit the
config context - never the runner:
Customize → Config contexts → network-baseline → set ntp_servers → Save.
The next runner pass renders the new intent and flags any device that hasn't
caught up as drift. Modularity comes from scope: a config context applies
to all devices, or only site = AMS / role = firewall / a platform / a
tag, and they stack by weight - a site override layers on top of a global
baseline.
The flow¶
┌──────────┐ 1. GET inventory (Danbyte data) ┌──────────────┐
│ Danbyte │ ─────────────────────────────────▶│ Runner │
│ (truth) │ │ Ansible / TF │
│ │◀──────────────────────────────────│ │
└──────────┘ 3. POST actual + template id └──────┬───────┘
▲ Danbyte renders intent & diffs │ 2. read running
│ ▼ config (SSH/API)
│ 4. drift shown on the Config tab ┌──────────┐
└───────────────────────────────────────────│ device │
└──────────┘
Step 1 - describe the intent in Danbyte¶
The "intended config" is built from two things you create in Customize, so you never hard-code values in the runner:
Config context - the data (variables). This is where a value like the NTP server lives. Scope it to all devices, or by site / role / platform / tags:
{ "ntp_servers": ["192.168.0.1", "192.168.0.2"],
"dns_servers": ["192.168.0.1"],
"syslog_host": "192.168.0.10",
"domain": "lab.acme.internal" }
Export template (object type device) - Jinja that turns that data, the
device's fields, and its assigned IPs into config
text:
hostname {{ device.name }}
ip domain-name {{ config_context.domain | default('example.com') }}
!
{% for s in config_context.ntp_servers | default([]) %}
ntp server {{ s }}
{% endfor %}
{% for s in config_context.dns_servers | default([]) %}
ip name-server {{ s }}
{% endfor %}
{% if config_context.syslog_host %}
logging host {{ config_context.syslog_host }}
{% endif %}
!
{% for i in interfaces %}
interface {{ i.name }}
{% for ip in ip_addresses %}
{% if ip.assigned_interface_id == i.id %}
ip address {{ ip.ip_address }}
{% endif %}
{% endfor %}
{% endfor %}
Template context: device, config_context (merged), interfaces,
ip_addresses, and routing (static routes, policies, keychains - see
Routing); address filters such as
netmask and cidr are listed under
export templates. The device's
Config → Render config box renders this on
demand - and you can bind the template
to the device, its role, or its platform so the box (and
GET /api/devices/<id>/render/) picks it automatically. For edge-fw-demo it produces:
hostname edge-fw-demo
ip domain-name lab.acme.internal
!
ntp server 192.168.0.1 ← from the config context
ntp server 192.168.0.2 ← from the config context
ip name-server 192.168.0.1 ← from the config context
logging host 192.168.0.10 ← from the config context
!
interface eth0
ip address 192.168.0.50 ← from IPAM (the assigned IP object)
So the NTP server is a config-context value (not a Service - Services document the ports a device exposes, for monitoring). Change it in the UI and the rendered intent changes with it.
Step 2 - authenticate the runner¶
Mint a token under Settings → API tokens (scoped to one tenant):
Step 3 - the two endpoints a runner needs¶
| Endpoint | Purpose |
|---|---|
GET /api/inventory/ansible/ |
Native Ansible dynamic inventory - devices and virtual machines as hosts, ansible_host (primary IP), danbyte metadata (danbyte.kind = device or virtual_machine, danbyte.custom_fields, danbyte.interfaces, danbyte.application_groups and danbyte.applications - see Application groups; VMs also carry cluster, cluster_group, host device, vcpus/memory_mb/disk_gb, and each VM interface's speed), merged config_context, and role_<slug> / site_<name> / platform_<slug> / status_<slug> / tag_<slug> / cf_<name> / app_group_<slug> groups - plus cluster_<name> / cluster_group_<name> for VMs and the all_devices / all_vms catch-alls. Filter with ?status=active&site=AMS&role=leaf&has_primary_ip=1, and scope to one kind with ?kind=device or ?kind=vm. Host names are expected unique across devices and VMs; on a collision the device wins. |
POST /api/devices/<id>/config-state/ |
Report a device's config. Send actual_config + a template id and Danbyte renders the intent (config context + IPAM) and diffs it → status ∈ in_sync \| drift \| unknown, the unified diff, and a history snapshot on change. (Or send intended_config yourself if the runner does the templating.) |
A runner that lets Danbyte render the config it pushes has two more:
GET /api/devices/render/?bundle=role&role_slug=leaf renders every file of
a bundle for every
matching device in one call, and POST /api/devices/<id>/config-pushed/
records what it put on the box so the device page can show changed since
last push before the next drift report. Keys are never in a render; the
<keychain:NAME> placeholder is the contract
the runner substitutes.
Ansible demo¶
inventory.py proxies Danbyte's inventory:
#!/usr/bin/env python3
import os, sys, urllib.request
req = urllib.request.Request(f"{os.environ['DANBYTE_URL']}/api/inventory/ansible/",
headers={"Authorization": f"Token {os.environ['DANBYTE_TOKEN']}"})
print("{}" if "--host" in sys.argv else urllib.request.urlopen(req).read().decode())
drift_check.yml - pull the actual config and let Danbyte render + diff:
- hosts: all
gather_facts: false
vars:
base: "{{ lookup('env','DANBYTE_URL') }}"
tok: "{{ lookup('env','DANBYTE_TOKEN') }}"
tasks:
- name: Resolve the export template id by name
ansible.builtin.uri:
url: "{{ base }}/api/export-templates/?page_size=200"
headers: { Authorization: "Token {{ tok }}" }
delegate_to: localhost
register: ets
- ansible.builtin.set_fact:
template_id: "{{ (ets.json.results | selectattr('name','equalto','baseline-config') | list | first).id }}"
- name: Read the running config off the device
ansible.builtin.raw: cat /etc/netdev/running.conf # or: show running-config
register: running
changed_when: false
- name: Report actual - Danbyte renders intent from the template and diffs
ansible.builtin.uri:
url: "{{ base }}/api/devices/{{ danbyte.id }}/config-state/"
method: POST
headers: { Authorization: "Token {{ tok }}" }
body_format: json
body:
actual_config: "{{ running.stdout }}"
template: "{{ template_id }}"
source: ansible
status_code: [200, 201, 202]
delegate_to: localhost
Editing data in the UI shows up as drift¶
Because Danbyte renders the intent, you don't touch the runner to change a
policy. Bump the NTP server in the config context from 192.168.0.1 →
192.168.0.99 and re-run - the device is unchanged, so Danbyte flags drift:
A push/remediate playbook would then apply the new NTP server to the device, and the next check returns to in sync. (Danbyte itself never touches the device - that's the runner's job, with the runner's credentials.)
Terraform demo¶
Terraform's role is provisioning from Danbyte's allocations - read an object's reserved address out of the API and stand the resource up at it:
terraform {
required_providers {
docker = { source = "kreuzwerker/docker" }
http = { source = "hashicorp/http" }
}
}
variable "danbyte_url" { default = "https://danbyte.example.com" }
variable "danbyte_token" { type = string, sensitive = true }
variable "device_id" { type = string }
data "http" "ips" { # Danbyte = source of truth
url = "${var.danbyte_url}/api/devices/${var.device_id}/ips/"
request_headers = { Authorization = "Token ${var.danbyte_token}" }
}
locals { device_ip = jsondecode(data.http.ips.response_body).results[0].ip_address }
resource "docker_network" "lan" {
name = "danbyte-lan"
driver = "macvlan"
options = { parent = "eno2" }
ipam_config { subnet = "192.168.0.0/24", gateway = "192.168.0.1" }
}
resource "docker_container" "device" {
name = "edge-fw-demo"
image = "danbyte-netdev:demo"
networks_advanced {
name = docker_network.lan.name
ipv4_address = local.device_ip # ← the IP Danbyte allocated
}
}
You now have a real host at the address Danbyte reserved - point the Ansible playbook at it to close the loop.
How the runner actually runs¶
Danbyte never schedules it - you do. Pick what fits:
- Cron / systemd timer on the runner host -
ansible-playbook drift_check.ymlevery few minutes for continuous, hands-off drift detection. - On demand - run it by hand, or from CI right after a change.
- Danbyte "Deploy" - register an automation target (an AWX job template,
a webhook, or a Danbyte script). A
device's Deploy button (or
POST /api/devices/<id>/deploy/) then tells that system to launch the run. Danbyte hands off the work; it still never touches the device itself. - A deploy pipeline - several targets run in order for the same devices, each step starting when the one before has a final status. See Deploy pipelines.
The Deploy dialog offers both: a pipeline (the one the device's role makes
the default is preselected) or a single target, and a Dry run box that
sends "dry_run": true in the payload (and in a script's parameters) so the
runner only reports what it would do. Over the API, the deploy, bulk deploy
and provision bodies take "dry_run": true too, and pipeline_id in place
of target_id.
Deploy runs, retries, and remediate¶
Every dispatch is recorded as a deploy run (Integrations → Deploy runs, and
the device's Config tab). Each run carries its event, attempt, dispatch
duration, and the target's response in detail.
- A run that fails (target unreachable, non-2xx, disabled) is marked
failedwith the reason. Hit Retry on the row (orPOST /api/deploy-runs/<id>/retry/) to re-fire the same target + devices as a new run - linked back viaretry_of, withattemptbumped. Retry is offered only while the target still exists and is enabled. - Remediate is just a deploy whose playbook pushes the intended config and
then re-checks drift, so a drifted/failed device returns to in sync in one
run. The companion runner ships a
remediate.yml(sync.yml→drift_check.yml); trigger it with aremediateevent from the Deploy button or runansible-playbook -i inventory.py remediate.ymlby hand.
A run moves through these statuses:
| Status | Means |
|---|---|
queued |
Recorded, waiting for a worker to dispatch it. |
launched |
Handed to the runner. For AWX and a webhook without a callback this is where it stays. |
succeeded |
The script run it started exited cleanly, or the runner reported success. |
failed |
The dispatch failed, the script run failed, timed out or was stopped, or the runner reported a failure. |
succeeded and failed are final: nothing changes a run once it has one.
Danbyte scripts as deploy targets¶
An automation target of kind Danbyte script runs one of your scripts instead of calling out to a runner. Pick the script on the target form (or in Guided setup); there is no URL, token or TLS setting. A deploy then queues a script run with these parameters:
plus the target's extra vars. device_ids, event and object_type
always come from the deploy; an extra var of the same name does not
override them. A provision sends the VM ids, with object_type
virtualmachine.
- The script must declare a
device_idsparameter. Saving a target with a script that lacks one is refused on thescriptfield, and a script whose parameter was removed afterwards fails at dispatch. - Who it runs as follows the script's own Run as.
The person who runs itis whoever pressed Deploy (or bulk deploy, retry, provision); for Auto-deploy on change it is the author of the change. A scheduled drift deploy has no person, so only a script that runs as its owner can serve it; anything else fails with the reason. - Rights. Whoever starts it needs
script: runon the script and must see it, exactly as when pressing Run on the script itself. A trusted script also needsscript: trust. This is checked when the target is saved and again at every dispatch, so a target never lets anyone start code they could not start themselves. Setting a script on a target needs the same rights; editing an unrelated field does not. - Test on a script target checks the script is set, enabled, declares
device_idsand that you may start it; it does not run it. - The script must be in the target's tenant; another tenant's script id is refused on create, edit and import.
The deploy run links to its script run: Deploy runs shows a
Script run link on the row, which opens the run page with the live log.
The API exposes script_run (the id) and script_run_status. When the
script run ends, the deploy run becomes succeeded (exit code 0) or
failed, with the last part of the log in detail.
Reporting the outcome from a webhook runner¶
A webhook runner can report how the deploy went. Danbyte includes the run's
id as run_id in every webhook payload; when the job is done, POST the
outcome back:
POST /api/deploy-runs/<run_id>/result/
Content-Type: application/json
X-Danbyte-Signature: sha512=<hex HMAC-SHA512 of the raw body, keyed with the target's signing secret>
{"status": "succeeded", "detail": "pushed 12 devices", "log": ["rendered 5 files", "frr restarted"]}
The signature is the same scheme Danbyte signs its own webhook deliveries
with, so the runner reuses the secret it already verifies with; no session
or API token is involved. status is succeeded or failed; detail is
optional text, kept up to 2000 characters.
Log lines. log is optional: a list of strings (or one string, split on
newlines). The lines are appended to the run's log, which the
pipeline run page shows. The log is
append-only and capped at 256 KiB per run; once full, one marker line ends
it and later lines are dropped. Each line is cut at 2000 characters.
Progress. While the job works, the runner can post
{"status": "running", "log": ["..."]} as often as it likes. That appends
the lines and leaves the run launched; it is signed and refused exactly
like a final post. Only the final succeeded / failed post ends the run.
- Only a webhook target with a signing secret can report. A missing or
wrong signature, an unknown run, or a target without a secret all answer
403. - Only a run in
launchedcan be finalised or take lines. A queued or already final run answers409, so a replayed callback cannot change a result or add to a finished log. - Without a callback (or for AWX) the run stays
launched. - In a pipeline, a step set to Wait for a reported result waits for this post before the next step starts, and fails after its timeout.
import hashlib, hmac, json, requests
body = json.dumps({"status": "succeeded", "detail": "ok"}).encode()
sig = "sha512=" + hmac.new(SECRET.encode(), body, hashlib.sha512).hexdigest()
requests.post(f"{DANBYTE}/api/deploy-runs/{run_id}/result/", data=body,
headers={"Content-Type": "application/json",
"X-Danbyte-Signature": sig})
Provisioning an intended VM¶
Provision on an intended VM's page
(POST /api/virtual-machines/<id>/provision/ with {"target_id": "<id>"})
sends the VM to an automation target to be built. Danbyte never calls a
hypervisor's write API: the runner - a rebuild script, AWX or a webhook
consumer - holds the hypervisor credentials and does the build.
- The target must take virtual machines: Object types includes
virtualmachine(or*). A target with none set takes devices only. - The VM must be Intended. The action needs the provision permission on virtual machines (not change), within the caller's row and site limits, and writes a Provision requested entry to the VM's change log naming the target and the run.
- The run is a deploy run with
eventprovisionandobject_typevirtualmachine. When the job runs it re-reads the VMs and keeps only those still intended in the target's tenant; with none left the run fails and nothing is sent. - The post goes through the same outbound guard as every deploy: no private
or loopback address unless allowed, the target's TLS setting, the
webhook's HMAC signature (
X-Danbyte-Signature, headerX-Danbyte-Event: deploy.provision) or AWX's bearer token. The token is stored encrypted and never written to the payload. - Retry on a failed provision run needs the provision permission on each VM as well, and is logged the same way.
The payload adds to the deploy payload; nothing in it changes for a device deploy:
{
"tenant": "acme",
"event": "provision",
"object_type": "virtualmachine",
"object_ids": ["<vm id>"],
// Kept for runners that only read these keys: they hold the VM ids here.
"device_ids": ["<vm id>"],
"limit": "<vm id>",
// The devices the VMs are (Is router), to fetch their bundle next.
"represents_device_ids": ["<device id>"],
"virtual_machines": [{
"id": "<vm id>", "name": "edge-r1", "intended": true, "vmid": 120,
"cluster": "pve-a", "node": "pve1",
"cpu_type": "host", "sockets": null, "vcpus": 2, "memory_mb": 2048,
"disk_gb": 16, "image": "local:import/debian-13.qcow2", "storage": "ceph-vm",
"hypervisor_options": {"onboot": 1},
"represents_device": {"id": "<device id>", "name": "edge-r1"},
"interfaces": [{"name": "eth0", "index": 0, "model": "virtio",
"bridge": "vmbr0", "firewall": null, "mac_address": "",
"mtu": 9000, "vlan": null, "enabled": true, "kind": ""}],
"disks": [{"key": "scsi0", "name": "", "size_gb": 16, "storage": "ceph-vm",
"controller": "scsi", "disk_format": ""}]
}]
}
The target's extra vars are merged on top, as for any deploy. The same build
description is build in a VM render
and backing_vm in the render of the device it represents.
Groups and interfaces (network automation)¶
The inventory is pre-grouped the way you'd group hosts by hand - so a play can
target a slice of the fleet with no when::
| Group | From |
|---|---|
role_<slug> |
Device role (role_leaf, role_firewall) |
site_<name> · region_<name> |
Site / region |
platform_<slug> |
Platform (platform_ios) |
status_<slug> |
Status (status_active) |
tag_<slug> |
Each tag |
cf_<name> |
Each boolean custom field that's on |
Each host also carries its interfaces at danbyte.interfaces - name, type,
MTU, MAC, enabled, VLAN, and assigned IPs (bare address + cidr) - so a
network play can render per-interface config straight from Danbyte + IPAM:
- hosts: role_leaf
gather_facts: false
tasks:
- name: Show the intended L3 interfaces
ansible.builtin.debug:
msg: "{{ item.name }} → {{ item.ip_addresses | map(attribute='cidr') | join(', ') }}"
loop: "{{ danbyte.interfaces | selectattr('ip_addresses') | list }}"
loop_control: { label: "{{ item.name }}" }
// danbyte.interfaces for one host
[
{ "name": "eth0", "type": "1000base-t", "enabled": true, "mtu": 1500,
"mac_address": "00:11:22:33:44:55", "virtual": false,
"vlan": { "vid": 100, "name": "prod" },
"ip_addresses": [ { "address": "10.0.0.5", "cidr": "10.0.0.5/24" } ],
"tags": [], "custom_fields": {} }
]
Advanced: feature-flag a playbook from a custom field¶
A per-device boolean custom field can gate a play - flip it in the UI, the next
run installs (or removes) the thing. See
Advanced: custom-field-driven playbook for the full
install_btop worked example.
Where it shows up¶
- Device → Config tab - status badge, the rendered intent, and the diff.
- Device → Config tab → Ansible inventory - a read-only preview of the
groups + hostvars a runner sees for this device (its slice of
/api/inventory/ansible/), with a Copy button. Verify the export without curling the API. Per-device endpoint:GET /api/devices/<id>/inventory/. - Config drift board -
GET /api/config-states/?status=drift, by status. - History -
GET /api/config-snapshots/?device=<id>- the drift→sync timeline.