Skip to content
Guides & References

Gate a CI/CD pipeline on rConfig backups and compliance

A recipe for a pipeline stage that backs up devices before and after a change, prints the diff, and fails if a device fails compliance afterwards.

API & DeveloperUpdated
On this page

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:

  1. Start a backup with v1 GET /download-now/{id}. This only starts it.
  2. 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.
  3. 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:

  1. Start and wait for a backup the same way.
  2. Fetch the before and after configs with includeConfig=true and print a unified diff.
  3. 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.
  4. 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.read and policycompliance.read. Keep it in your CI system’s secret store as RCONFIG_TOKEN.
  • The rConfig device IDs the change touches.
  • Python 3 with requests on the runner.

The script

Save it as rconfig_gate.py in the pipeline’s repository.

rconfig_gate.py
#!/usr/bin/env python3
"""Back up devices before and after a change, show the diff, and fail on
non-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 csv
import difflib
import io
import json
import os
import sys
import time
import requests
COMMAND = "show running-config" # which command's config to compare
BACKUP_WAIT = 600 # seconds to wait for each backup
COMPLIANCE_WAIT = 600 # seconds to wait for post-backup compliance
REQUIRE_COMPLIANCE = True
STATE_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.

.gitlab-ci.yml
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 $DEVICES

RCONFIG_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 informational
edge-rtr-01: Branch router baseline: Compliant

Adapting 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.

Type to search.