Agent-Skills.md

Agent Skills: Ansible Workflow

Ansible automation workflow guidelines. Activate when working with Ansible playbooks, ansible-playbook, inventory files (.yml, .ini), or Ansible-specific patterns.

UncategorizedID: ilude/claude-code-config/ansible-workflow
5

Skill Files

Browse the full folder contents for ansible-workflow.

Download Skill

Loading file tree…

skills/ansible-workflow/SKILL.md

Skill Metadata

Name
ansible-workflow
Description
Ansible automation workflow guidelines. Activate when working with Ansible playbooks, ansible-playbook, inventory files (.yml, .ini), or Ansible-specific patterns.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Ansible Workflow

Tool Grid

| Task | Tool | Command | |------|------|---------| | Lint | ansible-lint | ansible-lint | | YAML lint | yamllint | yamllint . | | Syntax check | ansible | ansible-playbook --syntax-check | | Dry run | ansible | ansible-playbook --check | | Run | ansible | ansible-playbook playbook.yml | | Test roles | molecule | molecule test | | Encrypt | sops | sops -e secrets.yml | | Decrypt | sops | sops -d secrets.yml |

Runtime Requirements

  • Ansible Core 2.18+ with Python 3.12+
  • ansible-lint and yamllint installed
  • SOPS for secrets management (RECOMMENDED over ansible-vault for GitOps)
  • Molecule + docker driver for role testing

Code Standards

FQCN Requirement

All module names MUST use Fully Qualified Collection Names (FQCN):

# CORRECT
- name: Copy configuration file
  ansible.builtin.copy:
    src: app.conf
    dest: /etc/app/app.conf

# INCORRECT - DO NOT USE
- name: Copy configuration file
  copy:
    src: app.conf
    dest: /etc/app/app.conf

Linting

All playbooks and roles MUST pass linting before commit:

# Run both linters
ansible-lint && yamllint .

Configuration templates available in assets/:

  • .ansible-lint.template - Production profile with strict mode
  • .yamllint.template - YAML linting with 120 char lines

Sensitive Data

Tasks handling sensitive data MUST use no_log: true:

- name: Set database password
  ansible.builtin.shell: |
    mysql -u root -p'{{ db_root_password }}' -e "SET PASSWORD..."
  no_log: true

- name: Create API token
  ansible.builtin.uri:
    url: "{{ api_endpoint }}/tokens"
    headers:
      Authorization: "Bearer {{ admin_token }}"
  no_log: true
  register: token_result

Secrets Management

SOPS (RECOMMENDED for GitOps)

SOPS is RECOMMENDED over ansible-vault for GitOps workflows:

# .sops.yaml
creation_rules:
  - path_regex: .*vars/secrets\.yml$
    age: age1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Encrypt
sops -e vars/secrets.yml > vars/secrets.enc.yml

# Decrypt inline during playbook
sops -d vars/secrets.enc.yml | ansible-playbook -e @/dev/stdin playbook.yml

ansible-vault (Legacy)

When ansible-vault is required:

# Encrypt variable file
ansible-vault encrypt group_vars/prod/vault.yml

# Run with vault
ansible-playbook --ask-vault-pass playbook.yml

Project Structure

Environment-Based Inventory

inventories/
├── prod/
│   ├── hosts.yml
│   ├── group_vars/
│   │   ├── all.yml
│   │   ├── webservers.yml
│   │   └── databases.yml
│   └── host_vars/
├── staging/
│   ├── hosts.yml
│   └── group_vars/
└── dev/
    ├── hosts.yml
    └── group_vars/

group_vars Organization

Organize group_vars by role name for clarity:

group_vars/
├── all/
│   ├── main.yml          # Common variables
│   └── secrets.enc.yml   # SOPS-encrypted secrets
├── webservers/
│   ├── nginx.yml         # Role: nginx
│   └── ssl.yml           # Role: ssl_certificates
└── databases/
    ├── postgresql.yml    # Role: postgresql
    └── backup.yml        # Role: db_backup

Role Structure

Roles SHOULD be single-purpose:

roles/
├── nginx/                # Web server only
├── ssl_certificates/     # SSL management only
├── postgresql/           # Database only
└── app_deploy/           # Application deployment only

Dynamic Inventories

AWS EC2

# inventories/aws/aws_ec2.yml
plugin: amazon.aws.aws_ec2
regions:
  - us-east-1
  - us-west-2
keyed_groups:
  - key: tags.Environment
    prefix: env
  - key: tags.Role
    prefix: role
filters:
  instance-state-name: running
hostnames:
  - private-ip-address
compose:
  ansible_host: private_ip_address

Azure RM

# inventories/azure/azure_rm.yml
plugin: azure.azcollection.azure_rm
auth_source: auto
include_vm_resource_groups:
  - production-rg
  - staging-rg
keyed_groups:
  - key: tags.Environment
    prefix: env
hostnames:
  - private_ipv4_addresses

GCP Compute

# inventories/gcp/gcp_compute.yml
plugin: google.cloud.gcp_compute
projects:
  - my-project-id
zones:
  - us-central1-a
  - us-central1-b
keyed_groups:
  - key: labels.environment
    prefix: env
hostnames:
  - private_ip

Handler Patterns

Proper Handler Usage

# tasks/main.yml
- name: Update nginx configuration
  ansible.builtin.template:
    src: nginx.conf.j2
    dest: /etc/nginx/nginx.conf
  notify: Restart nginx

- name: Update SSL certificate
  ansible.builtin.copy:
    src: "{{ ssl_cert_file }}"
    dest: /etc/nginx/ssl/cert.pem
  notify:
    - Validate nginx config
    - Reload nginx

# handlers/main.yml
- name: Validate nginx config
  ansible.builtin.command: nginx -t
  changed_when: false

- name: Reload nginx
  ansible.builtin.systemd:
    name: nginx
    state: reloaded

- name: Restart nginx
  ansible.builtin.systemd:
    name: nginx
    state: restarted

Handler Execution Order

Handlers execute in definition order, not notification order. Define handlers in logical sequence (validate -> reload -> restart).

Variable Precedence

Ansible variable precedence (highest to lowest):

  1. Extra vars (-e "var=value")
  2. Task vars (in task definition)
  3. Block vars
  4. Role and include vars
  5. Set facts / registered vars
  6. Play vars_files
  7. Play vars
  8. Host facts
  9. Playbook host_vars
  10. Inventory host_vars
  11. Playbook group_vars
  12. Inventory group_vars
  13. Role defaults

Best Practices

# Use role defaults for safe defaults
# roles/nginx/defaults/main.yml
nginx_worker_processes: auto
nginx_worker_connections: 1024

# Use group_vars for environment-specific overrides
# group_vars/prod/nginx.yml
nginx_worker_connections: 4096

# Use extra vars for one-time overrides only
ansible-playbook playbook.yml -e "nginx_worker_connections=8192"

Molecule Testing

Role Testing Setup

# roles/nginx/molecule/default/molecule.yml
dependency:
  name: galaxy
driver:
  name: docker
platforms:
  - name: instance
    image: geerlingguy/docker-${MOLECULE_DISTRO:-rockylinux9}-ansible
    pre_build_image: true
    privileged: true
    command: /usr/sbin/init
provisioner:
  name: ansible
verifier:
  name: ansible

Running Tests

molecule test              # Full test cycle
molecule converge          # Apply role
molecule verify            # Run verification
molecule destroy           # Cleanup

Performance Optimization

ansible.cfg Settings

Use the template at assets/ansible.cfg.template:

  • forks = 20 - Parallel execution
  • pipelining = True - Reduce SSH operations
  • gathering = smart - Cache facts
  • fact_caching = jsonfile - Persist facts

Task Optimization

# Use async for long-running tasks
- name: Upgrade all packages
  ansible.builtin.dnf:
    name: "*"
    state: latest
  async: 600
  poll: 10

# Use free strategy for independent tasks
- hosts: all
  strategy: free
  tasks:
    - name: Independent task 1
      ansible.builtin.command: /opt/script1.sh
    - name: Independent task 2
      ansible.builtin.command: /opt/script2.sh

Pre-Commit Checklist

Before committing Ansible code:

  1. [ ] ansible-lint passes with no warnings
  2. [ ] yamllint . passes
  3. [ ] ansible-playbook --syntax-check passes
  4. [ ] All modules use FQCN
  5. [ ] Sensitive tasks have no_log: true
  6. [ ] Secrets encrypted with SOPS (or vault)
  7. [ ] Molecule tests pass for modified roles
  8. [ ] Variables documented in role README