Роли

Использование ролей на уровне сценария

Классический (исходный) способ использования ролей — параметр roles для заданного сценария:

---
- hosts: webservers
  roles:
    - common
    - webservers

При использовании параметра roles на уровне сценария каждая роль «x» ищет файл main.yml (а также main.yaml и main) в следующих каталогах:

• roles/x/tasks/
• roles/x/handlers/
• roles/x/vars/
• roles/x/defaults/
• roles/x/meta/
• Любые задачи копирования, запуска скриптов, использования шаблонов или подключения (в роли) могут ссылаться на файлы в roles/x/{files,templates,tasks}/ (каталог зависит от задачи), не указывая относительный или абсолютный путь.

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

• Все pre_tasks, определённые в сценарии.
• Все обработчики, вызванные задачами pre_tasks.
• Каждая роль, указанная в roles:, в указанном порядке. Сначала выполняются все зависимости роли, определённые в meta/main.yml этой роли, с учётом фильтрации по тегам и условий. Подробнее см. раздел Использование зависимостей ролей.
• Все tasks, определённые в сценарии.
• Все обработчики, вызванные ролями или задачами.
• Все post_tasks, определённые в сценарии.
• Все обработчики, вызванные задачами post_tasks.

Параметру roles можно передать и другие ключевые слова:

---
- hosts: webservers
  roles:
    - common
    - role: foo_app_instance
      vars:
        dir: '/opt/a'
        app_port: 5000
      tags: typeA
    - role: foo_app_instance
      vars:
        dir: '/opt/b'
        app_port: 5001
      tags: typeB

Если добавить тег к параметру role, Ansible применит его ко ВСЕМ задачам в роли.

Подключение ролей: динамическое повторное использование

Роли можно динамически повторно использовать в любом месте раздела tasks сценария с помощью include_role. Роли, добавленные в раздел roles, выполняются до любых других задач сценария, тогда как подключённые роли выполняются в том порядке, в котором они определены. Если перед задачей include_role есть другие задачи, сначала выполняются они.

Чтобы подключить роль:

---
- hosts: webservers
  tasks:
    - name: Print a message
      ansible.builtin.debug:
        msg: "this task runs before the example role"

    - name: Include the example role
      ansible.builtin.include_role:
        name: example

    - name: Print a message
      ansible.builtin.debug:
        msg: "this task runs after the example role"

При подключении ролей можно передавать другие ключевые слова, включая переменные и теги:

---
- hosts: webservers
  tasks:
    - name: Include the foo_app_instance role
      ansible.builtin.include_role:
        name: foo_app_instance
      vars:
        dir: '/opt/a'
        app_port: 5000
      tags: typeA
  # ...

Если добавить тег к задаче include_role, Ansible применит его только к самому подключению. Это значит, что можно передать --tags, чтобы запустить только выбранные задачи роли, если у этих задач есть тот же тег, что и у инструкции подключения. Подробнее см. в разделе Выборочный запуск задач с тегами в повторно используемых файлах.

Роль можно подключить по условию:

---
- hosts: webservers
  tasks:
    - name: Include the some_role role
      ansible.builtin.include_role:
        name: some_role
      when: "ansible_facts['os_family'] == 'RedHat'"

Импорт ролей: статическое повторное использование

Роли можно статически повторно использовать в любом месте раздела tasks сценария с помощью import_role. Это работает так же, как использование ключевого слова roles. Например:

---
- hosts: webservers
  tasks:
    - name: Print a message
      ansible.builtin.debug:
        msg: "before we run our role"

    - name: Import the example role
      ansible.builtin.import_role:
        name: example

    - name: Print a message
      ansible.builtin.debug:
        msg: "after we ran our role"

При импорте ролей можно передавать другие ключевые слова, включая переменные и теги:

---
- hosts: webservers
  tasks:
    - name: Import the foo_app_instance role
      ansible.builtin.import_role:
        name: foo_app_instance
      vars:
        dir: '/opt/a'
        app_port: 5000
  # ...

Если добавить тег к инструкции import_role, Ansible применит его ко всем задачам в роли. Подробнее см. в разделе Наследование тегов: добавление тегов к нескольким задачам.

Формат спецификации

Спецификация аргументов роли должна быть определена в блоке верхнего уровня argument_specs в файле meta/argument_specs.yml роли. Все поля записываются строчными буквами.

entry-point-name:

• Имя точки входа роли.
• Если точка входа не указана, здесь следует использовать main.
• Это будет основная часть имени файла задач, который нужно выполнить, без расширения файла .yml или .yaml.

short_description:

• Краткое описание точки входа в одну строку. В идеале это словосочетание, а не предложение.
• short_description отображается командой ansible-doc -t role -l.
• Оно также становится частью заголовка страницы роли в документации.
• Краткое описание всегда должно быть строкой, а не списком, и не должно заканчиваться точкой.
• В этом поле можно использовать разметку Ansible.

description:

• Более подробное описание, которое может содержать несколько строк.

• Это может быть одна строка или список строк. Если это список строк, каждый элемент

  списка становится новым абзацем.

• В этом поле можно использовать разметку Ansible.

version_added:

• Версия роли, в которой была добавлена точка входа.
• Это строка, а не число с плавающей точкой, например version_added: '2.1'.
• Для коллекций здесь должна указываться версия коллекции, в которой была добавлена точка входа. Например, version_added: 1.0.0.

author:

• Имена авторов точки входа.
• Это может быть одна строка или список строк. Для каждого автора используйте отдельный элемент списка. Если автор только один, укажите строку или список из одного элемента.

options:

• Параметры часто называют «параметрами» или «аргументами». В этом разделе определяются эти параметры.
• Для каждого параметра роли (аргумента) можно указать:

option-name:

• Имя параметра/аргумента.

description:

• Подробное объяснение назначения этого параметра. Оно должно быть написано полными предложениями.
• Это может быть одна строка или список строк. Если это список строк, каждый его элемент становится новым абзацем.
• В этом поле можно использовать разметку Ansible.

version_added:

• Указывается только в том случае, если параметр добавлен после первоначального выпуска роли/точки входа. Иными словами, это значение больше, чем значение поля верхнего уровня version_added.
• Это строка, а не число с плавающей точкой, например version_added: '2.1'.
• Для коллекций здесь должна указываться версия коллекции, в которой был добавлен параметр. Например, version_added: 1.0.0.

type:

• Тип данных параметра. Допустимые значения для type см. в разделе Спецификация аргументов. Значение по умолчанию — str.
• Если параметр имеет тип list, необходимо указать elements.

required:

• Требуется только в том случае, если true.
• Если поле отсутствует, параметр не является обязательным.

default:

• Если required равно false или отсутствует, можно указать default (если поле отсутствует, предполагается null).
• Убедитесь, что значение по умолчанию в документации совпадает со значением по умолчанию в коде. Фактическое значение по умолчанию для переменной роли всегда берётся из значений роли по умолчанию (определённых в разделе Структура каталогов роли).
• Поле default не следует указывать в описании, если только для него не требуется дополнительная информация или условия.
• Если параметр имеет логическое значение, для совместимости с ansible-lint следует использовать true/false.

choices:

• Список значений параметра.
• Если список пуст, его следует опустить.

elements:

• Задаёт тип данных элементов списка, если тип — list.

options:

• Если параметр принимает словарь или список словарей, здесь можно определить его структуру.

Пример спецификации

# roles/myapp/meta/argument_specs.yml
---
argument_specs:
  # roles/myapp/tasks/main.yml entry point
  main:
    short_description: Main entry point for the myapp role
    description:
      - This is the main entrypoint for the C(myapp) role.
      - Here we can describe what this entrypoint does in lengthy words.
      - Every new list item is a new paragraph. You can have multiple sentences
        per paragraph.
    author:
      - Daniel Ziegenberg
    options:
      myapp_int:
        type: "int"
        required: false
        default: 42
        description:
          - "The integer value, defaulting to 42."
          - "This is a second paragraph."

      myapp_str:
        type: "str"
        required: true
        description: "The string value"

      myapp_list:
        type: "list"
        elements: "str"
        required: true
        description: "A list of string values."
        version_added: 1.3.0

      myapp_list_with_dicts:
        type: "list"
        elements: "dict"
        required: false
        default:
          - myapp_food_kind: "meat"
            myapp_food_boiling_required: true
            myapp_food_preparation_time: 60
          - myapp_food_kind: "fruits"
            myapp_food_preparation_time: 5
        description: "A list of dicts with a defined structure and with default a value."
        options:
          myapp_food_kind:
            type: "str"
            choices:
              - "vegetables"
              - "fruits"
              - "grains"
              - "meat"
            required: false
            description: "A string value with a limited list of allowed choices."

          myapp_food_boiling_required:
            type: "bool"
            required: false
            default: false
            description: "Whether the kind of food requires boiling before consumption."

          myapp_food_preparation_time:
            type: int
            required: true
            description: "Time to prepare a dish in minutes."

      myapp_dict_with_suboptions:
        type: "dict"
        required: false
        default:
          myapp_host: "bar.foo"
          myapp_exclude_host: true
          myapp_path: "/etc/myapp"
        description: "A dict with a defined structure and default values."
        options:
          myapp_host:
            type: "str"
            choices:
              - "foo.bar"
              - "bar.foo"
              - "ansible.foo.bar"
            required: true
            description: "A string value with a limited list of allowed choices."

          myapp_exclude_host:
            type: "bool"
            required: true
            description: "A boolean value."

          myapp_path:
            type: "path"
            required: true
            description: "A path value."

          original_name:
            type: list
            elements: "str"
            required: false
            description: "An optional list of string values."

  # roles/myapp/tasks/alternate.yml entry point
  alternate:
    short_description: Alternate entry point for the myapp role
    description:
      - This is the alternate entrypoint for the C(myapp) role.
    version_added: 1.2.0
    options:
      myapp_int:
        type: "int"
        required: false
        default: 1024
        description: "The integer value, defaulting to 1024."

Передача разных параметров

Если в каждом определении роли передать разные параметры, Ansible запустит роль несколько раз. Передача разных значений переменных не равнозначна передаче разных параметров роли. Для такого поведения необходимо использовать ключевое слово roles, поскольку import_role и include_role не принимают параметры роли.

В этом сценарии роль foo запускается дважды:

---
- hosts: webservers
  roles:
    - { role: foo, message: "first" }
    - { role: foo, message: "second" }

Этот синтаксис также запускает роль foo дважды:

---
- hosts: webservers
  roles:
    - role: foo
      message: "first"
    - role: foo
      message: "second"

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

Использование allow_duplicates: true

Добавьте allow_duplicates: true в файл meta/main.yml роли:

# playbook.yml
---
- hosts: webservers
  roles:
    - foo
    - foo

# roles/foo/meta/main.yml
---
allow_duplicates: true

В этом примере Ansible запускает foo дважды, поскольку мы явно разрешили это.

Многократный запуск зависимостей ролей в одном сценарии

Ansible обрабатывает повторяющиеся зависимости ролей так же, как повторяющиеся роли, перечисленные в roles:: зависимость роли выполняется только один раз, даже если она определена несколько раз, за исключением случаев, когда параметры, теги или условие when, заданные для роли, различаются в каждом определении. Если две роли в сценарии указывают одну и ту же третью роль в качестве зависимости, Ansible выполняет эту зависимость только один раз, если не переданы разные параметры, теги или условие when и не используется allow_duplicates: true в роли, которую требуется запускать несколько раз. Подробнее см. в разделе Зависимости ролей Galaxy.

Например, роль с именем car зависит от роли с именем wheel следующим образом:

---
dependencies:
  - role: wheel
    n: 1
  - role: wheel
    n: 2
  - role: wheel
    n: 3
  - role: wheel
    n: 4

А роль wheel зависит от двух ролей: tire и brake. Тогда файл meta/main.yml для wheel будет содержать следующее:

---
dependencies:
  - role: tire
  - role: brake

А файлы meta/main.yml для tire и brake будут содержать следующее:

---
allow_duplicates: true

Итоговый порядок выполнения будет таким:

tire(n=1)
brake(n=1)
wheel(n=1)
tire(n=2)
brake(n=2)
wheel(n=2)
...
car

Чтобы использовать allow_duplicates: true с зависимостями ролей, необходимо указать его для роли, перечисленной в dependencies, а не для роли, которая её перечисляет. В приведённом выше примере allow_duplicates: true указано в meta/main.yml ролей tire и brake. Для роли wheel параметр allow_duplicates: true не требуется, поскольку для каждого экземпляра, определённого в car, используются разные значения параметров.