Ansible Role

You are an Ansible automation engineer. The user wants to create a reusable Ansible role with proper directory structure, default variables, and event handlers.

What to check first

• Run ansible --version to confirm Ansible is installed
• Verify the target directory where you'll create the role (typically roles/ in your playbook project)
• Check if you have an existing ansible.cfg or will use default role search paths

Steps

1. Create the role directory structure using ansible-galaxy init role_name — this generates all subdirectories (tasks, handlers, defaults, vars, templates, files, meta)
2. Define role metadata in meta/main.yml with galaxy_info (author, description, license) and dependencies for any roles this one requires
3. Write default variables in defaults/main.yml — these are lowest priority and intended to be overridden by users of your role
4. Create task definitions in tasks/main.yml with the main entry point using include_tasks or import_tasks for modular organization
5. Define handlers in handlers/main.yml — these listen for notify calls from tasks and typically restart services or reload configurations
6. Add handler triggers in tasks using the notify key, specifying exact handler names that must match handler definitions
7. Place static files in files/ directory and reference with copy module using src: parameter (no leading slash for relative paths)
8. Store Jinja2 templates in templates/ directory and deploy with template module; use src: with .j2 extension

Code

# roles/webserver/meta/main.yml
---
galaxy_info:
  author: DevOps Team
  description: Configure nginx web servers
  license: MIT
  min_ansible_version: 2.9
  platforms:
    - name: Ubuntu
      versions:
        - focal
        - jammy
  galaxy_tags:
    - webserver
    - nginx

dependencies: []

# roles/webserver/defaults/main.yml
---
nginx_port: 80
nginx_user: www-data
nginx_worker_processes: auto
nginx_max_clients: 1024
nginx_enable_ssl: false
ssl_certificate_path: /etc/ssl/certs/server.crt
ssl_key_path: /etc/ssl/private/server.key

# roles/webserver/tasks/main.yml
---
- name: Update package cache
  apt:
    update_cache: yes
    cache_valid_time: 3600
  when: ansible_os_family == "Debian"

- name: Install nginx
  package:
    name: nginx
    state: present
  notify: restart nginx

- name: Deploy nginx configuration
  template:
    src: nginx.conf.j2
    dest: /etc/nginx/nginx.conf
    owner: root
    group: root
    mode: '0644'
  notify: reload nginx

- name

Note: this example was truncated in the source. See the GitHub repo for the latest full version.

Common Pitfalls

• Treating this skill as a one-shot solution — most workflows need iteration and verification
• Skipping the verification steps — you don't know it worked until you measure
• Applying this skill without understanding the underlying problem — read the related docs first

When NOT to Use This Skill

• When a simpler manual approach would take less than 10 minutes
• On critical production systems without testing in staging first
• When you don't have permission or authorization to make these changes

How to Verify It Worked

• Run the verification steps documented above
• Compare the output against your expected baseline
• Check logs for any warnings or errors — silent failures are the worst kind

Production Considerations

• Test in staging before deploying to production
• Have a rollback plan — every change should be reversible
• Monitor the affected systems for at least 24 hours after the change