Infrastructure as Codev1.0Updated 2026-03-04Free

Ansible

Agentless automation with playbooks, roles, inventory management, and Vault secrets

Gives Claude Code expertise in Ansible playbook writing, role development, inventory management, module usage, Ansible Vault, variables and templates, and CI/CD integration. Covers common modules for system administration and cloud provisioning.

Use case: Server provisioning, configuration management, application deployment, rolling updates, secret management with Vault, multi-tier orchestration

Download

§ The skill file

name: ansible

description: Use when writing Ansible playbooks, roles, inventory files, or using Ansible modules. Covers playbook structure, common modules, Vault secrets, variables, templates, and role development.

# Ansible Skill

Quick Start

Run a Playbook

bash

ansible-playbook -i inventory.yml playbook.yml
ansible-playbook -i inventory.yml playbook.yml --limit webservers --tags deploy
ansible-playbook -i inventory.yml playbook.yml --check --diff  # Dry run

Ad-hoc Commands

bash

ansible all -i inventory.yml -m ping
ansible webservers -i inventory.yml -m shell -a "uptime"
ansible dbservers -i inventory.yml -m service -a "name=postgresql state=restarted" --become

Inventory File

yaml

# inventory.yml
all:
  children:
    webservers:
      hosts:
        web1: {ansible_host: 10.0.1.10}
        web2: {ansible_host: 10.0.1.11}
      vars:
        http_port: 80
    dbservers:
      hosts:
        db1: {ansible_host: 10.0.2.10}
      vars:
        db_port: 5432
  vars:
    ansible_user: deploy
    ansible_ssh_private_key_file: ~/.ssh/deploy_key

API Reference

Playbook Structure

yaml

---
- name: Configure web servers
  hosts: webservers
  become: true
  vars:
    app_version: "2.1.0"
  tasks:
    - name: Install nginx
      ansible.builtin.apt:
        name: nginx
        state: present
        update_cache: true

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

    - name: Ensure nginx is running
      ansible.builtin.service:
        name: nginx
        state: started
        enabled: true

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

Common Modules

Module	Purpose	Example
`apt` / `yum` / `dnf`	Package management	`apt: name=nginx state=present`
`service` / `systemd`	Service management	`service: name=nginx state=started`
`copy`	Copy files to remote	`copy: src=app.conf dest=/etc/app.conf`
`template`	Jinja2 template rendering	`template: src=app.conf.j2 dest=/etc/app.conf`
`file`	File/directory permissions	`file: path=/data state=directory mode=0755`
`user`	User management	`user: name=deploy groups=sudo shell=/bin/bash`
`command` / `shell`	Run commands	`command: /opt/app/deploy.sh`
`git`	Clone/pull repos	`git: repo=https://... dest=/opt/app version=main`
`docker_container`	Docker management	`docker_container: name=web image=myapp:v1`
`uri`	HTTP requests	`uri: url=http://localhost/health`
`cron`	Cron jobs	`cron: name="backup" hour=2 job="/opt/backup.sh"`
`lineinfile`	Edit single line in file	`lineinfile: path=/etc/ssh/sshd_config regexp='^PermitRoot' line='PermitRootLogin no'`

Role Structure

roles/
  nginx/
    tasks/main.yml       # Task list
    handlers/main.yml    # Handlers (notify targets)
    templates/           # Jinja2 templates
    files/               # Static files
    vars/main.yml        # Role variables (high priority)
    defaults/main.yml    # Default variables (lowest priority)
    meta/main.yml        # Dependencies, metadata

Use a role:

yaml

- hosts: webservers
  roles:
    - role: nginx
      vars:
        nginx_port: 8080
    - role: app-deploy

Common Patterns

Ansible Vault (Secrets)

bash

# Encrypt a file
ansible-vault encrypt vars/secrets.yml

# Edit encrypted file
ansible-vault edit vars/secrets.yml

# Run playbook with vault password
ansible-playbook -i inventory.yml playbook.yml --ask-vault-pass
ansible-playbook -i inventory.yml playbook.yml --vault-password-file=~/.vault_pass

# Encrypt single value
ansible-vault encrypt_string 'my-secret-password' --name 'db_password'

In playbook:

yaml

vars_files:
  - vars/secrets.yml  # Encrypted file, auto-decrypted at runtime

Conditionals and Loops

yaml

# Conditional
- name: Install packages (Debian only)
  apt: name={{ item }} state=present
  loop: [nginx, curl, htop]
  when: ansible_os_family == "Debian"

# Loop with dict
- name: Create users
  user:
    name: "{{ item.name }}"
    groups: "{{ item.groups }}"
    state: present
  loop:
    - {name: deploy, groups: sudo}
    - {name: monitor, groups: docker}

# Register and check result
- name: Check if app is running
  command: systemctl is-active myapp
  register: app_status
  ignore_errors: true

- name: Start app if not running
  service: name=myapp state=started
  when: app_status.rc != 0

Rolling Updates

yaml

- hosts: webservers
  serial: 1            # One server at a time
  max_fail_percentage: 0  # Stop on any failure
  pre_tasks:
    - name: Remove from load balancer
      uri:
        url: "https://lb.example.com/api/servers/{{ inventory_hostname }}"
        method: DELETE
  roles:
    - app-deploy
  post_tasks:
    - name: Add back to load balancer
      uri:
        url: "https://lb.example.com/api/servers"
        method: POST
        body_format: json
        body: {host: "{{ inventory_hostname }}"}
    - name: Wait for health check
      uri:
        url: "http://{{ inventory_hostname }}:{{ http_port }}/health"
        status_code: 200
      retries: 10
      delay: 5

Best Practices

Idempotency: Every task should be safe to run multiple times. Use state: present not raw commands. Avoid command/shell when a module exists.
Roles over monolithic playbooks: Break playbooks into reusable roles. One role per service (nginx, postgresql, app-deploy). Share via Ansible Galaxy or internal repos.
Vault for secrets: Never commit plaintext secrets. Use Ansible Vault for passwords, API keys, and certificates. Store vault password in CI/CD secret manager.
Variable precedence: Understand the 22 levels of precedence. Use defaults/ for overridable defaults, vars/ for role internals, group_vars/ for environment-specific values.
Tags: Tag tasks for selective execution: ansible-playbook ... --tags deploy. Common tags: install, configure, deploy, security.
Check mode: Always test with --check --diff first. Shows what would change without making changes.
Handlers: Use handlers for service restarts triggered by config changes. Handlers run once at the end, even if notified multiple times.

§ Sources

https://docs.ansible.com/ansible/latest/ ↗https://docs.ansible.com/ansible/latest/collections/ansible/builtin/ ↗https://docs.ansible.com/ansible/latest/playbook_guide/ ↗https://docs.ansible.com/ansible/latest/vault_guide/ ↗