Network Automation

---
name: network-automation
description: "Cross-platform comparison and architecture guidance for all network automation technologies: Infrastructure as Code, GitOps for network, source of truth patterns, CI/CD pipelines, config drift detection, and tool selection. Use for \"network automation\", \"IaC networking\", \"GitOps network\", \"config drift\", \"source of truth\", \"network CI/CD\", \"automation comparison\", \"NetDevOps\", \"network as code\", \"automation platform selection\". Do NOT use for ansible-network-, netbox-, or terraform-network-specific configuration -- use that technology's own skill."
license: MIT
---

# Network Automation

This skill covers all network automation technologies, providing cross-tool expertise in Infrastructure as Code (IaC) for network, GitOps patterns, source of truth design, CI/CD pipelines for network changes, configuration drift detection, and tool selection. Sibling technology skills provide deep implementation details.

## When to Use This Skill vs. a Technology Skill

**Use this skill when the question is cross-tool or architectural:**
- "How should I design our network automation strategy?"
- "Compare Ansible vs Terraform for network automation"
- "How do I implement GitOps for network configuration?"
- "What is the source of truth pattern for network?"
- "How do I detect and remediate configuration drift?"
- "Design a CI/CD pipeline for network changes"
- "NetDevOps -- where do I start?"

**Route to a technology skill when the question is tool-specific:**
- "Write an Ansible playbook for Cisco IOS VLAN config" --> the `ansible-network` skill
- "Terraform state management for ACI" --> the `terraform-network` skill
- "NetBox IPAM design and custom fields" --> the `netbox` skill
- "Ansible 2.18 resource module changes" --> the `ansible-network` skill's `references/versions/2.18.md`

## How to Approach Tasks

1. **Classify** the request:
   - **Strategy / Architecture** -- Load `references/concepts.md` for IaC principles, GitOps, source of truth
   - **Tool selection** -- Compare tools below based on use case, team skills, infrastructure
   - **Implementation** -- Identify the tool, consult the technology skill
   - **Troubleshooting** -- Identify the tool and failure mode, consult the technology skill
   - **Process design** -- Apply CI/CD, drift detection, and compliance patterns below

2. **Gather context** -- Network scale, device vendors, existing tools, team expertise (developer vs network engineer), change management requirements, compliance mandates

3. **Analyze** -- Apply automation-specific reasoning. Network automation has unique challenges: stateful devices, limited rollback, production impact of errors, mixed vendor environments.

4. **Recommend** -- Provide tool-specific guidance with trade-offs and adoption path

5. **Qualify** -- State assumptions about team maturity, existing infrastructure, and organizational readiness

## IaC Principles for Network

Infrastructure as Code applied to networking means:
- **Declarative intent**: Define the desired state of the network, not the commands to get there
- **Version-controlled**: All network configuration stored in Git
- **Reproducible**: Same input produces same network state every time
- **Testable**: Changes validated in CI before production deployment
- **Auditable**: Git history provides complete change audit trail

### Network-Specific IaC Challenges
- **Stateful devices**: Network devices maintain state (sessions, routes, MAC tables) that is not captured in configuration
- **Partial application**: A failed automation run may leave a device partially configured (unlike cloud VMs which can be destroyed and recreated)
- **Blast radius**: A bad config pushed to production can disconnect thousands of users
- **Vendor diversity**: Multi-vendor environments require multiple tools/modules/providers
- **Idempotency gaps**: Some network operations are not naturally idempotent (e.g., "add route" vs "ensure route exists")

## Tool Comparison

### Ansible (Network Automation)

**Strengths:**
- Agentless: connects via SSH/NETCONF/API to network devices -- no software installed on devices
- Rich network module ecosystem: vendor-specific collections (cisco.ios, arista.eos, junipernetworks.junos, paloaltonetworks.panos)
- Resource modules: declarative, idempotent management of specific resources (VLANs, interfaces, OSPF, BGP)
- Low barrier to entry for network engineers (YAML-based, sequential playbook execution)
- Jinja2 templating for config generation from data models
- Strong community and vendor support
- Config backup and compliance checking built-in

**Considerations:**
- Procedural at heart (playbook runs top-to-bottom); not truly declarative like Terraform
- No state file: does not track what it has deployed (re-reads device state each run)
- Performance at scale: serial execution per host (can be parallelized but limited by forks)
- Error handling is verbose (many rescue/block constructs needed for robust playbooks)

**Best for:** Day-2 operations (config changes, backups, compliance, troubleshooting), multi-vendor environments, teams with network engineering background, config generation and deployment.

### Terraform (Network Providers)

**Strengths:**
- Truly declarative: define desired state, Terraform computes the plan to get there
- State file tracks deployed resources: knows what exists, what changed, what to remove
- `terraform plan` provides a preview of all changes before application
- Strong for API-driven platforms (Cisco ACI, Meraki, Palo Alto, F5, FortiOS)
- Modules enable reusable, composable infrastructure definitions
- Remote state with locking prevents concurrent conflicting changes
- Drift detection: `terraform plan` shows current state vs desired state

**Considerations:**
- Limited support for CLI-based devices (SSH/NETCONF); best with API-driven platforms
- State file management is critical (corruption = operational risk)
- Provider maturity varies widely across network vendors
- "Destroy" semantics can be dangerous for network infrastructure
- Learning curve for HCL syntax (different from YAML/Python)

**Best for:** API-driven network platforms (ACI, Meraki, PAN-OS, F5), greenfield deployments, infrastructure provisioning, teams already using Terraform for cloud/server infrastructure.

### NetBox (Source of Truth)

**Strengths:**
- Purpose-built IPAM + DCIM for network infrastructure
- Comprehensive data model: sites, racks, devices, interfaces, IPs, VLANs, cables, circuits
- REST and GraphQL APIs for programmatic access
- Ansible inventory plugin: generate dynamic inventory from NetBox data
- Terraform integration: query NetBox to drive infrastructure provisioning
- Custom fields and validators extend the data model for organization-specific needs
- Plugin ecosystem (BGP, DNS, routing, topology views)

**Considerations:**
- NetBox is a data store, not an automation engine -- it needs Ansible/Terraform/scripts to act on its data
- Data quality requires organizational discipline (stale data is worse than no data)
- Initial population effort is significant (document existing network in NetBox)
- Custom fields require planning to avoid proliferation

**Best for:** Single source of truth for network inventory, IPAM, and data modeling. Foundation for any mature automation practice.

## Source of Truth Pattern

The source of truth pattern is the foundation of mature network automation:

```
NetBox (Source of Truth)
  ├── Contains: devices, interfaces, IPs, VLANs, circuits, sites
  ├── Feeds: Ansible inventory (nb_inventory plugin)
  ├── Feeds: Terraform variables (HTTP data source)
  └── Feeds: Custom scripts (pynetbox API)

Git Repository (Desired State)
  ├── Contains: Ansible playbooks, Terraform configs, Jinja2 templates
  ├── Contains: Group/host variables that extend NetBox data
  └── CI/CD pipeline validates and deploys changes

Network Devices (Actual State)
  ├── Managed by: Ansible playbooks / Terraform apply
  ├── Monitored by: Drift detection (periodic config backup + diff)
  └── Inventory sourced from: NetBox
```

### Key Principle
NetBox is authoritative for **what exists** (inventory, addressing, topology). Git is authoritative for **how it should be configured** (templates, policies, variables). Ansible/Terraform bridge the gap between desired state and actual state.

## GitOps for Network

### GitOps Workflow

```
1. Developer/engineer creates feature branch
2. Makes changes to network config (Ansible vars, Terraform HCL, templates)
3. Pushes branch, creates Pull Request
4. CI pipeline runs:
   a. Lint: YAML/HCL syntax validation
   b. Dry-run: ansible-playbook --check / terraform plan
   c. Tests: unit tests on Jinja2 templates, variable validation
   d. Compliance: check against security/compliance rules
5. Peer review of PR (network engineer reviews the plan/diff)
6. Merge to main branch
7. CD pipeline runs:
   a. Deploy: ansible-playbook / terraform apply
   b. Validate: post-deployment connectivity tests, config diff
   c. Notify: Slack/Teams notification of deployment result
8. Rollback if validation fails
```

### Benefits
- **Audit trail**: Every change is a Git commit with author, timestamp, and description
- **Peer review**: Network changes reviewed before deployment (like code review)
- **Rollback**: Revert to previous Git commit to undo changes
- **Consistency**: Same pipeline for all network changes (no ad-hoc CLI sessions)
- **Compliance**: Automated policy checks in CI catch violations before deployment

### CI/CD Tools for Network
- GitHub Actions, GitLab CI, Jenkins, Azure DevOps
- Batfish for offline network config analysis (pre-deployment validation)
- Suzieq for network observability (post-deployment validation)
- pyATS (Cisco) for network test automation

## Config Drift Detection

Configuration drift occurs when actual device config diverges from desired state:

### Causes
- Manual CLI changes by engineers (bypassing automation)
- Emergency changes not backported to Git/automation
- Device firmware updates that alter default behavior
- Expired certificates, rotated credentials
- NTP/syslog server IP changes not propagated to all devices

### Detection Methods
1. **Periodic config backup + diff**: Backup running configs via Ansible (`ios_config backup: yes`), compare to previous backup
2. **Terraform plan**: `terraform plan` shows drift for API-managed resources
3. **Ansible check mode**: `ansible-playbook --check --diff` shows what would change without applying
4. **Oxidized/RANCID**: Dedicated config backup tools that detect and alert on changes
5. **NetBox comparison**: Compare NetBox intended state vs actual device state via API

### Remediation
- **Auto-remediate**: Re-run automation to enforce desired state (risky without review)
- **Alert and review**: Notify team of drift; engineer reviews and either updates automation or reverts device
- **Scheduled enforcement**: Re-run automation on a schedule (e.g., nightly) to correct drift automatically

## Idempotency in Network Context

Idempotent operations produce the same result whether run once or many times:

| Idempotent | Not Idempotent |
|---|---|
| "Ensure VLAN 10 exists with name MGMT" | "Add VLAN 10" (fails if already exists) |
| "Set interface description to X" | "Append X to interface description" |
| "Ensure OSPF area 0 has network 10.0.0.0/8" | "Add network 10.0.0.0/8 to OSPF" (duplicate) |
| Ansible resource modules (state: merged) | Raw CLI commands via `ios_command` |
| Terraform `resource` blocks | Terraform `null_resource` with local-exec |

### Best Practice
Always use idempotent operations (resource modules, Terraform resources) over raw commands. Raw commands require you to implement idempotency checks yourself (check before change), which is error-prone.

## Common Pitfalls

1. **Starting with tools instead of process** -- Define your automation workflow (source of truth, change process, validation, rollback) before selecting tools. Tools are interchangeable; process is fundamental.

2. **Automating without a source of truth** -- Ansible playbooks with hardcoded variables and no NetBox/CMDB create a new kind of sprawl (YAML sprawl instead of manual sprawl). Establish a source of truth first.

3. **No dry-run in production pipeline** -- Always run `--check` / `plan` before applying. Network changes have immediate production impact -- there is no staging network.

4. **Ignoring rollback** -- Every automation workflow needs a rollback procedure. For Ansible: keep backup configs and have a "restore" playbook. For Terraform: `terraform plan -destroy` on the failed resource.

5. **Treating network automation like server automation** -- Network devices are stateful, have limited APIs, and cannot be destroyed/recreated. "Cattle not pets" does not apply to production routers and switches.

6. **Manual changes after automation adoption** -- The most common automation failure. If engineers bypass automation for "quick fixes," drift accumulates and trust in automation erodes. Enforce process, not just tools.

7. **Over-automating too quickly** -- Start with read-only automation (config backup, inventory, compliance checks) before write operations (config changes). Build confidence incrementally.

8. **No testing infrastructure** -- Network automation benefits enormously from a lab environment (physical or virtual: CML, EVE-NG, Containerlab). Test playbooks/plans in lab before production.

## Technology Routing

| Request Pattern | Route To |
|---|---|
| Ansible, playbook, collection, network_cli, resource module, Jinja2, inventory | the `ansible-network` skill (see `references/versions/2.18.md` for version specifics) |
| Terraform, HCL, provider, state, plan, apply, ACI/Meraki/PAN-OS/FortiOS/F5 Terraform | the `terraform-network` skill |
| NetBox, IPAM, DCIM, source of truth, pynetbox, nb_inventory | the `netbox` skill (see `references/versions/4.5.md` for version specifics) |

## Reference Files

- `references/concepts.md` -- NetOps fundamentals: IaC principles, GitOps for network, source of truth pattern, config drift detection, declarative vs imperative, idempotency, CI/CD pipeline design. Read for "how does X work" or strategy questions.