Задачи и политики

Задача — это сценарий, управляющий применением состояния (SLS) на одном или нескольких миньонах.
Для создания задач в Salt.Box используются шаблоны задач, загружаемые из репозиториев SLS.

к сведению

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

Политика — режим выполнения задачи, предназначенный не для немедленного выполнения действий, а для задания правил и ограничений, в рамках созданных и запущенных задач.
При создании политики:

• Задача описывается как правило (политика), а не как разовое действие;
• Пользователь не выбирает конкретные миньоны напрямую, а работает с разрешёнными коллекциями.

Создание задачи

В процессе создания задачи пользователь Salt.Box выполняет следующие шаги:

1. Выбирает адресатов задачи.
2. Выбирает шаблон задачи и вводит общие параметры задачи.
3. Вводит параметры, определённые в шаблоне задачи.
4. Просматривает параметры на вкладке Обзор и подтверждает создание задачи.
5. Запускает и контролирует выполнение задачи со страницы Карточка задачи.

Выбор адресатов задачи

Создание задач в Salt.Box осуществляется со страницы миньонов (переход на страницу — через пункт Клиенты главного меню).

В Salt.Box действует алгоритм, по которому при создании задачи определяются целевые миньоны (т.е. миньоны, на которых будет выполняться задача):

1. Все миньоны текущей активной (выбранной пользователем из числа доступных ему) коллекции

   (этот вариант применяется по умолчанию).

2. Все миньоны, отобранные фильтром, применённым к исходной коллекции.

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

На Рис. 1 показан пример, в котором пользователем из коллекции root collection выбрана группа миньонов (отмечены пользователем флажками).

Рисунок 1. Выбор адресатов новой задачи

Нажмите кнопку + Создать задачу Рис. 1.

Выбор шаблона задачи и ввод общих параметров задачи

В открывшемся диалоговом окне Выберите шаблон задачи выберите нужный шаблон (например Package install) Рис. 2.
Если список шаблонов пуст, синхронизируйте шаблоны, как указано в разделе Шаблоны задач.

Рисунок 2. Диалоговое окно Выберите шаблон задачи

Ввод параметров, определённых в шаблоне задачи

В результате откроется диалоговое окно Настройка задачи Рис. 3.

к сведению

Состав параметров, определённых в шаблоне, зависит от соответствующего ему файла SLS.
На Рис. 3 показан пример набора параметров, определённых в выбранном пользователем шаблоне Установка пакета (Package name).

На вкладке Настройки в поле Package name введите название пакета, который хранится на сервере или в репозиториях ОС миньонов Рис. 3.
Если необходимо обновить уже установленный пакет на ОС миньона (миньонов) в поле Update следует выбрать параметр True (по умолчанию указано False).

Рисунок 3. Диалоговое окно Настройка задачи. Вкладка Настройки

к сведению

В поле аргументов вводится только название пакета. Например: Package name: htop Рис. 3.

примечание

Обязательные поля отмечены знаком *

к сведению

При массовом использовании задач есть функция расширенные настройки, которые позволяют распределять нагрузку при выполнении множества задач на определённом промежутке времени.
Для этого на вкладке Настройки необходимо активировать кнопку Расширенные настройки Рис. 4.
В таблице 1 приведено описание общих параметров задачи.

Рисунок 4. Кнопка Расширенные настройки

Таблица 1. Перечень общих параметров задачи

Параметр	Описание
Размер пакета	Размер «окна» выполнения (максимальное количество одновременно выполняемых задач). Значение 0 — без ограничений
Параллельные задачи	Максимальное количество одновременно выполняемых задач
Максимум попыток	Количество попыток выполнения задачи в случае недачного завершения
Задержка повтора	Задержка в секундах перед повторной попыткой

Нажать кнопку Далее к обзору Рис. 4.

В результате в диалоговом окне Настройка задачи откроется вкладка Обзор Рис. 5.

Рисунок 5. Диалоговое окно Настройка задачи. Вкладка Обзор

к сведению

Вкладка Обзор Рис. 5 предназначена для предварительного просмотра и проверки параметров задачи перед её запуском.
Вкладка Обзор позволяет пользователю:

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

Подтверждение создания задачи

После ввода параметров нажмите кнопку Создать задачу Рис. 5.
Будет создана задача, откроется страница Карточка задачи Рис. 6.
Первоначальный статус новой задачи — “created” (Создана).

Карточка задачи

Рисунок 6. Карточка задачи

Карточка задачи состоит из трех блоков:

• блок с кнопками управления и атрибутами задачи Рис. 6 [1]

  перечень атрибутов задачи приведён в таблице 2

  Таблица 2. Перечень атрибутов задачи

  Атрибут	Описание
  Тип задачи	Тип задачи
  Статус	Статус задачи
  Создано	Время создания задачи
  Пользователь	Имя пользователя, создавший задачу
  Подробнее о задаче	Дополнительная информация о задаче

• блок выполнения задачи Рис. 6 [2]

  • вкладка Все

    на вкладке отображается список всех адресатов (миньонов, на которые планируется или уже запущена задача)

  • вкладка Ожидает

    на вкладке отображается список адресатов (миньонов), находящихся в режиме ожидания

  • вкладка В процессе

    на вкладке отображается список адресатов (миньонов), находящихся в процессе выполнения

  • вкладка С ошибкой

    на вкладке отображается список адресатов (миньонов) с ошибками выполнения

  • вкладка Успешно

    на вкладке отображается список адресатов (миньонов) с успешно выполненными задачами

• таблица Карточки задачи Рис. 6 [3]

  перечень полей таблицы Карточки задачи приведён в таблице 3

  Таблица 3. Перечень полей таблицы Карточки задачи

  Имя поля	Значение
  ID клиента	Идентификатор задачи
  Мастер	Наименование мастера
  Статус	Статус миньона
  Количество запусков	Количество проделанных запусков задачи
  Запущена	Период запуска задачи
  Завершена	Период завершения задачи

Создание политики

В процессе создания политики пользователь Salt.Box выполняет следующие шаги:

1. Выбирает коллекции миньонов.
2. Выбирает шаблон задачи и вводит общие параметры политики.
3. Вводит параметры, определённые в шаблоне задачи.
4. Просматривает параметры на вкладке Обзор и подтверждает создание политики.
5. Запускает и контролирует выполнение политики со страницы Карточка задачи (политики).

Выбор коллекции миньонов

Создание политики в Salt.Box осуществляется со страницы миньонов.

В главном меню системы выберите пункт Клиенты Рис. 7.

Рисунок 7. Выбор пункта Клиенты в главном меню

На появившейся выдвижной панели Рис. 8 будут показаны все доступные коллекции.

Рисунок 8. Список доступных коллекций

к сведению

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

Выберите необходимую коллекцию (например,root collection) в рамках которой будет создана политика.
В рабочей области окна браузера будет выведен список миньонов выбранной коллекции Рис. 9.

Рисунок 9. Список миньонов выбранной коллекции. Кнопка + Создать политику

Выбор шаблона задачи и ввод общих параметров политики

На вкладке Список нажмите кнопку + Создать политику Рис. 9 [1].

В открывшемся диалоговом окне Выберите шаблон задачи из списка выберите шаблон задачи (например,
Random with sleep) Рис. 10.

Рисунок 10. Диалоговое окно Выберите шаблон задачи со списком шаблонов задач

к сведению

Если список шаблонов пуст, синхронизируйте шаблоны, как указано в разделе Шаблоны задач.

В результате откроется диалоговое окно Настройка задачи Рис. 11.
На вкладке Настройки в поле Time to sleep введите значение — количество секунд до случайного перехода в спящий режим.

Рисунок 11. Диалоговое окно Настройка задачи. Вкладка Настройки

примечание

Обязательные поля отмечены знаком *

к сведению

При массовом использовании политик есть функция применения расширенных настроек, которые позволяют распределять нагрузку при выполнении множества задач на определённом промежутке времени.
Для этого на вкладке Настройки необходимо активировать кнопку Расширенные настройки Рис. 12 [1].
Укажите общие параметры политики, как показано на Рис. 12.

Рисунок 12. Кнопка Расширенные настройки. Дополнительные параметры настройки политики

В таблице 4 приведено описание общих параметров политики.

Таблица 4. Перечень общих параметров задачи

Параметр	Описание
Размер пакета	Размер «окна» выполнения (максимальное количество одновременно выполняемых задач). Значение 0 — без ограничений
Параллельные задачи	Максимальное количество одновременно выполняемых задач
Максимум попыток	Количество попыток выполнения задачи в случае недачного завершения
Задержка повтора	Задержка в секундах перед повторной попыткой

Вкладка Обзор

Нажмите кнопку Далее к обзору Рис. 12 [2].

В результате в диалоговом окне Настройка задачи откроется вкладка Обзор Рис. 13 [1].

Рисунок 13. Диалоговое окно Настройка задачи. Вкладка Обзор

к сведению

Вкладка Обзор Рис. 13 предназначена для предварительного просмотра и проверки параметров задачи политики перед её запуском.
Вкладка Обзор позволяет пользователю:

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

Подтверждение создания политики

Нажмите кнопку Создать задачу Рис. 13 [2].
Будет создана политика, откроется страница Карточка задачи (политики) Рис. 14.

Рисунок 14. Карточка задачи (политики)

Первоначальный статус новой политики — “created” (Создана).

Карточка задачи (политики)

Карточка задачи (политики) состоит из трех блоков:

• блок с кнопками управления и атрибутами задачи (политики) Рис. 14 [1]

  перечень атрибутов политики приведён в таблице 5

  Таблица 5. Перечень атрибутов политики

  Атрибут	Описание
  Тип задачи	Тип задачи
  Статус	Статус задачи
  Создано	Время создания задачи
  Пользователь	Имя пользователя, создавший задачу
  Подробнее о задаче	Дополнительная информация о задаче

• блок выполнения задачи Рис. 14 [2]

  • вкладка Все

    на вкладке отображается список всех адресатов (миньонов, на которые планируется или уже запущена политика)

  • вкладка Ожидает

    на вкладке отображается список адресатов (миньонов), находящихся в режиме ожидания

  • вкладка В процессе

    на вкладке отображается список адресатов (миньонов), находящихся в процессе выполнения

  • вкладка С ошибкой

    на вкладке отображается список адресатов (миньонов) с ошибками выполнения

  • вкладка Успешно

    на вкладке отображается список адресатов (миньонов) с успешно выполненными политиками

• таблица Карточки задачи (политики) Рис. 14 [3]

  перечень полей таблицы Карточки задачи (политики) приведён в таблице 6

  Таблица 6. Перечень полей таблицы Карточки задачи (политики)

  Имя поля	Значение
  ID клиента	Идентификатор задачи
  Мастер	Наименование мастера
  Статус	Статус миньона
  Количество запусков	Количество проделанных запусков задачи
  Запущена	Период запуска задачи
  Завершена	Период завершения задачи

Для того чтобы запустить политику, в блоке с кнопками управления Рис. 14 [1], нажмите кнопку Запустить.
Будет запущена политика со сменой состояния атрибута миньонов Статус Рис. 15 [1] на Выполняется.
При этом в таблице Карточка задачи (политики) Рис. 15 [3] в строке миньонов в поле Статус атрибут поочерёдно изменится с Ожидает на В процессе
Рис. 15 [2].

Рисунок 15. Выполнение задачи (политики) в Карточке политики

Далее при завершении выполнения политики на миньонах атрибут Статус изменит состояние на Успешно или С ошибкой Рис. 16 [1].
Политика перейдёт в режим Ожидание клиентов Рис. 16 [2].

Рисунок 16. Завершение выполнения задачи (политики) в Карточке политики

Для отображения результатов выполнения задачи (политики) нажмите на строку клиента.
В результате справа откроется окно карточки миньона со вкладкой Результат запуска в виде блока JSON Рис. 17.

Рисунок 17. Вкладка Результат запуска

JSON-представление результата позволяет увидеть:

• какие состояния были применены,
• какие изменения внесены,
• что именно было выполнено — список операций (например, установка пакетов, изменение конфигурационных файлов),
• статус каждой операции — success, failed, changed и пр,
• ошибки и сообщения — подробные сообщения об ошибках конфигурации, синтаксиса SLS, недоступности миньона и т.п.,
• логи выполнения (если они включены) — часто присутствуют строки отладки и детали выполнения команд.

к сведению

Страница Результат запуска необходима для:

• проверки успешности применения политики/задачи,
• диагностики ошибок,
• анализа, какие изменения были внесены

Диаграммы состояний задач и политик

Граф выполнения задачи

На Рис. 18 показан граф выполнения задачи.

Условия переходов между статусами задачи, выполняемых автоматически либо при определённых действиях пользователя, приведены в таблице 7.

Рисунок 18. Граф выполнения задачи

Таблица 7. Таблица переходов графа выполнения задачи

Метка дуги	Условие перехода
1	Пользователь нажал кнопку Run
2	Пользователь нажал кнопку Stop
3	Система выполнила все необходимые операции для остановки
4	Пользователь нажал кнопку Run
5	Задача выполнена успешно

Граф выполнения политики

На Рис. 19 показан граф выполнения политики.

Условия переходов между статусами политики, выполняемых автоматически либо при определённых действиях пользователя, приведены в таблице 8.

Рисунок 19. Граф выполнения политики

Таблица 8. Таблица переходов графа выполнения политики

Метка дуги	Условие перехода
1	Пользователь нажал кнопку Run
2	Пользователь нажал кнопку Stop
3	Система выполнила все необходимые операции для остановки
4	Пользователь нажал кнопку Run
5	Политика переходит в режим ожидания миньона
6	После появления релевантного миньона выполнение политики возобновляется

Граф миньона (статус миньона) в составе задачи

Под миньоном в составе задачи подразумевается объект Salt.Box, содержащий объект Salt.Box Minion, попавший под нацеливание задачи и хранящий статус миньона.
Каждый отдельный миньон формирует собственный ответ Job Return с результатом выполнения SaltStak Job.
Результирующий статус миньона в составе задачи зависит, таким образом, от того, выполнены ли все команды на отдельных миньонах успешно.

На Рис. 20 показан граф миньона (статус миньона).

Условия переходов между статусами миньона приведены в таблице 9.

Рисунок 20. Граф миньона (статус миньона)

Таблица 9. Таблица переходов графа миньона (статус миньона) в составе задачи

Метка дуги	Условие перехода
1	Получено подтверждение от salt-master о создании SaltStack Job. Ожидаются ответы Job Return
2	Получены все Job Return, все успешны
3	Получены все Job Return, есть ответы с ошибками

к сведению

Граф миньона (статус миньона) в составе политики аналогичен графу миньона (статус миньона) в составе задачи

Граф выполнения команды на отдельном миньоне

На Рис. 21 показан граф выполнения команды при её выполнении на отдельном миньоне.

Условия переходов между статусами команды приведены в таблице 10.

Рисунок 21. Граф выполнения команды на отдельном миньоне

Таблица 10. Таблица переходов графа выполнения команды на отдельном миньоне

Метка дуги	Условие перехода
1	От salt-master получено подтверждение о создании SaltStack Job, миньон попал в нацеливание. Ожидается ответ Job Return по миньону
2	Получен успешный Job Return по миньону
3	Получен отрицательный Job Return по миньону
4	От salt-master получено подтверждение о создании SaltStack Job, но миньон по какой-то причине не попал в нацеливание

Диаграмма выполнения задачи

Рисунок 22. Диаграмма выполнения задачи

Таблица 11. Переходы (взаимодействия) на диаграмме выполнения задачи

№ взаимодействия	Описание
1	Если множество миньонов-адресатов задачи задано с помощью созданных колекции миньонов, и в то же время указан хотя бы один из параметров: Batch size или Parallel jobs — максимальное количество команд, которые могут выполняться одновременно, то перед созданием команд будет выполнено преобразование цели в набор списков миньонов, по Batch size миньонов в каждом.
2	Создание команд Salt.Box. Сначала будет создано Parallel jobs команд, последующие команды будут создаваться по мере выполнения созданных ранее команд.
3	Каждая созданная команда Salt.Box выполняет вызов службы salt-master, которая генерирует событие типа job: salt/job/<JID>/new.
4	Созданные события salt/job/<JID>/new публикуется на встроенной шине ZeroMQ.
5, 6, 7, 8	На диаграмме меткой "Minions of some Job #X" обозначена группа миньонов, являющихся целями одной (взятой произвольно) команды (Job #X), созданной на шаге №2. Аналогично, меткой "Minions of some Job #Y" обозначена группа миньонов-целей некоей другой команды (Job #Y). Обе группы содержат Batch size миньонов. Меткой "SaltStak job delivered" на диаграмме обозначены моменты получения миньонами команды, опубликованной на шине ZeroMQ. Моменты получения команды асинхронны вследствие разного времени реакции миньонов. На диаграмме в качестве примера показано, что миньоны группы "Minions of some Job #Y" получают команды позже миньонов группы "Minions of some Job #X", и существенно позже публикуют ответы (не показаны в пределах диаграммы).
9, 10	После выполнения команды каждый миньон отправляет на шину ZeroMQ ответ ("Job Return")
11	Ответ последнего миньона группы "Minions of some Job #X" (т.е. ответ, опубликованный на шине последним).
12, 13	Обратная цепочка передачи ответов миньонов от SaltStack к Salt.Box
14	Обработчик событий задачи получает сигнал о том, что все миньоны команды Job #X отправили ответы (либо не ответили по таймауту).
15	Сигнал об окончании выполнения команды Job #X инициирует создание очередной команды со следующей группой из Batch size миньонов-адресатов. Таким образом обеспечивается одновременное выполнение не более Parallel jobs команд.
16	Вновь созданная команда Salt.Box выполняет вызов службы salt-master, которая генерирует событие типа job: salt/job/<JID>/new.
17	Событие salt/job/<JID>/new публикуется на встроенной шине ZeroMQ.