ansible.builtin.setup 模块 – 收集远程主机的 facts

注意

此模块是 ansible-core 的一部分，包含在所有 Ansible 安装中。在大多数情况下，即使不指定 collections 关键字，也可以使用简短的模块名称 setup。但是，我们建议您使用 完全限定的集合名称 (FQCN) ansible.builtin.setup，以便轻松链接到模块文档并避免与可能具有相同模块名称的其他集合发生冲突。

摘要

• 此模块由 playbook 自动调用，以收集有关远程主机的有用变量，这些变量可以在 playbook 中使用。它也可以由 /usr/bin/ansible 直接执行，以检查主机可以使用哪些变量。Ansible 自动提供有关系统的许多 *facts*。

• 此模块也支持 Windows 目标。

参数

参数	注释
fact_path 路径	用于本地 Ansible facts（*.fact）的路径 - 此目录中的文件将被运行（如果可执行），其结果将添加到 ansible_local facts 中。如果文件不可执行，则会读取该文件。文件/结果格式可以是 JSON 或 INI 格式。默认的 fact_path 可以在 ansible.cfg 中指定，用于当 setup 作为 gather_facts 的一部分自动调用时。注意 - 对于 Windows 客户端，结果将添加到以本地文件（不带扩展名后缀）命名的变量中，而不是 ansible_local 中。 从 Ansible 2.1 开始，Windows 主机可以使用 fact_path。确保目标主机上存在此路径。此路径中的文件必须是 PowerShell 脚本 .ps1，输出一个对象。此对象将由 Ansible 格式化为 json，因此脚本应输出原始哈希表、数组或其他基本对象。 默认值： "/etc/ansible/facts.d"
filter 列表 / 元素=字符串	如果提供，则仅返回与 shell 风格（fnmatch）模式之一匹配的 facts。空列表基本上表示“无过滤器”。从 Ansible 2.11 开始，类型已从字符串更改为列表，并且默认值已变为空列表。仍然接受简单的字符串并将其用作单个模式。Ansible 2.11 之前的行为保持不变。 默认值： []
gather_subset 列表 / 元素=字符串	如果提供，则将收集的额外信息限制在给定的子集中。可能的值：all、all_ipv4_addresses、all_ipv6_addresses、apparmor、architecture、caps、chroot、cmdline、date_time、default_ipv4、default_ipv6、devices、distribution、distribution_major_version、distribution_release、distribution_version、dns、effective_group_ids、effective_user_id、env、facter、fips、hardware、interfaces、is_chroot、iscsi、kernel、local、lsb、machine、machine_id、mounts、network、ohai、os_family、pkg_mgr、platform、processor、processor_cores、processor_count、python、python_version、real_user_id、selinux、service_mgr、ssh_host_key_dsa_public、ssh_host_key_ecdsa_public、ssh_host_key_ed25519_public、ssh_host_key_rsa_public、ssh_host_pub_keys、ssh_pub_keys、system、system_capabilities、system_capabilities_enforced、systemd、user、user_dir、user_gecos、user_gid、user_id、user_shell、user_uid、virtual、virtualization_role、virtualization_type。可以指定一个值列表来指定更大的子集。值也可以与初始的!一起使用，以指定不应收集该特定子集。例如：!hardware,!network,!virtual,!ohai,!facter。如果指定了!all，则仅收集最小子集。为了避免收集最小子集，请指定!all,!min。要仅收集特定信息，请使用!all,!min，并指定特定的信息子集。如果您不想显示某些收集的信息，请使用filter参数。 默认值： ["all"]
gather_timeout 整数	设置单个信息收集的默认超时时间（以秒为单位）。 默认值： 10

属性

属性	支持	描述
check_mode	支持： 完全支持	可以在检查模式下运行并返回更改状态预测，而无需修改目标，如果不受支持，则操作将被跳过。
diff_mode	支持： 不支持	在差异模式下，将返回有关已更改内容（或可能需要在检查模式下更改的内容）的详细信息
facts	支持： 完全支持	操作返回一个ansible_facts字典，该字典将更新现有的主机信息
platform	平台： posix、windows	可以对其进行操作的目标操作系统/系列

备注

注意

• 随着后续版本的发布，将添加更多ansible信息。如果安装了facter或ohai，则这些程序中的变量也将被快照到JSON文件中，以便在模板中使用。这些变量以facter_和ohai_为前缀，因此很容易知道它们的来源。所有变量都冒泡到调用方。使用ansible信息并选择不安装facter和ohai意味着您可以避免在远程系统上使用Ruby依赖项。（另请参阅community.general.facter和community.general.ohai。）

• filter选项仅过滤ansible_facts下的一级子键。

• 如果目标主机是Windows，则目前您将无法使用filter，因为这是由模块的更简单的实现提供的。

• 此模块应在BSD系统上以提升的权限运行，以收集诸如ansible_product_version之类的信息。

• 有关委托信息的更多信息，请查看https://docs.ansible.org.cn/ansible/latest/user_guide/playbooks_delegation.html#delegating-facts。

示例

# Display facts from all hosts and store them indexed by `hostname` at `/tmp/facts`.
# ansible all -m ansible.builtin.setup --tree /tmp/facts

# Display only facts regarding memory found by ansible on all hosts and output them.
# ansible all -m ansible.builtin.setup -a 'filter=ansible_*_mb'

# Display only facts returned by facter.
# ansible all -m ansible.builtin.setup -a 'filter=facter_*'

# Collect only facts returned by facter.
# ansible all -m ansible.builtin.setup -a 'gather_subset=!all,facter'

- name: Collect only facts returned by facter
  ansible.builtin.setup:
    gather_subset:
      - '!all'
      - '!<any valid subset>'
      - facter

- name: Filter and return only selected facts
  ansible.builtin.setup:
    filter:
      - 'ansible_distribution'
      - 'ansible_machine_id'
      - 'ansible_*_mb'

# Display only facts about certain interfaces.
# ansible all -m ansible.builtin.setup -a 'filter=ansible_eth[0-2]'

# Restrict additional gathered facts to network and virtual (includes default minimum facts)
# ansible all -m ansible.builtin.setup -a 'gather_subset=network,virtual'

# Collect only network and virtual (excludes default minimum facts)
# ansible all -m ansible.builtin.setup -a 'gather_subset=!all,network,virtual'

# Do not call puppet facter or ohai even if present.
# ansible all -m ansible.builtin.setup -a 'gather_subset=!facter,!ohai'

# Only collect the default minimum amount of facts:
# ansible all -m ansible.builtin.setup -a 'gather_subset=!all'

# Collect no facts, even the default minimum subset of facts:
# ansible all -m ansible.builtin.setup -a 'gather_subset=!all,!min'

# Display facts from Windows hosts with custom facts stored in C:\custom_facts.
# ansible windows -m ansible.builtin.setup -a "fact_path='c:\custom_facts'"

# Gathers facts for the machines in the dbservers group (a.k.a Delegating facts)
- hosts: app_servers
  tasks:
    - name: Gather facts from db servers
      ansible.builtin.setup:
      delegate_to: "{{ item }}"
      delegate_facts: true
      loop: "{{ groups['dbservers'] }}"

作者

• Ansible核心团队

• Michael DeHaan

集合链接

• 问题跟踪器
• 仓库（源代码）
• 通信