Learn Ansible Modern Reference Guide

Chapter 1: The Modern Ansible Landscape

Ansible fundamentally changed. The old "batteries included" ansible package was split. Today, we use ansible-core (the raw engine) and Collections (the modules). Ansible remains agentless, using a push-model via SSH or WinRM, but how we package and run it has modernized.

Chapter 2: Setting Up the Environment

In the past, you used Python virtual environments. Today, enterprise automation runs entirely inside containers called Execution Environments (EEs) using ansible-navigator. This eliminates the "it works on my laptop" problem.

[defaults]
inventory = ./inventory.yml
host_key_checking = False
jinja2_native = True # Crucial modern setting

Chapter 3: Inventories & Connections

Inventories tell Ansible *where* to run. YAML is the modern standard for static inventories. However, in the cloud, static files are useless. You must learn dynamic inventories.

plugin: amazon.aws.aws_ec2
regions:
  - us-east-1
keyed_groups:
  - key: tags.Role
    prefix: role

Chapter 4: Ad-Hoc Commands & FQCNs

Ad-hoc commands are great for quick tasks (like restarting a service across 50 nodes). Modern Ansible strictly requires Fully Qualified Collection Names (FQCNs) for modules.

# The modern way to ping all webservers
ansible-navigator exec "ansible webservers -m ansible.builtin.ping"

Chapter 5: Playbooks & Idempotence

A playbook is declarative. It should describe the *end state*, not a list of commands. A truly idempotent playbook can be run 100 times in a row safely; if the state is already correct, it makes 0 changes.

- name: Run custom setup script
  ansible.builtin.command: /opt/setup.sh
  args:
    creates: /etc/setup_done.conf # Forces Idempotence

Chapter 6: Variables, Facts & State

Ansible gathers facts (system data like OS, IP address, disks) automatically. However, variable precedence (the order in which variables override each other) is the #1 cause of bugs in complex deployments.

Chapter 7: Control Flow & Loops

Ansible is not a programming language, but it offers control flow. You use when for conditionals and loop for iteration. Handlers are special tasks triggered only when a state changes.

- name: Create multiple users
  ansible.builtin.user:
    name: "{{ item.name }}"
    state: present
  loop:
    - { name: 'alice' }
    - { name: 'bob' }
  when: create_users_flag | bool

Chapter 8: Templates & Data Manipulation

Ansible uses Jinja2 for templating. Modern Ansible requires you to enable native types to avoid string-casting nightmares.

Chapter 9: Roles (Legacy vs Modern)

Roles allow you to break complex playbooks into reusable directories (tasks, handlers, vars). While standalone roles were the standard in Ansible 2.9, they are now typically packaged *inside* Collections.

Chapter 10: Ansible Collections

Collections are the modern distribution format. They package roles, modules, plugins, and playbooks together. Your enterprise should build internal Collections for its business logic.

collections:
  - name: amazon.aws
    version: ">=6.0.0"
  - name: community.general

Install them via: ansible-galaxy collection install -r requirements.yml

Chapter 11: Execution Environments & Builder

You must bundle your Collections and Python dependencies into immutable container images (Execution Environments) using ansible-builder v3.

Chapter 12: Secrets Management

Ansible Vault encrypts files, but modern GitOps relies on dynamic secret fetching.

- name: Database Task
  mysql_db:
    password: "{{ lookup('community.hashi_vault.hashi_vault', 'secret=database/creds:password') }}"
  no_log: true # CRITICAL

Chapter 13: Error Handling & Strategies

Production servers fail. You need resilient code. Use block, rescue, and always to catch errors and gracefully roll back changes.

Chapter 14: Testing & Linting

If you treat Infrastructure as Code, you must test it like code. Unlinted YAML leads to syntax failures in production.

Chapter 15: AAP / AWX

Ansible Automation Platform (AAP) or the upstream open-source AWX project provides a GUI, API, and RBAC over your Ansible code. It moves execution from a developer's laptop to a centralized, auditable server cluster.

Chapter 16: CI/CD Pipelines

Ansible should be deployed via CI/CD. When code is merged, a pipeline should lint it, test it, and update the AWX project via API.

name: Ansible CI
on: [push]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run ansible-lint
        run: pipx run ansible-lint site.yml

Chapter 17: Event-Driven Ansible (EDA)

The ultimate shift from reactive manual administration to self-healing infrastructure. EDA allows Ansible to listen to monitoring tools and trigger playbooks automatically.

---
- name: Webserver Auto-Remediation
  hosts: all
  sources:
    - ansible.eda.webhook:
        host: 0.0.0.0
        port: 5000
  rules:
    - name: Restart service on failure
      condition: event.payload.status == "down"
      action:
        run_playbook:
          name: restart_service.yml

Chapter 18: Cloud & IaC

Ansible complements Terraform. Terraform provisions the raw infrastructure (VPCs, EC2 instances), and Ansible configures the OS and applications running on them. Use the cloud.terraform collection to orchestrate Terraform directly from Ansible if needed.

Chapter 19: Network & Edge Automation

Ansible isn't just for Linux servers. It manages Cisco routers, Juniper switches, and Edge IoT devices natively.