Теги

Если у вас большой плейбук, может быть полезно запускать только определённые его части вместо всего плейбука. Это можно сделать с помощью тегов Ansible. Использование тегов для выполнения или пропуска выбранных задач — это двухэтапный процесс:

1. Добавьте теги к вашим задачам, либо индивидуально, либо с наследованием тегов из блока, плей, роли или импорта.
2. Выберите или пропустите теги при запуске плейбука.

• Добавление тегов с помощью ключевого слова tags

  • Добавление тегов к отдельным задачам
  • Добавление тегов к включениям

  • Наследование тегов: добавление тегов к нескольким задачам

    • Добавление тегов к блокам
    • Добавление тегов к плей
    • Добавление тегов к ролям
    • Добавление тегов к импортам
    • Наследование тегов для включений: блоки и ключевое слово apply
• Специальные теги: always и never

• Выбор или пропуск тегов при запуске плейбука

  • Предварительный просмотр результатов использования тегов
  • Выборочное выполнение помеченных задач в повторно используемых файлах
  • Глобальная настройка тегов

Добавление тегов с помощью ключевого слова tags

Вы можете добавить теги к одной задаче или включению. Вы также можете добавить теги к нескольким задачам, определив их на уровне блока, плей, роли или импорта. Ключевое слово tags охватывает все эти случаи использования. Ключевое слово tags всегда определяет теги и добавляет их к задачам; оно не выбирает и не пропускает задачи для выполнения. Вы можете выбирать или пропускать задачи только на основе тегов в командной строке при запуске плейбука. Подробнее см. Выбор или пропуск тегов при запуске плейбука.

Добавление тегов к отдельным задачам

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

tasks:
- name: Install the servers
  ansible.builtin.yum:
    name:
    - httpd
    - memcached
    state: present
  tags:
  - packages
  - webservers

- name: Configure the service
  ansible.builtin.template:
    src: templates/src.j2
    dest: /etc/foo.conf
  tags:
  - configuration

Вы можете применить один и тот же тег к нескольким отдельным задачам. В этом примере несколько задач помечены одним тегом «ntp»:

---
# file: roles/common/tasks/main.yml

- name: Install ntp
  ansible.builtin.yum:
    name: ntp
    state: present
  tags: ntp

- name: Configure ntp
  ansible.builtin.template:
    src: ntp.conf.j2
    dest: /etc/ntp.conf
  notify:
  - restart ntpd
  tags: ntp

- name: Enable and run ntpd
  ansible.builtin.service:
    name: ntpd
    state: started
    enabled: yes
  tags: ntp

- name: Install NFS utils
  ansible.builtin.yum:
    name:
    - nfs-utils
    - nfs-util-lib
    state: present
  tags: filesharing

Если бы вы запустили эти четыре задачи в плейбуке с --tags ntp, Ansible выполнил бы три задачи, помеченные ntp, и пропустил бы одну задачу, у которой нет этого тега.

Добавление тегов к включениям

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

Вы добавляете теги к включениям так же, как добавляете теги к любой другой задаче:

---
# file: roles/common/tasks/main.yml

- name: Dynamic re-use of database tasks
  include_tasks: db.yml
  tags: db

Вы можете добавить тег только к динамическому включению роли. В этом примере тег foo будет not применяться к задачам внутри роли bar:

---
- hosts: webservers
  tasks:
    - name: Include the bar role
      include_role:
        name: bar
      tags:
        - foo

С плей, блоками, ключевым словом role, и статическими импортами Ansible применяет наследование тегов, добавляя определённые вами теги ко всем задачам внутри плей, блока, роли или импортированного файла. Однако наследование тегов не применяется к динамическому повторному использованию с include_role и include_tasks. При динамическом повторном использовании (включениях) определённые вами теги применяются только к самому включению. Если вам нужно наследование тегов, используйте статический импорт. Если вы не можете использовать импорт, потому что остальная часть вашего плейбука использует включения, см. Наследование тегов для включений: блоки и ключевое слово apply, чтобы узнать способы решения этой проблемы.

Наследование тегов: добавление тегов к нескольким задачам

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

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

Если вы хотите применить тег к многим, но не ко всем задачам в вашем плей, используйте блок и определите теги на этом уровне. Например, мы можем отредактировать пример NTP, показанный выше, чтобы использовать блок:

# myrole/tasks/main.yml
tasks:
- name: ntp tasks
  tags: ntp
  block:
  - name: Install ntp
    ansible.builtin.yum:
      name: ntp
      state: present

  - name: Configure ntp
    ansible.builtin.template:
      src: ntp.conf.j2
      dest: /etc/ntp.conf
    notify:
    - restart ntpd

  - name: Enable and run ntpd
    ansible.builtin.service:
      name: ntpd
      state: started
      enabled: yes

- name: Install NFS utils
  ansible.builtin.yum:
    name:
    - nfs-utils
    - nfs-util-lib
    state: present
  tags: filesharing

Добавление тегов к плей

Если все задачи в плей должны получить один и тот же тег, вы можете добавить тег на уровне плей. Например, если у вас был плей только с задачами NTP, вы могли бы пометить весь плей:

- hosts: all
  tags: ntp
  tasks:
  - name: Install ntp
    ansible.builtin.yum:
      name: ntp
      state: present

  - name: Configure ntp
    ansible.builtin.template:
      src: ntp.conf.j2
      dest: /etc/ntp.conf
    notify:
    - restart ntpd

  - name: Enable and run ntpd
    ansible.builtin.service:
      name: ntpd
      state: started
      enabled: yes

- hosts: fileservers
  tags: filesharing
  tasks:
  ...

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

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

1. Добавьте один и тот же тег или несколько тегов ко всем задачам в роли, установив теги в roles. Смотрите примеры в этом разделе.
2. Добавьте один и тот же тег или несколько тегов ко всем задачам в роли, установив теги в статическом import_role в вашем плейбуке. Смотрите примеры в Добавление тегов к импортам.
3. Добавьте тег или несколько тегов к отдельным задачам или блокам внутри самой роли. Это единственный подход, который позволяет выбрать или пропустить некоторые задачи внутри роли. Чтобы выбрать или пропустить задачи внутри роли, вы должны установить теги на отдельных задачах или блоках, использовать динамическое include_role в вашем плейбуке и добавить один и тот же тег или несколько тегов к включению. Когда вы используете этот подход, а затем запускаете свой плейбук с --tags foo, Ansible выполняет само включение плюс любые задачи в роли, которые также имеют тег foo. Подробнее см. Добавление тегов к включениям.

Когда вы статически включаете роль в свой плейбук с помощью ключевого слова roles, Ansible добавляет все определённые вами теги ко всем задачам в роли. Например:

roles:
  - role: webserver
    vars:
      port: 5000
    tags: [ web, foo ]

или:

---
- hosts: webservers
  roles:
    - role: foo
      tags:
        - bar
        - baz
    # using YAML shorthand, this is equivalent to:
    # - { role: foo, tags: ["bar", "baz"] }

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

Вы также можете применить тег или несколько тегов ко всем задачам, импортированным статическими операторами import_role и import_tasks:

---
- hosts: webservers
  tasks:
    - name: Import the foo role
      import_role:
        name: foo
      tags:
        - bar
        - baz

    - name: Import tasks from foo.yml
      import_tasks: foo.yml
      tags: [ web, foo ]

Наследование тегов для включений: блоки и ключевое слово apply

По умолчанию Ansible не применяет наследование тегов к динамическому повторному использованию с include_role и include_tasks. Если вы добавите теги к включению, они применяются только к самому включению, а не к любым задачам в включённом файле или роли. Это позволяет выполнять выбранные задачи в роли или файле задач — см. Выборочное выполнение помеченных задач в повторно используемых файлах при запуске вашего плейбука.

Если вам нужно наследование тегов, вы, вероятно, захотите использовать импорты. Однако использование и включений, и импортов в одном плейбуке может привести к трудно диагностируемым ошибкам. По этой причине, если ваш плейбук использует include_* для повторного использования ролей или задач, и вам нужно наследование тегов для одного включения, Ansible предлагает два варианта решения. Вы можете использовать ключевое слово apply:

- name: Apply the db tag to the include and to all tasks in db.yaml
  include_tasks:
    file: db.yml
    # adds 'db' tag to tasks within db.yml
    apply:
      tags: db
  # adds 'db' tag to this 'include_tasks' itself
  tags: db

Или вы можете использовать блок:

- block:
   - name: Include tasks from db.yml
     include_tasks: db.yml
  tags: db

Специальные теги: always и never

Ansible зарезервировал два имени тегов для специального поведения: always и never. Если вы назначите тег always задаче или плей, Ansible всегда выполнит эту задачу или плей, если вы не пропустите её явно (--skip-tags always).

Например:

tasks:
- name: Print a message
  ansible.builtin.debug:
    msg: "Always runs"
  tags:
  - always

- name: Print a message
  ansible.builtin.debug:
    msg: "runs when you use tag1"
  tags:
  - tag1

Если вы назначите тег never задаче или плей, Ansible пропустит эту задачу или плей, если вы её явно не запросите (--tags never).

Например:

tasks:
  - name: Run the rarely-used debug task
    ansible.builtin.debug:
     msg: '{{ showmevar }}'
    tags: [ never, debug ]

Редко используемая задача debug в примере выше выполняется только тогда, когда вы явно запросите теги debug или never.

Выбор или пропуск тегов при запуске плейбука

После добавления тегов к задачам, включениям, блокам, играм, ролям и импортам, вы можете выборочно выполнять или пропускать задачи, основываясь на их тегах, при запуске ansible-playbook. Ansible выполняет или пропускает все задачи с тегами, соответствующими тегам, которые вы передаете в командной строке. Если вы добавили тег на уровне блока или игры, с roles, или с импортом, этот тег применяется ко всем задачам внутри блока, игры, роли или импортированной роли или файла. Если у вас есть роль с множеством тегов и вы хотите вызывать подмножества роли в разное время, либо используйте ее с динамическими включениями, либо разделите роль на несколько ролей.

ansible-playbook предлагает пять командно-строчных опций, связанных с тегами:

• --tags all - выполнить все задачи, игнорировать теги (поведение по умолчанию)
• --tags [tag1, tag2] - выполнить только задачи с тегами tag1 и tag2
• --skip-tags [tag3, tag4] - выполнить все задачи, за исключением тех, которые имеют теги tag3 и tag4
• --tags tagged - выполнить только задачи с хотя бы одним тегом
• --tags untagged - выполнить только задачи без тегов

Например, чтобы выполнить только задачи и блоки, помеченные тегами configuration и packages в очень длинном плейбуке:

ansible-playbook example.yml --tags "configuration,packages"

Чтобы выполнить все задачи, за исключением тех, которые помечены тегом packages:

ansible-playbook example.yml --skip-tags "packages"

Предварительный просмотр результатов использования тегов

При запуске роли или плейбука вы можете не знать или не помнить, какие задачи имеют какие теги или какие теги вообще существуют. Ansible предлагает две командно-строчные флага для ansible-playbook, которые помогут вам управлять плейбуками с тегами:

• --list-tags - сгенерировать список доступных тегов
• --list-tasks - при использовании с --tags tagname или --skip-tags tagname, сгенерировать предварительный просмотр задач с тегами

Например, если вы не знаете, является ли тег для задач конфигурации config или conf в плейбуке, роли или файле задач, вы можете отобразить все доступные теги без выполнения каких-либо задач:

ansible-playbook example.yml --list-tags

Если вы не знаете, какие задачи имеют теги configuration и packages, вы можете передать эти теги и добавить --list-tasks. Ansible отображает задачи, но не выполняет ни одну из них.

ansible-playbook example.yml --tags "configuration,packages" --list-tasks

У этих командно-строчных флагов есть одно ограничение: они не могут отображать теги или задачи в динамически включенных файлах или ролях. Смотрите Сравнение включений и импортов: динамическое и статическое повторное использование для получения дополнительной информации о различиях между статическими импортами и динамическими включениями.

Выборочное выполнение задач с тегами в повторно используемых файлах

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

# mixed.yml
tasks:
- name: Run the task with no tags
  ansible.builtin.debug:
    msg: this task has no tags

- name: Run the tagged task
  ansible.builtin.debug:
    msg: this task is tagged with mytag
  tags: mytag

- block:
  - name: Run the first block task with mytag
    ...
  - name: Run the second block task with mytag
    ...
  tags:
  - mytag

И вы можете включить файл задач выше в плейбуке:

# myplaybook.yml
- hosts: all
  tasks:
  - name: Run tasks from mixed.yml
    include_tasks:
      name: mixed.yml
    tags: mytag

При запуске плейбука с ansible-playbook -i hosts myplaybook.yml --tags "mytag", Ansible пропускает задачу без тегов, выполняет помеченную индивидуальную задачу и выполняет две задачи в блоке.

Настройка тегов глобально

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