Ansible 核心源码学习笔记

目录

• • 一、仓库概览
• • 二、核心架构分析
• • 三、学习路径详解
• • 四、核心模块实现
• • 五、执行引擎深入
• • 六、Playbook 解析机制
• • 七、插件系统
• • 八、实践指南

一、仓库概览

1.1 仓库结构

ansible-devel 是 Ansible 的核心开发仓库，包含完整的源代码实现：

1.2 核心目录详解

lib/ansible/ 核心库

lib/ansible/
├── cli/              # 命令行接口实现
│   ├── playbook.py   # ansible-playbook 入口
│   ├── adhoc.py      # ad-hoc 命令执行
│   └── ...
├── executor/         # 任务执行引擎
│   ├── task_executor.py
│   ├── play_iterator.py
│   └── ...
├── modules/          # 核心模块集合
│   ├── command.py
│   ├── copy.py
│   ├── service.py
│   └── ...
├── module_utils/     # 模块工具库
│   ├── basic.py      # AnsibleModule 基类
│   └── ...
├── playbook/         # Playbook 结构定义
│   ├── task.py
│   ├── play.py
│   └── role/
├── plugins/          # 插件系统
│   ├── action/
│   ├── connection/
│   ├── filter/
│   └── ...
├── inventory/        # 库存管理
├── parsing/          # 解析器
└── ...

bin/ 命令行入口

包含所有 Ansible 命令行工具：

• • ansible - Ad-hoc 命令执行
• • ansible-playbook - Playbook 执行
• • ansible-vault - 加密/解密
• • ansible-galaxy - 角色/集合管理
• • 等等...

二、核心架构分析

2.1 整体架构图

                    +-----------------------+
                    |   命令行入口 (CLI)    |
                    |  ansible-playbook等   |
                    +-----------+-----------+
                                |
                    +-----------v-----------+
                    |   Playbook Executor   |
                    |   (playbook_executor) |
                    +-----------+-----------+
                                |
                    +-----------v-----------+
                    |   Playbook 解析器     |
                    |   (play, task, role)  |
                    +-----------+-----------+
                                |
                    +-----------v-----------+
                    |   Task Executor       |
                    |   (task_executor.py)  |
                    +-----------+-----------+
               +----------------+----------------+
               |                |                |
    +----------v----------+ +---v----+ +--------v----------+
    |   Action Plugin     | | 模块   | | Connection Plugin  |
    |   (action/)         | | (modules/) | (connection/) |
    +---------------------+ +--------+ +-------------------+
                                                |
                                    +-----------v-----------+
                                    |   目标主机执行        |
                                    +-----------------------+

2.2 关键组件关系

1. 1. CLI 层 - 处理命令行参数，初始化环境
2. 2. Playbook 层 - 解析 Playbook，构建任务执行计划
3. 3. Executor 层 - 核心执行引擎，协调任务分发
4. 4. Plugin 层 - 可扩展的插件体系
5. 5. Module 层 - 实际的操作模块

三、学习路径详解

3.1 分阶段学习计划

🎯 第一阶段：了解架构（1-2天）

目标：理解 Ansible 的整体架构设计

1. 从 lib/ansible/init.py 开始

# 主要内容：
# - 命名空间结构
# - 版本信息导入
# - 核心常量定义

学习要点：

• • 理解模块的组织方式
• • 了解版本管理策略
• • 熟悉导入约定

2. 探索 bin/ 目录

查看各个 CLI 入口点，了解命令如何被调用：

• • bin/ansible
• • bin/ansible-playbook
• • 等等...

3. 阅读 AGENTS.md

学习要点：

• • 开发规范和测试命令
• • PR 流程
• • 代码风格指南

🎯 第二阶段：核心模块学习（3-5天）

目标：深入理解核心模块的实现

1. lib/ansible/modules/ - 核心模块

从最常用的模块开始学习：

模块结构（以 command.py 为例）：

# 1. 文档定义 (DOCUMENTATION, EXAMPLES, RETURN)
DOCUMENTATION = r"""
module: command
short_description: Execute commands on targets
options:
  cmd:
    type: str
    description: The command to run
...
"""

# 2. 导入依赖
from ansible.module_utils.basic import AnsibleModule

# 3. 主函数
defmain():
    module = AnsibleModule(...)
# 执行逻辑
    module.exit_json(...)

if __name__ == '__main__':
    main()

2. lib/ansible/module_utils/ - 模块工具

核心文件：

AnsibleModule 核心功能：

from .basic import AnsibleModule

# 核心特性：
# - 参数解析与验证
# - 结果输出 (exit_json/fail_json)
# - 幂等性处理
# - check_mode 支持

学习要点：

• • 理解模块参数定义
• • 学习如何处理模块返回结果
• • 掌握幂等性实现方式

🎯 第三阶段：执行引擎（5-7天）

目标：理解 Ansible 的任务执行机制

1. lib/ansible/executor/ - 执行器

核心文件：

TaskExecutor 主要流程：

classTaskExecutor:
"""任务执行器核心"""

defrun(self) -> UnifiedTaskResult:
"""主入口"""
# 1. 获取循环项
        items = self._get_loop_items()

# 2. 执行任务
if items isNone:
            utr = self._execute()  # 非循环
else:
            utr = self._run_loop()  # 循环

# 3. 返回结果
return utr

学习要点：

• • 理解任务如何被分发到目标主机
• • 学习循环机制的实现
• • 掌握结果处理流程

2. lib/ansible/cli/ - 命令行接口

PlaybookCLI 流程：

classPlaybookCLI(CLI):
"""ansible-playbook 命令处理"""

defrun(self):
# 1. 初始化解析器
super().run()

# 2. 加载 Playbook
# 3. 创建执行器
# 4. 执行

🎯 第四阶段：Playbook 解析（3-5天）

目标：理解 Playbook 解析和执行流程

1. lib/ansible/playbook/ - Playbook 结构

Task 类核心结构：

classTask(Base, Conditional, Taggable, CollectionSearch, Notifiable, Delegatable):
"""任务类，继承多个 Mixin"""

# 核心属性
    args = NonInheritableFieldAttribute(isa='dict', default=dict)
    action = NonInheritableFieldAttribute(isa='string')
    loop = NonInheritableFieldAttribute(isa='list')
    register = NonInheritableFieldAttribute(static=True)

学习要点：

• • 理解继承体系（Base, Conditional, Taggable 等）
• • 学习属性如何定义和验证
• • 掌握 Task 加载过程

2. lib/ansible/parsing/ - 解析器

🎯 第五阶段：插件系统（3-5天）

目标：理解插件架构

lib/ansible/plugins/ - 插件目录

plugins/
├── action/          # 动作插件
├── become/          # 提权插件
├── cache/           # 缓存插件
├── callback/        # 回调插件
├── connection/      # 连接插件
├── filter/          # 过滤器插件
├── inventory/       # 库存插件
├── lookup/          # 查找插件
├── shell/           # Shell 插件
├── strategy/        # 策略插件
└── test/            # 测试插件

核心插件类型详解：

插件加载机制：

• • 使用 PluginLoader 动态加载
• • 支持多路径搜索
• • 优先级管理

🎯 第六阶段：测试与开发（按需）

1. test/ - 测试框架

2. hacking/ - 开发工具

四、核心模块实现

4.1 模块开发规范

基本结构

# -*- coding: utf-8 -*-

# Copyright 声明

from __future__ import annotations

# 1. 文档定义
DOCUMENTATION = r"""
---
module: module_name
short_description: 简短描述
description:
    - 详细描述
version_added: "2.10"
options:
    option_name:
        description: 选项描述
        type: str
        required: true
"""

EXAMPLES = r"""
- name: 示例
  module_name:
    option_name: value
"""

RETURN = r"""
return_value:
    description: 返回值描述
    returned: always
    type: str
"""

# 2. 导入
from ansible.module_utils.basic import AnsibleModule

# 3. 主函数
defmain():
    module = AnsibleModule(
        argument_spec=dict(
            option_name=dict(type='str', required=True),
        ),
        supports_check_mode=True,
    )

# 业务逻辑
    result = dict(changed=False, msg='')

    module.exit_json(**result)

if __name__ == '__main__':
    main()

AnsibleModule 关键方法

五、执行引擎深入

5.1 任务执行流程

ansible-playbook site.yml
    ↓
PlaybookCLI.run()
    ↓
加载 Playbook → 解析 → 构建 Play 对象
    ↓
PlaybookExecutor.run()
    ↓
PlayIterator → 按序迭代 Play
    ↓
TaskExecutor.run()
    ↓
Action Plugin 执行
    ↓
连接到目标主机 → 传输模块 → 执行 → 返回结果
    ↓
Callback Plugin 处理结果

5.2 TaskExecutor 详解

task_executor.py 核心流程：

1. 初始化
   ├─ 设置连接
   ├─ 加载变量
   └─ 准备环境

2. 执行前
   ├─ 条件判断 (when)
   ├─ 标签过滤 (tags)
   └─ 循环准备 (loop)

3. 执行
   ├─ 选择 Action Plugin
   ├─ 执行 Action
   ├─ 处理返回
   └─ Handler 触发

4. 执行后
   ├─ 结果处理
   ├─ 变量注册 (register)
   └─ 重试逻辑 (until/retries)

六、Playbook 解析机制

6.1 Playbook 加载过程

YAML 文件
    ↓
DataLoader 读取 → YAML 解析
    ↓
Play.load() → 构建 Play 对象
    ├─ Task.load() → 构建 Task 对象
    ├─ Role.load() → 构建 Role 对象
    └─ Handler.load() → 构建 Handler 对象
    ↓
属性验证和继承
    ↓
准备执行

6.2 核心数据结构

继承体系：

Base (基类)
  ├─ Play
  ├─ Block
  ├─ Task
  │   └─ Handler
  └─ Role

Mixin 类：

• • Conditional - 条件判断
• • Taggable - 标签管理
• • Notifiable - 通知机制
• • Delegatable - 委托支持

七、插件系统

7.1 插件加载机制

插件发现：

1. 1. 标准路径（ansible/plugins/）
2. 2. 配置路径（ansible.cfg）
3. 3. 环境变量（ANSIBLE_*_PLUGINS）
4. 4. Collections

7.2 自定义插件开发

Action Plugin 示例

from ansible.plugins.action import ActionBase

classActionModule(ActionBase):
defrun(self, tmp=None, task_vars=None):
# 控制器端执行
        result = super(ActionModule, self).run(tmp, task_vars)
# 业务逻辑
return result

Filter Plugin 示例

classFilterModule:
deffilters(self):
return {
'my_filter': self.my_filter
        }

defmy_filter(self, value):
return value.upper()

八、实践指南

8.1 开发环境搭建

# 克隆仓库（已有）
cd ansible-devel

# 安装开发版本
pip install -e .

# 验证安装
ansible --version

8.2 测试命令

# 语法检查
ansible-playbook --syntax-check playbook.yml

# 单元测试
ansible-test units -v --docker default

# 集成测试
ansible-test integration -v --docker ubuntu2404

# 静态检查
ansible-test sanity -v --docker default

8.3 调试技巧

使用 -vvv 详细输出：

ansible-playbook -vvv playbook.yml

调试模块开发：

# 使用 hacking/test-module.py
./hacking/test-module.py -m ./my_module.py -a 'arg1=value1'

九、推荐学习顺序

1. 从简单模块入手 (command.py) → 理解模块结构
    ↓
2. 学习 module_utils/basic.py → 理解模块基类
    ↓
3. 学习 CLI 入口 (playbook.py) → 理解命令如何触发执行
    ↓
4. 深入 executor (task_executor.py) → 理解任务执行流程
    ↓
5. 学习 playbook (task.py, play.py) → 理解 Playbook 解析
    ↓
6. 探索 plugins → 理解插件机制
    ↓
7. 参与测试 → 验证理解

十、关键文件速查表

学习提示

1. 1. 从使用到实现：先熟悉 Ansible 的使用，再看源码
2. 2. 逐层深入：从模块 → 执行器 → 插件 → 核心
3. 3. 动手实践：修改代码，观察执行效果
4. 4. 配合测试：通过测试验证理解
5. 5. 阅读文档：AGENTS.md 是开发的好帮手

最后更新：2026-05-20

Ansible 核心源码学习笔记

目录

• • 一、仓库概览
• • 二、核心架构分析
• • 三、学习路径详解
• • 四、核心模块实现
• • 五、执行引擎深入
• • 六、Playbook 解析机制
• • 七、插件系统
• • 八、实践指南

一、仓库概览

1.1 仓库结构

ansible-devel 是 Ansible 的核心开发仓库，包含完整的源代码实现：

1.2 核心目录详解

lib/ansible/ 核心库

lib/ansible/
├── cli/              # 命令行接口实现
│   ├── playbook.py   # ansible-playbook 入口
│   ├── adhoc.py      # ad-hoc 命令执行
│   └── ...
├── executor/         # 任务执行引擎
│   ├── task_executor.py
│   ├── play_iterator.py
│   └── ...
├── modules/          # 核心模块集合
│   ├── command.py
│   ├── copy.py
│   ├── service.py
│   └── ...
├── module_utils/     # 模块工具库
│   ├── basic.py      # AnsibleModule 基类
│   └── ...
├── playbook/         # Playbook 结构定义
│   ├── task.py
│   ├── play.py
│   └── role/
├── plugins/          # 插件系统
│   ├── action/
│   ├── connection/
│   ├── filter/
│   └── ...
├── inventory/        # 库存管理
├── parsing/          # 解析器
└── ...

bin/ 命令行入口

包含所有 Ansible 命令行工具：

• • ansible - Ad-hoc 命令执行
• • ansible-playbook - Playbook 执行
• • ansible-vault - 加密/解密
• • ansible-galaxy - 角色/集合管理
• • 等等...

二、核心架构分析

2.1 整体架构图

                    +-----------------------+
                    |   命令行入口 (CLI)    |
                    |  ansible-playbook等   |
                    +-----------+-----------+
                                |
                    +-----------v-----------+
                    |   Playbook Executor   |
                    |   (playbook_executor) |
                    +-----------+-----------+
                                |
                    +-----------v-----------+
                    |   Playbook 解析器     |
                    |   (play, task, role)  |
                    +-----------+-----------+
                                |
                    +-----------v-----------+
                    |   Task Executor       |
                    |   (task_executor.py)  |
                    +-----------+-----------+
               +----------------+----------------+
               |                |                |
    +----------v----------+ +---v----+ +--------v----------+
    |   Action Plugin     | | 模块   | | Connection Plugin  |
    |   (action/)         | | (modules/) | (connection/) |
    +---------------------+ +--------+ +-------------------+
                                                |
                                    +-----------v-----------+
                                    |   目标主机执行        |
                                    +-----------------------+

2.2 关键组件关系

1. 1. CLI 层 - 处理命令行参数，初始化环境
2. 2. Playbook 层 - 解析 Playbook，构建任务执行计划
3. 3. Executor 层 - 核心执行引擎，协调任务分发
4. 4. Plugin 层 - 可扩展的插件体系
5. 5. Module 层 - 实际的操作模块

三、学习路径详解

3.1 分阶段学习计划

🎯 第一阶段：了解架构（1-2天）

目标：理解 Ansible 的整体架构设计

1. 从 lib/ansible/init.py 开始

# 主要内容：
# - 命名空间结构
# - 版本信息导入
# - 核心常量定义

学习要点：

• • 理解模块的组织方式
• • 了解版本管理策略
• • 熟悉导入约定

2. 探索 bin/ 目录

查看各个 CLI 入口点，了解命令如何被调用：

• • bin/ansible
• • bin/ansible-playbook
• • 等等...

3. 阅读 AGENTS.md

学习要点：

• • 开发规范和测试命令
• • PR 流程
• • 代码风格指南

🎯 第二阶段：核心模块学习（3-5天）

目标：深入理解核心模块的实现

1. lib/ansible/modules/ - 核心模块

从最常用的模块开始学习：

模块结构（以 command.py 为例）：

# 1. 文档定义 (DOCUMENTATION, EXAMPLES, RETURN)
DOCUMENTATION = r"""
module: command
short_description: Execute commands on targets
options:
  cmd:
    type: str
    description: The command to run
...
"""

# 2. 导入依赖
from ansible.module_utils.basic import AnsibleModule

# 3. 主函数
defmain():
    module = AnsibleModule(...)
# 执行逻辑
    module.exit_json(...)

if __name__ == '__main__':
    main()

2. lib/ansible/module_utils/ - 模块工具

核心文件：

AnsibleModule 核心功能：

from .basic import AnsibleModule

# 核心特性：
# - 参数解析与验证
# - 结果输出 (exit_json/fail_json)
# - 幂等性处理
# - check_mode 支持

学习要点：

• • 理解模块参数定义
• • 学习如何处理模块返回结果
• • 掌握幂等性实现方式

🎯 第三阶段：执行引擎（5-7天）

目标：理解 Ansible 的任务执行机制

1. lib/ansible/executor/ - 执行器

核心文件：

TaskExecutor 主要流程：

classTaskExecutor:
"""任务执行器核心"""

defrun(self) -> UnifiedTaskResult:
"""主入口"""
# 1. 获取循环项
        items = self._get_loop_items()

# 2. 执行任务
if items isNone:
            utr = self._execute()  # 非循环
else:
            utr = self._run_loop()  # 循环

# 3. 返回结果
return utr

学习要点：

• • 理解任务如何被分发到目标主机
• • 学习循环机制的实现
• • 掌握结果处理流程

2. lib/ansible/cli/ - 命令行接口

PlaybookCLI 流程：

classPlaybookCLI(CLI):
"""ansible-playbook 命令处理"""

defrun(self):
# 1. 初始化解析器
super().run()

# 2. 加载 Playbook
# 3. 创建执行器
# 4. 执行

🎯 第四阶段：Playbook 解析（3-5天）

目标：理解 Playbook 解析和执行流程

1. lib/ansible/playbook/ - Playbook 结构

Task 类核心结构：

classTask(Base, Conditional, Taggable, CollectionSearch, Notifiable, Delegatable):
"""任务类，继承多个 Mixin"""

# 核心属性
    args = NonInheritableFieldAttribute(isa='dict', default=dict)
    action = NonInheritableFieldAttribute(isa='string')
    loop = NonInheritableFieldAttribute(isa='list')
    register = NonInheritableFieldAttribute(static=True)

学习要点：

• • 理解继承体系（Base, Conditional, Taggable 等）
• • 学习属性如何定义和验证
• • 掌握 Task 加载过程

2. lib/ansible/parsing/ - 解析器

🎯 第五阶段：插件系统（3-5天）

目标：理解插件架构

lib/ansible/plugins/ - 插件目录

plugins/
├── action/          # 动作插件
├── become/          # 提权插件
├── cache/           # 缓存插件
├── callback/        # 回调插件
├── connection/      # 连接插件
├── filter/          # 过滤器插件
├── inventory/       # 库存插件
├── lookup/          # 查找插件
├── shell/           # Shell 插件
├── strategy/        # 策略插件
└── test/            # 测试插件

核心插件类型详解：

插件加载机制：

• • 使用 PluginLoader 动态加载
• • 支持多路径搜索
• • 优先级管理

🎯 第六阶段：测试与开发（按需）

1. test/ - 测试框架

2. hacking/ - 开发工具

四、核心模块实现

4.1 模块开发规范

基本结构

# -*- coding: utf-8 -*-

# Copyright 声明

from __future__ import annotations

# 1. 文档定义
DOCUMENTATION = r"""
---
module: module_name
short_description: 简短描述
description:
    - 详细描述
version_added: "2.10"
options:
    option_name:
        description: 选项描述
        type: str
        required: true
"""

EXAMPLES = r"""
- name: 示例
  module_name:
    option_name: value
"""

RETURN = r"""
return_value:
    description: 返回值描述
    returned: always
    type: str
"""

# 2. 导入
from ansible.module_utils.basic import AnsibleModule

# 3. 主函数
defmain():
    module = AnsibleModule(
        argument_spec=dict(
            option_name=dict(type='str', required=True),
        ),
        supports_check_mode=True,
    )

# 业务逻辑
    result = dict(changed=False, msg='')

    module.exit_json(**result)

if __name__ == '__main__':
    main()

AnsibleModule 关键方法

五、执行引擎深入

5.1 任务执行流程

ansible-playbook site.yml
    ↓
PlaybookCLI.run()
    ↓
加载 Playbook → 解析 → 构建 Play 对象
    ↓
PlaybookExecutor.run()
    ↓
PlayIterator → 按序迭代 Play
    ↓
TaskExecutor.run()
    ↓
Action Plugin 执行
    ↓
连接到目标主机 → 传输模块 → 执行 → 返回结果
    ↓
Callback Plugin 处理结果

5.2 TaskExecutor 详解

task_executor.py 核心流程：

1. 初始化
   ├─ 设置连接
   ├─ 加载变量
   └─ 准备环境

2. 执行前
   ├─ 条件判断 (when)
   ├─ 标签过滤 (tags)
   └─ 循环准备 (loop)

3. 执行
   ├─ 选择 Action Plugin
   ├─ 执行 Action
   ├─ 处理返回
   └─ Handler 触发

4. 执行后
   ├─ 结果处理
   ├─ 变量注册 (register)
   └─ 重试逻辑 (until/retries)

六、Playbook 解析机制

6.1 Playbook 加载过程

YAML 文件
    ↓
DataLoader 读取 → YAML 解析
    ↓
Play.load() → 构建 Play 对象
    ├─ Task.load() → 构建 Task 对象
    ├─ Role.load() → 构建 Role 对象
    └─ Handler.load() → 构建 Handler 对象
    ↓
属性验证和继承
    ↓
准备执行

6.2 核心数据结构

继承体系：

Base (基类)
  ├─ Play
  ├─ Block
  ├─ Task
  │   └─ Handler
  └─ Role

Mixin 类：

• • Conditional - 条件判断
• • Taggable - 标签管理
• • Notifiable - 通知机制
• • Delegatable - 委托支持

七、插件系统

7.1 插件加载机制

插件发现：

1. 1. 标准路径（ansible/plugins/）
2. 2. 配置路径（ansible.cfg）
3. 3. 环境变量（ANSIBLE_*_PLUGINS）
4. 4. Collections

7.2 自定义插件开发

Action Plugin 示例

from ansible.plugins.action import ActionBase

classActionModule(ActionBase):
defrun(self, tmp=None, task_vars=None):
# 控制器端执行
        result = super(ActionModule, self).run(tmp, task_vars)
# 业务逻辑
return result

Filter Plugin 示例

classFilterModule:
deffilters(self):
return {
'my_filter': self.my_filter
        }

defmy_filter(self, value):
return value.upper()

八、实践指南

8.1 开发环境搭建

# 克隆仓库（已有）
cd ansible-devel

# 安装开发版本
pip install -e .

# 验证安装
ansible --version

8.2 测试命令

# 语法检查
ansible-playbook --syntax-check playbook.yml

# 单元测试
ansible-test units -v --docker default

# 集成测试
ansible-test integration -v --docker ubuntu2404

# 静态检查
ansible-test sanity -v --docker default

8.3 调试技巧

使用 -vvv 详细输出：

ansible-playbook -vvv playbook.yml

调试模块开发：

# 使用 hacking/test-module.py
./hacking/test-module.py -m ./my_module.py -a 'arg1=value1'

九、推荐学习顺序

1. 从简单模块入手 (command.py) → 理解模块结构
    ↓
2. 学习 module_utils/basic.py → 理解模块基类
    ↓
3. 学习 CLI 入口 (playbook.py) → 理解命令如何触发执行
    ↓
4. 深入 executor (task_executor.py) → 理解任务执行流程
    ↓
5. 学习 playbook (task.py, play.py) → 理解 Playbook 解析
    ↓
6. 探索 plugins → 理解插件机制
    ↓
7. 参与测试 → 验证理解

十、关键文件速查表

学习提示

1. 1. 从使用到实现：先熟悉 Ansible 的使用，再看源码
2. 2. 逐层深入：从模块 → 执行器 → 插件 → 核心
3. 3. 动手实践：修改代码，观察执行效果
4. 4. 配合测试：通过测试验证理解
5. 5. 阅读文档：AGENTS.md 是开发的好帮手

最后更新：2026-05-20

👉 欢迎关注CSDN博客SkyWide 无限领航