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

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

undefined

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


**标准Role结构：**

undefined

Step 2: Define tasks

步骤2：定义任务

tasks/main.yml:

yaml

---

tasks/main.yml:

yaml

---

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

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

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

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

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

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

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

Avoid

name: Install package package: name: nginx


**Add descriptive names:**
```yaml

name: Install package package: name: nginx


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

Good

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

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

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 - 变量优先级与管理