Ansible入门二：【Ansible工具集】

一、Ansible 工具集概览

Ansible 安装后会提供一系列配套命令行工具，均基于同一套核心 Python 框架实现，分别覆盖不同自动化场景。

[root@Ans-prometheus ~]# ansible --version
ansible [core 2.17.14]
  config file = /etc/ansible/ansible.cfg
  configured module search path = ['/root/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
  ansible python module location = /usr/lib/python3/dist-packages/ansible
  ansible collection location = /root/.ansible/collections:/usr/share/ansible/collections
  executable location = /usr/bin/ansible
  python version = 3.10.12 (main, Mar  3 2026, 11:56:32) [GCC 11.4.0] (/usr/bin/python3)
  jinja version = 3.0.3
  libyaml = True


[root@Ans-prometheus ~]# ll /usr/bin/ansible*
-rwxr-xr-x 1 root root  979 Sep 10  2025 /usr/bin/ansible*
-rwxr-xr-x 1 root root  981 Dec  5  2024 /usr/bin/ansible-community*
-rwxr-xr-x 1 root root  993 Sep 10  2025 /usr/bin/ansible-config*
-rwxr-xr-x 1 root root 1001 Sep 10  2025 /usr/bin/ansible-connection*
-rwxr-xr-x 1 root root  995 Sep 10  2025 /usr/bin/ansible-console*
-rwxr-xr-x 1 root root  987 Sep 10  2025 /usr/bin/ansible-doc*
-rwxr-xr-x 1 root root  993 Sep 10  2025 /usr/bin/ansible-galaxy*
-rwxr-xr-x 1 root root  999 Sep 10  2025 /usr/bin/ansible-inventory*
-rwxr-xr-x 1 root root  997 Sep 10  2025 /usr/bin/ansible-playbook*
-rwxr-xr-x 1 root root  989 Sep 10  2025 /usr/bin/ansible-pull*
-rwxr-xr-x 1 root root 1647 Sep 10  2025 /usr/bin/ansible-test*
-rwxr-xr-x 1 root root  991 Sep 10  2025 /usr/bin/ansible-vault*

工具命令	核心定位	主要用途
`ansible`	临时批量干活的快捷命令	想一次性批量执行个简单操作，比如批量看负载、批量建个目录，不用写剧本，一条命令就搞定
`ansible-playbook`	跑剧本的主力工具	把要做的一整套步骤写成 YAML 剧本（比如部署一套服务），让它照着批量自动执行，是日常最常用的核心工具
`ansible-doc`	自带的离线说明书	忘了某个模块怎么用、有啥参数，直接敲命令查，不用上网搜，官方权威说明
`ansible-inventory`	主机清单核对工具	排查“为啥我写的主机/分组没生效”“变量最终值是啥”，能把所有主机、分组、变量合并后的结果全列出来
`ansible-vault`	敏感信息加密工具	配置文件里有密码、密钥，怕泄露，用它把文件加密后再存 Git，跑的时候自动解密
`ansible-console`	交互式批量终端	像进了一个专属 Ansible 命令行，随时切换分组、直接敲模块命令，调试、临时批量操作特别方便
`ansible-galaxy`	Ansible 的“应用商店”客户端	网上有很多别人写好的现成自动化脚本（角色/集合），用这个命令直接下载安装，不用自己从零写
`ansible-config`	配置项查看工具	想知道当前哪个配置文件生效、某个配置项的值是多少，用它直接查，不用自己翻配置文件
`ansible-connection`	连接问题排查工具	连不上目标主机的时候，用它看底层连接的完整日志，定位到底是密钥问题、端口问题还是协议问题
`ansible-pull`	反向拉取执行工具	正常是控制端往目标机推命令；这个反过来，目标机自己主动去 Git 拉剧本本地执行，适合机器特别多、或者控制端连不上目标的场景
`ansible-community`	社区版版本工具	主要用来查完整社区版的版本号，区分“精简核心版”和“全功能社区版”
`ansible-test`	开发者测试工具	给写自定义模块、插件的开发人员用的，测代码对不对、合不合规，普通运维基本用不上

所有工具均为 Python 脚本，可通过 file /usr/bin/ansible 验证其文件类型。

二、ansible-doc 文档查询工具

ansible-doc 是日常使用频率最高的参考工具，提供官方权威的模块、插件说明，是编写 Playbook 与 Ad-Hoc 命令的核心参考。

2.1 常用操作命令

列出全部可用模块

ansible-doc -l

[root@Ans-prometheus ~]# ansible-doc -l |wc -l
9858

过滤指定模块

[root@Ans-prometheus ~]# ansible-doc -l |grep  shell
ansible.builtin.shell                       Execute ...Execute shell commands on targets 

[root@Ans-prometheus ~]# ansible-doc -l |grep  ping
ansible.builtin.ping                        Try to connect to host, verify a usable python and...

查看模块完整官方文档

[root@Ans-prometheus ~]# ansible-doc ping
> MODULE ansible.builtin.ping (/usr/lib/python3/dist-packages/ansible/modules/ping.py)

  A trivial test module, this module always returns `pong' on successful contact. It does not make sense in playbooks, but it is useful from
  `/usr/bin/ansible' to verify the ability to login and that a usable Python is configured.
  This is NOT ICMP ping, this is just a trivial test module that requires Python on the remote-node.
  For Windows targets, use the ansible.windows.win_ping module instead.
  For Network targets, use the ansible.netcommon.net_ping module instead.

OPTIONS (red indicates it is required):

   data    Data to return for the `ping' return value.
           If this parameter is set to `crash', the module will cause an exception.
        default: pong
        type: str

ATTRIBUTES:

        check_mode:
        description: Can run in check_mode and return changed status prediction without modifying
          target, if not supported the action will be skipped.
        support: full

        diff_mode:
        description: Will return details on what has changed (or possibly needs changing in
          check_mode), when in diff mode
        support: none

        platform:
        description: Target OS/families that can be operated against
        platforms: posix
        support: N/A

SEE ALSO:
      * Module ansible.netcommon.net_ping
      * Module ansible.windows.win_ping

AUTHOR: Ansible Core Team, Michael DeHaan

EXAMPLES:
# Test we can logon to 'webservers' and execute python with json lib.
# ansible webservers -m ansible.builtin.ping

- name: Example from an Ansible Playbook
  ansible.builtin.ping:

- name: Induce an exception to see what happens
  ansible.builtin.ping:
    data: crash

RETURN VALUES:

   ping    Value provided with the `data' parameter.
        returned: success
        sample: pong
        type: str

输出内容包含：模块功能描述、适用平台、全部参数及默认值、属性说明、使用示例、返回字段定义等完整信息。

查看精简语法示例（快速复用）

[root@Ans-prometheus ~]# ansible-doc -s ping
- name: Try to connect to host, verify a usable python and return `pong' on success
  ping:
      data:                  # Data to return for the `ping' return value. If this parameter is set to `crash', the module will cause an exception.
[root@Ans-prometheus ~]#

输出简洁的 Playbook 写法片段，适合快速复制参数结构。

按插件类型查询
支持查询 become、callback、connection、inventory、lookup、shell 等类型插件：

ansible-doc -t shell -l

输出 JSON 结构化文档
便于程序解析或二次处理：

ansible-doc -j ping

2.2 模块标准属性

官方文档中每个模块均包含标准化属性标识：

check_mode：是否支持检查模式（干运行），支持的模块可在不修改目标的前提下预判变更。
diff_mode：是否支持差异展示，可输出变更前后的内容对比。
platform：明确支持的目标操作系统与平台范围，例如 posix、windows 等。

三、ansible-console 交互式终端

ansible-console 提供类 Shell 的交互式批量操作环境，适合临时批量操作、调试排查与快速验证。

3.1 基础启动

ansible-console

默认提示符格式：`当前用户@当前操作分组 (主机总数) [并发数] $`
例如 `root@all (7)[f:5]$` 表示：以 root 用户操作 all 分组下 7 台主机，并发数为 5。

3.2 常用内置命令

命令	功能说明
`help` / `?`	查看当前环境支持的所有命令与可用模块
`list`	列出当前分组下的全部主机清单
`cd <分组名/匹配模式>`	切换当前操作的主机范围，支持完整 Host Pattern 语法
`forks <数量>`	动态调整任务并发执行数
`become` / `become_user`	动态设置特权提权相关参数
`check`	切换检查模式开关
`diff`	切换差异展示开关
`exit` / `EOF`	退出交互式终端

3.3 使用示例

# 进入到交互式命令行
[root@Ans-prometheus ~]# ansible-console
Welcome to the ansible console. Type help or ? to list commands.

# 使用?或者help均能查看当前终端支持的子命令
root@all (7)[f:5]$ ?

Documented commands (type help <topic>):
========================================
EOF
amazon.aws.autoscaling_group
amazon.aws.autoscaling_group_info
amazon.aws.aws_az_info
amazon.aws.aws_caller_info
amazon.aws.aws_region_info
amazon.aws.backup_plan
...

# help查看子命令帮助信息
root@all (7)[f:5]$ help list
List the hosts in the current group or a list of groups if you add 'groups'.

# list列出当前管理的主机列表
root@all (7)[f:5]$ list
10.0.0.71
10.0.0.72
10.0.0.73
vsan01.node11
vsan01.node12
vsan02.node11
vsan02.node12

# cd切换到指定分组
root@consul1 (1)[f:5]$ cd csl

root@csl (3)[f:5]$ list  # 查看当前主机组的主机列表
10.0.0.71
10.0.0.72
10.0.0.73

# 使用ping模块检测主机是否存活
root@csl (3)[f:5]$ ping
10.0.0.72 | SUCCESS => {
    "changed": false,
    "ping": "pong"
}
10.0.0.73 | SUCCESS => {
    "changed": false,
    "ping": "pong"
}
10.0.0.71 | SUCCESS => {
    "changed": false,
    "ping": "pong"
}

# 查看内存大小
root@csl (3)[f:5]$ command "free -h"
10.0.0.71 | FAILED | rc=2 >>
[Errno 2] No such file or directory: b'free -h'
10.0.0.73 | FAILED | rc=2 >>
[Errno 2] No such file or directory: b'free -h'
10.0.0.72 | FAILED | rc=2 >>
[Errno 2] No such file or directory: b'free -h'

root@csl (3)[f:5]$ command free -h
10.0.0.71 | CHANGED | rc=0 >>
               total        used        free      shared  buff/cache   available
Mem:           921Mi       313Mi       135Mi       1.0Mi       471Mi       454Mi
Swap:          5.0Gi        25Mi       5.0Gi
10.0.0.72 | CHANGED | rc=0 >>
               total        used        free      shared  buff/cache   available
Mem:           921Mi       324Mi        79Mi       1.0Mi       516Mi       451Mi
Swap:          5.0Gi          0B       5.0Gi
10.0.0.73 | CHANGED | rc=0 >>
               total        used        free      shared  buff/cache   available
Mem:           921Mi       316Mi       174Mi       1.0Mi       430Mi       459Mi
Swap:          5.0Gi          0B       5.0Gi

root@csl (3)[f:5]$ shell free -h
10.0.0.73 | CHANGED | rc=0 >>
               total        used        free      shared  buff/cache   available
Mem:           921Mi       316Mi       174Mi       1.0Mi       430Mi       459Mi
Swap:          5.0Gi          0B       5.0Gi
10.0.0.72 | CHANGED | rc=0 >>
               total        used        free      shared  buff/cache   available
Mem:           921Mi       324Mi        79Mi       1.0Mi       516Mi       451Mi
Swap:          5.0Gi          0B       5.0Gi
10.0.0.71 | CHANGED | rc=0 >>
               total        used        free      shared  buff/cache   available
Mem:           921Mi       313Mi       135Mi       1.0Mi       471Mi       454Mi
Swap:          5.0Gi        25Mi       5.0Gi

root@csl (3)[f:5]$ apt name=unzip state=present
10.0.0.72 | SUCCESS => {
    "cache_update_time": 1782385837,
    "cache_updated": false,
    "changed": false
}
10.0.0.73 | SUCCESS => {
    "cache_update_time": 1782630916,
    "cache_updated": false,
    "changed": false
}
10.0.0.71 | SUCCESS => {
    "cache_update_time": 1782641031,
    "cache_updated": false,
    "changed": false
}
root@csl (3)[f:5]$

四、ansible 命令行常用选项

ansible 是 Ad-Hoc 临时任务的核心入口，通用语法为：

ansible <主机匹配模式> [选项] -m <模块名> -a "<模块参数>"

若省略 -m 参数，默认使用 command 模块。

4.1 信息与校验类

选项	功能说明
`--version`	输出版本号、配置文件路径、Python 环境、模块搜索路径等核心信息
`--list-hosts`	仅列出匹配到的主机，不执行任何任务，用于校验主机匹配结果
`-v / -vv / -vvv / -vvvv`	逐级提升输出详情： - `-v` 显示任务执行结果详情 - `-vv` 显示模块输入参数与完整返回 - `-vvv` 显示连接过程与远程执行详情 - `-vvvv` 开启 SSH 完整调试日志，用于排查连接故障
`--syntax-check`	仅做语法检查，不执行任务

4.2 清单与连接类

选项	功能说明
`-i <清单路径>`	指定主机清单文件或目录，默认读取 `/etc/ansible/hosts`
`-u <用户名>`	指定 SSH 远程登录用户名
`-k / --ask-pass`	交互式输入 SSH 登录密码，依赖系统安装 `sshpass` 工具
`--private-key <密钥路径>`	指定 SSH 认证私钥文件
`-T <秒数>`	设置 SSH 连接超时时间
`-c <连接类型>`	指定连接插件，默认 `smart`，可选 `ssh` / `paramiko` / `local` / `winrm` 等
`--ssh-common-args <参数>`	传递给 SSH/SCP/SFTP 的通用额外参数

4.3 特权提权类

选项	功能说明
`-b / --become`	启用特权提权，默认提权方式为 sudo
`--become-method <方式>`	指定提权方法，支持 sudo、su、runas 等
`--become-user <用户名>`	提权到的目标用户，默认为 `root`
`-K / --ask-become-pass`	交互式输入提权密码

4.4 执行控制类

选项	功能说明
`-m <模块名>`	指定执行的功能模块，缺省默认 `command`
`-a <参数字符串>`	传递给目标模块的参数，以空格分隔多个键值对
`-e <变量>`	传入额外全局变量，优先级最高，支持 `key=value` 或 JSON/YAML 格式
`-f <并发数>`	设置并行工作进程数，默认值为 5，大规模环境可适当调大
`-C / --check`	检查模式（干运行），仅预判变更，不实际修改目标主机
`-D / --diff`	展示文件/配置变更前后的内容差异，常与 `--check` 配合使用
`-B <秒数>`	后台异步执行任务，并设置超时时间
`-P <秒数>`	异步任务的结果轮询间隔，默认 15 秒
`-l <子集模式>`	在匹配结果中二次筛选主机，支持完整 Host Pattern 语法

五、主机匹配规则（Host Pattern）

Host Pattern 用于灵活指定任务执行的目标主机范围，支持多种匹配语法，可组合实现复杂筛选。

5.1 基础匹配

all / *：匹配清单中全部主机
单主机名/IP：精确匹配一台主机
分组名：匹配指定分组下的所有主机
多目标并列：使用空格或冒号分隔，表示逻辑或，例如 webservers:dbservers

默认内置分组：all（全部主机）、ungrouped（未加入任何自定义分组的主机）。

5.2 通配符匹配

支持 * 通配符做模糊匹配：

web*：匹配所有名称以 web 开头的主机或分组
192.168.1.*：匹配指定网段的全部主机

# 1.用通配符表示所有主机
[root@Ans-prometheus ~]# ansible "*" --list
  hosts (7):
    10.0.0.71
    10.0.0.72
    10.0.0.73
    vsan01.node11
    vsan01.node12
    vsan02.node11
    vsan02.node12

# 2.指定开头
[root@Ans-prometheus ~]# ansible "consul*" --list
  hosts (3):
    10.0.0.71
    10.0.0.72
    10.0.0.73

# 3.指定结尾
[root@Ans-prometheus ~]# ansible "*1" --list
  hosts (3):
    10.0.0.71
    vsan01.node11
    vsan02.node11

# 4.指定开头和结尾
[root@Ans-prometheus ~]# ansible "c*1" --list
  hosts (1):
    10.0.0.71
[root@Ans-prometheus ~]#

5.3 逻辑运算

语法	含义	数学关系
A:B	A 或者 B（并集）	∪
A:&B	A 并且 B（交集，主机同时在两个组）	∩
A:!B	在 A 里，但不在B 里	差集

# 主机清单
[root@Ans-prometheus /etc/ansible]# cat hosts
[consul1]
10.0.0.71
[consul2]
10.0.0.72
[consul3]
10.0.0.73

[csl]
10.0.0.[71:73]

# 逻辑"与"
[root@Ans-prometheus /etc/ansible]# ansible "consul1:&consul2" --list
[WARNING]: No hosts matched, nothing to do
  hosts (0):

[root@Ans-prometheus /etc/ansible]# ansible "consul1:&consul" --list
  hosts (1):
    10.0.0.71

# 逻辑"或"(可以使用":"表示，当然如果不写的话，默认就是或的关系)
[root@Ans-prometheus /etc/ansible]#ansible "consul1:consul2" --list
  hosts (2):
    10.0.0.71
    10.0.0.72

[root@Ans-prometheus /etc/ansible]# ansible "consul1 consul2" --list
  hosts (2):
    10.0.0.71
    10.0.0.72

# 逻辑"非"
[root@Ans-prometheus /etc/ansible]# ansible 'consul1:!consul2' --list
  hosts (1):
    10.0.0.71
[root@Ans-prometheus /etc/ansible]# ansible 'consul:!consul2' --list
  hosts (2):
    10.0.0.71
    10.0.0.73

# 综合表达式
[root@Ans-prometheus /etc/ansible]# ansible 'consul1:consul2:&consul:!consul2' --list
  hosts (1):
    10.0.0.71

5.4 正则匹配

以 ~ 开头标识正则表达式（采用 RE2 语法）：

~^web\d+\.example\.com$：匹配符合命名规则的主机
~.*prod.*：匹配名称中包含 prod 的主机

5.5 范围匹配

主机清单支持范围写法，匹配时自动展开为对应主机列表：

数字范围：web[01:10].example.com
字母范围：db-[a:f].example.com
步长设置：web[01:50:2].example.com（间隔为 2）

六、执行结果状态说明

Ansible 对每台主机的执行结果有明确状态标识，终端以不同颜色区分，核心状态如下：

状态标识	终端颜色	含义	典型场景
`SUCCESS`	绿色	执行成功，未对目标主机产生任何修改	连通性测试、信息采集、幂等模块重复执行
`CHANGED`	黄色	执行成功，且目标主机的状态发生了实际变更	安装软件、修改配置、创建文件目录
`FAILED`	红色	任务执行失败，命令/模块返回非零状态	命令不存在、权限不足、参数错误
`SKIPPED`	青色	任务被跳过，未执行	条件判断不满足、标签过滤排除
`UNREACHABLE`	暗红色	无法与目标主机建立连接	网络不通、认证失败、主机宕机、端口不可达

幂等性说明：官方专用模块（yum、copy、service 等）普遍内置幂等逻辑，重复执行结果一致；command / shell / raw 等通用执行模块无法判断命令副作用，默认始终返回 CHANGED。

七、常见错误与排查方案

7.1 主机模式无匹配

报错信息：

[WARNING]: Could not match supplied host pattern, ignoring: xxx
[WARNING]: provided hosts list is empty, only localhost is available.

原因：指定的主机/分组名称在当前加载的清单中不存在。
排查步骤：
1. 使用 ansible <pattern> --list-hosts 校验匹配结果
2. 确认是否通过 -i 指定了正确的清单文件路径
3. 检查主机名、分组名拼写与大小写

7.2 SSH 主机密钥校验失败

报错信息：

Using a SSH password instead of a key is not possible because Host Key checking is enabled and sshpass does not support this.

原因：开启了 SSH 主机密钥校验，且 sshpass 无法交互式确认主机指纹。
解决方案：
1. 生产环境推荐：手动 SSH 登录一次目标主机，确认指纹后写入 known_hosts
2. 测试/内网环境：在 ansible.cfg 中设置 host_key_checking = False 关闭校验
3. 优先使用密钥认证，避免密码登录方式

7.3 sshpass 依赖缺失

报错信息：

to use the 'ssh' connection type with passwords or pkcs11_provider, you must install the sshpass program

原因：使用密码认证时，必须依赖 sshpass 工具自动传递密码。
解决方案：安装系统 sshpass 软件包，或改用 SSH 密钥认证方式。

7.4 远程 Python 解释器缺失

报错信息：

module_stdout: "/bin/sh: 1: /usr/bin/python: not found"

原因：目标主机未安装 Python，或 Python 路径与 Ansible 默认搜索路径不一致。
解决方案：
1. 在目标主机安装 Python 3 环境
2. 通过主机变量 ansible_python_interpreter 指定正确路径，例如 /usr/bin/python3
3. 系统初始化等无 Python 场景，可使用 raw 模块执行命令，不依赖远程 Python 环境

7.5 连接超时/主机不可达

报错信息：Failed to connect to the host via ssh

排查步骤：
1. 手动执行 SSH 命令验证连通性与认证
2. 检查目标主机防火墙、安全组是否放行 SSH 端口
3. 确认 ansible_host、ansible_port 配置是否正确
4. 使用 -vvvv 参数查看完整 SSH 调试日志，定位具体失败环节

7.6 ansible‑console 执行 command 模块报找不到文件

报错信息：

[Errno 2] No such file or directory: b'free -h'
rc=2

原因：
在 ansible‑console 交互式终端中，command 模块不会调用 shell 解释器；如果用引号把命令+参数整体包裹 command "free -h"，会把 free -h 当成一个完整程序文件名去查找，系统并不存在该程序，直接报错。

注意区分：外部 bash 执行 ad‑hoc ansible xxx -m command -a "free -h" 的引号由本地Shell解析，是合法写法；但 ansible‑console 内部不能用引号把整条命令包起来。

解决方案：

command 模块命令和参数直接空格分隔，不要加双引号包裹整条命令

command free -h

如果需要管道、重定向、通配符等 shell 特性，改用 shell 模块

shell df -h | grep /

关键知识点：
- command：不经过shell，安全性高，不支持管道、重定向、通配符；
- shell：调用目标主机 /bin/sh，完整支持shell语法；
- 返回码 rc=2 代表：找不到可执行程序。

posted @ 2026-08-04 22:21 kyle_7Qc 阅读(17) 评论(0) 收藏举报

刷新页面返回顶部

kyle-7Qc

Ansible入门二：【Ansible工具集】

一、Ansible 工具集概览

二、ansible-doc 文档查询工具

2.1 常用操作命令

2.2 模块标准属性

三、ansible-console 交互式终端

3.1 基础启动

3.2 常用内置命令

3.3 使用示例

四、ansible 命令行常用选项

4.1 信息与校验类

4.2 清单与连接类

4.3 特权提权类

4.4 执行控制类

五、主机匹配规则（Host Pattern）

5.1 基础匹配

5.2 通配符匹配

5.3 逻辑运算

5.4 正则匹配

5.5 范围匹配

六、执行结果状态说明

七、常见错误与排查方案

7.1 主机模式无匹配

7.2 SSH 主机密钥校验失败

7.3 sshpass 依赖缺失

7.4 远程 Python 解释器缺失

7.5 连接超时/主机不可达

7.6 ansible‑console 执行 command 模块报找不到文件

公告