Действия — это механизм Deckhouse Development Portal для запуска операций во внешних инфраструктурных системах и сервисах. С их помощью можно, например:
- создавать проекты, переменные, ветки, теги, релизы и запросы на слияние в GitLab;
- создавать ресурсы в Kubernetes и получать их;
- создавать секреты в Deckhouse Stronghold и HashiCorp Vault, а также клиентов в Keycloak;
- создавать проекты в SonarQube, продукты и проверки (engagement) в DefectDojo, проекты в CodeScoring и репозитории, роли, пользователей и привилегии в Nexus Repository;
- создавать топики и ACL в Apache Kafka;
- выполнять вспомогательные действия для отладки и управления выполнением процессов (например, Debug и Wait).
Действие можно привязать к одному или нескольким ресурсам. После этого его можно запускать для любой сущности этих ресурсов.
Действие, которое используется в задачах процессов, удалить нельзя: портал отвечает ошибкой 409 со списком таких процессов. Чтобы удалить действие, сначала уберите его из задач этих процессов.
Конфигурация действия
Основная информация
При создании или редактировании действия укажите основную информацию:
| Поле | Обязательность | Описание |
|---|---|---|
| Название | Да | Произвольное название действия |
| Идентификатор | Да | Идентификатор действия. Генерируется автоматически из названия |
| Ресурс | Нет | Один или несколько ресурсов, для которых будет доступен запуск действия |
| Иконка | Нет | Иконка, которая отображается в карточке действия |
| Владелец | Нет | Учётная запись пользователя, отвечающего за конфигурацию и работоспособность действия |
| Команда-владелец | Нет | Команда, отвечающая за конфигурацию и работоспособность действия |
| Теги | Нет | Теги для классификации и поиска действий |
| Описание | Нет | Описание в Markdown. Отображается при запуске действия или процесса, содержащего действие |
Конфигурация запроса
Тип действия
Действие может быть следующих типов:
- «Встроенное (BuiltIn)» — логика выполнения действия описана внутри портала. Для встроенных действий необходимо выбрать один из преднастроенных бэкендов.
- «Вебхук (Webhook)» — логика выполнения действия полностью настраивается пользователем.
Параметры перезапуска
Если выполнение действия завершается с ошибкой, портал может автоматически выполнить повторные попытки. Настройте их в разделе «Параметры перезапуска»:
| Поле | Описание |
|---|---|
| Количество перезапусков | Сколько раз повторять выполнение после ошибки. 0 — одна попытка без перезапусков |
| Базовая задержка (сек.) | Задержка в секундах перед первым перезапуском. Перед каждой следующей попыткой пауза удваивается (экспоненциальная задержка) |
Формат тела запроса
Для вебхук-действий доступен выбор формата отправки тела запроса:
- JSON (по умолчанию) — тело запроса отправляется в формате JSON с заголовком
Content-Type: application/json. - «Form URL Encoded» — тело запроса отправляется в формате
application/x-www-form-urlencoded.
При выборе формата «Form URL Encoded» тело запроса должно содержать только плоские пары «ключ — значение». Вложенные структуры и массивы в этом формате не поддерживаются.
Если тело запроса пустое, вебхук отправляет запрос без тела и без заголовка Content-Type. Так настраиваются запросы GET и DELETE.
Вебхук-действие выполняется успешно, только если внешняя система вернула код ответа 2xx. Перенаправление с заголовком Location портал выполняет сам и проверяет код итогового ответа. Ответ 3xx без перенаправления, 4xx и 5xx завершают действие ошибкой.
Если внешняя система вернула код ответа с ошибкой, тело ответа сохраняется в ответе действия: JSON — как объект, остальное — в поле raw_body. Текст ошибки действия имеет вид unexpected status code: <код>, response: <тело ответа>, тело ответа обрезается до 8192 байт.
Пример:
token: {{ .credentials.token }}Расширенное логирование
Для вебхук-действий доступна опция «Расширенное логирование», которая включает детальное логирование всех деталей HTTP-запроса и ответа:
- URL запроса;
- HTTP-метод;
- HTTP-заголовки (включая токены);
- тело запроса;
- код статуса ответа;
- HTTP-заголовки ответа;
- тело ответа.
При включённой опции все эти данные записываются в лог выполнения действия. При выключённой опции логирование выполняется в стандартном режиме.
Включение расширенного логирования может привести к записи конфиденциальной информации (токены, пароли и т. д.) в логи. Используйте эту опцию с осторожностью и только при необходимости отладки.
Тело запроса
Каждое действие отправляет HTTP-запрос на встроенный бэкенд или на URL вебхука бэкенда. Обычно запрос включает тело запроса (body), в котором описывается, что именно будет отправлено. Тело запроса задаётся в YAML.
В тело запроса можно подставлять значения параметров из пользовательской формы с помощью шаблонов Go template.
Пример:
project_id: {{ .property.project_id }}При таком теле запроса выражение {{ .property.project_id }} будет заменено на значение параметра project_id, введённое пользователем в форме запуска действия.
Для встроенных типов действий параметр «Тело запроса» является конфигурацией действия, при этом доступен пример данной конфигурации.
Пользовательская форма
Параметры
В разделе «Пользовательская форма» указываются параметры, доступные пользователю для заполнения при запуске действия. Типы параметров описаны в разделе «Параметры».
Для каждого параметра доступны опции:
- «Редактируемый» — позволяет изменить значение параметра при запуске действия. Если опция выключена, значение изменить нельзя.
- «Обязательный» — требует указания значения при запуске действия.
- «Скрытый» — параметр не отображается в пользовательской форме при запуске действия.
Для каждого параметра можно задать значение по умолчанию, которое будет подставляться в форму при запуске.
Действие принимает только параметры, объявленные в пользовательской форме. Если при запуске, например из процесса или через API, передан параметр, которого нет в форме, запуск завершается ошибкой action "<slug>" does not declare property <name>.
Задайте значение по умолчанию для нередактируемых и скрытых параметров: при запуске действия пользователь не сможет их изменить.
Описание параметра отображается при запуске действия по кнопке со значком «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 }} |
.context | Контекст запуска процесса, например данные окружения, выбранного на главной | {{ .context.environment.slug }} |
Обновление параметров сущности
Чтобы включить обновление параметров, включите переключатель в заголовке раздела «Обновление параметров сущности». После этого портал применяет правила обновления и записывает значения в параметры сущности.
| Поле | Описание |
|---|---|
| Источник | Go-шаблон значения |
| Параметр сущности | Идентификатор параметра сущности в каталоге |
Если источник после подстановки даёт пустую строку, правило пропускается и текущее значение параметра сущности не меняется.
Например, при выполнении действия «Создание проекта в GitLab» в ответе (response) будет сохранена спецификация созданного проекта:
{
"id": "1",
"...": "..."
}Если после создания проекта в GitLab нужно сразу заполнить параметр сущности repository_id, укажите в правилах обновления:
- Источник:
{{ .response.id }}. - Параметр сущности:
repository_id.
Создание сущностей
Чтобы включить создание сущностей, включите переключатель в заголовке раздела «Создание сущностей». После этого портал автоматически создаёт новые сущности в выбранных ресурсах по заданным правилам. Правила задаются отдельно для каждого ресурса.
| Поле | Описание |
|---|---|
| Владелец — инициатор запуска | Владельцем создаваемых сущностей становится пользователь, запустивший действие. Если инициатор неизвестен (запуск автоматизацией или вебхуком), владельцем становится пользователь из поля «Владелец создаваемых сущностей» |
| Владелец создаваемых сущностей | Назначается владельцем всем сущностям, которые действие создаёт в каталоге |
| Команда-владелец создаваемых сущностей | Назначается командой-владельцем всем сущностям, которые действие создаёт в каталоге |
| Ресурс | Ресурс каталога, в котором будет создана сущность |
| Источник (идентификатор) | Go-шаблон для идентификатора создаваемой сущности |
| Источник (название) | Go-шаблон для названия создаваемой сущности |
| Дополнительные правила | Сопоставление Go-шаблона значения с параметром сущности |
Идентификатор и название обязательны для каждой группы правил. Если в ресурсе уже есть сущность с таким идентификатором, создание пропускается.
Например, при выполнении действия «Создание проекта в GitLab» в ответе может быть:
{
"id": "42",
"name": "my-project",
"...": "..."
}Чтобы после успешного выполнения действия создать сущность в ресурсе «Проекты GitLab», укажите в правилах:
- Ресурс: «Проекты GitLab».
- Источник (идентификатор):
{{ .response.id }}. - Источник (название):
{{ .response.name }}.
При необходимости добавьте дополнительные правила для заполнения параметров сущности, например сопоставьте {{ .response.path }} с параметром path.
Удаление сущностей
Чтобы включить удаление сущностей, включите переключатель в заголовке раздела «Удаление сущностей». После этого портал автоматически удаляет сущности в выбранных ресурсах по заданным правилам. Правила задаются отдельно для каждого ресурса.
| Поле | Описание |
|---|---|
| Ресурс | Ресурс каталога, в котором находится удаляемая сущность |
| Источник | Go-шаблон идентификатора сущности (например, {{ .response.id }}) |
Если сущности с полученным идентификатором нет в ресурсе, удаление пропускается.
Например, при выполнении действия «Удаление проекта в GitLab» в ответе может быть:
{
"id": "42",
"...": "..."
}Чтобы после успешного выполнения действия удалить сущность в ресурсе «Проекты GitLab», укажите в правилах:
- Ресурс: «Проекты GitLab».
- Источник:
{{ .response.id }}.
Создание связей сущности
Чтобы включить создание связей, включите переключатель в заголовке раздела «Создание связей сущности». После этого портал автоматически создаёт новые связи для выбранной сущности по заданным правилам. Набор правил задаётся отдельно для каждого ресурса.
| Поле | Описание |
|---|---|
| Ресурс | Любой из двух ресурсов, участвующих в нужной связи ресурсов: по выбранному ресурсу загружается список связей, в которых он указан как родительский или как дочерний. Можно выбрать ресурс сущности, для которой запускается действие, или ресурс другой стороны связи — в списке будет одна и та же связь, если оба ресурса входят в неё |
| Связь | Связь ресурсов в каталоге: в ней заданы родительский и дочерний ресурсы и роли сущностей при создании связи. По выбранной связи определяется, на какой стороне находится сущность запуска и какое из полей ниже задаёт идентификатор второй сущности из ответа действия |
| Идентификатор родительской сущности | Go-шаблон для идентификатора родительской сущности в каталоге |
| Идентификатор дочерней сущности | Go-шаблон для идентификатора дочерней сущности в каталоге |
Удаление связей сущности
Чтобы включить удаление связей, включите переключатель в заголовке раздела «Удаление связей сущности». После этого портал автоматически удаляет связи для выбранной сущности по заданным правилам. Набор правил задаётся отдельно для каждого ресурса.
| Поле | Описание |
|---|---|
| Ресурс | Любой из двух ресурсов, участвующих в нужной связи ресурсов: по выбранному ресурсу загружается список связей, в которых он указан как родительский или как дочерний. Можно выбрать ресурс сущности, для которой запускается действие, или ресурс другой стороны связи — в списке будет одна и та же связь, если оба ресурса входят в неё |
| Связь | Связь ресурсов в каталоге: в ней заданы родительский и дочерний ресурсы и роли сущностей при удалении связи. По выбранной связи определяется, на какой стороне находится сущность запуска и какое из полей ниже задаёт идентификатор второй сущности из ответа действия |
| Идентификатор родительской сущности | Go-шаблон для идентификатора родительской сущности в каталоге |
| Идентификатор дочерней сущности | Go-шаблон для идентификатора дочерней сущности в каталоге |
Если подходящей связи нет, удаление пропускается.
Обновление учётных данных пользователя
Чтобы включить обновление учётных данных, включите переключатель в заголовке раздела «Обновление учётных данных пользователя». После этого действие автоматически обновляет учётные данные пользователя в соответствии с правилами обновления.
| Поле | Описание |
|---|---|
| Источник | Go-шаблон значения |
| Тип учётных данных | Тип обновляемых учётных данных |
Например, при выполнении действия, которое возвращает новый API-ключ в ответе:
{
"apiKey": "new-api-key-12345",
"...": "..."
}Для обновления учётных данных укажите в правилах обновления:
- Источник:
{{ .response.apiKey }}. - Тип учётных данных: выберите тип учётных данных, которые будут обновлены.
По умолчанию учётные данные обновляются для пользователя, который запустил действие (инициатора). Чтобы обновить учётные данные другого пользователя, включите опцию «Обновлять учётные данные конкретного пользователя» и выберите пользователя в поле «Пользователь для обновления учётных данных».
Обновление хранилища процесса
Правила из раздела «Обновление хранилища процесса» применяются только при выполнении действия в рамках процесса: после успешного завершения действия значения записываются в хранилище запуска по заданным правилам, в порядке списка.
| Поле | Описание |
|---|---|
| Условие | Необязательный Go-шаблон; пустое — правило всегда выполняется. Результат рендеринга: true, false, 1 или 0 |
| Операция | Записать строку, Записать JSON, Добавить строку, Добавить JSON, Слить JSON (поверхностно), Удалить |
| Цель | Dot-path в хранилище без ведущей точки, например deploy.job_id или notification.items |
| Источник | Go-шаблон значения |
Другие действия и элементы процесса читают данные через {{ .store.<путь> }}. Внутри цикла в шаблонах доступен контекст {{ .store._loop.* }}.
Если правил нет (список пустой), при выполнении действия в процессе в хранилище ничего не записывается.
Подробное описание операций, примеры правил, цикл по коллекции и просмотр хранилища — в разделе «Хранилище процесса».
Синхронизация источников данных
Синхронизация источников данных после действия переносит в каталог объект, который действие создало или удалило во внешней системе, без ожидания синхронизации по расписанию.
Чтобы включить синхронизацию, включите переключатель в заголовке раздела «Синхронизация источников данных» и выберите источники в поле «Источники данных». Выберите источники, которые загружают в каталог объект, созданный или удалённый действием. Если переключатель включён, выберите хотя бы один источник данных.
Синхронизация запускается после успешного выполнения действия и применения правил обновления. Синхронизация выполняется в фоне: действие не ожидает её завершения и не завершается ошибкой, если синхронизация не удалась. Удалённые источники данных пропускаются.
Безопасность
Условия выполнения
Действие будет выполнено, только если статус сущности соответствует одному из выбранных значений в поле статусов. Если ограничения не заданы, это условие не применяется.
Маскирование полей действия
Для каждого действия можно включить маскирование полей, которые могут содержать конфиденциальную информацию.
Если включить данную опцию, то в записях выполнения действия будут скрыты:
- значения всех заполненных параметров;
- тело запроса (
body); - ответ (
response), сформированный по результатам выполнения.
Временный ответ
Для каждого действия можно включить опцию «Временный ответ». Она позволяет ограничить доступ к результату выполнения действия и скрыть его от других пользователей.
Если опция включена, то после успешного выполнения действия ответ:
- сохраняется как временный и отображается только пользователю, который запустил действие;
- удаляется из обычного поля ответа, чтобы он не был доступен другим пользователям.
Другие пользователи вместо содержимого ответа будут видеть только зашифрованный временный ответ.
Инициатор действия может удалить временный ответ вручную.
Временный ответ доступен только инициатору действия. Остальные пользователи не могут просмотреть его содержимое и не могут удалить его.
Подтверждение
Для действия можно включить обязательное подтверждение и задать количество подтверждающих. В этом случае действие не будет запущено, пока не будет получено указанное число подтверждений от заданных пользователей.
Текущее число подтверждений и список пользователей, от которых ожидается подтверждение, отображаются в таблице запусков действий для соответствующей сущности.
Если подтверждение требуется от конкретного пользователя, ему будет отправлено уведомление в веб-интерфейсе.
Уведомления о подтверждении
При включённом подтверждении можно включить уведомления и указать способ отправки. Если выбрана отправка на URL, указывается адрес вебхука, при необходимости отключается проверка TLS-сертификата сервера и добавляются дополнительные HTTP-заголовки запроса.
Авторизация
Использовать внешний сервис
Выбор внешних сервисов, для которых может выполняться действие. В случае добавления нескольких внешних сервисов конкретный можно будет выбрать непосредственно при запуске.
URL и HTTP-заголовки
Адрес, куда будет отправлен запрос, и HTTP-заголовки.
В URL вебхук-действия поддерживаются Go-шаблоны, в том числе условия {{ if }}.
В заголовках поддерживаются Go-шаблоны вида {{ .credentials.<идентификатор типа учётных данных> }} для подстановки учётных данных пользователя.
Выбрать учётную запись для запуска
По умолчанию доступ к внешним инфраструктурным сервисам выполняется с использованием учётных данных пользователя, который запустил действие. Чтобы действие выполнялось от имени конкретной учётной записи, включите опцию «Выбрать учётную запись для запуска» и выберите учётную запись в поле «Учётная запись для запуска».
Для действий, запускаемых как события автоматизации, указание учётной записи для запуска является обязательным.
Учётные данные
Для встроенных действий портал заранее определяет набор требуемых учётных данных. Их идентификаторы подгружаются при выборе встроенного бэкенда. Для каждого идентификатора необходимо выбрать тип учётных данных, который будет использоваться.
Для вебхук-действий обращение к учётным данным возможно в теле запроса с использованием конструкции {{ .credentials.<идентификатор типа учётных данных> }}.
HTTP-метод
Для вебхук-действий задаётся HTTP-метод исходящего запроса. Если метод не задан, используется POST.
Запуски действий
Записи запусков действий
При каждом запуске действия создаётся запись, содержащая инициатора, статус выполнения и подробный лог. Записи запусков для каждой сущности доступны на странице сущности на вкладке «Действия» в таблице «История выполнения». Если для действия требуется подтверждение, оно выполняется на этой же вкладке.
Над таблицей отображается блок «Что можно запустить» со списком действий, доступных для сущности, и поиском по действиям. Недавно запускавшиеся действия и статус их последнего запуска также отображаются в блоке «Запуск» на вкладке «Обзор». Записи в таблице группируются по статусам: «Все», «Активные», «Ожидающие подтверждения», «Созданные», «Успешные», «С проблемами», «Отменённые» и «Пропущенные». В раскрытой строке записи отображаются последние строки лога.
Запись о запуске можно удалить или перезапустить действие. При перезапуске создаётся новая запись. Разрешения, которые нужны для просмотра записей, их отмены, перезапуска и удаления, описаны в разделе «Записи запусков действий» ролевой модели.
Логирование запусков
Для каждого запуска действия в базе данных создаётся запись, содержащая полный лог выполнения.
Параметр модуля actions.logging.enabled управляет выводом логов запуска в stdout: при значении true логи выводятся, при false (по умолчанию) не выводятся.
Задайте параметр в секции settings ModuleConfig development-platform или в веб-интерфейсе Deckhouse Platform.
Записи с полным логом запуска в базе данных создаются независимо от значения actions.logging.enabled.
Минимальный уровень сообщений в логе запуска, который отображается в веб-интерфейсе, задаёт параметр модуля logger.executionLevel. По умолчанию — info: сообщения уровня debug не отображаются.
Статусы запуска действий
Для каждого запуска действия создаётся запись со статусом. Возможные статусы:
Created— запись создана, но действие ещё не запускалось.Unapproved— действие ожидает подтверждения.Running— действие выполняется.Failed— действие завершилось с ошибкой.Update failed— действие выполнено, но обновить параметры сущности не удалось.Success— действие выполнено успешно.Retrying— действие завершилось с ошибкой, выполняется повторная попытка запуска.Warning— действие выполнено, но часть операций завершилась с ошибкой. Например, действие CreateGitlabProjectVariables не смогло создать часть переменных.Declined— действие не запущено, так как статус сущности не соответствует условиям выполнения.Skipped— действие не запущено, так как оно выключено в конфигурации запуска процесса или процесс завершился успешно, не дойдя до задачи, например по другой ветке эксклюзивного шлюза.Canceled— запуск отменён пользователем или из-за остановки процесса.