task 2.1 · chapter 2 of 8: your first playbook · 20 min
Your first playbook
objective
Write a playbook that sets the same contact and login banner on every switch, and prove a second run changes nothing.
playbooks/hello.ymlopen a file in VS Code: Ctrl+P (Cmd+P on a Mac), type its name, Enter
| Contact | snmp-server contact netops@networkdoodles.com |
|---|---|
| Banner | Managed by Ansible - Network Doodles lab |
| Modules | cisco.ios.ios_config (config lines) · cisco.ios.ios_banner (banners) |
What is an Ansible playbook, and what does idempotent mean?
An ad-hoc command does one thing, once. A playbook is a file that describes the state you want, so you can apply it again tomorrow, review it in Git, and hand it to a colleague.
The key idea: a playbook says what the switch should look like, not a script of keystrokes. Before it sends a config line, Ansible reads the running config and checks whether the line is already there. If it is, nothing is sent. Run a playbook twice and the second run changes nothing, because there’s nothing left to change. That property has a name, idempotent, and it’s the reason it’s safe to run a playbook against a whole network.
What are the parts of a playbook?
- name: Hello, fabric # a PLAY: a name for humans
hosts: fabric # which hosts, from the inventory
gather_facts: false # don't run the server-style fact gathering (switches don't need it)
tasks: # the play's TASKS, run in order, on every host
- name: Who to call # a task: a name for humans...
cisco.ios.ios_config: # ...and exactly one MODULE
lines: # the module's arguments: config lines, as you'd type them
- snmp-server contact netops@networkdoodles.com
| Part | What it is |
|---|---|
| play | which hosts, and what to do to them. A playbook is a list of plays; ours has one. |
| task | one step: a name, and one module with its arguments. |
| module | cisco.ios.ios_config adds config lines, in config mode, only if they’re missing. |
| lines | the config, exactly as show running-config prints it. |
When it runs, the PLAY RECAP at the end counts what happened on each host: ok (already right),
changed (Ansible changed it), failed.
Who to call
Open the playbook. The play is written; its task list is empty apart from the TODOs:
editplaybooks/hello.ymlCtrl+P → hello.yml- name: Hello, fabric hosts: fabric gather_facts: false tasks: # TODO 2.1a ...Under
tasks:, add the first task.- name:starts 4 spaces in, lined up with the TODO comments:editplaybooks/hello.ymlCtrl+P → hello.ymltasks: - name: Who to call cisco.ios.ios_config: lines: - snmp-server contact netops@networkdoodles.comRun it:
run in the terminalmake run T=2.1TASK [Who to call] ********************************************* [WARNING]: To ensure idempotency and correct diff the input configuration lines should be similar to how they appear if present in the running configuration on device changed: [spine1] changed: [leaf1] changed: [leaf2] PLAY RECAP ***************************************************** leaf1 : ok=1 changed=1 unreachable=0 failed=0 ... leaf2 : ok=1 changed=1 unreachable=0 failed=0 ... spine1 : ok=1 changed=1 unreachable=0 failed=0 ...changed=1on each switch: Ansible logged in and sent the line. The warning isios_configreminding you of its one rule, every time it changes something: it compares your lines as text with the running config, so write them the way the switch prints them (snmp-server contact, notsnmp contact). Yours already are.Run it again. This time
changed=0, and no warning: the line is already there, so Ansible sends nothing. That’s idempotence, and it’s what the checker looks for.See it on a switch: click leaf1 on the Topology tab, then in its tab
show running-config | include contact.
A login banner
Add a second task that sets the login banner on every switch to exactly
Managed by Ansible - Network Doodles lab. Run it twice, as before.
A banner isn’t one config line: it’s a block of text between two delimiters. ios_config can’t compare that
reliably, so the collection has a module just for banners, cisco.ios.ios_banner, with three arguments:
banner (which one: login), text, and state: present.
hint
The new task goes after the first, at the same indentation: - name: 4 spaces in. The module name replaces
cisco.ios.ios_config:, and its three arguments go under it, 2 spaces further in.
hint
A login banner is shown before you type a password. The Topology tab’s terminal skips the login, so it doesn’t
show it. ssh admin@leaf1 in the VS Code terminal does, or ask the switch: show banner login.
show the solutionplaybooks/hello.yml
or pull it into your lab: make solve T=2.1, then git diff --staged shows what changed
- name: Login banner
cisco.ios.ios_banner:
banner: login
text: "Managed by Ansible - Network Doodles lab"
state: present
5 check: run it, then prove it
$ make run T=2.1
$ make check T=2.1when it's right, you'll see
╭─ task 2.1 · your first playbook
│ ✓ playbooks/hello.yml runs cleanly
│ ✓ spine1 has its contact: snmp-server contact netops@networkdoodles.com
│ ✓ leaf1 has its contact: snmp-server contact netops@networkdoodles.com
│ ✓ leaf2 has its contact: snmp-server contact netops@networkdoodles.com
│ ✓ the challenge: spine1 shows the login banner
│ ✓ the challenge: leaf1 shows the login banner
│ ✓ the challenge: leaf2 shows the login banner
│ ✓ a second run of playbooks/hello.yml changes nothing (changed=0)
╰─ 8/8 checks passed verified
background: part 2, Anatomy of a playbook