Ansible模块——通过 URL 下载文件

通过 URL 下载文件

ansible.builtin.get_url 可以通过 URL 下载文件。

选项名	类型	默认值	描述
attributes	str	null	设置文件系统对象的属性，格式参考 lsattr；支持 +, -, = 操作符。别名：attr。
backup	bool	false	创建目标文件的备份副本（带时间戳）。
checksum	str	''	提供格式为 <算法>:<值> 的校验和，如 sha256:abcd1234...，用于校验完整性并决定是否跳过下载。
ciphers	list	null	指定 SSL/TLS 加密套件，多个套件以 : 连接。
client_cert	path	null	PEM 格式的客户端证书，可包含私钥。
client_key	path	null	客户端私钥 PEM 文件；若 client_cert 已包含，则可省略。
decompress	bool	true	自动解压 gzip 编码响应内容。
dest	path	—	下载文件保存的目标路径（必须）。若为目录，会使用服务器提供的文件名。
force	bool	false	是否强制下载（即使目标文件存在）。只在 dest 是文件时有效。
force_basic_auth	bool	false	是否强制初次请求就发送 Basic Auth 头信息（用于兼容不返回 401 的服务）。
group	str	null	目标文件所属的组名。默认继承当前用户组。
headers	dict	null	自定义 HTTP 请求头，格式为字典。
http_agent	str	ansible-httpget	请求时发送的 User-Agent 标识。
mode	raw	null	文件权限，如 0644、u=rw,g=r,o=r。建议使用字符串格式以避免意外。
owner	str	null	目标文件所属用户名。默认为当前用户。
selevel	str	null	SELinux 上下文的 level 部分。
serole	str	null	SELinux 上下文的 role 部分。
setype	str	null	SELinux 上下文的 type 部分。
seuser	str	null	SELinux 上下文的 user 部分。
timeout	int	10	URL 请求超时时间（秒）。
tmp_dest	path	null	下载临时文件的目录，默认 ~/.ansible/tmp/，可以通过 remote_tmp 在配置文件设置默认位置。
unredirected_headers	list	[]	不跟随重定向的 HTTP 头名称列表，适用于防止认证信息泄露。
unsafe_writes	bool	false	是否允许非原子写操作（如 Docker 下）。有数据一致性风险。
url	str	—	下载的 URL，支持 http、https 和 ftp。
url_password	str	null	HTTP 基本认证密码。别名：password。
url_username	str	null	HTTP 基本认证用户名。别名：username。
use_gssapi	bool	false	是否使用 GSSAPI（Kerberos）进行认证。需要安装 gssapi Python 库。
use_netrc	bool	true	是否使用 ~/.netrc 中的凭据。
use_proxy	bool	true	是否使用环境变量中的代理配置。
validate_certs	bool	true	是否校验 HTTPS 证书，设为 false 可跳过验证（如自签名证书）。

常用选项：

选项名	类型	默认值	描述
backup	bool	false	创建目标文件的备份副本（带时间戳）。
checksum	str	''	提供格式为 <算法>:<值> 的校验和，如 sha256:abcd1234...，用于校验完整性并决定是否跳过下载。
dest	path	—	下载文件保存的目标路径（必须）。若为目录，会使用服务器提供的文件名。
force	bool	false	是否强制下载（即使目标文件存在）。只在 dest 是文件时有效。
force_basic_auth	bool	false	是否强制初次请求就发送 Basic Auth 头信息（用于兼容不返回 401 的服务）。
group	str	null	目标文件所属的组名。默认继承当前用户组。
headers	dict	null	自定义 HTTP 请求头，格式为字典。
http_agent	str	ansible-httpget	请求时发送的 User-Agent 标识。
mode	raw	null	文件权限，如 0644、u=rw,g=r,o=r。建议使用字符串格式以避免意外。
owner	str	null	目标文件所属用户名。默认为当前用户。
timeout	int	10	URL 请求超时时间（秒）。
unredirected_headers	list	[]	不跟随重定向的 HTTP 头名称列表，适用于防止认证信息泄露。
url	str	—	下载的 URL，支持 http、https 和 ftp。
url_password	str	null	HTTP 基本认证密码。别名：password。
url_username	str	null	HTTP 基本认证用户名。别名：username。
use_proxy	bool	true	是否使用环境变量中的代理配置。
validate_certs	bool	true	是否校验 HTTPS 证书，设为 false 可跳过验证（如自签名证书）。

- name: Download foo.conf
  ansible.builtin.get_url:
    url: http://example.com/path/file.conf
    dest: /etc/foo.conf
    mode: '0440'

- name: Download file and force basic auth
  ansible.builtin.get_url:
    url: http://example.com/path/file.conf
    dest: /etc/foo.conf
    force_basic_auth: yes

- name: Download file with custom HTTP headers
  ansible.builtin.get_url:
    url: http://example.com/path/file.conf
    dest: /etc/foo.conf
    headers:
      key1: one
      key2: two

- name: Download file with check (sha256)
  ansible.builtin.get_url:
    url: http://example.com/path/file.conf
    dest: /etc/foo.conf
    checksum: sha256:b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c

- name: Download file with check (md5)
  ansible.builtin.get_url:
    url: http://example.com/path/file.conf
    dest: /etc/foo.conf
    checksum: md5:66dffb5228a211e61d6d7ef4a86f5758

- name: Download file with checksum url (sha256)
  ansible.builtin.get_url:
    url: http://example.com/path/file.conf
    dest: /etc/foo.conf
    checksum: sha256:http://example.com/path/sha256sum.txt

- name: Download file from a file path
  ansible.builtin.get_url:
    url: file:///tmp/afile.txt
    dest: /tmp/afilecopy.txt

- name: < Fetch file that requires authentication.
        username/password only available since 2.8, in older versions you need to use url_username/url_password
  ansible.builtin.get_url:
    url: http://example.com/path/file.conf
    dest: /etc/foo.conf
    username: bar
    password: '{{ mysecret }}'