ansible.builtin.fetch 模块 – 从远程节点获取文件

注意

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

摘要 

此模块的工作方式类似于 ansible.builtin.copy，但方向相反。
它用于从远程机器获取文件并将其存储在本地文件树中，按主机名组织。
如果 dest 中已存在的文件与 src 不同，则会覆盖它们。
此模块也支持 Windows 目标。

注意

此模块具有相应的 action 插件。

参数 

参数	注释
dest 字符串 / 必需	保存文件的目录。例如，如果 `dest` 目录是 `/backup`，主机 `host.example.com` 上名为 `/etc/profile` 的 `src` 文件将保存到 `/backup/host.example.com/etc/profile`。主机名基于清单名称。
fail_on_missing 布尔值	设置为 `true` 时，如果由于任何原因无法读取远程文件，则任务将失败。在 Ansible 2.5 之前，设置此选项只会因源文件丢失而失败。在 Ansible 2.5 中，默认值已更改为 `true`。选项 `false` `true` ← (默认)
flat 布尔值	允许您覆盖将主机名/路径/到/文件追加到目标的默认行为。如果 `dest` 以 ‘/’ 结尾，它将使用源文件的基名，类似于 copy 模块。如果使用单个主机，或者如果检索的文件在每个主机上都是唯一命名的，这将非常有用。如果使用多个主机且文件名相同，则每个主机的文件将被覆盖。选项 `false` ← (默认) `true`
src 字符串 / 必需	要从中获取的远程系统上的文件。这必须是一个文件，而不是一个目录。递归获取可能会在以后的版本中支持。
validate_checksum 布尔值	验证获取文件后源和目标校验和是否匹配。选项 `false` `true` ← (默认)

属性 

属性	支持	描述
action	支持：完全支持	表示它有一个对应的 action 插件，因此可以在控制器上执行某些选项。
async	支持：不支持	支持与 `async` 关键字一起使用。
bypass_host_loop	支持：不支持	强制执行不按主机执行的“全局”任务，这将绕过按主机模板化以及串行、节流和其他循环考虑因素。条件将按使用 `run_once` 的方式工作，使用的变量将来自第一个可用主机。此操作在非锁步策略之外通常无法正常工作。
check_mode	支持：完全支持	可以在 check_mode 下运行并返回已更改状态预测，而无需修改目标，如果不受支持，则将跳过操作。
diff_mode	支持：完全支持	在 diff 模式下，将返回有关已更改内容（或可能需要在 check_mode 中更改的内容）的详细信息。
platform	平台： posix、windows	可以对其进行操作的目标操作系统/系列。
safe_file_operations	支持：不支持	使用 Ansible 的严格文件操作功能来确保正确的权限并避免数据损坏。
vault	支持：不支持	可以自动解密 Ansible 加密的 vault 文件。

备注 

注意

使用 become 运行 fetch 时，还将使用 ansible.builtin.slurp 模块来获取文件的内容以确定远程校验和。这实际上使传输大小加倍，并且根据文件大小，可能会消耗远程或本地主机上的所有可用内存，从而导致 MemoryError。因此，建议尽可能在没有 become 的情况下运行此模块。
在 Ansible 2.5 之前，除非设置了 fail_on_missing，否则此模块在读取远程文件失败时不会失败。
在 Ansible 2.5 或更高版本中，建议剧本编写者使用 fail_when 或 ignore_errors 来实现此功能。他们也可以显式地将 fail_on_missing 设置为 false 以获得非失败行为。

参见 

另请参见

ansible.builtin.copy: 将文件复制到远程位置。
ansible.builtin.slurp: 从远程节点读取文件内容。

示例 

- name: Store file into /tmp/fetched/host.example.com/tmp/somefile
  ansible.builtin.fetch:
    src: /tmp/somefile
    dest: /tmp/fetched

- name: Specifying a path directly
  ansible.builtin.fetch:
    src: /tmp/somefile
    dest: /tmp/prefix-{{ inventory_hostname }}
    flat: yes

- name: Specifying a destination path
  ansible.builtin.fetch:
    src: /tmp/uniquefile
    dest: /tmp/special/
    flat: yes

- name: Storing in a path relative to the playbook
  ansible.builtin.fetch:
    src: /tmp/uniquefile
    dest: special/prefix-{{ inventory_hostname }}
    flat: yes

作者

Ansible核心团队
Michael DeHaan