【自动化运维神器Ansible】Ansible常用模块之setup模块详解

[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 only network facts
  setup:
  gather_subset: network

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'

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

方法二：通过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: Set meaningful fact name
  set_fact:
  webserver_ip: "{{ ansible_facts.default_ipv4.address }}"
事实缓存：在大规模环境中配置事实缓存提高性能

ansible.cfg

[defaults]
gathering = smart
fact_caching = redis
错误处理：处理可能缺失的事实
- name: Handle missing fact gracefully
  debug:
  msg: "Serial number: {{ ansible_facts.product_serial | default('UNKNOWN') }}"
安全考虑：注意敏感事实数据的处理
- name: Do not log sensitive facts
  debug:
  msg: "DB password configured"
  no_log: true
  when: "'db_password' in ansible_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模块都扮演着关键角色。

【自动化运维神器Ansible】Ansible常用模块之setup模块详解

1 setup模块概述

1.1 setup模块的核心价值

1.2 与其他信息收集工具对比

2 setup模块工作原理

2.1 模块执行流程

2.2 数据收集架构

3 setup模块参数详解

3.1 核心参数

3.2 gather_subset可选值

3.3 参数使用示例

4 setup模块使用场景与实例

4.1 基础使用场景

4.2 高级使用场景

4.3 实际生产环境中的综合应用

5 setup模块收集的关键事实数据

5.1 系统基本信息

5.2 硬件信息

5.3 网络信息

5.4 存储信息

5.5 虚拟化信息

6 setup模块的性能优化

6.1 使用gather_subset限制收集范围

6.2 使用filter精确过滤

6.3 禁用不必要的事实收集

6.4 缓存事实数据

7 setup模块的高级技巧

7.1 自定义事实(Custom Facts)

7.2 事实数据的转换与处理

7.3 事实数据的调试与查看

8 setup模块的实践建议

ansible.cfg

9 常见问题与解决方案

9.1 常见问题汇总

9.2 调试技巧

10 总结