【自动化运维神器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模块都扮演着关键角色。
相关推荐
六点半88828 分钟前
【Linux】Linux编译器-gcc/g++使用
linux·运维·服务器
我才是一卓38 分钟前
排查解决 nvidia-suspend 导致的 linux 系统无响应/死机问题
linux·运维·服务器
Tipriest_2 小时前
linux eval命令的使用方法介绍
linux·运维·bash
laoma-cloud2 小时前
网络基础实操篇-05-路由基础-最佳实践
运维·网络·智能路由器
孟婆来包棒棒糖~2 小时前
Docker快速入门
运维·spring boot·docker·容器·tomcat
IT成长日记2 小时前
【自动化运维神器Ansible】Ansible常用模块之lineinfile模块详解
运维·自动化·ansible·常用模块·lineinfile
伤心男孩拯救世界(Code King)3 小时前
Linux网络:多路转接 epoll
linux·运维·网络
lisanmengmeng3 小时前
正向代理与反向代理
运维·服务器·网络
yyy0002003 小时前
Linux9 root密码修改
linux·运维·服务器