---
name: ansible-role-design
description: >
  Production-grade Ansible role structure patterns for directory layout, variable
  organization (defaults vs vars), handlers, and task organization, derived from
  analysis of 7 geerlingguy production roles.
when_to_use: >
  Use when creating Ansible roles, designing role directory structure, organizing role
  variables in defaults vs vars, writing role handlers, or structuring role tasks.
---

# Ansible Role Design

Production-grade role structure patterns derived from analysis of 7 geerlingguy roles.

## Standard Directory Structure

Every Ansible role follows this organizational pattern:

```text
role-name/
├── defaults/
│   └── main.yml          # User-configurable defaults (lowest precedence)
├── vars/
│   ├── Debian.yml        # OS-specific internal values
│   └── RedHat.yml
├── tasks/
│   ├── main.yml          # Task router
│   ├── install.yml       # Feature-specific tasks
│   └── configure.yml
├── handlers/
│   └── main.yml          # Event-triggered tasks
├── templates/
│   └── config.conf.j2    # Jinja2 templates
├── files/
│   └── static-file.txt   # Static files
├── meta/
│   └── main.yml          # Role metadata, dependencies
└── README.md             # Documentation
```

### Directory Purposes

| Directory | Purpose | Precedence |
|-----------|---------|------------|
| `defaults/` | User-overridable values | Lowest |
| `vars/` | Internal/OS-specific values | High |
| `tasks/` | Ansible tasks | N/A |
| `handlers/` | Service restarts, reloads | N/A |
| `templates/` | Jinja2 config files | N/A |
| `files/` | Static files to copy | N/A |
| `meta/` | Galaxy info, dependencies | N/A |

### When to Omit Directories

Only create directories that are actually needed:

- **Omit `templates/`** if using only `lineinfile` or `copy`
- **Omit `handlers/`** if role doesn't manage services
- **Omit `vars/`** if no OS-specific differences
- **Omit `files/`** if no static files to copy

## Task Organization

### Main Task File as Router

Use `tasks/main.yml` as a routing file that includes feature-specific files:

```yaml
# tasks/main.yml
---
- name: Include OS-specific variables
  ansible.builtin.include_vars: "{{ ansible_os_family }}.yml"

- name: Install packages
  ansible.builtin.include_tasks: install.yml

- name: Configure service
  ansible.builtin.include_tasks: configure.yml

- name: Setup users
  ansible.builtin.include_tasks: users.yml
  when: role_users | length > 0
```

### When to Split Tasks

| Scenario | Approach |
|----------|----------|
| < 30 lines | Keep in main.yml |
| 30-100 lines | Consider splitting |
| > 100 lines | Definitely split |
| Optional features | Separate file with `when:` |
| OS-specific logic | Separate files per OS |

### Task File Naming

Use descriptive, feature-based names:

```text
tasks/
├── main.yml              # Router only
├── install.yml           # Package installation
├── configure.yml         # Configuration tasks
├── users.yml             # User management
├── install-Debian.yml    # Debian-specific install
└── install-RedHat.yml    # RedHat-specific install
```

## Variable Organization

### defaults/ vs vars/

| Location | Purpose | User Override? |
|----------|---------|----------------|
| `defaults/main.yml` | User configuration | Yes (easily) |
| `vars/main.yml` | Internal constants | Possible but discouraged |
| `vars/Debian.yml` | OS-specific values | No (internal) |

### defaults/main.yml Example

```yaml
# defaults/main.yml
---
# User-configurable options
docker_edition: "ce"
docker_service_state: started
docker_service_enabled: true
docker_users: []

# Feature toggles
docker_install_compose: true
docker_compose_version: "2.24.0"
```

### vars/Debian.yml Example

```yaml
# vars/Debian.yml
---
# OS-specific internal values (not for user override)
docker_package_name: docker-ce
docker_service_name: docker
docker_config_path: /etc/docker/daemon.json
```

### Loading OS-Specific Variables

Simple pattern:

```yaml
- name: Include OS-specific variables
  ansible.builtin.include_vars: "{{ ansible_os_family }}.yml"
```

Advanced pattern with fallback:

```yaml
- name: Load OS-specific vars
  ansible.builtin.include_vars: "{{ lookup('first_found', params) }}"
  vars:
    params:
      files:
        - "{{ ansible_distribution }}.yml"
        - "{{ ansible_os_family }}.yml"
        - main.yml
      paths:
        - vars
```

## Variable Naming Convention

Prefix variables with role name:

```yaml
# Pattern: {role_name}_{feature}_{attribute}

# Examples
docker_edition: "ce"
docker_service_state: started
docker_compose_version: "2.24.0"
docker_users: []

# Grouped by feature
security_ssh_port: 22
security_ssh_password_auth: "no"
security_fail2ban_enabled: true
```

### Benefits

- Prevents conflicts with other roles
- Clear ownership of variables
- Easy to grep across codebase
- Self-documenting

## Handler Patterns

### Simple Handler Definitions

```yaml
# handlers/main.yml
---
- name: restart docker
  ansible.builtin.systemd:
    name: docker
    state: restarted

- name: reload nginx
  ansible.builtin.systemd:
    name: nginx
    state: reloaded
```

### Handler Naming

Use lowercase with action + service pattern:

```yaml
- name: restart ssh      # Not "Restart SSH Service"
- name: reload nginx     # Not "Reload Nginx Config"
- name: reload systemd   # For daemon-reload
```

### Throttled Handlers

For cluster operations, restart one node at a time:

```yaml
- name: restart pve-cluster
  ansible.builtin.systemd:
    name: pve-cluster
    state: restarted
  throttle: 1
```

## Template Organization

### When to Use Templates

Use `templates/` when:

- Configuration has conditional content
- Need variable substitution
- Complex multi-line configuration
- Users may need to extend/override

Use `lineinfile` when:

- Simple single-line changes
- Modifying existing system files

### Template Variables

Expose template paths as variables for user override:

```yaml
# defaults/main.yml
nginx_conf_template: nginx.conf.j2
nginx_vhost_template: vhost.j2
```

```yaml
# tasks/configure.yml
- name: Deploy nginx config
  ansible.builtin.template:
    src: "{{ nginx_conf_template }}"
    dest: /etc/nginx/nginx.conf
  notify: reload nginx
```

## Meta Configuration

### meta/main.yml Structure

```yaml
# meta/main.yml
---
galaxy_info:
  author: your_name
  description: Role description
  license: MIT
  min_ansible_version: "2.12"
  platforms:
    - name: Debian
      versions:
        - bullseye
        - bookworm
    - name: Ubuntu
      versions:
        - focal
        - jammy

dependencies:
  - role: common
  - role: geerlingguy.docker
    when: install_docker | default(false)
```

## Role Complexity Scaling

Based on geerlingguy role analysis:

| Role Complexity | Directories | Task Files | Examples |
|-----------------|-------------|------------|----------|
| Minimal | 3-4 | 1 (main.yml) | pip, git |
| Standard | 5-6 | 2-4 | security, docker |
| Complex | 7+ | 5-8 | postgresql, nginx |

### Minimal Role

```text
pip/
├── defaults/main.yml
├── tasks/main.yml
├── meta/main.yml
└── README.md
```

### Standard Role

```text
docker/
├── defaults/main.yml
├── vars/{Debian,RedHat}.yml
├── tasks/{main,install,configure}.yml
├── handlers/main.yml
├── meta/main.yml
└── README.md
```

### Complex Role

```text
postgresql/
├── defaults/main.yml
├── vars/{Debian,RedHat,Archlinux}.yml
├── tasks/{main,install,configure,users,databases}.yml
├── handlers/main.yml
├── templates/{postgresql.conf,pg_hba.conf}.j2
├── meta/main.yml
└── README.md
```

## Task Naming Convention

Start task names with action verbs:

```yaml
# GOOD
- name: Ensure Docker is installed
- name: Configure SSH security settings
- name: Add user to docker group

# BAD
- name: Docker installation
- name: SSH settings
- name: User docker group
```

## File Validation

Validate critical configuration files:

```yaml
- name: Update SSH configuration
  ansible.builtin.lineinfile:
    path: /etc/ssh/sshd_config
    regexp: "^PermitRootLogin"
    line: "PermitRootLogin no"
    validate: 'sshd -T -f %s'
  notify: restart ssh

- name: Update sudoers
  ansible.builtin.lineinfile:
    path: /etc/sudoers
    line: "{{ user }} ALL=(ALL) NOPASSWD: ALL"
    validate: 'visudo -cf %s'
```

## Documentation

Every role needs a README.md with:

1. **Description** - What the role does
2. **Requirements** - Prerequisites
3. **Role Variables** - All variables with defaults
4. **Dependencies** - Other roles needed
5. **Example Playbook** - How to use it

## Additional Resources

For detailed role design patterns and techniques, consult:

- **`references/role-structure-standards.md`** - Production role structure patterns from geerlingguy analysis
- **`references/handler-best-practices.md`** - Handler design, notification patterns, flush strategies
- **`references/meta-dependencies.md`** - Role dependencies, Galaxy metadata, platform support
- **`references/variable-management-patterns.md`** - Variable naming, scoping, precedence patterns
- **`references/documentation-templates.md`** - README templates and documentation standards

## Related Skills

- **ansible-playbook-design** - When to use roles vs playbooks
- **ansible-fundamentals** - Module selection and naming
- **ansible-testing** - Role testing with molecule