Ansible Playbooks

Ansible’s superpower is imperative-looking playbooks with declarative-looking outcomes — as long as your modules are idempotent. Where that promise breaks is where the interesting bugs live.

Directory layout

Directoryansible/
- Directoryinventory/
  - prod.yml
  - staging.yml
- Directorygroup_vars/
  - all.yml
  - webservers.yml
- Directoryroles/
  - Directorycommon/
    tasks/main.yml
    handlers/main.yml
    Directorytemplates/
    …
  - Directorynginx/
    …
  - Directorypostgres/
    …
- Directoryplaybooks/
  - site.yml
  - patching.yml
- ansible.cfg

A well-behaved role task

- name: Install nginx
  ansible.builtin.package:
    name: nginx
    state: present
  notify: reload nginx

- name: Render main config
  ansible.builtin.template:
    src: nginx.conf.j2
    dest: /etc/nginx/nginx.conf
    owner: root
    group: root
    mode: "0644"
    validate: "nginx -t -c %s"
  notify: reload nginx

- name: Ensure nginx enabled and started
  ansible.builtin.service:
    name: nginx
    state: started
    enabled: true

Handlers, notifications, and the run order

Handlers only run after all tasks in a play complete, and only once per handler even if notified many times. Useful for restart-once semantics. Force them earlier with:

- name: Flush handlers
  ansible.builtin.meta: flush_handlers

Idempotence — the honest picture

Type of task	Idempotent?
`package`, `service`, `file`	✅ Built-in check-then-act
`template`, `copy`	✅ Content-diff before write
`command`, `shell`	❌ You must guard with `creates:` / `changed_when:`
`uri`, `get_url`	Depends — check `force`, `checksum`

- name: Bootstrap a one-shot script
  ansible.builtin.shell: /opt/init/bootstrap.sh
  args:
    creates: /var/lib/reetwiz/.bootstrapped

plugin: azure.azcollection.azure_rm
include_vm_resource_groups:
  - core-rg
  - workloads-rg
keyed_groups:
  - prefix: tag
    key: tags['role']
auth_source: cli

plugin: amazon.aws.aws_ec2
regions:
  - eu-west-1
filters:
  tag:Environment: prod
keyed_groups:
  - prefix: role
    key: tags.Role

Testing playbooks locally

# lint
ansible-lint playbooks/site.yml

# check mode + diff (dry run)
ansible-playbook -i inventory/staging.yml playbooks/site.yml --check --diff

# molecule (per-role tests in ephemeral containers)
cd roles/nginx && molecule test