Gate a CI/CD pipeline on rConfig backups and compliance
A pipeline that pushes network changes (Ansible, Nornir, a vendor controller) should leave evidence of what it changed, and stop if the change broke policy. This recipe adds two stages around the change: one that takes a fresh backup of each device before, and one that takes another after, prints the diff, and fails the pipeline if any device fails compliance on its new config.
How it works
pipeline: [ rconfig-gate before ] -> [ your change ] -> [ rconfig-gate after ]Before the change, for each device:
- Start a backup with v1
GET /download-now/{id}. This only starts it. - Poll v2
GET /devices/{id}until the ID of the device’s newest config (last_config.id) changes. Every finished download, changed or not, failed or not, adds a new config record, so this works without comparing clocks. - Record the ID of the device’s newest config for the command in a state file the pipeline keeps between stages.
After the change, for each device:
- Start and wait for a backup the same way.
- Fetch the before and after configs with
includeConfig=trueand print a unified diff. - Wait for post-backup compliance to report on the new config, by polling the device’s compliance export for a row with the new config’s ID.
- Fail the stage if any device’s backup failed or any result is non-compliant.
The compliance step needs at least one policy assignment covering the devices with Run on backup on. Without it there is nothing to wait for; set REQUIRE_COMPLIANCE = False to skip that step.
What you need
- A token with
configs.read(downloads and configs),devices.readandpolicycompliance.read. Keep it in your CI system’s secret store asRCONFIG_TOKEN. - The rConfig device IDs the change touches.
- Python 3 with
requestson the runner.
The script
Save it as rconfig_gate.py in the pipeline’s repository.
#!/usr/bin/env python3"""Back up devices before and after a change, show the diff, and fail onnon-compliance. For use as two CI/CD pipeline stages.
Usage: python3 rconfig_gate.py before 12 15 31 python3 rconfig_gate.py after 12 15 31
Environment: RCONFIG_URL, RCONFIG_TOKEN. State is kept in rconfig_gate.json.Exit code 0 to continue the pipeline, 1 to stop it."""
import csvimport difflibimport ioimport jsonimport osimport sysimport timeimport requests
COMMAND = "show running-config" # which command's config to compareBACKUP_WAIT = 600 # seconds to wait for each backupCOMPLIANCE_WAIT = 600 # seconds to wait for post-backup complianceREQUIRE_COMPLIANCE = TrueSTATE_FILE = "rconfig_gate.json"
BASE = os.environ.get("RCONFIG_URL", "").rstrip("/")TOKEN = os.environ.get("RCONFIG_TOKEN", "")
def get(path, **params): response = requests.get(f"{BASE}/api/{path}", params=params, timeout=60, headers={"apitoken": TOKEN, "Accept": "application/json"}) response.raise_for_status() return response
def device(device_id): return get(f"v2/devices/{device_id}", with_credentials="false").json()
def last_config_id(record): return (record.get("last_config") or {}).get("id")
def backup(device_id): """Start a backup and wait until a new config record appears for the device.""" previous = last_config_id(device(device_id)) get(f"v1/download-now/{device_id}") deadline = time.monotonic() + BACKUP_WAIT while time.monotonic() < deadline: time.sleep(10) record = device(device_id) if last_config_id(record) != previous: return record raise SystemExit(f"device {device_id}: no backup finished within {BACKUP_WAIT}s")
def newest_config(device_id): body = get("v2/configs", **{"filter[device_id]": device_id, "filter[command]": COMMAND, "filter[latest_version]": 1, "perPage": 1}).json() if not body["data"]: raise SystemExit(f"device {device_id}: no '{COMMAND}' config found") return body["data"][0]["id"]
def config_text(config_id): return get(f"v2/configs/{config_id}", includeConfig="true").json().get("config", "")
def compliance_rows(device_id, config_id): """Rows of the device's compliance export that belong to this config.""" deadline = time.monotonic() + COMPLIANCE_WAIT while time.monotonic() < deadline: export = get(f"v2/policy-compliance-results/device/{device_id}/export", format="csv").text rows = [r for r in csv.DictReader(io.StringIO(export)) if str(r.get("Config ID")) == str(config_id)] if rows: return rows time.sleep(15) raise SystemExit(f"device {device_id}: no compliance result for config {config_id} within {COMPLIANCE_WAIT}s")
def main(): if not BASE or not TOKEN: raise SystemExit("set RCONFIG_URL and RCONFIG_TOKEN") if len(sys.argv) < 3 or sys.argv[1] not in ("before", "after"): raise SystemExit("usage: rconfig_gate.py before|after <device_id> [device_id...]") stage, device_ids = sys.argv[1], sys.argv[2:]
if stage == "before": state = {} for device_id in device_ids: device = backup(device_id) if device.get("last_backup_status") == 0: raise SystemExit(f"{device['device_name']}: backup failed before the change") state[device_id] = newest_config(device_id) print(f"{device['device_name']}: before = config {state[device_id]}") with open(STATE_FILE, "w") as handle: json.dump(state, handle) return 0
with open(STATE_FILE) as handle: state = json.load(handle)
failed = False for device_id in device_ids: device = backup(device_id) name = device["device_name"] if device.get("last_backup_status") == 0: print(f"FAIL {name}: backup failed after the change") failed = True continue
before, after = state[device_id], newest_config(device_id) diff = list(difflib.unified_diff( config_text(before).splitlines(), config_text(after).splitlines(), f"{name} config {before}", f"{name} config {after}", lineterm="")) print("\n".join(diff) if diff else f"{name}: no change")
if REQUIRE_COMPLIANCE: for row in compliance_rows(device_id, after): status = row.get("Compliance Status") print(f"{name}: {row.get('Report Name')}: {status}") if status != "Compliant": failed = True
return 1 if failed else 0
if __name__ == "__main__": sys.exit(main())In a pipeline
A GitLab CI example. Other CI systems follow the same shape: run before, make the change, run after, and keep rconfig_gate.json between the stages.
stages: [before, change, after]
variables: DEVICES: "12 15 31"
rconfig-before: stage: before script: python3 rconfig_gate.py before $DEVICES artifacts: paths: [rconfig_gate.json]
apply-change: stage: change script: ansible-playbook change.yml
rconfig-after: stage: after script: python3 rconfig_gate.py after $DEVICESRCONFIG_URL and RCONFIG_TOKEN come from masked CI/CD variables, not from the file.
What it prints
--- edge-rtr-01 config 5519+++ edge-rtr-01 config 5521@@ -40,3 +40,3 @@ ntp server 192.0.2.123-logging host 192.0.2.50+logging host 198.51.100.50 logging trap informationaledge-rtr-01: Branch router baseline: CompliantAdapting it
- Several commands per device. Change
COMMAND, or loop over a list of commands and diff each. - Warn instead of fail. Print non-compliant results but return
0, so the pipeline records the evidence without stopping. - Keep the evidence. Save the printed diff as a pipeline artefact, or attach it to the change ticket.
- Diffs as rConfig shows them. v2
GET /config-changes/by-config/{configId}returns the stored diff as HTML, the same as the UI.