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

  • создавать проекты, переменные, ветки или теги в GitLab;
  • создавать ресурсы в Kubernetes;
  • создавать секреты в Deckhouse Stronghold или HashiCorp Vault;
  • создавать проекты в SonarQube, DefectDojo и других системах;
  • создавать топики и ACL в Kafka.

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

Конфигурация действия

Основная информация

При создании или редактировании действия укажите основную информацию:

  • Название (обязательно) — произвольное название действия.
  • Идентификатор (обязательно) — идентификатор действия. Генерируется автоматически из названия.
  • Ресурс (опционально) — один или несколько ресурсов, для которых будет доступен запуск действия.
  • Иконка (опционально) — иконка, которая отображается в карточке действия.
  • Владелец (опционально) — учетная запись пользователя, отвечающего за конфигурацию и работоспособность действия.
  • Команда владельца (опционально) — команда, отвечающая за конфигурацию и работоспособность действия.
  • Теги (опционально) — теги для классификации и поиска действий.
  • Описание (опционально) — описание в Markdown. Отображается при запуске действия или сценария, содержащего действие.

Пользовательская форма

Параметры

В разделе «Пользовательская форма» укажите параметры, доступные для заполнения при запуске действия. Типы параметров описаны в разделе «Параметры».

Для каждого параметра доступны опции:

  • Редактируемый — позволяет изменить значение параметра при запуске действия. Если опция выключена, значение изменить нельзя.
  • Обязательный — требует указания значения при запуске действия.
  • Скрытый — параметр не отображается в пользовательской форме при запуске действия.

Для каждого параметра можно задать значение по умолчанию, которое будет подставляться в форму при запуске.

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

Описание параметра отображается при запуске действия по кнопке со значком «info». Рекомендуется заполнять его, чтобы было проще понять назначение параметров и снизить риск ошибок при запуске.

В значениях параметров можно использовать шаблонные функции Go template. Например, выражение {{ .entity.name }} в значении параметра означает, что при запуске действия будет подставлено название сущности, для которой оно запускается.

Условия параметров

Параметры могут автоматически скрываться или отображаться в пользовательской форме в зависимости от значения параметра типа Boolean. Настройка выполняется в разделе «Условия параметров», где задаются правила показа или скрытия для выбранных параметров.

Бэкенд

Тип

Действие может выполняться с использованием одного из двух типов бэкенда:

  • Встроенный — основная логика действия выполняется внутри платформы.

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

  • Вебхук — основная логика действия выполняется внешним сервисом, которому платформа отправляет HTTP-запрос.

Маскирование полей действия

Для каждого действия можно включить маскирование полей, которые могут содержать конфиденциальную информацию.

Если включить опцию «Маскировать поля действия», в записях выполнения действия будут скрыты:

  • поле body (тело запроса);
  • поле response (ответ, сформированный по результатам выполнения);
  • значения всех заполненных параметров.

Временный ответ

Для каждого действия можно включить опцию «Временный ответ». Она позволяет ограничить доступ к результату выполнения действия и скрыть его от других пользователей.

Если опция включена, то после успешного выполнения действия ответ:

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

Другие пользователи вместо содержимого ответа будут видеть только зашифрованный временный ответ.

Инициатор действия может удалить временный ответ вручную.

Временный ответ доступен только инициатору действия. Остальные пользователи не могут просмотреть его содержимое и не могут удалить его.

Количество перезапусков

Если выполнение действия завершается с ошибкой, платформа может автоматически выполнить повторные попытки. Параметр «Количество перезапусков» задаёт максимальное число таких повторных запусков.

Базовая задержка (сек.)

Параметр «Базовая задержка» задаёт интервал между повторными попытками. При каждом перезапуске задержка увеличивается (экспоненциально). Например, при базовой задержке 2 секунды перезапуски будут выполняться через 2, 4, 8 секунд и далее.

Тело запроса

Каждое действие отправляет HTTP-запрос на встроенный бэкенд или на URL вебхука бэкенда. Обычно запрос включает тело, в котором описывается спецификация операции.

Для встроенного бэкенда при редактировании действия доступен пример тела запроса.

Пример тела запроса

В тело запроса можно подставлять значения параметров из пользовательской формы с помощью шаблонов Go template в YAML.

Пример:

project_id: {{ .project_id }}

При таком теле запроса выражение {{ .project_id }} будет заменено на значение параметра project_id, введённое пользователем в форме запуска действия.

Итоговое тело запроса

Поле «Итоговое тело запроса» показывает, как будет выглядеть запрос после подстановки параметров и форматирования. Если итоговое тело является валидным JSON, в интерфейсе будет доступна подсветка синтаксиса. Если подсветки нет, проверьте корректность сформированного тела запроса.

URL

Для выполнения вебхук-действия в поле URL укажите адрес внешнего бэкенда, на который платформа отправит запрос.

Для встроенных действий поле URL может содержать адрес инфраструктурного сервиса, с которым выполняется взаимодействие, или оставаться пустым. Допустимые варианты зависят от конкретного типа встроенного действия и описаны в его документации.

Выключить проверку SSL

Параметр определяет, будет ли платформа проверять SSL-сертификат:

  • вебхук-бэкенда (для вебхук-действий);
  • инфраструктурного сервиса (для встроенных действий).

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

Метод

HTTP-метод запроса к вебхук-бэкенду. Для встроенных действий метод определяется автоматически в зависимости от типа действия.

Формат тела запроса

Для вебхук-действий доступен выбор формата отправки тела запроса:

  • JSON (по умолчанию) — тело запроса отправляется в формате JSON с заголовком Content-Type: application/json.
  • Form URL Encoded — тело запроса отправляется в формате application/x-www-form-urlencoded. В этом формате поддерживаются только плоские структуры ключ-значение, где все значения преобразуются в строки. Вложенные объекты и массивы не поддерживаются.

При выборе формата Form URL Encoded тело запроса должно содержать только плоские ключ-значение пары. Например:

token: {{ .credentials.token }}

Вложенные структуры и массивы в этом формате не поддерживаются.

Расширенное логирование

Для вебхук-действий доступна опция расширенное логирование, которая включает детальное логирование всех деталей HTTP-запроса и ответа:

  • URL запроса,
  • HTTP-метод,
  • HTTP-заголовки (включая токены),
  • Тело запроса,
  • Статус код ответа,
  • HTTP-заголовки ответа,
  • Тело ответа.

При включенной опции все эти данные записываются в лог выполнения действия. При выключенной опции логирование выполняется в стандартном режиме.

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

Заголовки

HTTP-заголовки в формате «ключ: значение», которые будут добавлены в запрос к вебхук-бэкенду. Для встроенных действий заголовки формируются автоматически в зависимости от типа действия.

Обновление сущности

Обновление параметров сущности

После выполнения действия результат (как правило, ответ инфраструктурной системы) сохраняется в поле response. Если включена опция «Обновление параметров сущности», платформа использует данные из response и применяет правила обновления, чтобы записать значения в параметры сущности.

Например, при выполнении действия «Создание проекта в GitLab» в поле response будет сохранена спецификация созданного проекта, например:

{
  "id": "1",
  "...": "..."
}

Если после создания проекта в GitLab нужно сразу заполнить параметр сущности repository_id, укажите в правилах обновления:

  • источник: {{ .response.id }};
  • параметр сущности: repository_id.

Запись в хранилище процесса

После выполнения действия результат записывается в поле response. В разделе «Обновление» конфигурации действия доступен блок «Запись в хранилище процесса». Он применяется только при выполнении действия в рамках процесса: если заданы правила записи в хранилище, то после успешного выполнения действия значения по этим правилам записываются в хранилище.

В блоке задаётся список правил:

ПолеОписаниеПримеры
ИсточникСтрока Go-шаблона, в котором контекстом является response этого действия. Шаблон выполняется после успешного выполнения действия; результат (строка) записывается в хранилище.{{ .id }} — получить поле id из ответа; {{ .result.projectId }} — получить вложенное поле projectId из result из ответа
Ключ в хранилищеНазвание ключа в хранилище процесса. Под этим ключом сохраняется значение из источника.projectId, deployJobId

Если правил нет (список пустой), при выполнении действия в процессе в хранилище ничего не записывается. Данные из хранилища можно использовать в последующих действиях того же процесса через плейсхолдеры {{ .store.<ключ> }}. Подробнее об использовании хранилища см. в разделе «Хранилище процесса».

Запись в хранилище выполняется только после успешного выполнения действия.

Обновление учётных данных пользователя

После выполнения действия результат записывается в поле response. Если включена опция обновление учётных данных пользователя, то на основании данных из response действие автоматически обновляет учётные данные пользователя в соответствии с правилами обновления.

Например, при выполнении действия, которое возвращает новый API-ключ в ответе:

{
  "apiKey": "new-api-key-12345",
  "...": "..."
}

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

  • Источник: {{ .response.apiKey }} — шаблон для получения значения из ответа действия.
  • Тип учётных данных: выбор типа учётных данных, которые будут обновлены.
Выбор пользователя для обновления учётных данных

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

Обновление учётных данных выполняется только после успешного выполнения действия. Если действие завершилось с ошибкой, учётные данные не обновляются.

Создание связей сущностей

Если включена опция «Создание связей сущностей», платформа автоматически создаст новые связи для выбранной сущности по заданным правилам. Набор правил задается отдельно для каждого ресурса.

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

Безопасность

Подтверждение перед запуском

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

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

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

Учетная запись для запуска действия

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

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

Учетные данные

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

Для вебхук-действий обращение к учетным данным возможно в теле запроса с использованием конструкции {{ .credentials.<идентификатор типа учетных данных> }}.

Запуски действий

Записи запусков действий

При каждом запуске действия создается запись, содержащая инициатора, статус выполнения и подробный лог. Записи запусков для каждой сущности доступны в карточке сущности на вкладке «Запуски действий». Если для действия требуется подтверждение, оно выполняется на этой же вкладке.

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

Логирование запусков

Для каждого запуска действия в базе данных создается запись, содержащая полный лог выполнения.

Параметр actions.logging.enabled в конфигурационном файле DDP управляет выводом логов запуска в stdout: при значении true логи выводятся, при false не выводятся.

Записи с полным логом запуска в базе данных создаются независимо от значения actions.logging.enabled.

Статусы действий

Для каждого запуска действия создается запись со статусом. Возможные статусы:

  • Created — запись создана, но действие еще не запускалось.
  • Unapproved — действие ожидает подтверждения.
  • Running — действие выполняется.
  • Failed — действие завершилось с ошибкой.
  • Update failed — действие выполнено, но обновить параметры сущности не удалось.
  • Success — действие выполнено успешно.
  • Retrying — действие завершилось с ошибкой, выполняется повторная попытка запуска.