目录
[1 setup模块概述](#1 setup模块概述)
[1.1 setup模块的核心价值](#1.1 setup模块的核心价值)
[1.2 与其他信息收集工具对比](#1.2 与其他信息收集工具对比)
[2 setup模块工作原理](#2 setup模块工作原理)
[2.1 模块执行流程](#2.1 模块执行流程)
[2.2 数据收集架构](#2.2 数据收集架构)
[3 setup模块参数详解](#3 setup模块参数详解)
[3.1 核心参数](#3.1 核心参数)
[3.2 gather_subset可选值](#3.2 gather_subset可选值)
[3.3 参数使用示例](#3.3 参数使用示例)
[4 setup模块使用场景与实例](#4 setup模块使用场景与实例)
[4.1 基础使用场景](#4.1 基础使用场景)
[4.2 高级使用场景](#4.2 高级使用场景)
[4.3 实际生产环境中的综合应用](#4.3 实际生产环境中的综合应用)
[5 setup模块收集的关键事实数据](#5 setup模块收集的关键事实数据)
[5.1 系统基本信息](#5.1 系统基本信息)
[5.2 硬件信息](#5.2 硬件信息)
[5.3 网络信息](#5.3 网络信息)
[5.4 存储信息](#5.4 存储信息)
[5.5 虚拟化信息](#5.5 虚拟化信息)
[6 setup模块的性能优化](#6 setup模块的性能优化)
[6.1 使用gather_subset限制收集范围](#6.1 使用gather_subset限制收集范围)
[6.2 使用filter精确过滤](#6.2 使用filter精确过滤)
[6.3 禁用不必要的事实收集](#6.3 禁用不必要的事实收集)
[6.4 缓存事实数据](#6.4 缓存事实数据)
[7 setup模块的高级技巧](#7 setup模块的高级技巧)
[7.1 自定义事实(Custom Facts)](#7.1 自定义事实(Custom Facts))
[7.2 事实数据的转换与处理](#7.2 事实数据的转换与处理)
[7.3 事实数据的调试与查看](#7.3 事实数据的调试与查看)
[8 setup模块的实践建议](#8 setup模块的实践建议)
[9 常见问题与解决方案](#9 常见问题与解决方案)
[9.1 常见问题汇总](#9.1 常见问题汇总)
[9.2 调试技巧](#9.2 调试技巧)
[10 总结](#10 总结)
1 setup模块概述
在自动化运维领域,信息收集是基础且关键的一环。Ansible作为领先的配置管理和应用部署工具,其setup模块扮演着"系统探针"的角色,能够全面收集目标主机的各种事实数据(Facts)。这些数据为后续的配置管理、条件判断和模板渲染提供了重要依据。
1.1 setup模块的核心价值
- 全面系统探测:自动收集目标主机的硬件、网络、操作系统等全方位信息
- 动态变量提供:将收集的信息转换为Ansible变量,供playbook使用
- 条件执行基础:为when条件判断提供系统状态依据
- 配置决策支持:基于不同主机特性执行差异化配置
1.2 与其他信息收集工具对比
|------------------|--------|-----------|------|--------|
| 工具/模块 | 数据范围 | 是否需要agent | 执行效率 | 数据格式 |
| Ansible setup | 全面系统信息 | 否 | 较高 | JSON |
| dmidecode | 硬件信息 | 否 | 高 | 文本 |
| lshw | 详细硬件信息 | 否 | 中 | 文本/XML |
| SaltStack grains | 系统信息 | 是 | 中 | JSON |
| Puppet facter | 系统信息 | 是 | 中 | JSON |
2 setup模块工作原理
2.1 模块执行流程

- Ansible通过SSH连接到目标主机
- 执行内置的Python收集脚本
- 按类别逐步收集各类系统信息
- 将收集的数据序列化为JSON格式
- 传输回控制节点并解析为变量
- 这些变量可以在后续的playbook中直接使用
2.2 数据收集架构

- 控制节点通过SSH触发目标主机上的收集过程
- 系统探测器作为核心组件协调各类信息的收集
- 收集的数据最终汇总为结构化JSON返回
- 自定义事实收集器允许扩展默认收集范围
3 setup模块参数详解
3.1 核心参数
|----------------|----|----------------------|------------------|
| 参数名 | 必填 | 默认值 | 说明 |
| filter | 否 | * | 过滤器,支持通配符匹配事实变量名 |
| gather_subset | 否 | all | 收集的子集,控制收集范围 |
| gather_timeout | 否 | 10 | 收集超时时间(秒) |
| fact_path | 否 | /etc/ansible/facts.d | 自定义事实文件路径 |
3.2 gather_subset可选值
|----------|------------|
| 值 | 收集内容 |
| all | 所有可用事实(默认) |
| min | 最小必要事实集 |
| hardware | 硬件相关事实 |
| network | 网络相关事实 |
| virtual | 虚拟化相关事实 |
| ohai | Ohai事实 |
| facter | Facter事实 |
3.3 参数使用示例
- name: Collect only network facts
ansible.builtin.setup:
gather_subset: network
- name: Collect all facts except hardware
ansible.builtin.setup:
gather_subset: '!hardware'
- name: Collect specific fact
ansible.builtin.setup:
filter: ansible_distribution*
4 setup模块使用场景与实例
4.1 基础使用场景
-
场景一:收集全部事实数据
- name: Gather all facts
setup:
- name: Gather all facts
-
场景二:收集特定子集的事实
- name: Gather only network facts
setup:
gather_subset: network
- name: Gather only network facts
4.2 高级使用场景
-
场景一:使用过滤器收集特定事实
-
name: Get only memory facts
setup:
filter: ansible_mem*
register: mem_facts -
name: Display total memory
debug:
msg: "Total memory: {{ mem_facts.ansible_facts.ansible_memtotal_mb }}MB"
-
-
场景二:条件化任务执行
- name: Install specific package for CentOS
yum:
name: centos-specific-pkg
state: present
when: ansible_facts['distribution'] == 'CentOS'
- name: Install specific package for CentOS
4.3 实际生产环境中的综合应用
- name: Configure server based on facts
hosts: all
tasks:
- name: Gather facts with timeout
setup:
gather_timeout: 20
- name: Set hostname based on serial
hostname:
name: "server-{{ ansible_facts.product_serial | replace(' ', '') | lower }}"
when: ansible_facts.product_serial is defined
- name: Configure network on physical servers
include_tasks: configure_network.yml
when: ansible_facts.virtualization_type == 'none'
- name: Configure swap based on memory
include_tasks: configure_swap.yml
when: ansible_facts.memtotal_mb < 4096
5 setup模块收集的关键事实数据
5.1 系统基本信息
|------------------------------|--------|--------------------------|
| 事实变量 | 说明 | 示例值 |
| ansible_distribution | 发行版名称 | "CentOS" |
| ansible_distribution_version | 发行版版本 | "7.9" |
| ansible_os_family | 操作系统家族 | "RedHat" |
| ansible_kernel | 内核版本 | "3.10.0-1160.el7.x86_64" |
5.2 硬件信息
|-------------------------|---------|-------------------|
| 事实变量 | 说明 | 示例值 |
| ansible_processor_vcpus | 虚拟CPU数量 | 4 |
| ansible_memtotal_mb | 总内存(MB) | 7982 |
| ansible_devices | 设备信息 | {磁盘详细信息} |
| ansible_product_serial | 产品序列号 | "VMware-42 1a..." |
5.3 网络信息
|----------------------------|----------|-----------------------|
| 事实变量 | 说明 | 示例值 |
| ansible_default_ipv4 | 默认IPv4信息 | {地址/网关等} |
| ansible_all_ipv4_addresses | 所有IPv4地址 | ["192.168.10.10"] |
| ansible_interfaces | 网络接口列表 | ["eth0", "lo"] |
| ansible_dns | DNS配置 | {nameservers, search} |
5.4 存储信息
|---------------------|------------|---------------------------|
| 事实变量 | 说明 | 示例值 |
| ansible_mounts | 挂载点信息 | [{mount: "/", size...}] |
| ansible_lvm | LVM信息 | {vg信息} |
| ansible_swapfree_mb | 可用swap(MB) | 2047 |
5.5 虚拟化信息
|-----------------------------------|-------|-----------|
| 事实变量 | 说明 | 示例值 |
| ansible_virtualization_type | 虚拟化类型 | "kvm" |
| ansible_virtualization_role | 虚拟化角色 | "guest" |
| ansible_virtualization_tech_guest | 客户机技术 | ["kvm"] |
6 setup模块的性能优化
6.1 使用gather_subset限制收集范围
- name: Gather only necessary facts
setup:
gather_subset:
- network
- virtual
6.2 使用filter精确过滤
- name: Get only specific facts
setup:
filter:
- 'ansible_default_ipv4'
- 'ansible_distribution'
6.3 禁用不必要的事实收集
- name: Playbook with facts disabled
hosts: all
gather_facts: no
tasks:
- name: Only gather what we need
setup:
filter: ansible_mem*
6.4 缓存事实数据
[defaults]
gathering = smart
fact_caching = jsonfile
fact_caching_connection = /tmp/ansible_facts
fact_caching_timeout = 86400 # 24小时
7 setup模块的高级技巧
7.1 自定义事实(Custom Facts)
方法一:通过facts.d目录
-
在目标主机创建/etc/ansible/facts.d/myfacts.fact:
[application]
version = 1.2.3
deploy_date = 2025-07-27 -
这些事实会自动被收集,可通过ansible_local访问:
- debug:
var: ansible_local.myfacts.application.version
- debug:
方法二:通过set_fact模块动态创建
- name: Set custom fact
set_fact:
app_environment: "production"
- name: Use custom fact
debug:
msg: "Deploying to {{ app_environment }}"
7.2 事实数据的转换与处理
- name: Process facts
hosts: all
tasks:
- name: Get memory facts
setup:
filter: ansible_mem*
- name: Calculate memory usage percentage
set_fact:
mem_usage: |
{{ (100 - (100 * ansible_facts.ansible_memfree_mb / ansible_facts.ansible_memtotal_mb)) | round(2) }}
- name: Alert on high memory usage
debug:
msg: "Warning! High memory usage: {{ mem_usage }}%"
when: mem_usage | float > 90
7.3 事实数据的调试与查看
-
查看所有事实:
ansible hostname -m setup
-
查看特定主机事实:
ansible hostname -m setup -a 'filter=ansible_distribution*'
-
在playbook中调试:
-
name: Display all facts
debug:
var: ansible_facts -
name: Display specific fact
debug:
var: ansible_facts.ansible_default_ipv4.address
-
8 setup模块的实践建议
-
按需收集:不要总是收集所有事实,使用gather_subset或filter限制范围
- name: Gather only required facts
setup:
gather_subset: '!all,!min,network'
- name: Gather only required facts
-
合理命名:使用有意义的变量名存储处理过的事实数据
- name: Set meaningful fact name
set_fact:
webserver_ip: "{{ ansible_facts.default_ipv4.address }}"
- name: Set meaningful fact name
-
事实缓存:在大规模环境中配置事实缓存提高性能
ansible.cfg
[defaults]
gathering = smart
fact_caching = redis -
错误处理:处理可能缺失的事实
- name: Handle missing fact gracefully
debug:
msg: "Serial number: {{ ansible_facts.product_serial | default('UNKNOWN') }}"
- name: Handle missing fact gracefully
-
安全考虑:注意敏感事实数据的处理
- name: Do not log sensitive facts
debug:
msg: "DB password configured"
no_log: true
when: "'db_password' in ansible_facts"
- name: Do not log sensitive facts
9 常见问题与解决方案
9.1 常见问题汇总
|----------|--------------------|--------------------------|
| 问题现象 | 可能原因 | 解决方案 |
| 事实收集超时 | 网络延迟或主机响应慢 | 增加gather_timeout值 |
| 缺少某些事实 | 未包含在gather_subset中 | 调整gather_subset参数 |
| 事实数据不准确 | 目标主机环境异常 | 手动验证目标主机状态 |
| 性能问题 | 收集太多事实 | 使用filter或gather_subset限制 |
| 自定义事实未加载 | 文件权限或格式问题 | 检查facts.d目录权限和文件格式 |
9.2 调试技巧
-
查看详细收集过程:
ANSIBLE_DEBUG=1 ansible-playbook playbook.yml
-
验证事实文件语法:
ansible -m setup localhost -a 'filter=ansible_local'
-
比较不同子集收集速度:
time ansible all -m setup -a 'gather_subset=min'
time ansible all -m setup -a 'gather_subset=all'
10 总结
Ansible的setup模块是自动化运维的基础组件,通过本文我们学习了解到:
- setup模块是Ansible事实数据的核心收集器
- 它能够收集系统各个层面的详细信息
- 通过参数可以灵活控制收集范围和内容
- 事实数据为条件判断和配置决策提供依据
- 性能优化技巧对大规模环境尤为重要
掌握setup模块的使用,是构建可靠自动化运维系统的基础。无论是简单的信息收集,还是复杂的条件化配置,setup模块都扮演着关键角色。