Перейти к содержанию

YAML-структура процедур

Статья описывает:

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

Структура конфигурационного YAML-файла

Сохраните конфигурационный YAML-файл и загрузите его в кластер.

Чтобы загрузить файлы в Sharx Base, введите команду

resource --spec <SPEC>
где spec — расположение YAML-файла.

При локальном расположении на АРМ пользователя введите путь до файла.

При расположении в стороннем репозитории укажите ссылку на данный файл.

Конфигурационный файл содержит служебную часть для команды resource и определение процедуры для плагина checker

apiVersion: v1 
kind: api 
metadata: 
  plugin: 
    checker: 
      procedure: add 
spec: 
  name: <NAME> 
  definition: | 
    config: 
      # Настройки процедуры 
    vars: 
      # Определение переменных 
    steps: 
      # Последовательность шагов 
    error-handlers: 
      # Обработчики ошибок

где

  • apiVersion — версия API;
  • kind — тип загружаемого объекта;
  • metadata.plugin.checker.procedure — действие над процедурой;
  • spec.name— уникальное имя процедуры в кластере;
  • spec.definition — YAML-определение процедуры.

Структура определения процедуры

Определение процедуры располагается в блоке spec.definition конфигурационного файла.

При добавлении или обновлении процедуры командами checker procedure add и checker procedure update в параметре definition указывайте только содержимое блока spec.definition.

config:
# Настройки процедуры
vars:
# Определение переменных
steps:
# Последовательность шагов
error-handlers:
# Обработчики ошибок

Подробнее о загрузке и управлении процедурами см. в статье Управление процедурами


Переменные vars

Переменные объявляются в корневом блоке vars определения процедуры.
При загрузке процедуры из конфигурационного файла блок vars располагается внутри spec.definition.

Базовое определение переменной

vars:
  name_var:
    type: "тип"
    default: "значение_по_умолчанию"  # необязательно
    visibility: "public|private"     # видимость переменной. По умолчанию private

Тип данных

Возможные значения типов данных:

  • string — текстовая строка;
  • number — целое или дробное число;
  • boolean — true или false;
  • array — массив ["a", "b", "c"];
  • object — набор пар {"key": "value"};
  • null — пустое значение.

Видимость переменных

Возможные значения:

  • private — переменная доступна только внутри процедуры, менять значение переменной нельзя. Значение по умолчанию;
  • public — если видимость переменной задана как public, то её значение можно задать при настройке запуска по расписанию командой checker procedure schedule или при ручном запуске командой checker procedure execute. Подробнее см. в статье Управление процедурами.
Пример
 vars:
   internal_var:
     type: "string"
     default: "secret"
     visibility: "private"  # нельзя изменить при запуске

   user_param:
     type: "number"
     visibility: "public"   # обязательно указать при запуске

Подстановка переменных

Используйте {{ имя }} для подстановки значений

vars:
  node_name:
    type: "string"
    default: "node-01"

steps:
  step1:
    action:
      apicall: "cluster nodes show --node {{ node_name }}"

Расширенная подстановка с JMESPath

JMESPath позволяет выполнять сложные операции с данными в шаблонах переменных.

Базовый синтаксис

"{{var_name | jmespath_expression}}"

Основные примеры:

  1. Фильтрация массива по условию

    # Получить имена только узлов в статусе online
    "{{nodes | [?status=='online'].name}}"
    # Результат: ["node-01", "node-03", "node-05"]
    
  2. Доступ к вложенным данным

    # Извлечь значение из сложного объекта
    "{{vm_info | metrics.cpu_usage}}"
    # Результат: 45.7 (процент использования CPU)
    
  3. Агрегация данных

    # Подсчитать количество элементов
    "{{vms | length(@)}}"
    # Результат: 12 (количество ВМ)
    
    # Суммировать значения
    "{{vms | sum_by([].cpu_cores)}}"
    # Результат: 48 (общее количество CPU ядер)
    
  4. Фильтрация по условию

    # Выбрать ВМ с CPU > 2 и получить их имена
    "{{vms | [?cpu_cores > `2`].name}}"
    # Результат: ["vm-db", "vm-app"]
    

Примечание

Для реализации более сложных процедур введены Расширения JMESPath

Распаковка массивов

vars:
  nodes:
    type: "array[string]"
    default: ["node1", "node2", "node3"]

# В шаблоне
"Проверка узлов: {{*nodes}}"
# Результат:
# "Проверка узла: node1"
# "Проверка узла: node2"
# "Проверка узла: node3"

Совместная распаковка массивов

Внимание

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

vars:
  nodes: ["a", "b"]
  ips:   ["1.1.1.1", "2.2.2.2"]

# В шаблоне
"{{*nodes}} имеет IP {{*ips}}"
# Результат:
# "a имеет IP 1.1.1.1"
# "b имеет IP 2.2.2.2"

Встроенные переменные

Кроме переменных, определяемых в процедуре, есть встроенные переменные, позволяющие взаимодействовать с контекстом исполнения процедуры. Встроенные переменные отличаются от обычных префиксом @ перед названием.

@deps

@deps позволяет добавлять зависимые подзадачи к текущей процедуре в конце шага. Все подзадачи должны завершиться перед тем, как процедура сможет перейти к следующему шагу. Эта переменная очищается в начале каждого шага.

@deps:
  type: "array[object]"
  default: []

Объекты, которые можно добавлять в переменную @deps, должны иметь формат TaskId.

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

  • checker procedure execute --json "yes" <...>.
  • scheduler request reschedule.

@deps_status

@deps_status содержит результаты выполнения всех зависимых подзадач, добавленных в @deps.

@deps_status:
  type: "array[object]"
  default: []

Объекты переменной @deps_status имеют следующую структуру:

{
  "step": "<название шага, на котором остановилась задача>",
  "task_status": "<статус задачи, один из: SUCCESS, TIMEOUT, ERROR>",
  "run_error": "<сообщение ошибки выполнения задачи>" | null,
  "task_steps_total": "<общее число шагов задачи>",
  "run_on_vip": "<выполняется ли задача только на VIP-узле>",
  "run_on_node": "<uuid узла, на котором задача должна выполняться>" | null,
  "task_uuid": "<uuid задачи>",
  "task_name": "<название задачи>" | null,
  "task_message": "<лог сообщений задачи>" | null,
  "worker_node": "<узел, на котором выполнялась задача>",
  "created_at": "<дата и время создания задачи>",
  "updated_at": "<дата и время последнего обновления задачи>"
  // ...другие поля, значение которых на данный момент не задокументировано
}

@result

@result содержит результат выполнения действия и очищается в начале каждого шага. Используется для логирования результата выполнения действия без сохранения в отдельную переменную.

@result:
  type: "object"

Шаги

Процедура разделена на последовательность шагов. Каждый шаг определяется как совокупность условий conditions и действия action. Перед исполнением процедуры запускается проверка всех условий. Пока все условия не будут соблюдены, процедура не может перейти к исполнению действия. После исполнения действия, процедура переходит на следующий шаг.

Основная часть условий и действий — это команда. В качестве команды можно указать одно из двух значений:

  • apicall: делает запрос с синтаксисом sdc-cli и передает результат исполнения команды на обработку в expect/parse
  • const: передает указанное значение напрямую в expect/parse. В качестве значения команды может быть указан либо один шаблон, результат исполнения которого будет передан дальше на обработку, либо список шаблонов. В случае списка шаблонов на обработку будет передан массив с результатами каждого из перечисленных шаблонов.
Пример
# Команда
apicall: "plugin command"
# Результат
<plugin command result>

# Команда
const: ["123", "abc"]
# Результат
["123", "abc"]

# Команда
apicall: 
- "plugin1 command"
- "plugin2 command"
# Результат
[
<plugin1 command result>,
<plugin2 command result>
]

Структура шага

steps:
  name_step:
    conditions:  # условия для выполнения
      - ...
    action:      # действие, которое выполнится
      ...
    on-error:    # обработчики ошибок для шага
      - ...
    attempts:    # настройки повторных попыток
      ...

Условия conditions

Перед тем, как перейти к исполнению действия шага action, нужно, чтобы были выполнены все условия conditions.
conditions — это список команд, которые будут запускаться каждый раз при исполнении шага. Все условия шага должны завершиться без ошибки и все выражения в expect должны быть true, после чего шаг перейдет к исполнению действия.

Для обработки результата выполнения команды условия предусмотрено поле expect, которое является списком выражений. Каждое выражение имеет следующую структуру:

conditions:
  - apicall: "cluster nodes list"  # команда
    expect:                        # проверки результата
      - filter: "[?status=='online'] | length(@)"  # JMESPath
        op: ">="                   # операция сравнения
        value: 3                   # ожидаемое значение

где

  • filter — выражение jmespath, обрабатывающее результат исполнения команды. Результат этого выражения передается в op.
  • op — операция сравнения: ==, !=, >, >=, <, <=. Левым операндом будет результат исполнения filter, а правым value. Если слева от операции поставить * (*==, *<=, и т.д.), то операция повторится для каждого элемента левого операнда.
  • value — значение, с которым op будет сравнивать результат исполнения filter.

Если хотя бы одно выражение вернуло false, то условие считается невыполненным, и шаг повторяется. Пока все условия не выполнены и ни одно из выражений не завершилось с ошибкой, процедура будет проверять текущий шаг. Это поведение можно изменить с помощью attempts.

Пример
vars:
  nodes_to_test:
    type: "array[string]"
    default: ['node1', 'node2']
steps:
  step1:
    conditions:
      - apicall: "cluster nodes list" # [{"status": "online", ...}, ...]
        expect:
          # Вариант 1. Все узлы, кроме nodes_to_test имеют статус `online`
        - filter: "[?!contains({{node_to_test}}, @.name)].status"
          op: "*=="
          value: "online"
          # Вариант 2. Все узлы, кроме nodes_to_test имеют статус `online`
        - filter: "[?status=='online'].name"
          op: "*!="
          value: "{{*nodes_to_test}}"
      - apicall: "cluster nodes show --node {{*nodes_to_test}}" # [{"node": "node1", ...}, {"node": "node2", ...}]
        expect:
          # Узлы из `nodes_to_test` имеют статус `online`
        - filter: "[].status"
          op: "*=="
          value: "online"

Действия action

После того как все условия conditions были выполнены, шаг переходит к действию action.
Действие — это команда, выполняющая определенную операцию и, возможно, обновляющая одну или несколько переменных.

В отличие от поля expect, которое используется в условиях, поле parse предназначено для обработки результата действия и работы с переменными. Формат выражений у parse отличается тем, что вместо проверки результата происходит обработка и сохранение в переменную.

Основные операции, поддерживаемые выражениями в parse:

  • store — записать значение фильтра в переменную;
  • push — добавить значение в конец массива. Используется только для переменных типа array;
  • extend — добавить в конец массива все значения массива, полученного в результате исполнения команды. Используется только для переменных типа array и результата типа array.
Пример
vars:
  value_var:
    type: "string"
  array_var:
    type: "array[string]"
    default: []
steps:
  step1:
    action:
      apicall: "<...>"
      parse:
        - filter: "<...>"
          op: "extend"
          var: "array_var"
        - filter: "<...>"
          op: "push"
          var: "array_var"
        - filter: "<...>"
          op: "store"
          var: "value_var"

Попытки attempts

Попытки attempts ограничивают количество повторных выполнений команды. При необходимости в поле attempts указывается максимальное или минимальное количество попыток перед тем, как команда завершится с ошибкой. Между попытками можно определить минимальный интервал, с которым будут считаться попытки.

Пример
steps:
  # Эта команда будет выполнена до трех раз с интервалом в 60 секунд между каждой попыткой при ошибке в действии. Если после третьего исполнения действие все еще завершается с ошибкой, то весь шаг также завершится с последней полученной ошибкой.
  step1:
    action:
      apicall: "<...>"
      attempts:
        max: 3
        interval: 60
  # Это условие будет запущенно как минимум 2 раза с интервалом 60 секунд между каждой попыткой. Если во время одной из двух попыток будет ошибка или `expect` вернет false, то условие завершится с ошибкой.
  step2:
    conditions:
      - apicall: "<...>"
        expect:
        - <...>
        attempts:
          min: 2
          interval: 60

Обработка ошибок

Во время выполнения шага может произойти ошибка: было достигнуто ограничение на количество попыток, во время парсинга вывода произошла ошибка, плагин вернул ошибку, и т.д. Для обработки ошибок предусмотрено общее для всех шагов поле error-handlers. Данное поле содержит команды, которые могут вызываться при ошибках, а также команды, вызываемые по умолчанию для определенных типов ошибок.

vars:
  <...>
steps:
  <...>
error-handlers:
  <...>

Для того, чтобы во время ошибки шага был выбран нужный обработчик ошибок, требуется указать его в поле on-error. Это поле может быть указано для шага, действия или условия, более глубокое указание имеет приоритет. on-error является списком названий обработчиков handler и типов ошибок error-type, для которых нужно использовать данный обработчик. Типы ошибок error-type:

  • "AttemptsLimitReached" — ошибка, вызываемая при достижении ограничения в attempts;
  • "*"— любой тип ошибки.
Пример
vars:
  <...>
steps:
  step1:
    conditions:
      - # <...>
        on-error: # выбор нужного обработчика ошибок для условия
        - error-type: "AttemptsLimitReached" # тип ошибки — достижение ограничения
          handler: "notify" # название обработчика
    action:
      # <...>
      on-error: # выбор нужного обработчика ошибок для действия
        - error-type: "*" # любой тип ошибки
          handler: "_continue" # название обработчика
    on-error: # выбор нужного обработчика ошибок для шага
      - error-type: "AttemptsLimitReached" # тип ошибки — достижение ограничения
        handler: "notify" # название обработчика
error-handlers:
    <...>   

Обработчики ошибок могут указывать, что делать после обработки ошибки. Для этого используется поле control-flow со следующими возможными вариантами:

  • repeat — повторить шаг еще раз;
  • continue — пропустить шаг и перейти к следующему;
  • exit — завершить процедуру с статусом SUCCESS;
  • terminate — завершить процедуры со статусом ERROR. Вариант по умолчанию.
Пример
vars:
  <...>
steps:
  step1:
    conditions:
      - # <...>
        on-error: 
        - error-type: "AttemptsLimitReached" 
          handler: "notify"
    action:
      # <...>
      on-error: 
        - error-type: "*" 
          handler: "_continue"
    on-error:
      - error-type: "AttemptsLimitReached"
        handler: "notify"
error-handlers:
  notify: # название обработчика
    error-type-default: "*"  # любой тип ошибки по умолчанию
    apicall: "<...>" # команда, выполняющая запрос с синтаксисом sdc-cli
    control-flow: "continue" # действие после обработки ошибки

Встроенные обработчики ошибок

Для всех процедур по умолчанию определены следующие обработчики ошибок

error-handlers:
  _terminate:
    control-flow: "terminate" # завершить процедуры со статусом ERROR
  _exit:
    control-flow: "exit" # завершить процедуру со статусом SUCCESS
  _continue:
    control-flow: "continue" # пропустить шаг и перейти к следующему
  _repeat:
    control-flow: "repeat" #повторить шаг еще раз

Логирование

Для любой команды можно добавить поле log, которое выводит сообщение в журнал выполнения процедуры. Поле log может содержать сообщения before и after, которые выводятся до и после выполнения команды. Если поле log не указано явно, по умолчанию используется сообщение after.

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

Пример
vars:
  somevar:
    type: "object"
    default: "{}"
steps:
  step1:
    conditions:
      - apicall: "<...>"
        log: "step1, condition 1, after: {{ somevar }}"
    action:
      apicall: "<...>"
      parse:
        - filter: "<...>"
          op: "store"
          var: "somevar"
      log:
        before: "step1, action, before: {{ somevar }}"
        after: "step1, action, after: {{ somevar }}"

Результат

step1, condition 1, after: {}
step1, action, before: {}
step1, action, after: <...>

Конфигурация config

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

config:
  run-on-node: <node_uuid> # Процедура будет исполняться на указанном узле
  run-on-vip: <bool> # Процедура будет исполняться только на VIP-узле
  timeout: <int> # Максимальное время исполнения процедуры в секундах, по истечении которого процедура завершится

Расширения JMESPath

Стандартный набор функций jmespath, который используется для преобразования результатов выполнения команд, ограничен, поэтому для реализации более сложных процедур введены следующие расширения

union(array1, array2)

Объединение массивов

filter: "union({{array1}}, {{array2}})"

intersection(array1, array2)

Пересечение массивов — общие элементы двух массивов.

filter: "intersection({{array1}}, {{array2}})"

difference(array1, array2)

Разность массивов (элементы из array1, которых нет в array2)

filter: "difference({{all_nodes}}, {{drained_nodes}})"

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

  1. Управление процедурами.
  2. Примеры процедур.