ansible-fundamentals

name: ansible-fundamentals description: > Core principles and golden rules for writing production-quality Ansible automation, covering FQCN requirements, module selection guidance, and execution patterns using uv run. when_to_use: > Use when writing Ansible playbooks, creating Ansible tasks, running ansible-playbook commands, selecting Ansible modules, or working with Ansible collections.

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

Prefer Native Modules

Native modules provide:

• Built-in idempotency (no need for changed_when)
• Better error handling
• Cross-platform compatibility
• Clear documentation

# PREFER native module
- name: Create user
  ansible.builtin.user:
    name: deploy
    groups: docker
    state: present

# AVOID command when module exists
- name: Create user
  ansible.builtin.command: useradd -G docker deploy
  # Requires: changed_when, failed_when, idempotency logic

When Command/Shell is Acceptable

Use command or shell modules when:

1. No native module exists for the operation
2. Interacting with vendor CLI tools (certbot, kubectl, aws)
3. Running one-off scripts

Add proper controls:

- name: Enable Apache module
  ansible.builtin.command: a2enmod {{ module_name }}
  register: mod_result
  changed_when: "'already enabled' not in mod_result.stdout"
  failed_when:
    - mod_result.rc != 0
    - "'already enabled' not in mod_result.stdout"

Collections in Use

This repository uses these Ansible collections:

Installing Collections

# Install from requirements
cd ansible && uv run ansible-galaxy collection install -r requirements.yml

# Install specific collection
uv run ansible-galaxy collection install community.docker

Common Execution Patterns

Running Playbooks

# Basic execution
uv run ansible-playbook playbooks/my-playbook.yml

# With extra variables
uv run ansible-playbook playbooks/create-vm.yml \
  -e "vm_name=docker-01" \
  -e "vm_memory=4096"

# Limit to specific hosts
uv run ansible-playbook playbooks/update.yml --limit proxmox

# Check mode (dry run)
uv run ansible-playbook playbooks/deploy.yml --check --diff

# With tags
uv run ansible-playbook playbooks/setup.yml --tags "network,storage"

Linting

# Run ansible-lint
uv run ansible-lint ansible/playbooks/

Diagnostic Commands

# Check syntax without running
uv run ansible-playbook --syntax-check playbooks/my-playbook.yml

# List hosts in inventory
uv run ansible-inventory --list

# Test connection to all hosts
uv run ansible all -m ping

Task Naming Conventions

Use descriptive names with action verbs:

Examples:

- name: Ensure Docker is installed
- name: Configure SSH security settings
- name: Create admin user account
- name: Deploy application configuration

Secrets Management

Secrets (passwords, API keys, tokens) live in plain YAML files on the local machine or in GitHub Actions secrets — no third-party secrets manager. Keep it simple.

# group_vars/all.yml or host_vars/hostname.yml (gitignored if sensitive)
db_password: 'changeme'
api_key: 'mykey'

Pass GitHub Actions secrets as extra vars at runtime:

uv run ansible-playbook playbooks/deploy.yml -e "db_password={{ secrets.DB_PASSWORD }}"

Always use no_log: true on tasks that reference these values to prevent exposure in logs.

Related Skills

• ansible-idempotency - Detailed changed_when/failed_when patterns
• ansible-error-handling - Block/rescue, retry patterns