unarchive

Модуль ansible.builtin.unarchive распаковывает в файловую систему управляемых узлов содержимое указанного архива.

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

Особенности работы модуля ansible.builtin.unarchive:

• Для работы модуля на управляемом узле должны быть установлены соответствующие утилиты:

  • gtar – для работы с архивами .tar, .tar.gz, .tar.bz2 и .tar.xz;

  • unzip и zipinfo – для работы с архивами .zip;

  • zstd – для работы с архивами .tar.zst.

• Модуль не обрабатывает файлы .gz, .bz2, .xz и .zst, если они не находятся в архиве .tar.

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

• Модуль не будет распаковывать сжатый файл, которые не является архивом.

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

• Если архив уже загружен на управляемый узел, для его распаковки в значении параметра remote_src укажите true.

• Если требуется проверка контрольной суммы файла, задайте параметру remote_src значение true, а для загрузки архива используйте модуль ansible.builtin.get_url или ansible.builtin.uri.

• Для узлов под управлением ОС Windows используйте модуль community.windows.win_unzip.

Параметры

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

attributes, attr

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

man chattr

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

• = – установить строго указанный набор атрибутов;

• + – добавить указанные атрибуты к существующим;

• - – удалить указанные атрибуты из существующих.

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

creates

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

Путь, указанный в параметре dest, должен быть родительским по отношению к этому пути.

decrypt

Управление автоматической расшифровкой исходных файлов с использованием хранилища секретов.

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

• false – не расшифровывать файл;

• true – расшифровывать файл.

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

dest

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

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

Указанный путь должен существовать, так как модуль не создает недостающие каталоги.

exclude

Список названий файлов и каталогов, которые следует пропустить при распаковке архива.

Этот параметр нельзя использовать одновременно с include.

Значение по умолчанию: [] (пустой список).

extra_opts

Список дополнительных аргументов, передаваемых в команду распаковки.

Каждый аргумент, отделенный пробелом, должен быть указан в отдельном элементе списка.

Значение по умолчанию: [] (пустой список).

group

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

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

include

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

Этот параметр нельзя использовать одновременно с exclude.

Значение по умолчанию: [] (пустой список).

io_buffer_size

Количество оперативной памяти в байтах, используемое в качестве буфера при извлечении файлов из архива.

Значение по умолчанию: 65536 (64 КБ).

keep_newer

Сохранение существующих файлов, более новых, чем извлеченные из архива.

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

• false – выключено;

• true – включено.

Значение по умолчанию: false (файлы из архива заменят уже существующие в любом случае).

list_files

Возврат списка файлов, содержащихся в архиве.

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

• false – не возвращать;

• true – вернуть.

mode

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

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

• Восьмеричное число, например, 0644 или 0755. Обязательно указывать с ведущим нулем или в кавычках:

  • 0644;

  • '644'.

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

• Строковое значение, например, u=rw,g=r,o=r или u+rwx,g+rx,o=r.

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

• если файл или каталог на управляемом узле уже существует, режим доступа сохраняется;

• если объект создается заново и параметр mode не задан, режим доступа определяется системным значением umask на управляемом узле.

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

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

owner

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

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

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

remote_src

Поиск архива на управляемом узле.

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

• false – путь к архиву следует искать на управляющем узле;

• true – путь к архиву следует искать на управляемом узле или по URL, если параметр src содержит последовательность ://.

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

selevel

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

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

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

serole

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

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

setype

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

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

seuser

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

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

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

src

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

Значение этого параметра по-разному интерпретируется в зависимости от значения параметра remote_src:

• remote_src=false.

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

• remote_src=true.

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

• remote_src=true и src содержит ://.

  Управляемый узел загружает архив по указанному URI.

  Примечание

  Используйте это поведение только для простых случаев. Во всех остальных случаях использование модуля ansible.builtin.get_url более предпочтительно.

unsafe_writes

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

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

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

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

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

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

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

• true – если атомарная запись невозможна, будет использован небезопасный способ записи.

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

validate_certs

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

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

• false – проверка отключена.

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

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

• true – проверка выполняется.

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

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

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

• dest – путь к каталогу с распакованными файлами.

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

• files – список файлов в архиве.

  Условия: list_files=true.

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

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

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

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

• handler – обработчик архиватора, использованный для распаковки файлов.

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

• mode – режим доступа к каталогу с распакованными файлами и каталогами в восьмеричной системе счисления.

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

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

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

• size – размер каталога с распакованными файлами в байтах. При расчете значения не учитывается содержимое подкаталогов.

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

• src – путь к архиву. Если в значении параметра src указан URL, или архив загружается с управляющего узла, в значении этого поля указывается путь к временному файлу с архивом на управляемом узле.

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

• state – состояние каталога с распакованными файлами. Практически всегда это directory.

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

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

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

Атрибуты

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

Атрибут	Описание
action	Модуль имеет соответствующее расширение действия (action plugin). Это означает, что часть работы выполняется на управляющем узле.
async	Модуль не поддерживает асинхронное выполнение.
bypass_host_loop	Модуль не поддерживает глобальное выполнение задачи.
check_mode	Модуль частично поддерживает режим проверки. Режим проверки не поддерживается для архивов .tar.gz.
diff_mode	Модуль частично поддерживает режим сравнения. Если архиватор gtar не поддерживает аргумент --diff, модуль всегда распаковывает архив.
platform	Модуль поддерживает только POSIX-совместимые ОС.
safe_file_operations	Модуль не использует строгие механизмы Ansible для работы с файлами чтобы обеспечить правильные режимы доступа и предотвратить повреждение данных.
vault	Модуль поддерживает автоматическую расшифровку исходных файлов с использованием хранилища секретов.

Примеры

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

Распаковка архива в указанный каталог

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

---
- name: Upload from control node and extract
  ansible.builtin.unarchive:
    src: ./offline-bundle.zip
    dest: /opt/

Загрузка и распаковка архива средствами ansible.builtin.unarchive

Следующий пример описывает загрузку архива из внешнего источника и его распаковку с использованием только возможностей модуля ansible.builtin.unarchive:

---
- name: Download and unpack archive
  ansible.builtin.unarchive:
    src: https://download.dojotoolkit.org/release-1.17.3/dojo-release-1.17.3.tar.gz
    dest: /var/www/libs/
    remote_src: yes

Дополнительные аргументы вызова распаковщика

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

---
- name: Unpack and test
  ansible.builtin.unarchive:
    src: ./protected-archive.zip
    dest: /opt/rbta/
    extra_opts:
      - "-P p@ssW0rD"