Ansible Best Practices

The most common mistake in growing Ansible codebases is writing one giant playbook with dozens of tasks instead of decomposing work into roles. A role is a self-contained directory structure (tasks, handlers, templates, files, vars, defaults) that packages a single responsibility, like 'nginx' or 'postgresql', and can be reused across playbooks and even shared publicly via Ansible Galaxy. Following the standard roles/<role_name>/{tasks,handlers,templates,files,vars,defaults}/main.yml layout means anyone opening the repo for the first time immediately understands where to look for a given piece of configuration.

Idempotency means running a playbook twice produces the same end state as running it once, with the second run reporting no changes if nothing needs to change. Ansible's built-in modules like apt, service, and template are idempotent by design, but the moment you reach for the shell or command module to run an arbitrary script, you lose that guarantee unless you explicitly add a creates, removes, or changed_when condition. Best practice is to always prefer a purpose-built module over shell/command whenever one exists, because idempotent tasks make playbooks safe to re-run in production without fear of duplicating work or causing unintended side effects.

Never commit plaintext passwords, API keys, or TLS private keys into a playbook or inventory file. Ansible Vault encrypts sensitive variables or entire files using AES256, and encrypted content can live safely in the same Git repository as the rest of your automation. Best practice is to keep a single vault.yml per environment (e.g. group_vars/production/vault.yml), reference vault variables indirectly from a separate plaintext vars.yml using a naming convention like vault_db_password, and store the vault password itself in a secrets manager or CI secret store rather than a file checked into version control.

Run ansible-lint on every playbook to catch style issues and known anti-patterns (like using shell when a module exists, or missing become: true where privilege escalation is needed) before they reach a pull request. Tag tasks and roles meaningfully (--tags deploy, --tags config) so operators can run a narrow slice of a large playbook without executing everything, and use --check (dry-run) combined with --diff to preview exactly what would change against a live system before applying it for real. For genuine pre-deployment testing, tools like Molecule spin up disposable Docker containers to verify a role converges correctly and stays idempotent on a second run.