Ansible Playbooks: YAML, Inventory, and Safe Automation

1. What makes an Ansible playbook work?

An Ansible inventory identifies the managed hosts or groups. A playbook contains one or more plays; each play selects hosts and lists tasks. A module performs an action or checks a desired state. Modules are commonly referenced using a fully qualified collection name (FQCN), such as cisco.ios.ios_command.

Traditional Ansible modules can configure Linux hosts over SSH. Network devices often use a network-specific connection plugin, such as ansible.netcommon.network_cli, and modules supplied by vendor collections. Ansible generally runs from a controller; you do not need to install the Ansible control software on each network switch.

2. Create a predictable inventory

Use descriptive groups and keep your production scope separate from a lab. This INI example shows a group called edge_switches with two illustrative Cisco IOS devices. The 192.0.2.0/24 address block is reserved for documentation; replace these values only with devices you are authorized to manage.

[edge_switches]
sw-lab-01 ansible_host=192.0.2.10
sw-lab-02 ansible_host=192.0.2.11

[edge_switches:vars]
ansible_connection=ansible.netcommon.network_cli
ansible_network_os=cisco.ios.ios
ansible_user=automation

Inventory does not discover devices automatically in this example. A play targeting edge_switches can affect every matched host unless you restrict it, so verify the group and use --list-hosts before a sensitive run.

3. Read the structure of a YAML playbook

YAML indentation is meaningful. Use spaces consistently, do not use tabs for indentation, and keep lists aligned. The following playbook uses one play, two tasks and a registered result. It deliberately requests information rather than configuration changes.

---
- name: Read version information from lab switches
  hosts: edge_switches
  gather_facts: false
  tasks:
    - name: Request device version
      cisco.ios.ios_command:
        commands:
          - show version
      register: version_result

    - name: Display returned version output
      ansible.builtin.debug:
        var: version_result.stdout[0]

Important: This example expects the appropriate cisco.ios and ansible.netcommon collections, reachable authorized devices and working authentication. It has been checked for YAML structure but not executed against live network equipment.

4. Start with a read-only network check

The safest introduction is to inspect a known lab switch before automating a change. Ansible sends the specified command using the selected connection plugin and receives output from that device. The show version command in the example above is intended as a read-only status query.

ansible-playbook -i inventory.ini show-version.yml --list-hosts
ansible-playbook -i inventory.ini show-version.yml --syntax-check
ansible-playbook -i inventory.ini show-version.yml --list-tasks

Once you have reviewed the devices, module compatibility and credentials, run it only in a permitted test environment:

ansible-playbook -i inventory.ini show-version.yml --limit sw-lab-01

5. Build a controlled configuration backup

A backup playbook can collect a configuration from each supported switch and save it on the Ansible controller. The following example illustrates the workflow with cisco.ios.ios_command and delegated local file operations. It reads the device’s configuration; it does not push a new one.

---
- name: Back up authorized Cisco IOS devices
  hosts: edge_switches
  gather_facts: false
  tasks:
    - name: Create a private local backup directory
      ansible.builtin.file:
        path: "{{ playbook_dir }}/backups"
        state: directory
        mode: "0700"
      delegate_to: localhost
      run_once: true

    - name: Read the active configuration
      cisco.ios.ios_command:
        commands:
          - show running-config
      register: running_config
      no_log: true

    - name: Save configuration on the controller
      ansible.builtin.copy:
        content: "{{ running_config.stdout[0] }}\n"
        dest: "{{ playbook_dir }}/backups/{{ inventory_hostname }}.cfg"
        mode: "0600"
      delegate_to: localhost
      no_log: true

The run_once directory task prepares the destination before the parallel per-host copies. For basic direct execution this is a convenient pattern; execution strategies, delegation, controller permissions and filesystem behavior should be tested in your environment. The example intentionally does not include an automatic restore operation.

6. Validate scope, syntax and expected behavior

A valid YAML file is not proof that a playbook is safe for your environment. Syntax checks, target listing, task review and an approved lab test answer different questions. These commands support a staged review.

ansible-playbook -i inventory.ini backup-config.yml --syntax-check
ansible-playbook -i inventory.ini backup-config.yml --list-hosts
ansible-playbook -i inventory.ini backup-config.yml --list-tasks
ansible-playbook -i inventory.ini show-version.yml --limit sw-lab-01

Use --limit to narrow the target list, inspect the active inventory, verify the relevant module versions, and maintain a rollback plan before any configuration-changing playbook is approved.

7. Understand idempotency, check mode and secrets

Ansible Vault can encrypt variable files at rest. It does not automatically make console logs, generated backups or decrypted in-memory data secure. Use no_log where appropriate, protect credentials and avoid exposing sensitive diffs to logs. For sensitive configuration tasks, consider turning off diff output.

8. Use the NetOps Ansible Playbook Generator

The NetOps Ansible Playbook Generator provides a starting point for network configuration backup YAML. On its current page you select a target host or group from inventory and a network OS, then generate YAML to inspect and adapt. The tool helps draft playbook text; it does not connect to switches, validate your credentials or execute the resulting automation.

Network collections are versioned separately from ansible-core. A playbook that references cisco.ios.ios_command needs the corresponding Cisco collection, along with a compatible connection plugin. The exact host variables, commands and connection details depend on the device platform.

9. Checklist before automating network infrastructure

Automation reduces repetitive manual effort, but multiplies the impact of incorrect targeting. The most valuable practice is a controlled, reviewable workflow from a small lab to an approved production scope.

10. Frequently asked questions

11. Technical references

1. Ansible — Playbooks: syntax, execution, idempotency and verification
2. Ansible — Building and using inventory
3. Ansible — cisco.ios.ios_command module
4. Ansible — network_cli connection plugin
5. Ansible — Check mode and diff mode limitations
6. Ansible — Vault and sensitive data
7. IETF RFC 5737 — Documentation-only IPv4 address blocks

Last reviewed: October 27, 2026 · Prepared by: NetOps Tools · Educational content for authorized network administration. Sample IPs and hostnames are documentation examples, not live targets. Collection requirements and device behavior vary by version and vendor. This article does not certify any deployment as safe.