role-builder

Role Builder

Quick Start

Create well-structured Ansible roles with proper organization, reusability, and idempotency.

Instructions

Step 1: Initialize role structure

# Create role using ansible-galaxy
ansible-galaxy init my_role

# Or create manually
mkdir -p roles/my_role/{tasks,handlers,templates,files,vars,defaults,meta}

Standard role structure:

my_role/
├── tasks/
│   └── main.yml          # Main task list
├── handlers/
│   └── main.yml          # Handlers
├── templates/
│   └── config.j2         # Jinja2 templates
├── files/
│   └── script.sh         # Static files
├── vars/
│   └── main.yml          # Role variables
├── defaults/
│   └── main.yml          # Default variables
├── meta/
│   └── main.yml          # Role metadata and dependencies
└── README.md             # Role documentation

Step 2: Define tasks

tasks/main.yml:

---
# Main task file for my_role

- name: Install required packages
  ansible.builtin.package:
    name: "{{ item }}"
    state: present
  loop: "{{ required_packages }}"
  tags: [packages]

- name: Create application directory
  ansible.builtin.file:
    path: "{{ app_directory }}"
    state: directory
    owner: "{{ app_user }}"
    group: "{{ app_group }}"
    mode: '0755'
  tags: [setup]

- name: Deploy configuration file
  ansible.builtin.template:
    src: config.j2
    dest: "{{ app_directory }}/config.yml"
    owner: "{{ app_user }}"
    group: "{{ app_group }}"
    mode: '0644'
  notify: restart application
  tags: [config]

- name: Ensure service is running
  ansible.builtin.service:
    name: "{{ service_name }}"
    state: started
    enabled: true
  tags: [service]

Step 3: Create handlers

handlers/main.yml:

---
# Handlers for my_role

- name: restart application
  ansible.builtin.service:
    name: "{{ service_name }}"
    state: restarted

- name: reload application
  ansible.builtin.service:
    name: "{{ service_name }}"
    state: reloaded

- name: validate configuration
  ansible.builtin.command:
    cmd: "{{ app_binary }} --validate-config"
  changed_when: false

Step 4: Define variables

defaults/main.yml (default values):

---
# Default variables for my_role

app_user: appuser
app_group: appgroup
app_directory: /opt/myapp
service_name: myapp

required_packages:
  - python3
  - python3-pip
  - git

vars/main.yml (role-specific variables):

---
# Role-specific variables

app_binary: /usr/local/bin/myapp
config_template: config.j2

Step 5: Add metadata

meta/main.yml:

---
galaxy_info:
  author: Your Name
  description: Role for deploying my application
  company: Your Company
  license: MIT
  min_ansible_version: '2.9'
  
  platforms:
    - name: Ubuntu
      versions:
        - focal
        - jammy
    - name: EL
      versions:
        - '8'
        - '9'
  
  galaxy_tags:
    - application
    - deployment

dependencies:
  - role: common
    vars:
      common_packages:
        - curl
        - wget

Role Design Patterns

Pattern 1: Modular tasks

Break tasks into separate files:

# tasks/main.yml
---
- name: Include installation tasks
  ansible.builtin.include_tasks: install.yml
  tags: [install]

- name: Include configuration tasks
  ansible.builtin.include_tasks: configure.yml
  tags: [configure]

- name: Include service tasks
  ansible.builtin.include_tasks: service.yml
  tags: [service]

Pattern 2: Conditional execution

- name: Install on Debian-based systems
  ansible.builtin.apt:
    name: "{{ package_name }}"
    state: present
  when: ansible_os_family == "Debian"

- name: Install on RedHat-based systems
  ansible.builtin.yum:
    name: "{{ package_name }}"
    state: present
  when: ansible_os_family == "RedHat"

Pattern 3: Idempotent operations

- name: Ensure configuration is present
  ansible.builtin.lineinfile:
    path: /etc/myapp/config
    line: "{{ config_line }}"
    state: present
    create: true
  # Idempotent - only changes if line is missing

- name: Ensure service is running
  ansible.builtin.service:
    name: myapp
    state: started
  # Idempotent - only starts if not running

Best Practices

Use fully qualified collection names:

# Good
- name: Install package
  ansible.builtin.package:
    name: nginx

# Avoid
- name: Install package
  package:
    name: nginx

Add descriptive names:

# Good
- name: Install nginx web server
  ansible.builtin.package:
    name: nginx

# Avoid
- name: Install
  ansible.builtin.package:
    name: nginx

Use tags for selective execution:

- name: Install packages
  ansible.builtin.package:
    name: "{{ item }}"
  loop: "{{ packages }}"
  tags: [packages, install]

- name: Configure application
  ansible.builtin.template:
    src: config.j2
    dest: /etc/app/config
  tags: [config, configure]

Implement error handling:

- name: Attempt risky operation
  ansible.builtin.command:
    cmd: /usr/local/bin/risky-command
  register: result
  failed_when: false
  changed_when: result.rc == 0
  tags: [risky]

- name: Handle failure
  ansible.builtin.debug:
    msg: "Operation failed, continuing anyway"
  when: result.rc != 0

Advanced

For detailed information, see:

• Role Structure - Complete role directory layout and organization
• Handlers - Handler patterns and best practices
• Variables - Variable precedence and management