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

注意

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

概要 

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

参数 

参数	注释
fact_path 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	支持：完全支持	可以在check_mode下运行并返回更改状态预测，而无需修改目标，如果不支持，则会跳过该操作。
diff_mode	支持：不支持	在差异模式下，将返回有关已更改内容（或可能需要在check_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，因为这是由模块的更简单的实现提供的。
为了收集诸如ansible_product_version之类的信息，此模块应在BSD系统上以提升的权限运行。
有关委托事实的更多信息，请查看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

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

概要

参数

属性

备注

示例

作者

集合链接

概要 

参数 

属性 

备注 

示例 