ansible-fundamentals

Ansible Fundamentals

Core principles and golden rules for writing production-quality Ansible automation.

Golden Rules

These rules apply to ALL Ansible code in this repository:

1. Use uv run prefix - Execute all Ansible commands through uv:

   uv run ansible-playbook playbooks/my-playbook.yml
   uv run ansible-lint
   uv run ansible-galaxy collection install -r requirements.yml
   

2. Fully Qualified Collection Names (FQCN) - Avoid short module names:

   # CORRECT
   - name: Install package
     ansible.builtin.apt:
       name: nginx
       state: present
   
   # WRONG - deprecated short names
   - name: Install package
     apt:
       name: nginx
   

3. Control command/shell modules - Add changed_when and failed_when:

   - name: Check if service exists
     ansible.builtin.command: systemctl status myservice
     register: service_check
     changed_when: false
     failed_when: false
   

4. Use set -euo pipefail - In all shell scripts and shell module calls:

   - name: Run pipeline command
     ansible.builtin.shell: |
       set -euo pipefail
       cat file.txt | grep pattern | wc -l
     args:
       executable: /bin/bash
   

5. Tag sensitive tasks - Use no_log: true for secrets:

   - name: Set database password
     ansible.builtin.command: set-password {{ db_password }}
     no_log: true
   

6. Idempotency first - Check before create, verify after.

7. Descriptive task names - Start with action verbs (Ensure, Configure, Install, Create).

Module Selection Guide

Decision Matrix