From ansible-workflows
Provides golden rules for Ansible: uv run execution, FQCN modules, idempotency, shell best practices, sensitive task handling, and module selection guidance. Use for playbooks, tasks, ansible-playbook, or collections.
npx claudepluginhub basher83/lunar-claude --plugin ansible-workflowsThis skill uses the workspace's default tool permissions.
Core principles and golden rules for writing production-quality Ansible automation.
Guides Ansible playbook creation, roles, inventories, project structure, modules, handlers, error handling, and debugging YAML syntax, module failures, variable precedence.
Generates Ansible playbooks, roles, inventories, and configs for server provisioning, app deployment, service configuration, and idempotent automation.
Generates or scaffolds Ansible playbooks, roles, tasks, handlers, inventory, and vars from requests. Handles full projects, snippets, or docs with templates and best practices.
Share bugs, ideas, or general feedback.
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"
mem: 4096
# Lint all Ansible files
mise run ansible-lint
# Run playbook with secrets from Infisical
cd ansible && uv run ansible-playbook playbooks/my-playbook.yml
# Check syntax
uv run ansible-playbook --syntax-check playbooks/my-playbook.yml
# List hosts in inventory
uv run ansible-inventory --list
# Test connection
uv run ansible all -m ping
# BAD
- name: Copy file
copy:
src: file.txt
dest: /tmp/
# GOOD
- name: Copy file
ansible.builtin.copy:
src: file.txt
dest: /tmp/
# BAD - always shows changed, no error handling
- name: Check status
ansible.builtin.command: systemctl status app
# GOOD
- name: Check status
ansible.builtin.command: systemctl status app
register: status_check
changed_when: false
failed_when: false
# BAD - shell not needed
- name: List files
ansible.builtin.shell: ls -la /tmp
# GOOD - command is sufficient
- name: List files
ansible.builtin.command: ls -la /tmp
changed_when: false
# BAD - password in logs
- name: Set password
ansible.builtin.command: set-password {{ password }}
# GOOD
- name: Set password
ansible.builtin.command: set-password {{ password }}
no_log: true