Управление процедурами

Ключевые понятия описаны в статье Checker.

В статье описано управление процедурами:

Добавление, обновление и удаление процедуры.
Делегирование процедуры во ВЦОД.
Планирование выполнения по расписанию.
Запуск процедуры вручную.
Отслеживание статуса выполнения.

Определить процедуру

Примечание

Действия выполняются пользователем с ролью Администратор кластера

Чтобы определить процедуру, выполните следующие шаги:

Проверьте название и описание процедуры на корректность без добавления процедуры в систему
```
checker procedure add --name <NAME>
                      --definition <DEFINITION>
                      [--json <no|yes>]
                      --validate "yes"
```
где
- name — имя процедуры. Должно быть уникально в пределах кластера;
- definition — определение процедуры. Передается как строка в формате YAML. Подробнее см. YAML-структура процедур и Примеры процедур;
- json — формат возвращения ошибки. Возможные значения:
  - "no" — ошибка возвращается в человекочитаемом формате. Значение по умолчанию,
  - "yes" — ошибка возвращается в формате JSON;
- validate — проверка названия и описания процедуры на корректность без добавления процедуры в систему. В данной команде проверка должна быть включена "yes".
Если при проверке получены ошибки, исправьте их.
Если проверка прошла успешно, приступайте к следующему шагу.
Чтобы определить процедуру, введите
```
checker procedure add --name <NAME>
                      --definition <DEFINITION>                          
```
где
- name — имя процедуры;
- definition — определение процедуры. Передается как строка в формате YAML.

Обновить процедуру

Чтобы обновить процедуру, сначала проверьте корректность нового описания без обновления в системе
```
checker procedure update --name <NAME>
                         --definition <DEFINITION> 
                         [--json <no|yes>]
                         --validate "yes"  
```
где
- name — имя обновляемой процедуры;
- definition — новое определение процедуры;
- json — формат возвращения ошибки. Возможные значения:
  - "no" — ошибка возвращается в человекочитаемом формате. Значение по умолчанию,
  - "yes" — ошибка возвращается в формате JSON;
- validate — проверка названия и описания процедуры на корректность без добавления процедуры в систему. В данной команде проверка должна быть включена "yes".
Если при проверке получены ошибки, исправьте их.
Если проверка прошла успешно, приступайте к следующему шагу.
Обновите процедуру в системе
```
checker procedure update --name <NAME>
                          --definition <DEFINITION> 
```
где
- name — имя обновляемой процедуры;
- definition — новое проверенное определение процедуры.

Просмотреть определение процедуры

Чтобы просмотреть определение процедуры, введите

checker procedure show    --name <NAME>
                          [--json <no|yes>]

где

name — имя обновляемой процедуры;
json — формат возвращения ответа. Возможные значения:
- "no" — ответ возвращается в человекочитаемом формате. Значение по умолчанию,
- "yes" — ответ возвращается в формате JSON.

Команда поможет узнать, какие переменные vars требует процедура, и есть ли у них значения по умолчанию.

Удалить процедуру

Чтобы удалить процедуру, введите

checker procedure del  --name <NAME>
                       [--json <no|yes>]

где name — имя удаляемой процедуры.

Делегировать процедуру

После того, как процедура определена, необходимо ее делегировать, то есть сделать доступной для целевых ВЦОД

Чтобы делегировать процедуру во ВЦОД, введите команду
```
checker procedure delegate --name <NAME> 
                           --ns <NS>
```
где
- name — имя процедуры;
- ns — имя ВЦОД. При значении * процедура будет делегирована во все ВЦОД.
После делегирования процедура станет доступна в указанных ВЦОД для запуска вручную или по расписанию.
Чтобы убрать делегирование процедуры из ВЦОД, используйте следующую команду
```
checker procedure undelegate --name <NAME> 
                             --ns <NS>
```
При значении --ns * процедура будет убрана из всех ВЦОД.

Планирование выполнения процедуры

Планирование процедур по расписанию доступно как для кластера во ВЦОД управления, так и для отдельных ВЦОД. Администратор кластера может планировать процедуры, предназначенные для выполнения на уровне кластера, например, фенсинг узлов.
Для процедур, которые должны выполняться во ВЦОД, администратор кластера предварительно делегирует их, после чего администратор соответствующего ВЦОД может настроить для них расписание.

Чтобы процедура выполнялась автоматически по расписанию, введите команду
```
checker procedure schedule add --name <NAME>
                              [--vars '{"var": "value"}']
                              --cron <cron>
```
где
- name — имя процедуры;
- vars — переменная процедуры. Имеет значение --vars '{"var": "value"}'. Обязательно, если переменная public не имеет значения по умолчанию.
- cron — периодичность выполнения процедуры. Период задается в формате "*****" где
  - первая * — минута. От 0 до 59,
  - вторая * — час. От 0 до 23,
  - третья * — день месяца. От 1 до 31,
  - четвертая * — месяц. От 1 до 12,
  - пятая * — день недели. От 0 до 7. Воскресенье=0 или 7.
Пример

"* * * * 7" — выполняется каждое воскресенье,
"* 2 * * 7" — каждые два часа по воскресеньям,
"*/1 * * * *" — каждую минуту.
Полное описание синтаксиса и примеров cron см. GitLab Docs/Cron

Изменить расписание для выполнения процедуры

checker procedure schedule update --name <NAME>
                                 [--vars '{"var": "value"}']
                                 --cron <cron>

Просмотр запланированных процедур
```
checker procedure schedule list
```
Чтобы удалить процедуру из расписания, сначала узнайте ее идентификатор командой
```
checker procedure schedule list
```
Затем удалите процедуру из расписания
Удалить процедуру из плана исполнения
```
checker procedure schedule del --uuid <UUID>
```
где uuid — идентификатор процедуры.

Примечание

Удаление из расписания не останавливает уже запущенный экземпляр процедуры, но новые запуски по расписанию прекратятся

Ручной запуск процедур

Если нужно протестировать процедуру или выполнять ее вручную, введите команду

checker procedure execute --name <NAME> 
                          [--vars '{"var": "value"}']
                          [--json <no|yes>]

где

name — имя процедуры;
vars — переменная процедуры. Имеет значение --vars '{"var": "value"}'. Обязательно, если переменная public не имеет значения по умолчанию;
json — формат возвращения ответа. Возможные значения:
- "no" — ответ возвращается в человекочитаемом формате. Значение по умолчанию,
- "yes" — ответ возвращается в формате JSON.

Принудительная остановка процедур

Чтобы остановить процедуру вручную, введите

checker procedure interrupt --uuid <UUID>

где uuid — идентификатор запущенной процедуры.

Команда может быть применена к процедуре, запущенной по плану или вручную.

Статусы запущенных процедур

Все запуски процедур, как по расписанию, так и ручные, имеют статус выполнения. Запланированные процедуры хранят только последний статус. История статуса хранится 90 дней, затем автоматически удаляется.

Чтобы просмотреть список статусов всех процедур, введите команду
```
checker procedure status list
```

Чтобы просмотреть статус определенной процедуры, введите

checker procedure status show --uuid <UUID>
                              [--json <no|yes>]

где

uuid — идентификатор статуса процедуры, полученный в результате команды checker procedure status list;
json — формат возвращения ответа. Возможные значения:
- "no" — ответ возвращается в человекочитаемом формате. Значение по умолчанию,
- "yes" — ответ возвращается в формате JSON.

В результате команды по статусу вернется следующая информация:

PENDING— процедура создана, но еще не начала выполняться;
IN_PROGRESS — процедура исполняется;
WAITING— процедура ждет завершения другой задачи;
SUCCESS — успешное завершение;
TIMEOUT— завершена по таймауту;
ERROR — завершена с ошибкой.

Пример получения списка статусов и детальной информации

checker procedure status list
[
  {
    "task_uuid": "0c6910ba-7f28-4ccb-9d6a-2a7d575cfadd",
    <...>
  }
]

checker procedure status show --uuid 0c6910ba-7f28-4ccb-9d6a-2a7d575cfadd
{
  "task_status": "IN_PROGRESS",
  <...>
}

Практические советы

Тестирование новой процедуры

Сначала проверьте имя и определение новой процедуры

checker procedure add --name "procedure_name" --definition "<YAML>" --validate "yes" --json "no|yes"

Добавьте процедуру в систему

checker procedure add --name "procedure_name" --definition "<YAML>"

Делегируйте процедуру во ВЦОД

checker procedure delegate --name "procedure_name" --ns "ns_name"

Запустите процедуру вручную для проверки выполнения
```
checker procedure execute --name "procedure_name" --vars '{}' --json "no|yes"
```
Получите UUID задачи из ответа.

Отслеживайте выполнение

checker procedure status show --uuid <UUID>

Проверьте логи и результат. Если процедура отработала без ошибок, добавьте ее в выполнение по расписанию.

Анализ проблем

Используйте параметр --json yes для машинночитаемого вывода ошибок.
Проверяйте логи через команду checker procedure status show.
Убедитесь, что процедура делегирована в нужный ВЦОД.
Проверьте корректность cron-выражения.

Дополнительная информация

Статья с описанием YAML-структуры процедур.
Примеры процедур с готовыми сценариями для типовых задач.

Термины и определения содержатся в статьях: