2_【自动化引擎Ansible Runner】私有数据目录与命令行实战

课程二：掌握核心 - 私有数据目录与命令行实战

在第一课中，我们初步接触了私有数据目录，知道它是 Runner 存储输入和输出的地方。本课将深入剖析它的标准结构，并学习 Runner 提供的多种运行模式，让你能够灵活地管理 Ansible 任务的执行。

2.1 私有数据目录深度解析

私有数据目录（Private Data Directory）是 Ansible Runner 的核心设计。当你执行 ansible-runner run . 时，Runner 会期望在 . 目录下存在特定的子目录和文件，用于提供执行所需的数据。同时，Runner 也会在该目录下生成输出。

一个完整的私有数据目录结构通常如下：

bash 复制代码

.
├── inventory/                # 清单文件存放目录
│   ├── hosts                 # 静态清单文件
│   └── group_vars/           # 组变量目录
├── env/                       # 环境配置目录
│   ├── settings              # Runner 本身的配置（如超时、进程隔离）
│   ├── envvars               # 环境变量文件
│   ├── ssh_key               # SSH 私钥文件
│   └── cmdline               # 传递给 ansible-playbook 的额外命令行参数
├── project/                   # Playbook 项目目录
│   ├── playbook.yml           # 要执行的 Playbook
│   └── roles/                 # 角色目录（如果有）
├── artifacts/                 # 输出工件目录（自动生成）
│   └── <执行ID>/           # 每次执行的唯一目录
│       ├── job_events/        # 事件 JSON 文件
│       ├── stdout             # 标准输出文本
│       ├── status             # 执行状态
│       └── rc                 # 返回码
└── ./

inventory/ ：存放 Ansible 清单文件。可以是单个文件 hosts，也可以是包含多个文件的目录。
env/ ：存放 Runner 执行时的环境配置。例如，你可以通过 env/settings 设置 Runner 的超时时间，通过 env/envvars 设置传递给 Ansible 的环境变量。
project/ ：存放要执行的 Playbook 及其依赖（如角色、模块）。Runner 在执行时会自动将 project 目录的内容复制到一个临时位置，以确保每次执行的隔离性。
artifacts/ ：Runner 自动生成的目录，存放每次执行的结果。每次执行会创建一个以UUID命名的子目录，里面包含 stdout、status、rc 以及详细的 job_events

注意：并不是所有子目录都必须存在。Runner 会根据需要自动创建缺失的目录，并提供合理的默认值。例如，如果你没有提供 inventory，Runner 会默认使用 localhost。

2.2 命令模式详解：run、start、stop、is-alive

ansible-runner 提供了多种执行模式，以适应不同的使用场景。

命令	作用	特点
`run`	前台运行一个任务	阻塞当前终端，直到任务完成，输出实时显示。
`start`	后台启动一个任务	立即返回任务标识符（UUID），任务在后台执行。
`stop`	停止一个后台任务	通过任务标识符停止正在执行的任务。
`is-alive`	检查后台任务是否存活	通过任务标识符查询任务状态。

2.2.1 `run` 命令

你已经用过 run 命令了。它会在前台执行 Playbook，输出实时打印到终端。这对于调试和交互式使用非常方便。

css 复制代码

ansible-runner run /path/to/private_data_dir -p playbook.yml

2.2.2 `start` 命令

当你的 Playbook 需要长时间运行，或者你希望将任务放到后台而不阻塞当前终端时，可以使用 start。这是异步执行模式，立即返回并在后台运行

css 复制代码

ansible-runner start /path/to/private_data_dir -p playbook.yml

运行start后，日志会写入到文件（如 daemon.log）

2.2.3 `is-alive` 命令

要检查后台任务是否还在运行，使用 is-alive 并指定任务标识符

检查默认标识符的进程状态：

csharp 复制代码

ansible-runner is-alive .

检查特定标识符的进程状态：

csharp 复制代码

ansible-runner is-alive -i 7a91a613-7fa4-46f2-a563-c597e8f583ad

启用调试模式检查：

csharp 复制代码

ansible-runner is-alive . --debug

返回值说明

退出码 0 - 进程正在运行
退出码 1 - 进程未运行或已停止
其他退出码 - 检查过程中出现错误

2.2.4 `stop` 命令

如果需要强制停止一个正在执行的后台任务，可以使用 stop：

arduino 复制代码

ansible-runner stop .

2.3 实操案例：手动创建私有数据目录并使用多种命令

案例1：手动创建私有数据目录结构

创建一个新目录 runner_deepdive 并进入：
bash 复制代码
```
mkdir runner_deepdive
cd runner_deepdive
```
创建必要的子目录：
bash 复制代码
```
mkdir -p inventory project env
```

在 project 目录中创建一个简单的 Playbook test.yml：

yaml 复制代码

cat > project/test.yml << 'EOF'
---
- name: 长时间运行的任务
  hosts: localhost
  gather_facts: no
  tasks:
    - name: 等待 10 秒
      ansible.builtin.pause:
        seconds: 10
    - name: 打印完成消息
      ansible.builtin.debug:
        msg: "任务完成！"
EOF

在 inventory 目录中创建一个清单文件 hosts：
bash 复制代码
```
echo "localhost ansible_connection=local" > inventory/hosts
```
现在，我们有了一个完整的私有数据目录。

案例2：使用 `run` 前台执行

css 复制代码

# 注意：该路径为私有数据目录下，-p直接指定playbook即可，它会自动从project/下找到该文件
ansible-runner run . -p test.yml

你会看到 pause 任务等待 10 秒，然后打印完成消息。同时，注意观察 artifacts 目录下是否生成了新目录。

案例3：使用 `start` 后台执行

css 复制代码

ansible-runner start . -p test.yml

记下输出的任务标识符，是一个PID。

案例4：检查任务状态

csharp 复制代码

ansible-runner is-alive .

在任务执行期间，退出码为0；正常退出或者未运行，则为1；

案例5：停止任务（可选）

如果你在任务执行期间想停止它，可以使用 stop。但我们的 test.yml 只执行 10 秒，你可以快速在另一个终端执行 stop 来体验：

arduino 复制代码

ansible-runner stop .

2.4 探索工件：从 JSON 事件中获取信息

执行完成后，进入 artifacts 目录下的最新目录，查看 job_events 中的文件。你会发现每个事件文件都对应 Playbook 执行的一个步骤。尝试用 jq 或 python -m json.tool 查看最后一个事件文件（通常是 -complete 或 -finished 事件），里面包含了最终的执行统计信息。

json 复制代码

// cat 9-85ec1837-d39f-4f49-b863-385f7f56c80a.json  | jq
{
  "uuid": "85ec1837-d39f-4f49-b863-385f7f56c80a",
  "counter": 9,
  "stdout": "(ctrl+C then 'C' = continue early, ctrl+C then 'A' = abort)",
  "start_line": 8,
  "end_line": 9,
  "runner_ident": "b45cc5eb-4aac-44b3-aab1-eb88cc899f4c",
  "event": "verbose",
  "pid": 20681,
  "created": "2026-03-18T02:23:35.655809+00:00",
  "parent_uuid": "000c293a-cf94-5035-b71b-000000000003",
  "event_data": {
    "playbook": "test.yml",
    "playbook_uuid": "c7071528-d7e1-44dd-b259-873c0ebccc71",
    "play": "长时间运行的任务",
    "play_uuid": "000c293a-cf94-5035-b71b-000000000001",
    "play_pattern": "localhost",
    "task": "等待10秒",
    "task_uuid": "000c293a-cf94-5035-b71b-000000000003",
    "task_action": "ansible.builtin.pause",
    "resolved_action": "ansible.builtin.pause",
    "task_args": "",
    "task_path": "/usr/local/src/py_projects/automatic/ansible-runner/tip2-私有数据目录与命令行实战/runner_deepdive/project/test.yml:6",
    "uuid": "85ec1837-d39f-4f49-b863-385f7f56c80a"
  }
}

2.5 小结

本课我们深入学习了：

私有数据目录的标准结构及其作用。
run、start、is-alive、stop 四种命令的使用方法。
如何手动构建私有数据目录，并灵活运用不同命令管理任务执行。

掌握这些内容后，你已经能够独立地组织 Runner 的执行环境，并控制任务的运行方式了。

2_【自动化引擎Ansible Runner】私有数据目录与命令行实战

课程二：掌握核心 - 私有数据目录与命令行实战

2.1 私有数据目录深度解析

2.2 命令模式详解：run、start、stop、is-alive

2.2.1 run 命令

2.2.2 start 命令

2.2.3 is-alive 命令

2.2.4 stop 命令

2.3 实操案例：手动创建私有数据目录并使用多种命令

案例1：手动创建私有数据目录结构

案例2：使用 run 前台执行

案例3：使用 start 后台执行

案例4：检查任务状态

案例5：停止任务（可选）

2.4 探索工件：从 JSON 事件中获取信息

2.5 小结

2.2.1 `run` 命令

2.2.2 `start` 命令

2.2.3 `is-alive` 命令

2.2.4 `stop` 命令

案例2：使用 `run` 前台执行

案例3：使用 `start` 后台执行