get_url

Содержание

get_url#

Модуль ansible.builtin.get_url предназначен для загрузки файлов по HTTP, HTTPS или FTP на управляемые узлы. Эти узлы должны иметь прямой доступ к ресурсам по указанным URI.

Особенности работы#

Особенности использования модуля ansible.builtin.get_url:

Если на управляемом узле установлены переменные окружения прокси, такие как http_proxy, https_proxy или ftp_proxy, все соответствующие запросы будут отправляться через указанные прокси-серверы. Чтобы изменить это поведение, используйте один из следующих способов:
- Задайте нужную переменную окружения для конкретной задачи, например:
```
---
- hosts: all
remote_user: root
tasks:
  - name: Install cobbler
    ansible.builtin.package:
      name: cobbler
      state: present
    environment:
      http_proxy: http://proxy.example.com:8080
```
- Укажите для этого модуля параметр use_proxy.
Запросы могут перенаправляться с HTTP на HTTPS. Убедитесь, что настройки прокси заданы корректно для обоих протоколов.
При запуске сценария с параметром --check (в режиме проверки без фактического выполнения) файл не будет загружен. В этом режиме Ansible не проверяет контрольную сумму файла и может ошибочно указать, что файл будет изменен, даже если на самом деле он не отличается от уже существующего.

Примечание

В режиме проверки модуль вместо загрузки файла выполняет запрос HEAD. Этот HTTP-запрос не загружает содержимое, а только проверяет доступность файла и его метаданные по указанному URL.
Для загрузки файлов на управляемые узлы под управлением ОС Windows используйте модуль ansible.windows.win_get_url.

Параметры#

Модуль принимает следующие параметры:

attributes, attr#

Изменение атрибутов целевого файла после загрузки на управляемые узлы. Чтобы узнать о поддерживаемых атрибутах, обратитесь к руководству chattr в целевой системе:

man chattr

Значение параметра должно представлять собой строку, содержащую атрибуты в порядке, принятом в выводе lsattr в целевой системе. Строка также может включать один из следующих операторов:

= – установить строго указанный набор атрибутов;
+ – добавить указанные атрибуты к существующим;
- – удалить указанные атрибуты из существующих.

Если оператор не указан, используется оператор =. Это значит, что будут сброшены все ранее установленные атрибуты, кроме явно указанных в строке.

backup#

Создание резервной копии целевого файла перед заменой.

Возможные значения:

false – не создавать резервную копию;
true – создавать резервную копию.

Значение по умолчанию: false.

checksum#

Контрольная сумма для проверки целостности загружаемого файла и успешности завершения передачи. Модуль вычисляет хеш загруженного файла и сравнивает со значением этого параметра.

Формат значения:

<algorithm>:<checksum_or_url>

Здесь:

<algorithm> – алгоритм хеширования;
<checksum_or_url> – контрольная сумма или URL-адрес, по которому ее можно получить.

Например:

Контрольная сумма

checksum: "sha1:2fd4e1c67a2d28fced849ee1bb76e7391b93eb12"

URL

checksum: "sha256:http://example.com/path/sha1sum.txt"

Для расчета хеша используется библиотека Python hashlib. Набор доступных алгоритмов зависит от версий Python и OpenSSL/LibreSSL. Универсальным выбором является SHA-1, этот алгоритм поддерживается во всех версиях Python и на всех платформах.

Внимание

В системах, работающих в режиме, совместимом со стандартом FIPS, алгоритм MD5 может быть недоступен.

Если файл уже существует по пути, указанному в параметре dest, Ansible вычислит хеш существующего файла (destination_checksum) и сравнит его со значением, указанным в параметре checksum. Если значения совпадают и force=false, загрузка будет пропущена. В противном случае файл будет загружен заново с перезаписью старой версии.

Если для доступа к хешу требуется авторизация, используйте параметры url_username и url_password.

Значение по умолчанию: "".

ciphers#

Список шифров SSL/TLS, которые следует использовать при выполнении запроса.

Для указания нескольких шифров одной строкой используйте : в качестве разделителя, например:

ciphers: "ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-SHA"

Список поддерживаемых шифров зависит от версий Python и OpenSSL/LibreSSL.

client_cert#

Путь к файлу с клиентским сертификатом в формате PEM, используемым для аутентификации по TLS/SSL.

Файл может содержать приватный ключ. В этом случае не требуется указывать параметр client_key.

client_key#

Путь к файлу с приватным ключом клиентского сертификата в формате PEM.

Если ключ уже содержится в файле, указанном в client_cert, этот параметр указывать не требуется.

decompress#

Попытка автоматически распаковать ответ, сжатый с использованием кодировки gzip.

Возможные значения:

false – не распаковывать;
true – пытаться распаковать содержимое.

Значение по умолчанию: true.

dest#

Обязательный параметр.

Абсолютный путь для загрузки файла в целевой системе.

Если в качестве значения указан каталог, то:

Загружаемый файл получит название, возвращенное сервером. Если сервер не указал название, то используется название файла из URL (например, из URL https://example.com/files/archive.zip будет взято archive.zip).
Значения параметров force и checksum игнорируются. Файл загружается в любом случае, но перезаписывается только при изменении содержимого.

force#

Перезапись существующего файла.

Если force=true и dest – не каталог, то файл будет загружаться каждый раз, если его содержимое отличается.

Если force=false, то файл будет загружаться только в случае его отсутствия в расположении, указанном в параметре dest.

Возможные значения:

false – перезаписывать только при отсутствии;
true – принудительно загружать и заменять.

Рекомендуется использовать это значение только для файлов небольшого размера.

Значение по умолчанию: false.

force_basic_auth#

Принудительная отправка заголовка Authorization: Basic в первоначальном запросе.

Модуль использует библиотеку httplib2. Она отправляет учетные данные только после получения от веб-сервера ответа со статусом 401. Важно отслеживать это, поскольку некоторые базовые сервисы аутентификации не отправляют код состояния 401, из-за чего аутентификация не сможет быть пройдена без force_basic_auth. В этом случае аутентификация без использования параметра force_basic_auth не сработает.

Возможные значения:

false – не отправлять заголовок в первоначальном запросе;
true – принудительно отправлять заголовок в первоначальном запросе.

Значение по умолчанию: false.

group#

Название группы, которой будет принадлежать загруженный файл. Параметр работает как утилита chown.

Если значение не задано, используется основная (primary) группа пользователя, от имени которого выполняется задача. При выполнении задачи с привилегиями root предыдущая группа-владелец может быть сохранена.

headers#: Пользовательские HTTP-заголовки в формате словаря (hash/dict) для отправки с запросом.

http_agent#

Заголовок User-Agent, отображаемый на стороне сервера.

Значение по умолчанию: ansible-httpget.

mode#

Режим доступа к загруженному файлу.

Значения могут быть следующих типов:

Восьмеричное число, например, 0644 или 0755. Обязательно указывать с ведущим нулем или в кавычках:
- 0644;
- '644'.
Если указать значение без кавычек или ведущего нуля, Ansible обработает его как десятичное число, что приведет к непредсказуемому результату.
Строковое значение, например, u=rw,g=r,o=r или u+rwx,g+rx,o=r.

Поведение по умолчанию:

если файл уже существует, режим доступа сохраняется;
если файл не существует, режим доступа определяется системным значением umask на управляемом узле.

Предупреждение

Рекомендуется всегда явно задавать значение параметра mode, чтобы избежать назначения небезопасных или непредсказуемых режимов доступа. См. описание уязвимости CVE-2020-1736.

owner#

Название учетной записи пользователя, которому будет принадлежать загруженный файл. Параметр работает как утилита chown.

Если значение параметра не указано, владельцем становится активный пользователь. При выполнении задачи с привилегиями root предыдущий владелец будет сохранен.

Если используется числовое значение, владельцем становится пользователь с указанным идентификатором. Во избежание непредсказуемых назначений избегайте числовых значений.

selevel#

Уровень копируемого файла или каталога в контексте безопасности SELinux.

Представляет собой MLS/MCS-атрибут, также известный как range, который задает уровень доступа к объекту в системе с включенным SELinux.

Если установлено значение _default, используется уровень по умолчанию из политики SELinux для данного объекта (если такая политика определена).

serole#

Роль копируемого файла или каталога в контексте безопасности SELinux.

Если установлено значение _default, используется роль по умолчанию из политики SELinux для данного объекта (если такая политика определена).

setype#

Тип копируемого файла или каталога в контексте безопасности SELinux.

Если установлено значение _default, используется тип по умолчанию из политики SELinux для данного объекта (если такая политика определен).

seuser#

Пользователь копируемого файла или каталога в контексте безопасности SELinux.

Если значение не указано, используется системная политика определения пользователя.

Если установлено значение _default, используется пользователь по умолчанию из политики SELinux для данного объекта (если такая политика определена).

timeout#

Время ожидания (в секундах) при выполнении запроса по URL.

Значение по умолчанию: 10.

tmp_dest#

Абсолютный путь, по которому будет временно сохранен загружаемый файл.

Значение по умолчанию: значение переменной remote_tmp.

unredirected_headers#

Список HTTP-заголовков, которые не будут передаваться при автоматических перенаправлениях.

Список нечувствителен к регистру.

Может быть полезно для исключения, например, заголовка Authorization, чтобы предотвратить утечку учетных данных.

Значение по умолчанию: [] (передаются все заголовки).

unsafe_writes#

Использование атомарной записи для предотвращения повреждения данных или несогласованного чтения целевого файлового объекта.

По умолчанию модуль использует атомарные операции записи, при которых данные сначала записываются во временный файл, а затем временный файл заменяет целевой. Это исключает возможность считывания неполных или поврежденных данных другим процессом во время записи.

На некоторых системах (например, при работе с томами Docker) атомарные операции могут быть недоступны или вызывать ошибки. В этом случае установка значения true позволяет Ansible выполнить небезопасную (неатомарную) запись напрямую в целевой файл.

Предупреждение

Небезопасная запись может привести к состоянию гонки и повреждению данных.

Возможные значения:

false – атомарные операции обязательны. При их невозможности задача завершится с ошибкой.
true – если атомарная запись невозможна, используется небезопасный способ записи.

Значение по умолчанию: false.

url#

Обязательный параметр.

URL-адрес для загрузки.

Поддерживаются схемы: http, https, ftp.

Формат:

(http|https|ftp)://[user[:pass]@]host[:port]/path

url_password, password#

Пароль для базовой HTTP-аутентификации (HTTP Basic Auth).

Значение этого параметра игнорируется, если не задано значение параметра url_username.

url_username, username#

Название учетной записи для базовой HTTP-аутентификации (HTTP Basic Auth).

Может использоваться без параметра url_password, если сервер допускает пустой пароль.

use_gssapi#

Использование GSSAPI при выполнении запроса.

Для использования параметра необходима библиотека Python gssapi.

Учетные данные можно передать следующими способами:

указать значения для параметров url_username и url_password;
установить переменную окружения KRB5CCNAME, указывающую на кеш учетных данных Kerberos.

Внимание

Аутентификация NTLM не поддерживается, даже если установлен механизм GSSAPI для NTLM.

Возможные значения:

false – не использовать GSSAPI;
true – использовать GSSAPI.

Значение по умолчанию: false.

use_netrc#

Использование файла ~/.netrc для получения учетных данных при базовой HTTP-аутентификации (HTTP Basic Auth).

Возможные значения:

false – игнорировать ~/.netrc;
true – использовать ~/.netrc.

Значение по умолчанию: true.

use_proxy#

Использование прокси.

Возможные значения:

false – не использовать прокси, даже если иное указано в переменной среды в целевой системе;
true – использовать прокси.

Значение по умолчанию: true.

validate_certs#

Проверка сертификата TLS при загрузке файла с сервера.

Возможные значения:

true – включена;
false – выключена.

Предупреждение

Используйте это значение только в случае загрузки файла с собственного сервера, использующего самоподписанный сертификат.

Значение по умолчанию: true.

Возвращаемые значения#

В этом списке указаны только возвращаемые значения, специфичные для модуля ansible.builtin.get_url.

backup_file – название файла резервной копии, созданной после загрузки.

Условия: целевой файл был изменен и backup=true.
checksum_dest – контрольная сумма SHA-1 целевого файла после загрузки.

Условия: успешное выполнение задачи.
checksum_src – контрольная сумма SHA-1 исходного файла.

Условия: успешное выполнение задачи.
dest – путь к файлу в целевом системе.

Условия: успешное выполнение задачи.
elapsed – количество секунд, затраченное на выполнение загрузки.

Условия: всегда.
gid – идентификатор группы-владельца целевого файла.

Условия: успешное выполнение задачи.
group – название группы-владельца целевого файла.

Условия: успешное выполнение задачи.
md5sum – контрольная сумма MD5 файла после загрузки.

Условия: если поддерживается в целевой системе.
mode – права доступа к целевому файлу.

Условия: успешное выполнение задачи.
msg – сообщение HTTP-запроса.

Условия: всегда.
owner – название учетной записи пользователя-владельца файла после выполнения задачи.

Условия: успешное выполнение задачи.
secontext – контекст безопасности SELinux целевого файла.

Условия: успешное выполнение задачи.
size – размер целевого файла в байтах.

Условия: успешное выполнение задачи.
src – абсолютный путь к временному файлу, полученному в ходе загрузки.

Условия: всегда.
state – состояние целевого объекта после выполнения задачи.

Условия: успешное выполнение задачи.
status_code – HTTP-код состояния, полученный в ответ на запрос.

Условия: всегда.
uid – идентификатор учетной записи пользователя-владельца файла после выполнения задачи.

Условия: успешное выполнение задачи.
url – фактически использованный URL-адрес для загрузки.

Условия: всегда.

Атрибуты#

Атрибуты определяют функции Ansible, которые может использовать модуль.

Атрибут	Описание
`check_mode`	Модуль частично поддерживает режим проверки (`check_mode`). Возвращаемое значение `changed` определяется сравнением с пустым файлом источника.
`diff_mode`	Модуль не поддерживает режим сравнения (`diff_mode`).
`platform`	Модуль поддерживает только POSIX-совместимые ОС.

Примеры#

Для изучения возможностей модуля ознакомьтесь с приведенными ниже примерами.

Загрузка файла с установкой прав доступа#

Следующий пример описывает загрузку конфигурационного файла с установкой прав 644:

---
- name: Download config file with specific permissions
  ansible.builtin.get_url:
    url: https://download.example.org/configs/app.conf
    dest: /etc/myapp/app.conf
    mode: "644"

Загрузка файла с базовой HTTP-аутентификацией#

Следующий пример описывает загрузку файла, требующего базовой аутентификации:

---
- name: Download file with basic authentication
  ansible.builtin.get_url:
    url: https://download.example.org/private/archive.tar.gz
    dest: /opt/archive.tar.gz
    url_username: admin
    url_password: supersecret
    force_basic_auth: true

Загрузка файла с пользовательскими HTTP-заголовками#

Следующий пример описывает передачу заголовков при загрузке файла:

---
- name: Download file with custom headers
  ansible.builtin.get_url:
    url: https://download.example.org/api/v1/resource
    dest: /tmp/resource.json
    headers:
      X-Api-Key: myapikey
      Accept: application/json

Загрузка файла с проверкой контрольной суммы по URL#

Следующий пример описывает загрузку файла с проверкой контрольной суммы, размещенной на удаленном ресурсе:

---
- name: Download ISO and verify checksum from remote file
  ansible.builtin.get_url:
    url: https://download.example.org/iso/my-os.iso
    dest: /tmp/my-os.iso
    checksum: sha256:https://download.example.org/iso/my-os.iso.sha256

Загрузка скрипта установки из репозитория#

Следующий пример описывает загрузку скрипта установки из удаленного репозитория:

---
- name: Download setup script from public repository
  ansible.builtin.get_url:
    url: https://raw.githubusercontent.com/example-org/tools/main/setup.sh
    dest: /usr/local/bin/setup.sh
    mode: "755"

Загрузка файла через прокси-сервер#

Следующий пример описывает использование прокси для загрузки файла:

---
- name: Download file using a proxy
  ansible.builtin.get_url:
    url: http://example.com/resources/tool.tar.gz
    dest: /opt/tool.tar.gz
  environment:
    http_proxy: http://proxy.example.org:3128
    https_proxy: http://proxy.example.org:3128