Расширения

Расширения#

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

Описание работы различных типов расширений см. в документе Расширение.

Повышение привилегий#

Расширение

Описание

Пример

ansible.builtin.runas

Выполнение задач от имени другого пользователя в Windows.

 
---
# ...
  tasks:
    - name: Install application as Administrator
      ansible.windows.win_package:
        path: C:\\installers\\app.msi
        state: present
      become: true
      become_method: ansible.builtin.runas
      become_user: Administrator

ansible.builtin.su

Выполнение задач от имени другого пользователя в Linux.

 
---
# ...
  tasks:
    - name: Pull execution environment image from Private Automation Hub
      ansible.builtin.shell: "podman pull {{ ee_image }}"
      become: true
      become_method: ansible.builtin.su
      become_user: {{ privileged_user }}

ansible.builtin.sudo

Выполнение задач с привилегиями администратора в Linux.

 
---
# ...
  tasks:
    - name: Restart nginx service with sudo
      ansible.builtin.service:
        name: nginx
        state: restarted
      become: true
      become_method: ansible.builtin.sudo

Кеширование#

Расширение

Описание

Пример

ansible.builtin.jsonfile

Сохранение кеша в виде файлов формата JSON.

 
[defaults]
fact_caching = ansible.builtin.jsonfile
fact_caching_connection = /tmp/ansible_facts
fact_caching_timeout = 7200

ansible.builtin.memory

Временное хранение фактов в оперативной памяти. Используется только в рамках текущего процесса.

 
[defaults]
fact_caching = ansible.builtin.memory

Обратный вызов#

Расширение

Описание

Пример

ansible.builtin.default

Вывод данных в стандартный поток.

 
[defaults]
stdout_callback = ansible.builtin.default

ansible.builtin.junit

Вывод результата работы набора сценариев в формате JUnit XML.

 
[defaults]
stdout_callback = ansible.builtin.junit
junit_output_dir = /tmp/junit-reports

ansible.builtin.minimal

Вывод только ключевой информации о выполнении задач.

 
[defaults]
stdout_callback = ansible.builtin.minimal

ansible.builtin.oneline

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

 
[defaults]
stdout_callback = ansible.builtin.oneline

ansible.builtin.tree

Сохранение результатов выполнения сценариев в виде файлов в формате JSON.

 
[defaults]
callback_whitelist = ansible.builtin.tree
tree_dir = /tmp/ansible-output

Соединение#

Расширение

Описание

Пример

ansible.builtin.local

Локальное выполнение задач на управляющем узле.

 
---
# ...
  hosts: localhost
  connection: ansible.builtin.local
  tasks:
    - name: Run local task
      ansible.builtin.shell: echo "Running locally"

ansible.builtin.paramiko_ssh

Подключение по протоколу SSH через библиотеку Python Paramiko.

 
[defaults]
connection = ansible.builtin.paramiko_ssh

ansible.builtin.psrp

Подключение к узлам Windows по протоколу PSRP.

 
[defaults]
connection = ansible.builtin.psrp

ansible.builtin.ssh

Подключение по протоколу SSH.

 
[defaults]
connection = ansible.builtin.ssh

ansible.builtin.winrm

Подключение к узлам Windows по протоколу WinRM.

 
[defaults]
connection = ansible.builtin.winrm

Фильтры#

Расширение

Описание

Пример

ansible.builtin.b64decode

Декодирование строки из формата Base64.

 
---
# ...
  tasks:
    - name: Decode Base64 string
      ansible.builtin.debug:
        msg: "{{ 'SGVsbG8gd29ybGQ=' | ansible.builtin.b64decode }}"

ansible.builtin.b64encode

Кодирование строки в формат Base64.

 
---
# ...
  tasks:
    - name: Encode string to Base64
      ansible.builtin.debug:
        msg: "{{ 'Hello world' | ansible.builtin.b64encode }}"

ansible.builtin.basename

Получение базового названия файла или каталога из полного пути.

 
---
# ...
  tasks:
    - name: Get basename of file path
      ansible.builtin.debug:
        msg: "{{ '/etc/nginx/nginx.conf' | ansible.builtin.basename }}"

ansible.builtin.bool

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

 
---
# ...
  vars:
    feature_enabled: "yes"
  tasks:
    - name: Convert string to boolean
      ansible.builtin.debug:
        msg: "{{ feature_enabled | ansible.builtin.bool }}"

ansible.builtin.checksum

Вычисление контрольной суммы по алгоритму SHA-1.

 
---
# ...
  tasks:
    - name: Calculate checksum of string
      ansible.builtin.debug:
        msg: "{{ 'important content' | ansible.builtin.checksum }}"

ansible.builtin.combinations

Формировка всех возможных комбинаций элементов списка.

 
---
# ...
  tasks:
    - name: Generate combinations
      ansible.builtin.debug:
        msg: "{{ [1, 2, 3] | ansible.builtin.combinations(2) }}"

ansible.builtin.combine

Объединение нескольких словарей в один.

 
---
# ...
  vars:
    dict1: {a: 1, b: 2}
    dict2: {b: 3, c: 4}
  tasks:
    - name: Merge dictionaries
      ansible.builtin.debug:
        msg: "{{ dict1 | ansible.builtin.combine(dict2) }}"

ansible.builtin.comment

Добавление комментариев.

 
---
# ...
  tasks:
    - name: Comment a line
      ansible.builtin.debug:
        msg: "{{ 'MaxConnections 100' | ansible.builtin.comment('#') }}"

ansible.builtin.commonpath

Получение части пути, общей для путей из указанного списка.

 
---
# ...
  tasks:
    - name: Find common path
      ansible.builtin.debug:
        msg: "{{ ['/etc/nginx/nginx.conf', '/etc/dev'] | ansible.builtin.commonpath }}"

ansible.builtin.dict2items

Преобразование словаря в список пар типа ключ-значение.

 
---
# ...
  vars:
    my_dict: {one: 1, two: 2}
  tasks:
    - name: Convert dict to items
      ansible.builtin.debug:
        msg: "{{ my_dict | ansible.builtin.dict2items }}"

ansible.builtin.difference

Вычисление разницы между двумя списками.

 
---
# ...
  vars:
    list1: [a, b, c]
    list2: [b, c]
  tasks:
    - name: Show difference between lists
      ansible.builtin.debug:
        msg: "{{ list1 | ansible.builtin.difference(list2) }}"

ansible.builtin.dirname

Получение названия каталога из полного пути.

 
---
# ...
  tasks:
    - name: Get directory from path
      ansible.builtin.debug:
        msg: "{{ '/var/log/syslog' | ansible.builtin.dirname }}"

ansible.builtin.expanduser

Замена символа ~ в пути на абсолютный путь к домашнему каталогу пользователя.

 
---
# ...
  tasks:
    - name: Expand tilde to home directory
      ansible.builtin.debug:
        msg: "{{ '~/.ssh/id_rsa' | ansible.builtin.expanduser }}"

ansible.builtin.expandvars

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

 
---
# ...
  tasks:
    - name: Expand environment variable
      ansible.builtin.debug:
        msg: "{{ '$HOME/.ssh' | ansible.builtin.expandvars }}"

ansible.builtin.extract

Извлечение значения по индексу или ключу из структуры.

 
---
# ...
  vars:
    my_dict: {"key1": "value1", "key2": "value2"}
  tasks:
    - name: Extract value by key
      ansible.builtin.debug:
        msg: "{{ my_dict | ansible.builtin.extract('key2') }}"

ansible.builtin.fileglob

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

 
---
# ...
  tasks:
    - name: List configuration files
      ansible.builtin.debug:
        msg: "{{ '/etc/nginx/*.conf' | ansible.builtin.fileglob }}"

ansible.builtin.flatten

Выравнивание вложенных списков до указанного значения.

 
---
# ...
  vars:
    nested_list: [[1, 2], [3, 4]]
  tasks:
    - name: Flatten nested list
      ansible.builtin.debug:
        msg: "{{ nested_list | ansible.builtin.flatten }}"

ansible.builtin.from_json

Преобразование строки в формате JSON в словарь Ansible.

 
---
# ...
  vars:
    json_data: '{"name": "admin", "role": "devops"}'
  tasks:
    - name: Parse JSON string
      ansible.builtin.debug:
        msg: "{{ json_data | ansible.builtin.from_json }}"

ansible.builtin.from_yaml

Преобразование строки в формате YAML в словарь Ansible.

 
---
# ...
  vars:
    yaml_data: "name: admin\nrole: devops"
  tasks:
    - name: Parse YAML string
      ansible.builtin.debug:
        msg: "{{ yaml_data | ansible.builtin.from_yaml }}"

ansible.builtin.from_yaml_all

Преобразование строки с несколькими документами YAML в список словарей Ansible.

 
---
# ...
  vars:
    multi_yaml: |
      ---
      kind: Deployment
      name: backend
      ---
      kind: Service
      name: backend-svc
  tasks:
    - name: Parse multi-document YAML
      ansible.builtin.debug:
        msg: "{{ multi_yaml | ansible.builtin.from_yaml_all }}"

ansible.builtin.hash

Вычисление хеша данных по указанному алгоритму.

 
---
# ...
  tasks:
    - name: Hash password with SHA256
      ansible.builtin.debug:
        msg: "{{ 'supersecret' | ansible.builtin.hash('sha256') }}"

ansible.builtin.human_readable

Преобразование битов и байтов в удобочитаемый формат.

 
---
# ...
  tasks:
    - name: Convert bytes to readable format
      ansible.builtin.debug:
        msg: "{{ 15728640 | ansible.builtin.human_readable }}"

ansible.builtin.human_to_bytes

Преобразование строки в удобочитаемом формате в число байтов.

 
---
# ...
  tasks:
    - name: Convert human size to bytes
      ansible.builtin.debug:
        msg: "{{ '15 MB' | ansible.builtin.human_to_bytes }}"

ansible.builtin.intersect

Поиск пересечения элементов в списках.

 
---
# ...
  vars:
    list1: ['nginx', 'postgres', 'redis']
    list2: ['redis', 'mysql']
  tasks:
    - name: Find common packages
      ansible.builtin.debug:
        msg: "{{ list1 | ansible.builtin.intersect(list2) }}"

ansible.builtin.items2dict

Преобразование списка пар типа ключ-значение в словарь.

 
---
# ...
  vars:
    pairs:
      - {'key': 'env', 'value': 'prod'}
      - {'key': 'debug', 'value': false}
  tasks:
    - name: Convert pairs to dict
      ansible.builtin.debug:
        msg: "{{ pairs | ansible.builtin.items2dict }}"

ansible.builtin.log

Вычисление логарифма числа.

 
---
# ...
  tasks:
    - name: Calculate natural log
      ansible.builtin.debug:
        msg: "{{ 100 | ansible.builtin.log }}"

ansible.builtin.mandatory

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

 
---
# ...
  vars:
    # the secret_token variable is not defined
  tasks:
    - name: Fail if secret_token is not set
      ansible.builtin.debug:
        msg: "{{ secret_token | ansible.builtin.mandatory }}"

ansible.builtin.md5

Вычисление хеша данных по алгоритму MD5.

 
---
# ...
  tasks:
    - name: Calculate MD5 hash of a string
      ansible.builtin.debug:
        msg: "{{ 'important_data' | ansible.builtin.md5 }}"

ansible.builtin.normpath

Нормализация пути к файлу или каталогу путем удаления лишних слешей и обработки переходов к вышестоящим каталогам.

 
---
# ...
  tasks:
    - name: Normalize a path
      ansible.builtin.debug:
        msg: "{{ '/var/www/../index.html' | ansible.builtin.normpath }}"

ansible.builtin.password_hash

Вычисление хеша пароля.

 
---
# ...
  vars:
    plain_password: "MySecretPass123"
  tasks:
    - name: Generate password hash
      ansible.builtin.debug:
        msg: "{{ plain_password | ansible.builtin.password_hash('sha512') }}"

ansible.builtin.path_join

Объединение компонентов пути.

 
---
# ...
  vars:
    parts:
      - "/var"
      - "log"
      - "ansible"
  tasks:
    - name: Join path components
      ansible.builtin.debug:
        msg: "{{ parts | ansible.builtin.path_join }}"

ansible.builtin.permutations

Генерация всех перестановок элементов списка.

 
---
# ...
  vars:
    my_list: [1, 2, 3]
  tasks:
    - name: Generate all permutations of a list
      ansible.builtin.debug:
        msg: "{{ my_list | ansible.builtin.permutations }}"

ansible.builtin.pow

Возведение числа в степень.

 
---
# ...
  tasks:
    - name: Calculate power of a number
      ansible.builtin.debug:
        msg: "{{ 5 | ansible.builtin.pow(3) }}"  # 5 в кубе

ansible.builtin.product

Декартово произведение списков.

 
---
# ...
  vars:
    list1: [1, 2]
    list2: ['a', 'b']
  tasks:
    - name: Generate Cartesian product of two lists
      ansible.builtin.debug:
        msg: "{{ [list1, list2] | ansible.builtin.product }}"

ansible.builtin.quote

Экранирование строки.

 
---
# ...
  vars:
    unsafe_string: "some string with spaces & special$chars"
  tasks:
    - name: Escape string for safe usage
      ansible.builtin.debug:
        msg: "{{ unsafe_string | ansible.builtin.quote }}"

ansible.builtin.random

Выбор случайного числа или элемента.

 
---
# ...
  vars:
    ports: [8080, 8081, 8082]
  tasks:
    - name: Choose random port from list
      ansible.builtin.debug:
        msg: "{{ ports | ansible.builtin.random }}"

ansible.builtin.realpath

Преобразование относительного пути в абсолютный.

 
---
# ...
  tasks:
    - name: Convert relative path to absolute
      ansible.builtin.debug:
        msg: "{{ './configs/nginx.conf' | ansible.builtin.realpath }}"

ansible.builtin.regex_escape

Экранирование специальных символов в регулярных выражениях.

 
---
# ...
  vars:
    user_input: "a+b*c?"
  tasks:
    - name: Escape regex special characters
      ansible.builtin.debug:
        msg: "{{ user_input | ansible.builtin.regex_escape }}"

ansible.builtin.regex_findall

Поиск всех совпадений по регулярному выражению.

 
---
# ...
  vars:
    text: "error: fail at line 10; error: fail at line 25"
    pattern: "error: [^;]+"
  tasks:
    - name: Find all error messages
      ansible.builtin.debug:
        msg: "{{ text | ansible.builtin.regex_findall(pattern) }}"

ansible.builtin.regex_replace

Замена фрагмента строки по регулярному выражению.

 
---
# ...
  vars:
    path: "/home/user//folder///file.txt"
    pattern: "/+"
    replacement: "/"
  tasks:
    - name: Normalize path by replacing multiple slashes
      ansible.builtin.debug:
        msg: "{{ path | ansible.builtin.regex_replace(pattern, replacement) }}"

ansible.builtin.regex_search

Поиск первого совпадения по регулярному выражению.

 
---
# ...
  vars:
    text: "User: admin, Role: root"
    pattern: "Role: (\\w+)"
  tasks:
    - name: Extract user role from string
      ansible.builtin.debug:
        msg: "{{ (text | ansible.builtin.regex_search(pattern)).groups()[0] }}"

ansible.builtin.rekey_on_member

Преобразование списка словарей в один словарь, где ключи берутся из одного из полей (членов) каждого словаря.

 
---
# ...
  vars:
    users:
      - id: 1
        name: "alice"
      - id: 2
        name: "bob"
  tasks:
    - name: Rekey list of dicts by 'id'
      ansible.builtin.debug:
        msg: "{{ users | ansible.builtin.rekey_on_member('id') }}"

ansible.builtin.relpath

Преобразование абсолютного пути в относительный.

 
---
# ...
  vars:
    start: "/home/user/project"
    target: "/home/user/project/src/module/file.py"
  tasks:
    - name: Get relative path from start to target
      ansible.builtin.debug:
        msg: "{{ target | ansible.builtin.relpath(start) }}"

ansible.builtin.root

Извлечение корня из числа.

 
---
# ...
  tasks:
    - name: Calculate square root of 16
      ansible.builtin.debug:
        msg: "{{ 16 | ansible.builtin.root(2) }}"

ansible.builtin.sha1

Вычисление хеша строки по алгоритму SHA-1.

 
---
# ...
  vars:
    secret: "supersecret"
  tasks:
    - name: Compute SHA-1 hash
      ansible.builtin.debug:
        msg: "{{ secret | ansible.builtin.sha1 }}"

ansible.builtin.shuffle

Перемешивание элементов списка.

 
---
# ...
  vars:
    servers: ["node1", "node2", "node3"]
  tasks:
    - name: Shuffle list of servers
      ansible.builtin.debug:
        msg: "{{ servers | ansible.builtin.shuffle }}"

ansible.builtin.split

Преобразование строки в список с помощью разделителя.

 
---
# ...
  vars:
    data: "one,two,three"
  tasks:
    - name: Split string by comma
      ansible.builtin.debug:
        msg: "{{ data | ansible.builtin.split(',') }}"

ansible.builtin.splitext

Разделение пути на название файла и расширение.

 
---
# ...
  vars:
    filepath: "/tmp/archive.tar.gz"
  tasks:
    - name: Split file path into name and extension
      ansible.builtin.debug:
        msg: "{{ filepath | ansible.builtin.splitext }}"

ansible.builtin.strftime

Форматирование даты и времени по шаблону.

 
---
# ...
  vars:
    timestamp: 1689993600
    format: "%Y-%m-%d %H:%M:%S"
  tasks:
    - name: Format timestamp as readable date
      ansible.builtin.debug:
        msg: "{{ timestamp | ansible.builtin.strftime(format) }}"

ansible.builtin.subelements

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

 
---
# ...
  vars:
    servers:
      - name: "server1"
        ips:
          - "10.0.0.1"
          - "10.0.0.2"
      - name: "server2"
        ips:
          - "10.0.1.1"
  tasks:
    - name: Loop over servers and their IPs
      ansible.builtin.debug:
        msg: "Server {{ item.0.name }} has IP {{ item.1 }}"
      loop: "{{ servers | ansible.builtin.subelements('ips') }}"

ansible.builtin.symmetric_difference

Возврат элементов, уникальных для обоих списков.

 
---
# ...
  vars:
    list_a: ["nginx", "mysql", "redis"]
    list_b: ["mysql", "postgres", "redis"]
  tasks:
    - name: Find symmetric difference between two lists
      ansible.builtin.debug:
        msg: "{{ list_a | ansible.builtin.symmetric_difference(list_b) }}"

ansible.builtin.ternary

Условный тернарный оператор.

 
---
# ...
  vars:
    is_enabled: true
  tasks:
    - name: Use ternary operator
      ansible.builtin.debug:
        msg: "{{ is_enabled | ansible.builtin.ternary('Enabled', 'Disabled') }}"

ansible.builtin.to_datetime

Преобразование строки в объект datetime.

 
---
# ...
  vars:
    raw_date: "2024-01-15T14:00:00Z"
  tasks:
    - name: Convert to datetime object
      ansible.builtin.debug:
        msg: "{{ raw_date | ansible.builtin.to_datetime('%Y-%m-%dT%H:%M:%SZ') }}"

ansible.builtin.to_json

Преобразование переменной или структуры данных Ansible в строку формата JSON.

 
---
# ...
  vars:
    user:
      name: "admin"
      role: "root"
  tasks:
    - name: Convert dict to JSON string
      ansible.builtin.debug:
        msg: "{{ user | ansible.builtin.to_json }}"

ansible.builtin.to_nice_json

Преобразование переменной в удобочитаемый JSON.

 
---
# ...
  vars:
    config:
      app: "myapp"
      version: 2
  tasks:
    - name: Pretty-print JSON
      ansible.builtin.debug:
        msg: "{{ config | ansible.builtin.to_nice_json }}"

ansible.builtin.to_nice_yaml

Преобразование переменной в удобочитаемый YAML.

 
---
# ...
  vars:
    data:
      key: value
      number: 123
  tasks:
    - name: Convert to pretty YAML
      ansible.builtin.debug:
        msg: "{{ data | ansible.builtin.to_nice_yaml }}"

ansible.builtin.to_uuid

Генерация UUID версии 5.

 
---
# ...
  tasks:
    - name: Generate UUID
      ansible.builtin.debug:
        msg: "{{ '' | ansible.builtin.to_uuid }}"

ansible.builtin.to_yaml

Преобразование переменной в строку в формате YAML.

 
---
# ...
  vars:
    list:
      - apple
      - banana
  tasks:
    - name: Convert list to YAML
      ansible.builtin.debug:
        msg: "{{ list | ansible.builtin.to_yaml }}"

ansible.builtin.type_debug

Определение типа переменной.

 
---
# ...
  vars:
    var: 42
  tasks:
    - name: Show variable type
      ansible.builtin.debug:
        msg: "{{ var | ansible.builtin.type_debug }}"

ansible.builtin.union

Объединение двух списков с удалением дубликатов.

 
---
# ...
  vars:
    a: [1, 2, 3]
    b: [3, 4]
  tasks:
    - name: Union of lists
      ansible.builtin.debug:
        msg: "{{ a | ansible.builtin.union(b) }}"

ansible.builtin.unique

Удаление дубликатов из списка.

 
---
# ...
  vars:
    values: [1, 2, 2, 3, 1]
  tasks:
    - name: Remove duplicates
      ansible.builtin.debug:
        msg: "{{ values | ansible.builtin.unique }}"

ansible.builtin.unvault

Расшифровка данных, зашифрованных с помощью Ansible Vault.

 
---
# ...
  vars:
    secret: !vault |
      $ANSIBLE_VAULT;1.1;AES256
      ...
  tasks:
    - name: Decrypt vault variable
      ansible.builtin.debug:
        msg: "{{ secret | ansible.builtin.unvault }}"

ansible.builtin.urldecode

Декодирование строк URL.

 
---
# ...
  vars:
    encoded: "name%3Dvalue%26id%3D42"
  tasks:
    - name: Decode URL
      ansible.builtin.debug:
        msg: "{{ encoded | ansible.builtin.urldecode }}"

ansible.builtin.urlsplit

Разделение URL на компоненты.

 
---
# ...
  vars:
    full_url: "https://example.com:8080/path?query=value"
  tasks:
    - name: Split URL into parts
      ansible.builtin.debug:
        msg: "{{ full_url | ansible.builtin.urlsplit }}"

ansible.builtin.vault

Шифрование данных с помощью Ansible Vault.

 
---
# ...
  vars:
    secret: "my_secret_value"
  tasks:
    - name: Encrypt with vault
      ansible.builtin.debug:
        msg: "{{ secret | ansible.builtin.vault }}"

ansible.builtin.win_basename

Получение названия файла из пути в ОС Windows.

 
---
# ...
  vars:
    win_path: "C:\\Users\\Admin\\document.txt"
  tasks:
    - name: Get basename from Windows path
      ansible.builtin.debug:
        msg: "{{ win_path | ansible.builtin.win_basename }}"

ansible.builtin.win_dirname

Получение каталога из пути в ОС Windows.

 
---
# ...
  vars:
    win_path: "D:\\Games\\Steam\\steam.exe"
  tasks:
    - name: Get dirname from Windows path
      ansible.builtin.debug:
        msg: "{{ win_path | ansible.builtin.win_dirname }}"

ansible.builtin.win_splitdrive

Разделение пути на диск и остальной путь в ОС Windows.

 
---
# ...
  vars:
    win_path: "E:\\Data\\backup.zip"
  tasks:
    - name: Split Windows path into drive and path
      ansible.builtin.debug:
        msg: "{{ win_path | ansible.builtin.win_splitdrive }}"

ansible.builtin.zip

Объединение элементов нескольких списков параллельно.

 
---
# ...
  vars:
    keys: ["name", "age"]
    values: ["Alice", 30]
  tasks:
    - name: Zip keys and values
      ansible.builtin.debug:
        msg: "{{ keys | ansible.builtin.zip(values) }}"

ansible.builtin.zip_longest

Объединение нескольких списков в список списков (кортежей) с совмещением элементов с одинаковыми индексами.

 
---
# ...
  vars:
    x: ["a", "b"]
    y: [1]
  tasks:
    - name: Zip longest lists
      ansible.builtin.debug:
        msg: "{{ x | ansible.builtin.zip_longest(y, fillvalue='N/A') }}"

Инвентарь#

Расширение

Описание

Пример

ansible.builtin.advanced_host_list

Обработка шаблонов узлов с диапазонами.

 
---
# ...
  hosts: all[1:3]
  tasks:
    - ansible.builtin.debug:
        msg: "Running on {{ inventory_hostname }}"

ansible.builtin.auto

Автоматическое определение расширения инвентаря.

 
[defaults]
inventory = auto_inventory.yaml

ansible.builtin.constructed

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

 
---
# ...
  plugin: ansible.builtin.constructed
  strict: false
  groups:
    alse: ansible_facts['os_family'] == "Astra Linux"

ansible.builtin.generator

Создание узлов и групп узлов на основе шаблонов с использованием Jinja2 и файла конфигурации в формате YAML.

 
---
# ...
  plugin: ansible.builtin.generator
  hosts:
    count: 3
    name: "vm{{ item }}"
    loop_control:
      loop_var: item

ansible.builtin.host_list

Указание списка узлов в виде строки, разделенной запятыми.

 
---
- name: Example using host_list
  hosts: server1,server2
  gather_facts: no
  tasks:
    - name: Check availability
      ansible.builtin.ping:
      # ...

ansible.builtin.ini

Использование файла инвентаря в формате INI.

 
[web]
server1
server2 ansible_host=10.1.1.2

ansible.builtin.script

Использование внешнего сценария в качестве источника инвентаря.

 
#!/bin/bash
echo '{
  "web": {
    "hosts": ["server1", "server2"]
  }
}'

ansible.builtin.toml

Использование файла инвентаря в формате TOML.

 
[web]
hosts = ["host1", "host2"]

ansible.builtin.yaml

Использование файла инвентаря в формате YAML.

 
---
all:
  children:
    web:
      hosts:
        host1:
        host2:

Поиск#

Расширение

Описание

Пример

ansible.builtin.config

Получение действующих настроек Ansible.

 
---
# ...
  tasks:
    - name: Show default config value
      ansible.builtin.debug:
        msg: "{{ lookup('ansible.builtin.config', 'DEFAULT_TIMEOUT') }}"

ansible.builtin.csvfile

Чтение данных из файла в формате CSV или TSV.

 
---
# ...
  vars:
    user_data: "{{ lookup('ansible.builtin.csvfile', 'users.csv') }}"
  tasks:
    - name: Show user data
      ansible.builtin.debug:
        msg: "{{ user_data }}"

ansible.builtin.dict

Преобразование словаря в список элементов типа ключ-значение.

 
---
# ...
  vars:
    my_dict: { "a": 1, "b": 2 }
  tasks:
    - name: Loop over dict
      ansible.builtin.debug:
        msg: "{{ item.key }} => {{ item.value }}"
      loop: "{{ lookup('ansible.builtin.dict', my_dict) }}"

ansible.builtin.env

Чтение значения переменной окружения.

 
---
# ...
  tasks:
    - name: Show environment variable
      ansible.builtin.debug:
        msg: "{{ lookup('ansible.builtin.env', 'HOME') }}"

ansible.builtin.file

Чтение содержимого файла.

 
---
# ...
  tasks:
    - name: Read config file
      ansible.builtin.debug:
        msg: "{{ lookup('ansible.builtin.file', 'config.txt') }}"

ansible.builtin.fileglob

Возврат списка файлов, соответствующих шаблону.

 
---
# ...
  tasks:
    - name: List files
      ansible.builtin.debug:
        msg: "{{ lookup('ansible.builtin.fileglob', '*.conf', wantlist=True) }}"

ansible.builtin.first_found

Возврат первого найденного файла из списка в соответствии с заданным списком путей или шаблонов.

 
---
# ...
  vars:
    params:
      files:
        - settings.yml
        - default.yml
  tasks:
    - name: Load config
      ansible.builtin.debug:
        msg: "{{ lookup('ansible.builtin.first_found', params) }}"

ansible.builtin.indexed_items

Возврат списка элементов с их индексами.

 
---
# ...
  vars:
    mylist: ["alpha", "beta"]
  tasks:
    - name: Show indexed items
      ansible.builtin.debug:
        msg: "{{ item.0 }}: {{ item.1 }}"
      loop: "{{ lookup('ansible.builtin.indexed_items', mylist) }}"

ansible.builtin.ini

Чтение данных из файла в формате INI.

 
---
# ...
  tasks:
    - name: Read setting from INI
      ansible.builtin.debug:
        msg: "{{ lookup('ansible.builtin.ini', 'my_key', file='settings.ini', section='my_section') }}"

ansible.builtin.inventory_hostnames

Получение списка узлов из инвентаря по шаблону.

 
---
# ...
  tasks:
    - name: Get web hosts
      ansible.builtin.debug:
        msg: "{{ lookup('ansible.builtin.inventory_hostnames', 'web') }}"

ansible.builtin.items

Перечисление элементов списка.

 
---
# ...
  vars:
    servers: ['srv1', 'srv2']
  tasks:
    - name: Iterate over items
      ansible.builtin.debug:
        msg: "{{ item }}"
      loop: "{{ lookup('ansible.builtin.items', servers) }}"

ansible.builtin.lines

Разбиение текста на строки.

 
---
# ...
  vars:
    raw_output: |
      line1
      line2
  tasks:
    - name: Print lines
      ansible.builtin.debug:
        msg: "{{ item }}"
      loop: "{{ lookup('ansible.builtin.lines', raw_output) }}"

ansible.builtin.list

Преобразование значения в список.

 
---
# ...
  vars:
    csv_string: "a,b,c"
  tasks:
    - name: Convert to list
      ansible.builtin.debug:
        msg: "{{ lookup('ansible.builtin.list', csv_string.split(',')) }}"

ansible.builtin.nested

Формирование вложенных пар из нескольких списков.

 
---
# ...
  vars:
    x: [1, 2]
    y: ['a', 'b']
  tasks:
    - name: Show combinations
      ansible.builtin.debug:
        msg: "{{ item }}"
      loop: "{{ lookup('ansible.builtin.nested', x, y) }}"

ansible.builtin.password

Генерация и сохранение пароля в файл или возврат ранее сгенерированного пароля, если файл уже существует.

 
---
# ...
  tasks:
    - name: Generate password
      ansible.builtin.debug:
        msg: "{{ lookup('ansible.builtin.password', '/tmp/secret.txt', length=8) }}"

ansible.builtin.pipe

Возврат результата выполнения команды.

 
---
# ...
  tasks:
    - name: Get current user
      ansible.builtin.debug:
        msg: "{{ lookup('ansible.builtin.pipe', 'whoami') }}"

ansible.builtin.random_choice

Выбор случайного значения из списка.

 
---
# ...
  vars:
    servers: ['srv1', 'srv2', 'srv3']
  tasks:
    - name: Pick random server
      ansible.builtin.debug:
        msg: "{{ lookup('ansible.builtin.random_choice', servers) }}"

ansible.builtin.sequence

Генерация числовой последовательности.

 
---
# ...
  tasks:
    - name: Show numbers
      ansible.builtin.debug:
        msg: "{{ item }}"
      loop: "{{ lookup('ansible.builtin.sequence', start=1, end=3) }}"

ansible.builtin.subelements

Объединение родительских и вложенных элементов.

 
---
# ...
  vars:
    users:
      - name: alice
        groups: ['admin', 'dev']
  tasks:
    - name: Show subelements
      ansible.builtin.debug:
        msg: "{{ item }}"
      loop: "{{ lookup('ansible.builtin.subelements', users, 'groups') }}"

ansible.builtin.template

Рендеринг шаблона Jinja2 из файла.

 
---
# ...
  tasks:
    - name: Render Jinja2 template
      ansible.builtin.debug:
        msg: "{{ lookup('ansible.builtin.template', 'mytemplate.j2') }}"

ansible.builtin.together

Группировка нескольких списков по элементам.

 
---
# ...
  vars:
    a: [1, 2]
    b: ['x', 'y']
  tasks:
    - name: Show zipped lists
      ansible.builtin.debug:
        msg: "{{ lookup('ansible.builtin.together', a, b) }}"

ansible.builtin.unvault

Расшифровка данных, зашифрованных с помощью Ansible Vault.

 
---
# ...
  tasks:
    - name: Load secret data
      ansible.builtin.debug:
        msg: "{{ lookup('ansible.builtin.unvault', 'secrets.yml') }}"

ansible.builtin.url

Загрузка содержимого по URL.

 
---
# ...
  tasks:
    - name: Download content
      ansible.builtin.debug:
        msg: "{{ lookup('ansible.builtin.url', 'https://example.com/data.txt') }}"

ansible.builtin.varnames

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

 
---
# ...
  vars:
    my_var_1: one
    my_var_2: two
  tasks:
    - name: Find matching vars
      ansible.builtin.debug:
        msg: "{{ lookup('ansible.builtin.varnames', 'my_var_*') }}"

ansible.builtin.vars

Получение значения переменной по названию.

 
---
# ...
  vars:
    user: "admin"
  tasks:
    - name: Access variable dynamically
      ansible.builtin.debug:
        msg: "{{ lookup('ansible.builtin.vars', 'user') }}"

Оболочки#

Расширение

Описание

Пример

ansible.builtin.cmd

Выполнение команд в командной строке Windows.

 
---
# ...
  tasks:
    - name: Run Windows command with cmd
      ansible.builtin.win_command: "net use"

ansible.builtin.powershell

Выполнение команд в Windows PowerShell.

 
---
# ...
  tasks:
    - name: Run PowerShell script
      ansible.builtin.win_shell: |
        Get-Service | Where-Object {$_.Status -eq "Running"}

ansible.builtin.sh

Выполнение команд в /bin/sh.

 
---
# ...
  tasks:
    - name: Run shell command with /bin/sh
      ansible.builtin.shell: |
        echo "User: $(whoami)"

Стратегии#

Расширение

Описание

Пример

ansible.builtin.debug

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

 
[defaults]
strategy = debug

ansible.builtin.free

Параллельное выполнение задач на узлах без ожидания синхронизации.

 
[defaults]
strategy = free

ansible.builtin.host_pinned

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

 
[defaults]
strategy = host_pinned

ansible.builtin.linear

Линейная стратегия с синхронным выполнением задач.

 
[defaults]
strategy = linear

Тестирование#

Расширение

Описание

Пример

ansible.builtin.abs

Проверка, является ли путь абсолютным.

 
---
# ...
  vars:
    my_path: "/etc/hosts"
  tasks:
    - name: Check if path is absolute
      ansible.builtin.debug:
        msg: "Absolute path"
      when: my_path is ansible.builtin.abs

ansible.builtin.all

Проверка, что все элементы в списке истинные.

 
---
# ...
  vars:
    services_status: [true, true, true]
  tasks:
    - name: All services are running
      ansible.builtin.debug:
        msg: "All good"
      when: services_status is ansible.builtin.all

ansible.builtin.any

Проверка, что хотя бы один элемент в списке истинный.

 
---
# ...
  vars:
    services_status: [false, false, true]
  tasks:
    - name: At least one service is up
      ansible.builtin.debug:
        msg: "Something is alive"
      when: services_status is ansible.builtin.any

ansible.builtin.changed

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

 
---
# ...
  tasks:
    - name: Install package
      package:
        name: httpd
        state: present
      register: result

    - name: Notify on change
      ansible.builtin.debug:
        msg: "Package was installed"
      when: result is ansible.builtin.changed

ansible.builtin.contains

Проверка наличия элемента в списке.

 
---
# ...
  vars:
    user_groups: ['admins', 'wheel']
  tasks:
    - name: Is user in admins group?
      ansible.builtin.debug:
        msg: "Access granted"
      when: user_groups is ansible.builtin.contains('admins')

ansible.builtin.directory

Проверка, что путь указывает на существующий каталог.

 
---
# ...
  vars:
    dir_path: "/var/log"
  tasks:
    - name: Clean directory
      file:
        path: "{{ dir_path }}"
        state: absent
      when: dir_path is ansible.builtin.directory

ansible.builtin.exists

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

 
---
# ...
  vars:
    config_path: "/etc/myapp/config.yml"
  tasks:
    - name: Config exists
      ansible.builtin.debug:
        msg: "Using existing config"
      when: config_path is ansible.builtin.exists

ansible.builtin.failed

Проверка, завершилась ли задача с ошибкой.

 
---
# ...
  tasks:
    - name: Run a command that may fail
      ansible.builtin.command: /bin/false
      register: result
      ignore_errors: true

    - name: Notify if previous task failed
      ansible.builtin.debug:
        msg: "Previous task failed"
      when: result is ansible.builtin.failed

ansible.builtin.falsy

Определение, является ли значение логически ложным.

 
---
# ...
  vars:
    my_flag: false
  tasks:
    - name: Skip if flag is falsy
      ansible.builtin.debug:
        msg: "Nothing to do"
      when: my_flag is ansible.builtin.falsy

ansible.builtin.file

Проверка, что путь указывает на файл.

 
---
# ...
  vars:
    config_path: "/etc/app.conf"
  tasks:
    - name: Validate file
      ansible.builtin.debug:
        msg: "Valid file"
      when: config_path is ansible.builtin.file

ansible.builtin.finished

Проверка, завершена ли асинхронная задача.

 
---
# ...
  tasks:
    - name: Wait for async result
      async_status:
        jid: "{{ job_result.ansible_job_id }}"
      register: async_status_result

    - name: Check if finished
      ansible.builtin.debug:
        msg: "Async task done"
      when: async_status_result is ansible.builtin.finished

ansible.builtin.link

Проверка, что объект по пути является символической ссылкой.

 
---
# ...
  vars:
    target_path: "/usr/bin/mytool"
  tasks:
    - name: Check if symlink
      ansible.builtin.debug:
        msg: "This is a symlink"
      when: target_path is ansible.builtin.link

ansible.builtin.link_exists

Проверка существования пути, включая символические ссылки.

 
---
# ...
  vars:
    link_path: "/usr/local/bin/app"
  tasks:
    - name: Link exists
      ansible.builtin.debug:
        msg: "Valid symlink"
      when: link_path is ansible.builtin.link_exists

ansible.builtin.match

Проверка соответствия строки регулярному выражению.

 
---
# ...
  vars:
    my_email: "admin@example.com"
  tasks:
    - name: Validate email
      ansible.builtin.debug:
        msg: "Valid email"
      when: my_email is ansible.builtin.match("^[\\w.-]+@[\\w.-]+\\.[a-zA-Z]{2,}$")

ansible.builtin.mount

Проверка, что путь является точкой монтирования.

 
---
# ...
  vars:
    mount_path: "/mnt/data"
  tasks:
    - name: Mounted check
      ansible.builtin.debug:
        msg: "Mount point OK"
      when: mount_path is ansible.builtin.mount

ansible.builtin.nan

Обнаружение значений NaN.

 
---
# ...
  vars:
    result_value: "NaN"
  tasks:
    - name: Handle NaN
      ansible.builtin.debug:
        msg: "Not a number"
      when: result_value is ansible.builtin.nan

ansible.builtin.reachable

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

 
---
# ...
  tasks:
    - name: Try to ping host
      ansible.builtin.ping:
      register: result
      ignore_unreachable: true

    - name: Notify if host is unreachable
      ansible.builtin.debug:
        msg: "Host unreachable"
      when: result is not ansible.builtin.reachable

ansible.builtin.regex

Проверка строки на полное соответствие регулярному выражению.

 
---
# ...
  vars:
    username: "admin_01"
  tasks:
    - name: Username matches pattern
      ansible.builtin.debug:
        msg: "Valid username"
      when: username is ansible.builtin.regex("^[a-zA-Z0-9_]+$")

ansible.builtin.same_file

Проверка, указывают ли два пути на один и тот же файл.

 
---
# ...
  vars:
    src: "/etc/hosts"
    dst: "/private/etc/hosts"
  tasks:
    - name: Check file identity
      ansible.builtin.debug:
        msg: "Same file"
      when: src is ansible.builtin.same_file(dst)

ansible.builtin.search

Проверка наличия совпадения строки с регулярным выражением.

 
---
# ...
  vars:
    log_line: "ERROR: Disk full"
  tasks:
    - name: Error found in log
      ansible.builtin.debug:
        msg: "Disk issue detected"
      when: log_line is ansible.builtin.search("disk", ignorecase=True)

ansible.builtin.skipped

Проверка, была ли задача пропущена.

 
---
# ...
  tasks:
    - name: Run optional step
      command: /usr/bin/false
      when: false
      register: maybe_skipped
      ignore_errors: true

    - name: Check if skipped
      ansible.builtin.debug:
        msg: "Task was skipped"
      when: maybe_skipped is ansible.builtin.skipped

ansible.builtin.started

Проверка, была ли асинхронная задача запущена.

 
---
# ...
  tasks:
    - name: Run an async job
      ansible.builtin.command: /bin/sleep 5
      async: 10
      poll: 0
      register: async_result

    - name: Check if async job started
      ansible.builtin.debug:
        msg: "Async job started"
      when: async_result is ansible.builtin.started

ansible.builtin.subset

Проверка, входит ли один список в состав другого.

 
---
# ...
  vars:
    required_roles: ['admin', 'user']
    actual_roles: ['user', 'admin', 'devops']
  tasks:
    - name: All required roles present
      ansible.builtin.debug:
        msg: "Access granted"
      when: required_roles is ansible.builtin.subset(actual_roles)

ansible.builtin.success

Проверка успешности выполнения задачи.

 
---
# ...
  tasks:
    - name: Try command
      command: /usr/bin/true
      register: try_result

    - name: Check success
      ansible.builtin.debug:
        msg: "Command succeeded"
      when: try_result is ansible.builtin.success

ansible.builtin.superset

Проверка, включает ли один список все элементы другого.

 
---
# ...
  vars:
    config_set: ['a', 'b', 'c']
    required: ['a', 'b']
  tasks:
    - name: Config covers requirements
      ansible.builtin.debug:
        msg: "Config is complete"
      when: config_set is ansible.builtin.superset(required)

ansible.builtin.truthy

Проверка, является ли значение логически истинным.

 
---
# ...
  vars:
    deploy_enabled: "yes"
  tasks:
    - name: Deploy is allowed
      ansible.builtin.debug:
        msg: "Proceeding with deployment"
      when: deploy_enabled is ansible.builtin.truthy

ansible.builtin.unreachable

Проверка, завершилась ли задача из-за полной недоступности узла.

 
---
# ...
  tasks:
    - name: Node unreachable
      ansible.builtin.debug:
        msg: "Host is unreachable"
      when: result is ansible.builtin.unreachable

ansible.builtin.uri

Проверка, является ли строка корректным URI.

 
---
# ...
  vars:
    endpoint: "urn:isbn:3250541540"
  tasks:
    - name: URI is valid
      ansible.builtin.debug:
        msg: "Valid resource reference"
      when: endpoint is ansible.builtin.uri

ansible.builtin.url

Проверка, является ли строка корректным URL.

 
---
# ...
  vars:
    endpoint: "https://api.example.com/v1/data"
  tasks:
    - name: Valid API URL
      ansible.builtin.debug:
        msg: "Ready to connect"
      when: endpoint is ansible.builtin.url

ansible.builtin.urn

Проверка, является ли строка корректным URN.

 
---
# ...
  vars:
    identifier: "urn:isbn:0451450523"
  tasks:
    - name: Valid URN
      ansible.builtin.debug:
        msg: "URN recognized"
      when: identifier is ansible.builtin.urn

ansible.builtin.vault_encrypted

Проверка, что строка зашифрована с помощью Ansible Vault.

 
---
# ...
  vars:
    secret_data: "$ANSIBLE_VAULT;1.1;AES256..."
  tasks:
    - name: Encrypted string
      ansible.builtin.debug:
        msg: "This is vault data"
      when: secret_data is ansible.builtin.vault_encrypted

ansible.builtin.version

Сравнение версии ПО.

 
---
# ...
  vars:
    current_version: "2.5.1"
  tasks:
    - name: Version is sufficient
      ansible.builtin.debug:
        msg: "Version OK"
      when: current_version is ansible.builtin.version('>=2.4')

Переменные#

Расширение

Описание

Пример

ansible.builtin.host_group_vars

Загрузка переменных из файлов в каталогах host_vars/ и group_vars/ с привязкой их к соответствующим группам и узлам из описания инвентаря.
ansible.cfg:#
[defaults]
yaml_valid_extensions = .yml, .yaml, .json

[vars_host_group_vars]
stage = all
group_vars/webservers.yml#
app_port: 8080
playbook.yml#
---
# ...
  tasks:
    - name: Show app port
      ansible.builtin.debug:
        msg: "App runs on port {{ app_port }}"