Роли

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

Классический (исходный) способ использования ролей — с опцией 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
      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
      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
      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
      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
      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.
• Это также становится частью заголовка страницы роли в документации.
• Короткое описание должно всегда быть строкой, а не списком, и не должно заканчиваться точкой.

description:

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

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

  является новым абзацем.

version_added:

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

author:

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

options:

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

option-name:

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

description:

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

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 не должно быть включено в описание, если не требуется дополнительная информация или условия.
• Если параметр является булевым значением, используйте true/false, если вы хотите быть совместимым с ansible-lint.

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 дважды, потому что мы явно разрешили это сделать.

Выполнение зависимостей ролей несколько раз в одном play

Ansible обрабатывает дублированные зависимости ролей как дублированные роли, перечисленные под roles:: Ansible выполняет зависимости ролей только один раз, даже если они определены несколько раз, если параметры, теги или условие «когда» для роли не отличаются для каждого определения. Если две роли в play перечисляют третью роль в качестве зависимости, Ansible выполняет эту зависимость только один раз, если вы не передадите разные параметры, теги, условие «когда» или не используете 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, использует разные значения параметров.