Best practices & real-world patterns

The checklist that separates a playbook that works once on your laptop from one a whole team trusts against production.

• Prefer real modules (apt, copy, service) over shell/command — modules give you idempotency and clear change-reporting for free; raw shell gives you neither.
• Structure any non-trivial project as roles from the start — retrofitting later is painful, and roles are barely more setup.
• Keep environment differences in group_vars/<env>, not scattered when conditions throughout tasks.
• Always --check --diff before the first real run against a new or unfamiliar host group.
• Vault anything sensitive — never plain-text secrets in a committed file, even in a "private" repo.
• Pin role and collection versions in requirements.yml — an unpinned upstream role can change behavior under you.
• Use handlers for restarts, not a bare service: state=restarted task — you want restarts triggered by actual change, not on every run.
• Run playbooks through CI against a staging inventory before they ever touch a production one.

# a project layout that scales past one person
inventories/
  staging/hosts.ini
  production/hosts.ini
group_vars/
  staging/vars.yml
  production/vars.yml
  production/vault.yml   # encrypted
roles/
  nginx/
  postgres/
  app/
site.yml
requirements.yml