State Management and Idempotency
Get the code for this lesson
Every file this lesson builds is on GitHub. Type it out as you read, because that's where the learning happens. Then use the repo to check your work when something won't run, or to grab the data files and templates so you can focus on the Python.
Why Idempotency Matters¶
Ask yourself: "What happens if I run this automation script twice?"
Bad answer: "It breaks things on the second run" Good answer: "It's safe to run as many times as needed"
Idempotent operations are repeatable without side effects.
The Problem: Non-Idempotent Operations¶
# ❌ NOT IDEMPOTENT
def reset_access_port(device, interface, vlan):
"""Put a port back to the standard access configuration."""
device.send_config_set([
f"default interface {interface}", # wipes the port first
f"interface {interface}",
"switchport mode access",
f"switchport access vlan {vlan}",
"no shutdown",
])
# Run 1: ✓ Port configured
# Run 2: ✗ Port wiped and rebuilt — the link drops, though nothing needed to change
# Run 3-5: ✗ Another outage for that user on every scheduled run
Non-idempotent operations are unreliable:
- Cause side effects on every run (link flaps, reset sessions), not just the first
- Can't tell you whether anything actually changed
- Can't be scheduled or retried safely
- Cause automation distrust
Note that the commands themselves aren't the problem. IOS will happily accept vlan 100 or switchport access vlan 10 again. The problem is a script that pushes blindly, so it can't report what changed and can't avoid disruptive steps when nothing needs doing.
The Solution: Idempotent Operations¶
# ✅ IDEMPOTENT
def ensure_access_port(device, interface, vlan):
"""Ensure the port has the standard access configuration (safe to repeat)."""
wanted = ["switchport mode access", f"switchport access vlan {vlan}"]
# Read first: what is actually configured?
current = device.send_command(f"show running-config interface {interface}")
current_lines = {line.strip() for line in current.splitlines()}
missing = [line for line in wanted if line not in current_lines]
if not missing and "shutdown" not in current_lines:
print(f"{interface} already correct, nothing sent")
return "unchanged"
# Change only what differs. No "default interface", so no link flap.
device.send_config_set([f"interface {interface}", *missing, "no shutdown"])
print(f"{interface} updated: {missing or ['no shutdown']}")
return "changed"
# Run 1: ✓ Port updated
# Run 2: ✓ Already correct, nothing sent, no flap
# Run 3-5: ✓ Already correct, nothing sent
Pattern 1: Check-Before-Change¶
The Implementation¶
# src/idempotent_operations.py
from dataclasses import dataclass
from enum import Enum
class OperationStatus(Enum):
"""Status of an idempotent operation."""
CREATED = "created"
ALREADY_EXISTS = "already_exists"
UPDATED = "updated"
UNCHANGED = "unchanged"
FAILED = "failed"
@dataclass
class OperationResult:
"""Result of an idempotent operation."""
status: OperationStatus
message: str
details: dict = None
class IdempotentOperations:
"""Idempotent network operations (safe to repeat)."""
@staticmethod
def ensure_vlan_exists(device, vlan_id: int, vlan_name: str) -> OperationResult:
"""
Ensure VLAN exists with given name (idempotent).
Safe to call multiple times—won't duplicate VLAN.
"""
# Check if VLAN already exists
output = device.send_command(f"show vlan id {vlan_id}")
# The VLAN's row starts with its ID and the next column is its name.
# A missing VLAN prints "VLAN id N not found in current VLAN database".
row = next(
(line.split() for line in output.splitlines()
if line.split()[:1] == [str(vlan_id)]),
None,
)
if row is not None:
# VLAN exists, verify name matches exactly
if len(row) > 1 and row[1] == vlan_name:
return OperationResult(
status=OperationStatus.UNCHANGED,
message=f"VLAN {vlan_id} exists with correct name",
details={"vlan_id": vlan_id, "vlan_name": vlan_name}
)
else:
# VLAN exists but name differs, update it
device.send_config_set([f"vlan {vlan_id}", f"name {vlan_name}"])
return OperationResult(
status=OperationStatus.UPDATED,
message=f"VLAN {vlan_id} name updated to {vlan_name}",
details={"vlan_id": vlan_id, "vlan_name": vlan_name}
)
# VLAN doesn't exist, create it
device.send_config_set([f"vlan {vlan_id}", f"name {vlan_name}"])
return OperationResult(
status=OperationStatus.CREATED,
message=f"VLAN {vlan_id} created with name {vlan_name}",
details={"vlan_id": vlan_id, "vlan_name": vlan_name}
)
@staticmethod
def ensure_interface_config(device, interface: str, config_lines: list) -> OperationResult:
"""
Ensure interface has specific configuration (idempotent).
Args:
device: Netmiko device
interface: Interface name (e.g., "Gi0/0/1")
config_lines: List of config commands to apply
"""
# Get current interface configuration
current_config = device.send_command(f"show running-config interface {interface}")
# Check if all config lines already exist
all_exist = all(line in current_config for line in config_lines)
if all_exist:
return OperationResult(
status=OperationStatus.UNCHANGED,
message=f"Interface {interface} already has required configuration",
details={"interface": interface, "lines": config_lines}
)
# Apply missing configuration
device.send_config_set([f"interface {interface}", *config_lines])
return OperationResult(
status=OperationStatus.UPDATED,
message=f"Interface {interface} configuration applied",
details={"interface": interface, "lines": config_lines}
)
@staticmethod
def ensure_bgp_neighbor(device, asn: int, neighbor_ip: str, neighbor_asn: int) -> OperationResult:
"""Ensure BGP neighbor is configured (idempotent)."""
# Check if neighbor already exists
output = device.send_command("show ip bgp summary")
if neighbor_ip in output:
return OperationResult(
status=OperationStatus.UNCHANGED,
message=f"BGP neighbor {neighbor_ip} already configured",
details={"neighbor_ip": neighbor_ip}
)
# Configure BGP neighbor
device.send_config_set([
f"router bgp {asn}",
f"neighbor {neighbor_ip} remote-as {neighbor_asn}",
])
return OperationResult(
status=OperationStatus.CREATED,
message=f"BGP neighbor {neighbor_ip} configured",
details={"neighbor_ip": neighbor_ip, "neighbor_asn": neighbor_asn}
)
Usage Example¶
from netmiko import ConnectHandler
from idempotent_operations import IdempotentOperations, OperationStatus
device = ConnectHandler(
device_type="cisco_ios",
host="10.0.0.1",
username="admin",
password="password"
)
ops = IdempotentOperations()
# Run 1: Creates VLAN 100
result = ops.ensure_vlan_exists(device, 100, "DATA")
print(f"{result.status.value}: {result.message}")
# Output: created: VLAN 100 created with name DATA
# Run 2: Detects VLAN 100 already exists
result = ops.ensure_vlan_exists(device, 100, "DATA")
print(f"{result.status.value}: {result.message}")
# Output: unchanged: VLAN 100 exists with correct name
# Run 3: Safe to call again and again
result = ops.ensure_vlan_exists(device, 100, "DATA")
print(f"{result.status.value}: {result.message}")
# Output: unchanged: VLAN 100 exists with correct name
device.disconnect()
Pattern 2: State-Driven Configuration¶
The Problem¶
Imperative code (commands in order) doesn't guarantee desired state:
# ❌ IMPERATIVE - Order-dependent
device.send_config_set(["interface Gi0/0/1", "ip address 10.0.0.1 255.255.255.0"])
# Runs once at build time. If someone manually removes the IP later,
# nothing notices and nothing fixes it.
The Solution: Declarative State¶
# ✅ DECLARATIVE - Desired state always applied
desired_state = {
"interfaces": {
"Gi0/0/1": {
"ip": "10.0.0.1",
"netmask": "255.255.255.0",
"enabled": True
}
}
}
# Ensure device matches desired state (idempotent)
ensure_device_state(device, desired_state)
Implementation¶
# src/state_driver.py
import re
def canonical_interface(name: str) -> str:
"""
Reduce an interface name to one comparable form.
The device reports "GigabitEthernet0/0/1"; people write "Gi0/0/1".
Both become "gi0/0/1", so desired and current state can be matched.
"""
return re.sub(r"^([A-Za-z]{2})[A-Za-z-]*", lambda m: m.group(1).lower(), name.strip())
class StateDrivenConfigurator:
"""Apply desired state to device (idempotent)."""
def __init__(self, device):
self.device = device
def get_current_state(self) -> dict:
"""Retrieve current device state."""
return {
"interfaces": self._get_interfaces(),
"vlans": self._get_vlans(),
"bgp": self._get_bgp_state(),
}
def _get_interfaces(self) -> dict:
"""Get current interface configuration."""
output = self.device.send_command("show ip interface brief")
interfaces = {}
# Columns: Interface, IP-Address, OK?, Method, Status, Protocol
for line in output.splitlines()[1:]:
parts = line.split()
if len(parts) < 6:
continue
interfaces[canonical_interface(parts[0])] = {
"ip": parts[1],
"status": " ".join(parts[4:-1]), # "up", "administratively down"
}
return interfaces
def _get_vlans(self) -> dict:
"""Get current VLAN configuration."""
output = self.device.send_command("show vlan brief")
vlans = {}
for line in output.split('\n'):
if line.split() and line.split()[0].isdigit():
parts = line.split()
vlan_id = parts[0]
vlan_name = parts[1] if len(parts) > 1 else ""
vlans[vlan_id] = {"name": vlan_name}
return vlans
def _get_bgp_state(self) -> dict:
"""Get current BGP state."""
output = self.device.send_command("show ip bgp summary")
# Established peers show a prefix count in the last column
# (State/PfxRcd); others show a state such as Idle or Active.
# IOS never prints the word "Established" in this table.
established = 0
in_table = False
for line in output.splitlines():
if line.startswith("Neighbor"):
in_table = True
continue
parts = line.split()
if in_table and parts and parts[-1].isdigit():
established += 1
return {"neighbors_established": established}
def ensure_interfaces(self, desired_interfaces: dict):
"""Ensure interface configuration matches desired state."""
current = self.get_current_state()["interfaces"]
for interface, desired_config in desired_interfaces.items():
current_config = current.get(canonical_interface(interface), {})
# Check if interface configuration matches
if current_config.get("ip") != desired_config.get("ip"):
print(f"Updating {interface} IP...")
self.device.send_config_set([
f"interface {interface}",
f"ip address {desired_config['ip']} {desired_config['netmask']}",
])
def ensure_vlans(self, desired_vlans: dict):
"""Ensure VLAN configuration matches desired state."""
current = self.get_current_state()["vlans"]
for vlan_id, vlan_config in desired_vlans.items():
if vlan_id not in current:
print(f"Creating VLAN {vlan_id}...")
self.device.send_config_set([
f"vlan {vlan_id}",
f"name {vlan_config['name']}",
])
def apply_desired_state(self, desired_state: dict):
"""Apply all desired state (idempotent)."""
print("Applying desired state...")
if "interfaces" in desired_state:
self.ensure_interfaces(desired_state["interfaces"])
if "vlans" in desired_state:
self.ensure_vlans(desired_state["vlans"])
print("✓ Desired state applied")
Usage¶
device = ConnectHandler(
device_type="cisco_ios",
host="10.0.0.1",
username="admin",
password="password"
)
configurator = StateDrivenConfigurator(device)
desired_state = {
"interfaces": {
"Gi0/0/1": {
"ip": "10.0.0.1",
"netmask": "255.255.255.0"
}
},
"vlans": {
"100": {"name": "DATA"},
"101": {"name": "VOICE"}
}
}
# Run 1: Applies all configuration
configurator.apply_desired_state(desired_state)
# Run 2: Checks state, skips what's already correct
configurator.apply_desired_state(desired_state)
# Run 3-N: Safe to run anytime
configurator.apply_desired_state(desired_state)
Pattern 3: Nornir with Idempotent Tasks¶
# src/nornir_idempotent_tasks.py
from nornir import InitNornir
from nornir.core.task import Task, Result
from idempotent_operations import IdempotentOperations
def ensure_vlans(task: Task) -> Result:
"""Nornir task: Ensure VLANs exist (idempotent)."""
device = task.host.get_connection("netmiko", task.nornir.config)
ops = IdempotentOperations()
# Get VLAN configuration from inventory or task data
vlans = task.host.get("vlans", {})
results = []
for vlan_id, vlan_config in vlans.items():
result = ops.ensure_vlan_exists(
device,
vlan_id,
vlan_config["name"]
)
results.append(result)
return Result(
host=task.host,
result={
"vlans": [
{
"vlan_id": r.details["vlan_id"],
"status": r.status.value,
"message": r.message
}
for r in results
]
}
)
# Usage
nr = InitNornir(config_file="config.yaml")
results = nr.run(task=ensure_vlans)
# Results show what changed
for hostname, result in results.items():
for vlan in result[0].result["vlans"]:
print(f"{hostname}: VLAN {vlan['vlan_id']} - {vlan['status']}")
Best Practices¶
1. Separate Checking from Doing¶
# ✅ GOOD
def ensure_vlan_exists(device, vlan_id):
# 1. Check
if vlan_exists(device, vlan_id):
return "already_exists"
# 2. Create only if needed
create_vlan(device, vlan_id)
return "created"
# ❌ BAD - Assumes creation is needed
def create_vlan(device, vlan_id):
device.send_config_set([f"vlan {vlan_id}"])
return "created" # even when it already existed: the caller is misled
2. Return Operation Status¶
# ✅ GOOD - Caller knows what happened
status = ensure_vlan_exists(device, 100)
if status == "created":
print("New VLAN created")
elif status == "unchanged":
print("VLAN already existed")
# ❌ BAD - Caller doesn't know
ensure_vlan_exists(device, 100) # Did something happen?
3. Make Operations Small and Focused¶
# ✅ GOOD - Single responsibility
def ensure_vlan_exists(device, vlan_id, vlan_name):
# Only concerned with VLAN existence
pass
# ❌ BAD - Too much responsibility
def configure_vlan_and_interfaces_and_bgp(device, vlan_id):
# Does too many things, hard to reason about
pass
4. Test Idempotency Explicitly¶
# tests/test_idempotent_operations.py
from idempotent_operations import IdempotentOperations, OperationStatus
class FakeSwitch:
"""
Just enough of a Netmiko connection to test idempotency: it remembers
VLANs, so a second run sees what the first run created. A MagicMock
can't do that, and a stateless fake would make the test meaningless.
"""
def __init__(self):
self.vlans = {}
def send_command(self, command):
vlan_id = command.split()[-1] # "show vlan id 100"
if vlan_id not in self.vlans:
return f"VLAN id {vlan_id} not found in current VLAN database"
return (
"VLAN Name Status Ports\n"
"---- -------------------------------- --------- -----\n"
f"{vlan_id:<4} {self.vlans[vlan_id]:<32} active\n"
)
def send_config_set(self, commands):
vlan_id = commands[0].split()[1] # "vlan 100"
self.vlans[vlan_id] = commands[1].split()[1] # "name DATA"
def test_operation_is_idempotent():
"""Running the same operation repeatedly must be safe and honest."""
switch = FakeSwitch()
ops = IdempotentOperations()
# Run 1 creates it
assert ops.ensure_vlan_exists(switch, 100, "DATA").status == OperationStatus.CREATED
# Runs 2 and 3 change nothing
assert ops.ensure_vlan_exists(switch, 100, "DATA").status == OperationStatus.UNCHANGED
assert ops.ensure_vlan_exists(switch, 100, "DATA").status == OperationStatus.UNCHANGED
# A different desired name is an update, not a recreate
assert ops.ensure_vlan_exists(switch, 100, "VOICE").status == OperationStatus.UPDATED
Summary¶
| Concept | Definition |
|---|---|
| Idempotent | Safe to run multiple times, always produces same result |
| Check-before-change | Verify state before making changes |
| Declarative | "What state do we want?" not "What commands run?" |
| Status reporting | Tell caller what actually happened |
Idempotent automation is reliable, repeatable, and trustworthy.
Next Steps¶
- Structured Logging — Track what idempotent operations did
- Health Checks & Pre-Flight — Validate before idempotent deployment
Get notified when the book ships
Christopher is writing a book on production-grade Cisco network automation: one script, followed from twelve lines to a system that upgrades hundreds of devices, and every failure along the way. Join the list to hear when it ships and when new Academy material goes up.
One list, occasional emails, unsubscribe any time. Sign-up is handled by Kit; see the Privacy Policy.
Need this applied in a live Cisco environment?
This guide is part of the Nautomation Prime Academy and stays free to read, share, and reuse. If you want the pattern built, governed, or adapted for your estate, I'm available for contract engagements, and I take on smaller fixed-scope projects by enquiry. If you are a registered UK charity or CIC, there is a free and low-cost route instead.