Ansible

ansible-playbook site.yml --check --diff --limit staging
ansible-playbook site.yml --check --diff --tags nginx

# inventory/prod.ini
[web]
web-[01:04].example.com

[db]
db-01.example.com ansible_host=192.0.2.11

[prod:children]
web
db

[prod:vars]
ansible_user=deploy

# inventory/prod.yml: the YAML form, clearer for nested group vars
all:
  children:
    web:
      hosts:
        web-01.example.com:
        web-02.example.com:
      vars:
        nginx_workers: 4

ansible-inventory -i inventory/prod.yml --graph
ansible-inventory -i inventory/prod.yml --host web-01.example.com   # merged variables for one host
ansible all -i inventory/prod.yml -m ansible.builtin.ping --limit web

# inventory/prod.aws_ec2.yml: file name must end in .aws_ec2.yml or .aws_ec2.yaml
plugin: amazon.aws.aws_ec2
regions: [ap-southeast-2]
filters:
  instance-state-name: running
  tag:Environment: prod
hostnames: [tag:Name, private-ip-address]   # first that exists becomes inventory_hostname
compose:
  ansible_host: private_ip_address          # connect on the private address
  ansible_user: "'ec2-user'"                # compose values are Jinja; quote literals twice
keyed_groups:
  - key: tags.Role                          # group "role_web" from tag Role=web
    prefix: role
  - key: placement.availability_zone
    prefix: az
groups:
  db: "'db' in tags.Role"                   # conditional group from an expression
cache: true                                 # reuse results between runs
cache_plugin: ansible.builtin.jsonfile
cache_connection: ~/.cache/ansible-inventory
cache_timeout: 600

- name: Configure web tier
  hosts: web
  become: true
  serial: "25%"                 # a quarter of the group at a time
  max_fail_percentage: 0        # any failure in a batch stops the play
  pre_tasks:
    - name: Drain from the load balancer
      ansible.builtin.uri:
        url: "https://lb.example.com/drain/{{ inventory_hostname }}"
        method: POST
      delegate_to: localhost

  roles:
    - role: nginx
      tags: [nginx]

  tasks:
    - name: Deploy configuration
      ansible.builtin.template:
        src: nginx.conf.j2
        dest: /etc/nginx/nginx.conf
        owner: root
        mode: "0644"
        validate: nginx -t -c %s      # refuse to install a config that fails its own check
      notify: Reload nginx

  handlers:
    - name: Reload nginx
      ansible.builtin.service:
        name: nginx
        state: reloaded

  handlers:
    - name: Reload nginx
      ansible.builtin.service: { name: nginx, state: reloaded }
      listen: nginx config changed
    - name: Purge nginx cache
      ansible.builtin.file: { path: /var/cache/nginx, state: absent }
      listen: nginx config changed
  tasks:
    - name: Install site
      ansible.builtin.template: { src: site.conf.j2, dest: /etc/nginx/conf.d/site.conf }
      notify: nginx config changed

roles/nginx/
  defaults/main.yml       # tunables, lowest precedence
  vars/main.yml           # constants the role relies on; hard to override
  tasks/main.yml          # entry point; include_tasks/import_tasks for the rest
  handlers/main.yml
  templates/              # referenced by bare name from template:
  files/                  # referenced by bare name from copy:
  meta/main.yml           # dependencies, platforms, galaxy_info
  meta/argument_specs.yml # validated role parameters (2.11+)
  molecule/default/       # tests
  README.md

# roles/nginx/meta/argument_specs.yml
argument_specs:
  main:
    short_description: Install and configure nginx
    options:
      nginx_workers:
        type: int
        default: 4
        description: Worker processes
      nginx_sites:
        type: list
        elements: dict
        required: true
        options:
          name: { type: str, required: true }
          port: { type: int, default: 80 }

ansible-galaxy role init roles/nginx                               # scaffold
ansible-doc -t role -l                                             # roles with argument_specs on the roles path
ansible-doc -t role roles/nginx                                    # render the spec as documentation
ansible-galaxy collection install -r requirements.yml -p collections/   # vendor collections into the project

- name: Package present
  ansible.builtin.package:
    name: nginx
    state: present

- name: Line in a config file
  ansible.builtin.lineinfile:
    path: /etc/security/limits.conf
    regexp: '^\*\s+soft\s+nofile'
    line: '*    soft    nofile 65535'

- name: Run a migration exactly once
  ansible.builtin.command: /opt/my-app/bin/migrate
  args:
    creates: /var/lib/my-app/.migrated        # skipped when this path exists

- name: Script with an explicit change test
  ansible.builtin.command: /usr/local/bin/sync-data
  register: sync
  changed_when: "'updated' in sync.stdout"
  failed_when: sync.rc not in [0, 2]

{# nginx.conf.j2 #}
worker_processes {{ ansible_facts['processor_vcpus'] }};
upstream app {
{% for host in groups['app'] %}
    server {{ hostvars[host]['ansible_facts']['default_ipv4']['address'] }}:8080;
{% endfor %}
}

ansible web-01 -m ansible.builtin.setup | less                        # every fact
ansible web-01 -m ansible.builtin.setup -a 'filter=ansible_mounts'

- name: Show a value at the point of use
  ansible.builtin.debug:
    var: nginx_workers
    verbosity: 1              # printed only with -v or more

- name: Filters that come up in every playbook
  ansible.builtin.debug:
    msg:
      - "{{ nginx_port | default(80) }}"                                   # default when undefined (add true to also cover empty/false)
      - "{{ my_dict | combine({'extra': 1}, recursive=true) }}"           # merge dicts
      - "{{ groups['web'] | map('extract', hostvars, ['ansible_facts', 'default_ipv4', 'address']) | list }}"   # facts across hosts
      - "{{ services | selectattr('enabled', 'equalto', true) | map(attribute='name') | list }}"
      - "{{ items | rejectattr('state', 'defined') | list }}"
      - "{{ users | dict2items | selectattr('value.shell', 'search', 'bash') | items2dict }}"
      - "{{ '192.0.2.10/24' | ansible.utils.ipaddr('address') }}"        # ansible.utils collection
      - "{{ lookup('ansible.builtin.env', 'HOME') }}"                      # lookups run on the control node
      - "{{ '/etc/nginx/nginx.conf' | basename }} {{ path | dirname }} {{ path | realpath }}"
      - "{{ text | regex_search('version (\\d+\\.\\d+)', '\\1') | first }}"
      - "{{ data | to_nice_yaml(indent=2) }} {{ data | to_json }} {{ raw | from_yaml }}"
      - "{{ secret | password_hash('sha512', 65534 | random(seed=inventory_hostname) | string) }}"   # stable salt per host
      - "{{ 'abc' | b64encode }} {{ list_a | difference(list_b) }} {{ list_a | intersect(list_b) | unique }}"
      - "{{ ansible_date_time.epoch | int | strftime('%Y-%m-%d') }}"
      - "{{ my_var | type_debug }}"                                       # str, int, list, dict, AnsibleUnsafeText

- name: Tests in conditionals
  ansible.builtin.assert:
    that:
      - result is succeeded                       # also failed, changed, skipped
      - job is finished                           # async job
      - version is version('2.19', '>=')          # semantic comparison, not string
      - path is file                              # exists on the control node; also directory, exists, link
      - my_var is defined and my_var is not none
      - hostname is match('^web-\d+$')            # match anchors at start; search does not; regex takes flags
      - value is truthy                           # 'yes', 1, [x]; falsy for '', 0, []
      - item is subset(['a', 'b', 'c'])           # also superset, contains
      - "'web' in group_names"
    fail_msg: "Preconditions failed on {{ inventory_hostname }}"
    quiet: true

- name: Start a long upgrade and move on
  ansible.builtin.command: /opt/my-app/bin/upgrade --all
  async: 3600                                  # kill the job after an hour
  poll: 0                                      # do not wait
  register: upgrade_job

- name: Do other work while it runs
  ansible.builtin.include_tasks: prepare.yml

- name: Wait for the upgrade to finish
  ansible.builtin.async_status:
    jid: "{{ upgrade_job.ansible_job_id }}"
  register: upgrade_result
  until: upgrade_result is finished
  retries: 360                                 # retries x delay must cover the expected runtime
  delay: 10

- name: Remove the job status file
  ansible.builtin.async_status:
    jid: "{{ upgrade_job.ansible_job_id }}"
    mode: cleanup

- name: Run on every host at once, each with a 30 minute budget, waiting in-line
  ansible.builtin.command: /usr/bin/dnf -y upgrade
  async: 1800
  poll: 15                                     # Ansible reconnects every 15 s; the SSH session can drop in between

ansible-vault create group_vars/prod/vault.yml
ansible-vault edit group_vars/prod/vault.yml
ansible-vault encrypt group_vars/prod/vault.yml                  # encrypt an existing plaintext file in place
ansible-vault encrypt_string --stdin-name db_password            # prompts on stdin; keeps the value out of shell history
ansible-playbook site.yml --vault-password-file ~/.config/ansible/vault-pass

ansible-vault encrypt --vault-id prod@prompt group_vars/prod/vault.yml          # header records the id: $ANSIBLE_VAULT;1.2;AES256;prod
ansible-vault encrypt --vault-id dev@~/.config/ansible/dev-pass group_vars/dev/vault.yml
ansible-playbook site.yml --vault-id prod@prompt --vault-id dev@~/.config/ansible/dev-pass
ansible-playbook site.yml --vault-id prod@./get-vault-pass.sh                  # executable: prints the password on stdout
ansible-vault rekey --vault-id prod@prompt --new-vault-id prod@prompt group_vars/prod/vault.yml   # rotate the password
ansible-vault view group_vars/prod/vault.yml                                   # decrypt to stdout without editing
ansible-vault decrypt --output - group_vars/prod/vault.yml | yq '.vault_db_password'   # one value, nothing written to disk

# ansible.cfg in the project directory
[defaults]
inventory = inventory/prod.yml
forks = 25
host_key_checking = True
callback_result_format = yaml
callbacks_enabled = ansible.posix.profile_tasks

[ssh_connection]
pipelining = True
ssh_args = -o ControlMaster=auto -o ControlPersist=60s

# roles/nginx/molecule/default/molecule.yml
dependency:
  name: galaxy
  options: { requirements-file: requirements.yml }
driver:
  name: podman
platforms:
  - name: fedora
    image: registry.fedoraproject.org/fedora:44
    command: /sbin/init                          # systemd inside the container so service: works
    privileged: true
    pre_build_image: true
  - name: rhel9
    image: registry.access.redhat.com/ubi9/ubi-init
    pre_build_image: true
provisioner:
  name: ansible
  inventory:
    group_vars:
      all: { nginx_workers: 2 }
  config_options:
    defaults: { callback_result_format: yaml }
verifier:
  name: ansible                                  # runs verify.yml; testinfra is the alternative
scenario:
  test_sequence: [dependency, syntax, create, converge, idempotence, verify, destroy]

# molecule/default/converge.yml
- name: Converge
  hosts: all
  become: true
  roles: [{ role: nginx }]
---
# molecule/default/verify.yml
- name: Verify
  hosts: all
  gather_facts: false
  tasks:
    - name: nginx answers
      ansible.builtin.uri: { url: http://localhost/, status_code: 200 }

molecule test                          # whole sequence, destroys at the end even on failure
molecule create && molecule converge   # iterate: converge re-applies to the running instance
molecule verify
molecule login -h fedora               # shell into an instance
molecule idempotence                   # fails if a second converge reports changed
molecule destroy
molecule test -s ha                    # another scenario in molecule/ha/
molecule list

# .ansible-lint at the project root
profile: production
exclude_paths: [.cache/, .github/, collections/]
skip_list:
  - package-latest             # state: latest is deliberate in the patching role
warn_list:
  - experimental
  - yaml[line-length]
enable_list:
  - no-log-password            # opt-in rules
  - no-same-owner
offline: true                  # do not install requirements or refresh schemas in CI

ansible-lint                                  # whole project, profile from .ansible-lint
ansible-lint --profile safety roles/nginx     # one path at a stricter or looser profile
ansible-lint --fix                            # apply autofixes (FQCN, key order, yaml formatting); review the diff
ansible-lint -L                               # list rules and their tags
ansible-lint --offline --parseable            # machine-readable path:line: [rule] message, for CI annotations
ansible-lint --generate-ignore                # write .ansible-lint-ignore with every current violation, then burn it down

# Hosts that are not reachable
ansible all -m ansible.builtin.ping -o | grep -v SUCCESS

# OS version per host
ansible all -m ansible.builtin.setup -a 'filter=ansible_distribution*' --tree "$TMPDIR/facts" >/dev/null && jq -r '"\(.ansible_facts.ansible_distribution) \(.ansible_facts.ansible_distribution_version)"' "$TMPDIR"/facts/*

# Package version everywhere
ansible web -m ansible.builtin.command -a 'rpm -q nginx' -o

# Every command or shell task without a guard
grep -rnE 'ansible\.builtin\.(shell|command):' roles/ playbooks/

# Variables one host resolves to
ansible-inventory --host web-01.example.com | jq 'keys'

# Vault files that are not encrypted
grep -L '^\$ANSIBLE_VAULT' group_vars/*/vault.yml

# Vault id every encrypted file expects
for f in group_vars/*/vault.yml; do printf '%s\t%s\n' "$f" "$(head -1 "$f" | cut -d';' -f4)"; done

# Hosts a play would touch, one per line, for review before a production run
ansible-playbook site.yml --limit prod --list-hosts | sed -n '/hosts (/,$p' | tail -n +2 | tr -d ' '

# Tasks that would run for a tag
ansible-playbook site.yml --tags nginx --list-tasks

# Uptime and load across the fleet, one line per host
ansible all -m ansible.builtin.command -a 'uptime' -o | sort

# Reboot required (Fedora/RHEL): non-zero exit means yes
ansible all -m ansible.builtin.command -a 'needs-restarting -r' -o | grep -v 'rc=0'

# Pending updates count per host
ansible all -m ansible.builtin.shell -a 'dnf -q check-update | grep -c . || true' -o

# Free memory in MB per host, sorted
ansible all -m ansible.builtin.setup -a 'filter=ansible_memfree_mb' -o | sed -E 's/^([^ ]+).*"ansible_memfree_mb": ([0-9]+).*/\2\t\1/' | sort -n

# Kernel version distribution
ansible all -m ansible.builtin.command -a 'uname -r' -o | awk '{print $NF}' | sort | uniq -c | sort -rn

# Effective ansible.cfg settings that differ from defaults
ansible-config dump --only-changed

# Which ansible.cfg is in use
ansible --version | grep 'config file'

# Every module a project uses, by FQCN, with counts
grep -rhoE '^\s+[a-z_]+\.[a-z_]+\.[a-z_]+:' roles/ playbooks/ | tr -d ' :' | sort | uniq -c | sort -rn

# Collections required by the project versus installed
diff <(yq -r '.collections[] | .name // .' requirements.yml | sort) <(ansible-galaxy collection list --format json | jq -r '.[] | keys[]' | sort -u)

# Variables defined in defaults/ that no task or template references
for v in $(yq -r 'keys[]' roles/nginx/defaults/main.yml); do grep -rq "$v" roles/nginx/{tasks,templates,handlers,vars} 2>/dev/null || echo "unused: $v"; done

# Role variables not prefixed with the role name (ansible-lint var-naming)
yq -r 'keys[]' roles/nginx/defaults/main.yml | grep -v '^nginx_'

# Run a single role against one host without a playbook
ansible web-01.example.com -m ansible.builtin.include_role -a name=nginx --become

# Template a file locally and print it, using a host's variables
ansible web-01.example.com -m ansible.builtin.template -a 'src=roles/nginx/templates/nginx.conf.j2 dest=/dev/stdout' --check --diff 2>/dev/null | sed -n '/^+++/,$p'

# Evaluate a Jinja expression against real inventory variables
ansible web-01.example.com -m ansible.builtin.debug -a "msg={{ groups['web'] | map('extract', hostvars, 'ansible_host') | list }}"

# Facts for one host saved as JSON for offline querying
ansible web-01.example.com -m ansible.builtin.setup --tree "$TMPDIR/facts" && jq '.ansible_facts | keys' "$TMPDIR/facts/web-01.example.com"

# Diff inventory between two branches without connecting anywhere
diff <(git show main:inventory/prod.yml | ansible-inventory -i /dev/stdin --list 2>/dev/null | jq -S .) <(ansible-inventory -i inventory/prod.yml --list | jq -S .)

# Start a long job everywhere and return immediately (job ids in the output)
ansible all -m ansible.builtin.command -a '/opt/my-app/bin/reindex' -B 3600 -P 0 --become

# Lint only files changed on this branch
git diff --name-only main... -- '*.yml' '*.yaml' | xargs -r ansible-lint

# Time per task for a run, slowest first
ANSIBLE_CALLBACKS_ENABLED=ansible.posix.profile_tasks ansible-playbook site.yml --check 2>&1 | sed -n '/^=====/,$p' | head -20

# Kill a stuck run's leftover async jobs on the targets
ansible all -m ansible.builtin.shell -a 'pkill -f ansible_async_wrapper; rm -rf ~/.ansible_async' --become

#!/usr/bin/env bash
# preflight.sh [limit]: connectivity, interpreter and become check for every host, tab-separated
set -euo pipefail
limit=${1:-all}
tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT

ansible "$limit" -m ansible.builtin.setup -a 'gather_subset=min' --tree "$tmp/facts" >/dev/null 2>&1 || true
ansible "$limit" -m ansible.builtin.command -a 'id -un' --become -o > "$tmp/become.txt" 2>&1 || true

printf 'HOST\tREACHABLE\tPYTHON\tOS\tBECOME\n'
for host in $(ansible "$limit" --list-hosts | tail -n +2 | tr -d ' '); do
  f="$tmp/facts/$host"
  if [ -f "$f" ] && jq -e '.ansible_facts' "$f" >/dev/null 2>&1; then
    reach=yes
    py=$(jq -r '.ansible_facts.ansible_python_version // "?"' "$f")
    os=$(jq -r '"\(.ansible_facts.ansible_distribution // "?") \(.ansible_facts.ansible_distribution_version // "")"' "$f")
  else
    reach=NO py=- os=-
  fi
  if grep -q "^$host | CHANGED.*\"stdout\": \"root\"" "$tmp/become.txt"; then become=ok
  elif grep -q "^$host | " "$tmp/become.txt"; then become=FAIL
  else become=-; fi
  printf '%s\t%s\t%s\t%s\t%s\n' "$host" "$reach" "$py" "$os" "$become"
done | column -t -s $'\t'

#!/usr/bin/env bash
# drift-report.sh PLAYBOOK [ansible-playbook args...]: hosts and tasks that would change under --check
set -euo pipefail
playbook=$1; shift
tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT

ANSIBLE_STDOUT_CALLBACK=ansible.builtin.json ANSIBLE_CALLBACK_RESULT_FORMAT=json \
  ansible-playbook "$playbook" --check --diff "$@" > "$tmp/run.json" || true   # non-zero when hosts are unreachable; still report

jq -r '
  .plays[] as $p
  | $p.tasks[]
  | .task.name as $t
  | .hosts | to_entries[]
  | select(.value.changed == true or .value.failed == true or .value.unreachable == true)
  | "\(.key)\t\(if .value.unreachable then "UNREACHABLE" elif .value.failed then "FAILED" else "would change" end)\t\($p.play.name) / \($t)"
' "$tmp/run.json" | sort > "$tmp/drift.tsv"

if [ ! -s "$tmp/drift.tsv" ]; then echo "no drift: every host matches $playbook"; exit 0; fi
printf 'hosts with drift: %s\n\n' "$(cut -f1 "$tmp/drift.tsv" | sort -u | wc -l)"
column -t -s $'\t' "$tmp/drift.tsv"
exit 2

#!/usr/bin/env python3
"""Rotate one vaulted variable in several vault files without decrypting the others to disk.

Usage: rotate-secret.py vault_db_password group_vars/prod/vault.yml group_vars/dev/vault.yml
Requires ANSIBLE_VAULT_PASSWORD_FILE or a vault_identity_list in ansible.cfg that covers every file.
"""
import secrets
import subprocess
import sys
from pathlib import Path

import yaml

key, *files = sys.argv[1:]
new_value = secrets.token_urlsafe(32)

for f in map(Path, files):
    decrypted = subprocess.run(["ansible-vault", "decrypt", "--output", "-", str(f)], check=True, capture_output=True, text=True).stdout
    data = yaml.safe_load(decrypted) or {}
    if key not in data:
        print(f"{f}: {key} not present, skipping", file=sys.stderr)
        continue
    data[key] = new_value
    vault_id = f.read_text().splitlines()[0].split(";")[3] if f.read_text().count(";") >= 3 else None
    cmd = ["ansible-vault", "encrypt", "--output", str(f)]
    if vault_id:
        cmd += ["--encrypt-vault-id", vault_id]
    subprocess.run(cmd, input=yaml.safe_dump(data, sort_keys=False), check=True, text=True)
    print(f"{f}: rotated {key}" + (f" (vault id {vault_id})" if vault_id else ""))
print("new value written; deploy with ansible-playbook and update the consuming service", file=sys.stderr)