gh-poindexter12-waypoint-technologies/skills/ansible/SKILL.md

name, description

name

description

ansible

Ansible automation reference for playbooks, roles, inventory, variables, and modules. Includes Proxmox VE and Docker integration via community.general and community.docker collections. Use when writing playbooks, troubleshooting Ansible runs, or designing automation workflows. Triggers: ansible, playbook, inventory, role, task, handler, vars, jinja2, galaxy, proxmox_kvm, proxmox_lxc, docker_container, docker_compose.

Ansible Skill

Ansible automation reference for configuration management and application deployment.

Quick Reference

# Test connectivity
ansible all -m ping
ansible <group> -m ping

# Run playbook
ansible-playbook playbook.yml
ansible-playbook playbook.yml -l <host>    # Limit to host
ansible-playbook playbook.yml --check      # Dry-run
ansible-playbook playbook.yml -vvv         # Verbose

# Tags
ansible-playbook playbook.yml --tags "deploy"
ansible-playbook playbook.yml --skip-tags "backup"
ansible-playbook playbook.yml --list-tags

# Variables
ansible-playbook playbook.yml -e "var=value"
ansible-playbook playbook.yml -e "@vars.yml"

# Ad-hoc commands
ansible <group> -m shell -a "command"
ansible <group> -m copy -a "src=file dest=/path"
ansible <group> -m apt -a "name=package state=present"

# Galaxy
ansible-galaxy collection install -r requirements.yml
ansible-galaxy role install <role>

Reference Files

Load on-demand based on task:

Topic	File	When to Load
Playbook Structure	playbooks.md	Writing playbooks
Inventory	inventory.md	Host/group configuration
Variables	variables.md	Variable precedence, facts
Modules	modules.md	Common module reference
Troubleshooting	troubleshooting.md	Common errors, debugging

Proxmox Integration

Topic	File	When to Load
Proxmox Modules	proxmox/modules.md	VM/LXC management via API
Proxmox Auth	proxmox/authentication.md	API tokens, credentials
Proxmox Gotchas	proxmox/gotchas.md	Common issues, workarounds
Dynamic Inventory	proxmox/dynamic-inventory.md	Auto-discover VMs/containers

Docker Integration

Topic	File	When to Load
Docker Deployment	docker/deployment.md	Containers, images, networks, volumes
Compose Patterns	docker/compose-patterns.md	Roles, templates, multi-service stacks
Docker Troubleshooting	docker/troubleshooting.md	Common errors, debugging

Playbook Quick Reference

---
- name: Deploy application
  hosts: webservers
  become: true
  vars:
    app_port: 8080

  pre_tasks:
    - name: Validate requirements
      ansible.builtin.assert:
        that:
          - app_secret is defined

  tasks:
    - name: Install packages
      ansible.builtin.apt:
        name: "{{ item }}"
        state: present
      loop:
        - nginx
        - python3

    - name: Deploy config
      ansible.builtin.template:
        src: app.conf.j2
        dest: /etc/app/app.conf
      notify: Restart app

  handlers:
    - name: Restart app
      ansible.builtin.service:
        name: app
        state: restarted

  post_tasks:
    - name: Verify deployment
      ansible.builtin.uri:
        url: "http://localhost:{{ app_port }}/health"

Variable Precedence (High to Low)

1. Extra vars (-e "var=value")
2. Task vars
3. Block vars
4. Role/include vars
5. Play vars
6. Host facts
7. host_vars/
8. group_vars/
9. Role defaults

Directory Structure

ansible/
├── ansible.cfg          # Configuration
├── inventory/
│   └── hosts.yml        # Inventory
├── group_vars/
│   ├── all.yml          # All hosts
│   └── webservers.yml   # Group-specific
├── host_vars/
│   └── server1.yml      # Host-specific
├── roles/
│   └── app/
│       ├── tasks/
│       ├── handlers/
│       ├── templates/
│       ├── files/
│       └── defaults/
├── playbooks/
│   └── deploy.yml
├── templates/
│   └── config.j2
└── requirements.yml     # Galaxy dependencies

Idempotency Checklist

• Tasks produce same result on repeated runs
• No changed_when: true unless necessary
• Use state: present/absent not shell commands
• Check mode (--check) shows accurate changes
• Second run shows all "ok" (no changes)