Back to Details

role-builder

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Role Builder

Ansible Role 构建指南

Quick Start

快速开始

Create well-structured Ansible roles with proper organization, reusability, and idempotency.
创建结构清晰、具备可组织性、可复用性和幂等性的Ansible roles。

Instructions

操作步骤

Step 1: Initialize role structure

步骤1：初始化Role结构

bash
undefined
bash
undefined

Create role using ansible-galaxy

Create role using ansible-galaxy

ansible-galaxy init my_role
ansible-galaxy init my_role

Or create manually

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
undefined
mkdir -p roles/my_role/{tasks,handlers,templates,files,vars,defaults,meta}

**标准Role结构：**
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
undefined

Step 2: Define tasks

步骤2：定义任务

tasks/main.yml:
yaml
---
tasks/main.yml:
yaml
---

Main task file for my_role

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]
undefined
  • 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]
undefined

Step 3: Create handlers

步骤3：创建Handlers

handlers/main.yml:
yaml
---
handlers/main.yml:
yaml
---

Handlers for my_role

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
undefined
  • 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
undefined

Step 4: Define variables

步骤4：定义变量

defaults/main.yml (default values):
yaml
---
defaults/main.yml (默认值):
yaml
---

Default variables for my_role

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):**
```yaml
---
app_user: appuser app_group: appgroup app_directory: /opt/myapp service_name: myapp
required_packages:
  • python3
  • python3-pip
  • git

**vars/main.yml (Role专属变量):**
```yaml
---

Role-specific variables

Role-specific variables

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

Step 5: Add metadata

步骤5：添加元数据

meta/main.yml:
yaml
---
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
meta/main.yml:
yaml
---
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

Role设计模式

Pattern 1: Modular tasks

模式1：模块化任务

Break tasks into separate files:
yaml
undefined
将任务拆分为独立文件：
yaml
undefined

tasks/main.yml

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]
undefined
  • 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]
undefined

Pattern 2: Conditional execution

模式2：条件执行

yaml
- 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"
yaml
- 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

模式3：幂等操作

yaml
- 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
yaml
- 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:
yaml
undefined
使用完整的集合名称：
yaml
undefined

Good

Good

  • name: Install package ansible.builtin.package: name: nginx
  • name: Install package ansible.builtin.package: name: nginx

Avoid

Avoid

  • name: Install package package: name: nginx

**Add descriptive names:**
```yaml
  • name: Install package package: name: nginx

**添加描述性名称：**
```yaml

Good

Good

  • name: Install nginx web server ansible.builtin.package: name: nginx
  • name: Install nginx web server ansible.builtin.package: name: nginx

Avoid

Avoid

  • name: Install ansible.builtin.package: name: nginx

**Use tags for selective execution:**
```yaml
- 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:
yaml
- 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
  • name: Install ansible.builtin.package: name: nginx

**使用标签实现选择性执行：**
```yaml
- 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]
实现错误处理：
yaml
- 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
如需详细信息，请参阅：
  • Role Structure - 完整的Role目录布局与组织方式
  • Handlers - Handler模式与最佳实践
  • Variables - 变量优先级与管理