Network Automation Guide

This is an original planning guide. It is not a vendor manual, an official standard, or legal advice. Example addresses use documentation ranges. Review every command before you paste it.

Automation applies a reviewed change, it does not invent one

Network automation is a way to apply the same reviewed change to many devices, and to show you the diff before it does. It is not a reason to skip the ticket. The ticket still names the devices, the change, the test, and the rollback. The tool only makes the typing match the ticket.

Start read-only. Collect the running configuration, the version, and the neighbour state into a file you can compare. A playbook that configures before it has ever read is a playbook you do not know. The first week of an automation project should not change a single interface. It should prove you can log in, read, and log out without saving a secret into a repository.

Secrets do not go in git. Usernames may. Host lists may. Passwords, SNMP communities, and private keys may not. Use the secret store you already trust, and make the job fail closed when the secret is missing. A repository that contains a firewall password is an incident even if the change it made was correct.

The generators on this site draft a script or a playbook in the browser from values you type. They do not log into your network. Read the draft. Run it in a lab or with a dry-run the platform provides. Then let a person approve the diff. A green pipeline is not a review.

The diff is the change

A diff that adds a VLAN, allows it on a named trunk, and nothing else, is a change you can approve. A diff that also reorders the whole file, changes a banner, and touches an unrelated ACL is three changes. Reject it or split it. Tools that rewrite an entire configuration make noisy diffs. Prefer a tool that edits the statements you named. If you cannot get a quiet diff, the review takes longer, and you should say so in the schedule.

Approve the diff against the ticket, not against your memory of the meeting. If the ticket says VLAN 10 and the diff says VLAN 11, the diff is wrong. If the ticket says VLAN 10 and the diff also deletes VLAN 40, the diff is wrong even though VLAN 10 is present. Read the deletions with more care than the additions. Deletions are how a trunk loses a VLAN the meeting did not mention.

A dry run that claims it would change a device is useful only if the dry run and the real run use the same template. If people edit the template between the dry run and the apply, the approval is void. Freeze the template, record its hash or its commit, and apply that commit. A later commit is a later change.

Devices that fail to collect should not be configured by a blast that ignores errors. Stop on the first failure until you trust the tool. Continuing after an error is how half a network gets a VLAN and half does not, which is a worse outage than the one you were fixing. Partial success is a state you must detect and report, not a success with a footnote.

A lab that matches production closely enough

The lab needs the same software family as production, not a container that merely accepts the syntax. A command that is legal on the lab version and illegal on the production version will be approved in the lab and fail in the window, or worse, mean something else. Write the versions in the ticket. If they differ, the first automation task is to stop claiming they are the same.

Give the lab a tiny copy of the real addressing plan, using documentation prefixes if the lab must not leak. 192.0.2.0/24 and 198.51.100.0/24 are for that lab writing. Do not point the lab at production gear. A playbook with an inventory that includes one production host by mistake is the incident story everyone has already heard. Separate inventories. Separate credentials. A job that can reach production should not be the job a learner runs.

Test rollback in the lab. Apply, test, roll back, test. If the rollback is not automated, write the exact commands and time them. A rollback you have not timed does not fit in the window you scheduled. The window must hold the change and the rollback. If it does not, the window is too small or the change is too big.

Idempotence means running the job twice does not make a second, different change. Run it twice in the lab. The second diff should be empty. A second diff that adds another line is a template bug. Fix it before the window. Production is a bad place to discover that the job appends.

The window itself

One human owns the apply. Automation does not remove that person. They watch the first devices, run the test from the ticket, and only then let the job continue. A job that configures fifty devices while the owner is in another meeting is not automation. It is unattended change.

The test is the same test as a manual change. A host in the new VLAN gets an address and reaches the one application. A host that should not be in the VLAN does not. If you cannot test until all fifty are done, you cannot stop at five. Restructure the change so the first five are a complete test.

Logs from the tool are part of the ticket. Store the commit id, the inventory that was targeted, the person who approved, and the time. You will need that when a device is found later with a surprise configuration. The log is how you know whether the tool did it.

After the window, the source of truth is the repository plus the devices, and they must match. A drift check the next day is part of the change, not a nice extra. Drift means someone configured by hand or the tool failed silently. Both are worth knowing before the next window stacks a diff on a lie.

A first automated change worth doing

Pick a change you already do by hand every week: a VLAN on a closet, a banner, an NTP server, a standard SNMP user. Automate that, end to end, including the review. Do not start with a firewall policy rewrite. The first win is a boring change with a quiet diff and a rollback you used once in anger in the lab.

Write the failure. If the tool cannot log in, what happens? If the device reboots mid-push, what is true? If the runner loses network, does it retry and double-apply? Answer those in a paragraph on the job's page. A job without a failure paragraph is a demo.

Keep a manual path. The day the automation server is down should not be a day you cannot add a VLAN to one closet. The manual command, reviewed, remains valid. Automation is the normal path, not the only path. Document both so the on-call does not invent a third.

Read the device before you plan to write.
Keep secrets out of the repository.
Produce a diff that contains only the ticket.
Approve that diff against the ticket.
Apply in a lab of the same software family and roll it back.
Apply to the first production devices with a person watching.
Test, then continue, then check for drift the next day.

Mistakes that automate an outage

A production inventory used from a lab account.

A password in a repository.

A diff too noisy to review, approved anyway.

Continuing after the first device errors.

No tested rollback.

A second run that is not idempotent.

Starting with the firewall policy instead of a boring change.

No drift check, so the repository becomes fiction.

Automation checks before the job is allowed to write

Confirm this before you call the change done: The inventory for this job cannot see the lab and production at once. A secret scan of the repository is clean. The diff matches the ticket and the deletions were read. The template commit that was approved is the commit that will run. The lab version matches production closely enough that the command means the same thing. Rollback was timed in the lab. The second lab run produced an empty diff. The first production batch is small enough to test. The on-call still has a manual method. Tomorrow's drift check is on the calendar. The runner's credentials are admin credentials and are stored as such. Documentation prefixes used in lab notes are not in the production inventory. The owner of the apply is named and is watching the first batch. A failure on the first device stops the job. The manual VLAN method is written where the on-call can find it. The job page explains what happens if the runner loses its path. Deletions in the diff were read aloud. And the lab inventory and the production inventory are different files. If one of those fails, stop.

Tools for this guide

These tools run in the browser on this site. They do not log into your machines.

Guides in this cluster

These supporting pages belong to this pillar.

Companion: System: Bash Scripting Basics.