This skill should be used when writing Ansible playbooks, creating Ansible tasks, running ansible-playbook commands, selecting Ansible modules, or working with Ansible collections. Provides golden rules, FQCN requirements, module selection guidance, and execution patterns using uv run.
Core principles and golden rules for writing production-quality Ansible automation.
These rules apply to ALL Ansible code in this repository:
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
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
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
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
Tag sensitive tasks - Use no_log: true for secrets:
- name: Set database password
ansible.builtin.command: set-password {{ db_password }}
no_log: true
Idempotency first - Check before create, verify after.
Descriptive task names - Start with action verbs (Ensure, Configure, Install, Create).
| Need | Use | Why |
|---|---|---|
| Install packages | ansible.builtin.apt/yum/dnf | Native modules handle state |
| Manage files | ansible.builtin.copy/template/file | Idempotent by default |
| Edit config lines | ansible.builtin.lineinfile | Surgical edits, not full replace |
| Run commands | ansible.builtin.command | When no native module exists |
| Need shell features | ansible.builtin.shell | Pipes, redirects, globs |
| Manage services | ansible.builtin.systemd/service | State management built-in |
| Manage users | ansible.builtin.user | Cross-platform, idempotent |
Native modules provide:
changed_when)# 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
Use command or shell modules when:
Add proper controls:
- name: Create Proxmox API token
ansible.builtin.command: >
pveum user token add {{ username }}@pam {{ token_name }}
register: token_result
changed_when: "'already exists' not in token_result.stderr"
failed_when:
- token_result.rc != 0
- "'already exists' not in token_result.stderr"
no_log: true
This repository uses these Ansible collections:
| Collection | Purpose | Example Modules |
|---|---|---|
ansible.builtin | Core functionality | copy, template, command, user |
ansible.posix | POSIX systems | authorized_key, synchronize |
community.general | General utilities | interfaces_file, ini_file |
community.proxmox | Proxmox VE | proxmox_vm, proxmox_kvm |
infisical.vault | Secrets management | read_secrets |
community.docker | Docker management | docker_container, docker_image |
# Install from requirements
cd ansible && uv run ansible-galaxy collection install -r requirements.yml
# Install specific collection
uv run ansible-galaxy collection install community.proxmox
# 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"
# Run ansible-lint
mise run ansible-lint
# Or directly
uv run ansible-lint ansible/playbooks/
Use descriptive names with action verbs:
| Verb | Use When |
|---|---|
| Ensure | Verifying state exists |
| Configure | Modifying settings |
| Install | Adding packages |
| Create | Making new resources |
| Remove | Deleting resources |
| Deploy | Releasing applications |
| Update | Modifying existing resources |
Examples:
- name: Ensure Docker is installed
- name: Configure SSH security settings
- name: Create admin user account
- name: Deploy application configuration
Use snake_case with descriptive names:
# GOOD - clear, descriptive
proxmox_api_user: terraform@pam
docker_compose_version: "2.24.0"
vm_memory_mb: 4096
# BAD - vague, abbreviated
pve_usr: terraform@pam
dc_ver: "2.24.0"