Действия — это механизм платформы для запуска операций во внешних инфраструктурных системах и сервисах. С их помощью можно, например:
- создавать проекты, переменные, ветки или теги в GitLab;
- создавать ресурсы в Kubernetes;
- создавать секреты в Deckhouse Stronghold или HashiCorp Vault;
- создавать проекты в SonarQube, DefectDojo и других системах;
- создавать топики и ACL в Kafka.
Действие можно привязать к одному или нескольким ресурсам. После этого его можно запускать для любой сущности этих ресурсов.
Конфигурация действия
Основная информация
При создании или редактировании действия укажите основную информацию:
| Название | Обязательность | Описание |
|---|---|---|
| Название | Да | Произвольное название действия |
| Идентификатор | Да | Идентификатор действия. Генерируется автоматически из названия |
| Ресурс | Нет | Один или несколько ресурсов, для которых будет доступен запуск действия |
| Иконка | Нет | Иконка, которая отображается в карточке действия |
| Владелец | Нет | Учётная запись пользователя, отвечающего за конфигурацию и работоспособность действия |
| Команда владелец | Нет | Команда, отвечающая за конфигурацию и работоспособность действия |
| Теги | Нет | Теги для классификации и поиска действий |
| Описание | Нет | Описание в Markdown. Отображается при запуске действия или процесса, содержащего действие |
Конфигурация запроса
Тип действия
Действие может быть следующих типов:
- «Встроенное (BuiltIn)» — логика выполнения действия описана внутри платформы. Для встроенных действий необходимо выбрать один из преднастроенных бэкендов.
- «Вебхук (Webhook)» — логика выполнения действия полностью настраивается пользователем.
Параметры перезапуска
Если выполнение действия завершается с ошибкой, платформа может автоматически выполнить повторные попытки.
Количество перезапусков
Сколько раз повторять выполнение после ошибки. 0 — одна попытка без перезапусков.
Базовая задержка (сек.)
Задержка в секундах перед первым перезапуском; перед каждой следующей попыткой пауза удваивается (экспоненциальная задержка).
Формат тела запроса
Для вебхук-действий доступен выбор формата отправки тела запроса:
- 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-запрос на встроенный бэкенд или на URL вебхука бэкенда. Обычно запрос включает тело, в котором описывается, что именно будет отправлено. Тело запроса задаётся в YAML.
В тело запроса можно подставлять значения параметров из пользовательской формы с помощью шаблонов Go template.
Пример:
project_id: {{ .property.project_id }}При таком теле запроса выражение {{ .property.project_id }} будет заменено на значение параметра project_id, введённое пользователем в форме запуска действия.
Для встроенных типов действий параметр «Тело запроса» является конфигурацией действия, при этом доступен пример данной конфигурации.
Пользовательская форма
Параметры
В разделе «Пользовательская форма» указываются параметры, доступные пользователю для заполнения при запуске действия. Типы параметров описаны в разделе «Параметры».
Для каждого параметра доступны опции:
- «Редактируемый» — позволяет изменить значение параметра при запуске действия. Если опция выключена, значение изменить нельзя.
- «Обязательный» — требует указания значения при запуске действия.
- «Скрытый» — параметр не отображается в пользовательской форме при запуске действия.
Для каждого параметра можно задать значение по умолчанию, которое будет подставляться в форму при запуске.
Для нередактируемых или скрытых параметров рекомендуется задавать значение по умолчанию, так как при запуске действия пользователь не сможет их изменить.
Описание параметра отображается при запуске действия по кнопке со значком «info». Рекомендуется заполнять его, чтобы было проще понять назначение параметров и снизить риск ошибок при запуске.
В значениях параметров можно использовать шаблонные функции Go template. Например, выражение {{ .entity.name }} в значении параметра означает, что при запуске действия будет подставлено название сущности, для которой оно запускается.
Условия параметров
Параметры могут автоматически скрываться или отображаться в пользовательской форме в зависимости от значения параметра типа Boolean. Настройка выполняется в разделе «Условия параметров», где задаются правила показа или скрытия для выбранных параметров.
Обновление
Контексты шаблонизации
Все обновления выполняются только после успешного завершения действия. В Go-шаблонах доступны следующие контексты шаблонизации:
| Контекст | Описание | Пример |
|---|---|---|
.property | Значения из пользовательской формы | {{ .property.repo }} |
.response | Разобранный ответ действия (JSON) | {{ .response.id }} |
.entity | Параметры сущности каталога, для которой выполняется действие | {{ .entity.slug }} |
.workflow | Параметры сценария | {{ .workflow.branch }} |
.process | Параметры процесса | {{ .process.releaseId }} |
.global | Глобальные переменные (идентификатор набора, затем ключ) | {{ .global.myGroup.apiUrl }} |
.team | Переменные команды, выбранной при запуске | {{ .team.token }} |
.store | Переменные из хранилища процесса | {{ .store.myKey }} |
Обновление параметров сущности
Если включена опция «Обновление параметров сущности», платформа применяет правила обновления и записывает значения в параметры сущности.
| Поле | Описание |
|---|---|
| Источник | Go-шаблон значения |
| Параметр сущности | Идентификатор параметра сущности в каталоге |
Например, при выполнении действия «Создание проекта в GitLab» в поле response будет сохранена спецификация созданного проекта:
{
"id": "1",
"...": "..."
}Если после создания проекта в GitLab нужно сразу заполнить параметр сущности repository_id, укажите в правилах обновления:
- Источник:
{{ .response.id }}. - Параметр сущности:
repository_id.
Создание связей сущности
Если включена опция «Создание связей сущности», платформа автоматически создаст новые связи для выбранной сущности по заданным правилам. Набор правил задаётся отдельно для каждого ресурса.
| Поле | Описание |
|---|---|
| Ресурс | Любой из двух ресурсов, участвующих в нужной связи ресурсов: по выбранному ресурсу загружается список связей, в которых он указан как родительский или как дочерний. Можно выбрать ресурс сущности, для которой запускается действие, или ресурс другой стороны связи — в списке будет одна и та же связь, если оба ресурса входят в неё |
| Связь | Связь ресурсов в каталоге: в ней заданы родительский и дочерний ресурсы и роли сущностей при создании связи. По выбранной связи определяется, на какой стороне находится сущность запуска и какое из полей ниже задаёт идентификатор второй сущности из ответа действия |
| Идентификатор родительской сущности | Go-шаблон для идентификатора родительской сущности в каталоге |
| Идентификатор дочерней сущности | Go-шаблон для идентификатора дочерней сущности в каталоге |
Обновление учётных данных пользователя
Если включена опция обновления учётных данных пользователя, то действие автоматически обновляет учётные данные пользователя в соответствии с правилами обновления.
| Поле | Описание |
|---|---|
| Источник | Go-шаблон значения |
| Тип учётных данных | Тип обновляемых учётных данных |
Например, при выполнении действия, которое возвращает новый API-ключ в ответе:
{
"apiKey": "new-api-key-12345",
"...": "..."
}для обновления учётных данных укажите в правилах обновления:
- Источник:
{{ .response.apiKey }}. - Тип учётных данных: выберите тип учётных данных, которые будут обновлены.
Выбор пользователя для обновления учётных данных
По умолчанию учётные данные обновляются для пользователя, который запустил действие (инициатора).
Чтобы обновить учётные данные другого пользователя, включите опцию «Обновлять учётные данные конкретного пользователя» и выберите нужного пользователя.
Обновление хранилища процесса
Правила из раздела «Обновление хранилища процесса» применяются только при выполнении действия в рамках процесса: если они заданы, то после успешного выполнения действия значения по этим правилам записываются в хранилище.
| Поле | Описание |
|---|---|
| Источник | Go-шаблон значения |
| Ключ в хранилище | Ключ, под которым значение сохраняется в хранилище процесса |
Другие действия в процессе могут читать сохранённое значение через шаблон {{ .store.key }}, где key — указанный ключ.
Если правил нет (список пустой), при выполнении действия в процессе в хранилище ничего не записывается. Данные из хранилища можно использовать в последующих действиях того же процесса через плейсхолдеры {{ .store.<ключ> }}. Подробности описаны в разделе «Хранилище процесса».
Безопасность
Условия выполнения
Действие будет выполнено, только если статус сущности соответствует одному из выбранных значений в поле статусов. Если ограничения не заданы, это условие не применяется.
Маскирование полей действия
Для каждого действия можно включить маскирование полей, которые могут содержать конфиденциальную информацию.
Если включить данную опцию, то в записях выполнения действия будут скрыты:
- значения всех заполненных параметров;
- тело запроса (
body); - ответ (
response), сформированный по результатам выполнения.
Временный ответ
Для каждого действия можно включить опцию «Временный ответ». Она позволяет ограничить доступ к результату выполнения действия и скрыть его от других пользователей.
Если опция включена, то после успешного выполнения действия ответ:
- сохраняется как временный и отображается только пользователю, который запустил действие;
- удаляется из обычного поля ответа, чтобы он не был доступен другим пользователям.
Другие пользователи вместо содержимого ответа будут видеть только зашифрованный временный ответ.
Инициатор действия может удалить временный ответ вручную.
Временный ответ доступен только инициатору действия. Остальные пользователи не могут просмотреть его содержимое и не могут удалить его.
Подтверждение
Для действия можно включить обязательное подтверждение и задать количество подтверждающих. В этом случае действие не будет запущено, пока не будет получено указанное число подтверждений от заданных пользователей.
Текущее число подтверждений и список пользователей, от которых ожидается подтверждение, отображаются в таблице запусков действий для соответствующей сущности.
Если подтверждение требуется от конкретного пользователя, ему будет отправлено уведомление в интерфейсе платформы.
Уведомления о подтверждении
При включённом подтверждении можно включить уведомления и указать способ отправки. Если выбрана отправка на URL, указывается адрес вебхука, при необходимости отключается проверка TLS-сертификата сервера и добавляются дополнительные HTTP-заголовки запроса.
Авторизация
Использовать внешний сервис
Выбор внешних сервисов, для которых может выполняться действие. В случае добавления нескольких внешних сервисов конкретный можно будет выбрать непосредственно при запуске.
URL и HTTP-заголовки
Адрес, куда будет отправлен запрос, и HTTP-заголовки.
В заголовках поддерживаются Go-шаблоны вида {{ .credentials.<идентификатор типа учётных данных> }} для подстановки учётных данных пользователя.
Выбрать учётную запись для запуска
По умолчанию доступ к внешним инфраструктурным сервисам выполняется с использованием учётных данных пользователя, который запустил действие. При необходимости можно явно указать, что действие должно выполняться от имени конкретной учётной записи.
Для действий, запускаемых как события автоматизации, указание учётной записи для запуска является обязательным.
Учётные данные
Для встроенных действий платформа заранее определяет набор требуемых учётных данных. Их идентификаторы подгружаются при выборе встроенного бэкенда. Для каждого идентификатора необходимо выбрать тип учётных данных, который будет использоваться.
Для вебхук-действий обращение к учётным данным возможно в теле запроса с использованием конструкции {{ .credentials.<идентификатор типа учётных данных> }}.
HTTP-метод
Для вебхук-действий задаётся HTTP-метод исходящего запроса.
Запуски действий
Записи запусков действий
При каждом запуске действия создаётся запись, содержащая инициатора, статус выполнения и подробный лог. Записи запусков для каждой сущности доступны в карточке сущности на вкладке «Запуски действий». Если для действия требуется подтверждение, оно выполняется на этой же вкладке.
Запись о запуске можно удалить или перезапустить действие. При перезапуске создаётся новая запись.
Логирование запусков
Для каждого запуска действия в базе данных создаётся запись, содержащая полный лог выполнения.
Параметр actions.logging.enabled в конфигурационном файле Deckhouse Development Platform (DDP) управляет выводом логов запуска в stdout: при значении true логи выводятся, при false не выводятся.
Записи с полным логом запуска в базе данных создаются независимо от значения actions.logging.enabled.
Статусы действий
Для каждого запуска действия создаётся запись со статусом. Возможные статусы:
- «Created» — запись создана, но действие ещё не запускалось.
- «Unapproved» — действие ожидает подтверждения.
- «Running» — действие выполняется.
- «Failed» — действие завершилось с ошибкой.
- «Update failed» — действие выполнено, но обновить параметры сущности не удалось.
- «Success» — действие выполнено успешно.
- «Retrying» — действие завершилось с ошибкой, выполняется повторная попытка запуска.