diff --git a/content/documentation/admin/actions/overview.md b/content/documentation/admin/actions/overview.md new file mode 100644 index 0000000..2665f79 --- /dev/null +++ b/content/documentation/admin/actions/overview.md @@ -0,0 +1,227 @@ +--- +title: Overview +weight: 10 +--- + +Actions are a platform mechanism for running operations in external infrastructure systems and services, that is, outside the platform. For example, you can use actions to: + +- create projects, variables, branches, or tags in GitLab +- create resources in Kubernetes +- create secrets in Deckhouse Stronghold or HashiCorp Vault +- create projects in SonarQube, DefectDojo, and other systems +- create topics and ACLs in Kafka + +An action can be associated with one or more resources. After that, it can be run for any data entity of those resources. + +## Action configuration + +### Basic information + +When creating or editing an action, specify the following: + +- **Name** (required): An arbitrary name for the action. +- **Identifier** (required): The action identifier. It is generated automatically from the name. +- **Resource** (optional): One or more resources for which this action will be available. +- **Icon** (optional): An icon displayed in the action card. +- **Owner** (optional): The user account responsible for the action configuration and reliability. +- **Owner team** (optional): The team responsible for the action configuration and reliability. +- **Tags** (optional): Tags used to classify and search for actions. +- **Description** (optional): A Markdown description shown when running the action or a scenario that includes it. + +### User form + +#### Parameters + +In the **User form** section, define the parameters that users can fill in when running the action. Parameter types are described in the **Parameters** section. + +Each parameter supports the following options: + +- **Editable**: Allows changing the parameter value when running the action. If disabled, the value cannot be changed. +- **Required**: Requires a value to be provided when running the action. +- **Hidden**: Hides the parameter from the user form when running the action. + +You can also set a default value for each parameter. The platform will prefill the user form with it. + +{{< alert level="info" >}} +For non-editable or hidden parameters, it is recommended to always set a default value, because users cannot change them when running the action. +{{< /alert >}} + +A parameter description is available when running the action via the **info** icon. Filling in descriptions is recommended: it makes the purpose of parameters clearer and reduces the risk of mistakes. + +Parameter values can use [Go template](https://developer.hashicorp.com/nomad/tutorials/templates/go-template-syntax). For example, using `{{ .entity.name }}` as a parameter value means the platform will substitute the name of the entity the action is being run for. + +#### Parameter conditions + +Parameters can be automatically shown or hidden in the user form depending on the value of a `Boolean` parameter. Configure this behavior in the **Parameter conditions** section, where you define show/hide rules for selected parameters. + +### Backend + +#### Type + +An action can use one of two backend types: + +- **Built-in (BuiltIn)**: The main action logic runs inside the platform. + + > When selecting a built-in backend, you must choose a specific built-in action type. Depending on the selected type, the platform automatically generates an example request body and determines which credentials are required to run the action. + +- **Webhook (Webhook)**: The main action logic runs in an external service. The platform sends an HTTP request to that service. + +#### Field masking + +For each action, you can enable masking for fields that may contain sensitive information. + +If **Mask action fields** is enabled, the following will be hidden in action run records: + +- the `body` field (request body); +- the `response` field (response produced after the action completes); +- values of all filled-in parameters. + +#### Temporary response + +For each action, you can enable the **Temporary response** option. It restricts access to the action result and hides it from other users. + +When the option is enabled and the action completes successfully: + +- the response is stored as a temporary response and is visible **only** to the user who started the action; +- the regular response is cleared so it is not available to other users. + +Other users will see only an encrypted temporary response instead of the actual content. + +The action initiator can delete the temporary response manually. + +{{< alert level="info" >}} +A temporary response is available only to the action initiator. Other users cannot view its contents and cannot delete it. +{{< /alert >}} + +#### Retry count + +If an action fails, the platform can retry it automatically. The **retry count** parameter defines the maximum number of automatic retries. + +#### Base delay (sec) + +The **base delay** parameter defines the delay between retries. The delay increases on each retry (exponentially). For example, with a base delay of 2 seconds, retries will occur after 2, 4, 8 seconds, and so on. + +#### Request body + +Each action sends an HTTP request either to the built-in backend or to the webhook backend URL. In most cases, the request includes a body describing the operation specification. + +For built-in backends, an example request body is available while editing the action. + +#### Request body example + +You can inject parameter values from the user form into the request body using [Go template](https://developer.hashicorp.com/nomad/tutorials/templates/go-template-syntax) with YAML syntax. + +Example: + +```yaml +project_id: {{ .project_id }} +``` + +With this request body, the `{{ .project_id }}` expression will be replaced with the `project_id` parameter value entered by the user in the action run form. + +#### Final request body + +The **Final request body** field shows what the request will look like after parameter substitution and formatting. If the final body is valid JSON, the UI will display syntax highlighting. If highlighting is not available, verify that the generated request body is correct. + +#### URL + +To run a webhook action, specify the external backend address in the **URL** field. The platform will send the request to this address. + +For built-in actions, the **URL** field can either contain the address of the infrastructure service the action interacts with or be left empty. The allowed options depend on the specific built-in action type and are described in its documentation. + +#### Disable SSL verification + +This option defines whether the platform verifies the SSL certificate of: + +- the webhook backend (for webhook actions); +- the infrastructure service (for built-in actions). + +Enable this option if you use self-signed or otherwise untrusted certificates. + +#### Method + +The HTTP method used for requests to the webhook backend. For built-in actions, the method is determined automatically based on the action type. + +#### Headers + +HTTP headers in the `key: value` format that will be added to the request to the webhook backend. For built-in actions, headers are generated automatically depending on the action type. + +### Entity updates + +#### Updating entity parameters + +After an action runs, the result (typically the response from the infrastructure system) is stored in the `response` field. If **Update entity parameters** is enabled, the platform uses the data from `response` and applies the update rules to write values into the entity parameters. + +For example, when running the **Create GitLab project** action, the `response` field will contain the specification of the created project, for example: + +```json +{ + "id": "1", + "...": "..." +} +``` + +If you need to populate the `repository_id` entity parameter right after creating a GitLab project, specify the following in the update rules: + +- **Source:** `{{ .response.id }}` +- **Entity parameter:** `repository_id` + +#### Creating entity relationships + +If **Create entity relationships** is enabled, the platform will automatically create new relationships for the selected entity according to the configured rules. Define a separate set of rules for each resource. + +In a relationship rule, you specify the **parent** and **child** resources. Entity lookup is performed using a single identifier: either by the parent resource or by the child resource. + +Within a single rule, provide **only one** identifier. If both parent and child identifiers are specified, the lookup will be performed by the **parent** resource. + +### Security + +#### Approval before execution + +You can require approvals for an action and set the number of required approvers. In this case, the action will not start until the specified number of approvals is received from the configured users. + +The current number of approvals and the list of users whose approval is required are shown in the action runs table for the corresponding entity. + +If approval is required from a specific user, they will receive a notification in the platform UI. + +#### Account used to run the action + +By default, access to external infrastructure services uses the credentials of the user who started the action. If needed, you can explicitly configure the action to run using the credentials of a specific account. + +For actions that are triggered as automation events, specifying the account to run the action is required. + +#### Credentials + +For built-in actions, the platform predefines the required set of credentials. Their identifiers are loaded when you select the built-in backend. For each identifier, you must choose which credential type to use. + +For webhook actions, you can reference credentials in the request body using `{{ .credentials. }}`. + +## Action runs + +### Action run records + +Each time an action is started, a run record is created that includes the initiator, execution status, and a detailed log. Run records for each entity are available in the entity card on the **Action runs** tab. If approvals are required, they are collected on the same tab. + +You can delete a run record or rerun the action. Rerunning creates a new run record. + +### Run logging + +For each action run, a database record is created containing the full execution log. + +The `actions.logging.enabled` parameter in the DDP configuration file controls whether run logs are printed to stdout: when set to `true`, logs are printed; when set to `false`, they are not. + +{{< alert level="info" >}} +Database records with the full action run log are created regardless of the `actions.logging.enabled` value. +{{< /alert >}} + +### Action statuses + +Each action run has a status record. Possible statuses are: + +- **Created** — the run record is created, but the action has not started yet. +- **Unapproved** — the action is waiting for approvals. +- **Running** — the action is in progress. +- **Failed** — the action finished with an error. +- **Update failed** — the action completed, but updating the entity parameters failed. +- **Success** — the action completed successfully. +- **Retrying** — the action finished with an error and is being retried. diff --git a/content/documentation/admin/actions/overview.ru.md b/content/documentation/admin/actions/overview.ru.md index 972cbc1..02b024f 100644 --- a/content/documentation/admin/actions/overview.ru.md +++ b/content/documentation/admin/actions/overview.ru.md @@ -3,57 +3,56 @@ title: Обзор weight: 10 --- -Действия — это механизм платформы, предназначенный для выполнения операций во внешних инфраструктурных системах и сервисах, находящихся за пределами платформы. -С помощью действий можно, например, создавать: +Действия — это механизм платформы для запуска операций во внешних инфраструктурных системах и сервисах, то есть за пределами платформы. С помощью действий можно, например: -- проекты, переменные, ветки либо теги для проектов в Gitlab. -- ресурсы в Kubernetes. -- секреты в Deckhouse Stronghold, либо в HashiCorp Vault. -- проекты в SonarQube, DefectDojo, и других системах. -- топики и ACL в Kafka. +- создавать проекты, переменные, ветки или теги в GitLab; +- создавать ресурсы в Kubernetes; +- создавать секреты в Deckhouse Stronghold или HashiCorp Vault; +- создавать проекты в SonarQube, DefectDojo и других системах; +- создавать топики и ACL в Kafka. -Каждое действие может быть привязано к одному или нескольким ресурсам и может быть запущено для любой сущности данных ресурсов. +Действие можно привязать к одному или нескольким ресурсам. После этого его можно запускать для любой сущности данных этих ресурсов. ## Конфигурация действия ### Основная информация -Для каждого действия, при его создании или изменении, указывается основная информация: +При создании или редактировании действия укажите основную информацию: -- **Название** (обязательно) — название действия в произвольном формате. +- **Название** (обязательно) — произвольное название действия. - **Идентификатор** (обязательно) — идентификатор действия. Генерируется автоматически из названия. - **Ресурс** (опционально) — один или несколько ресурсов, для которых будет доступен запуск действия. -- **Иконка** (опционально) — иконка, которая будет отображаться в карточке действия. +- **Иконка** (опционально) — иконка, которая отображается в карточке действия. - **Владелец** (опционально) — учетная запись пользователя, отвечающего за конфигурацию и работоспособность действия. -- **Команда владелец** (опционально) — команда, отвечающая за конфигурацию и работоспособность действия. -- **Теги** (опционально) — теги, которые могут помогать в понимании того, зачем и когда используется действие. -- **Описание** (опционально) — описание действия в Markdown, которое будет отображаться при запуске действия или сценария, содержащего действие. +- **Команда владельца** (опционально) — команда, отвечающая за конфигурацию и работоспособность действия. +- **Теги** (опционально) — теги для классификации и поиска действий. +- **Описание** (опционально) — описание в Markdown. Отображается при запуске действия или сценария, содержащего действие. ### Пользовательская форма #### Параметры -В разделе «Пользовательская форма» указываются параметры, которые будут доступны для заполнения при запуске действия. Типы параметров описаны в документации в разделе [«Параметры»](../../user/properties/). +В разделе «Пользовательская форма» укажите параметры, доступные для заполнения при запуске действия. Типы параметров описаны в разделе [«Параметры»](../../user/properties/). -Для каждого параметра доступен выбор следующих опций: +Для каждого параметра доступны опции: -- **Редактируемый** — позволяет изменить значение параметра при запуске действия. Если опция отключена, значение параметра изменить нельзя. +- **Редактируемый** — позволяет изменить значение параметра при запуске действия. Если опция выключена, значение изменить нельзя. - **Обязательный** — требует указания значения при запуске действия. - **Скрытый** — параметр не отображается в пользовательской форме при запуске действия. -Для каждого параметра можно задать значение по умолчанию, которое будет подставляться в пользовательскую форму при запуске действия. +Для каждого параметра можно задать значение по умолчанию, которое будет подставляться в форму при запуске. {{< alert level="info" >}} -Для нередактируемых или скрытых параметров рекомендуется всегда указывать значение по умолчанию, так как при запуске действия пользователь не может их изменить. +Для нередактируемых или скрытых параметров рекомендуется задавать значение по умолчанию, так как при запуске действия пользователь не сможет их изменить. {{< /alert >}} -Описание каждого параметра будет отображаться при запуске действия при нажатии на кнопку со значком «info». Заполнение описаний рекомендуется, так как они упрощают понимание назначения параметров и снижают риск ошибок при запуске. +Описание параметра отображается при запуске действия по кнопке со значком «info». Рекомендуется заполнять описания, чтобы было проще понять назначение параметров и снизить риск ошибок при запуске. -В качестве значений для пользовательской формы возможно использование шаблонных функций [Go template](https://developer.hashicorp.com/nomad/tutorials/templates/go-template-syntax). Например, выражение `{{ .entity.name }}`, заданное в качестве значения параметра, будет означать, что при запуске действия подставится название сущности, для которой запускается действие. +В значениях параметров можно использовать шаблонные функции [Go template](https://developer.hashicorp.com/nomad/tutorials/templates/go-template-syntax). Например, выражение `{{ .entity.name }}` в значении параметра означает, что при запуске действия будет подставлено название сущности, для которой оно запускается. #### Условия параметров -Параметры могут быть скрыты или показаны в пользовательской форме в зависимости от значения параметра типа `Boolean`. Настройка скрытия или показа параметров осуществляется в разделе «Условия параметров». +Параметры могут автоматически скрываться или отображаться в пользовательской форме в зависимости от значения параметра типа `Boolean`. Настройка выполняется в разделе «Условия параметров», где вы задаёте правила показа/скрытия для выбранных параметров. ### Бэкенд @@ -63,50 +62,54 @@ weight: 10 - **Встроенный (BuiltIn)** — основная логика действия выполняется внутри платформы. - > При выборе встроенного бэкенда необходимо указать конкретный тип встроенного действия. В зависимости от выбранного типа платформа автоматически формирует пример тела запроса и определяет перечень учетных данных, необходимых для выполнения действия. + > При выборе встроенного бэкенда необходимо указать тип встроенного действия. В зависимости от выбранного типа платформа автоматически формирует пример тела запроса и определяет список учетных данных, необходимых для выполнения действия. - **Вебхук (Webhook)** — основная логика действия выполняется внешним сервисом, которому платформа отправляет HTTP-запрос. #### Маскирование полей действия -Для каждого действия можно настроить маскировку полей, содержащих потенциально конфиденциальную информацию. +Для каждого действия можно включить маскирование полей, которые могут содержать конфиденциальную информацию. -При установке флага **маскировать поля действия** в записях действия будут скрыты: +Если включить опцию «Маскировать поля действия», в записях выполнения действия будут скрыты: -- Поле `body` (тело запроса). -- Поле `response` (ответ, который генерируется после выполнения действия). -- Значение всех заполненных параметров. +- поле `body` (тело запроса); +- поле `response` (ответ, сформированный по результатам выполнения); +- значения всех заполненных параметров. #### Временный ответ -Для каждого действия можно включить опцию **временный ответ**, которая позволяет скрыть ответ действия от других пользователей. +Для каждого действия можно включить опцию «Временный ответ». Она позволяет ограничить доступ к результату выполнения действия и скрыть его от других пользователей. -При включенной опции, после успешного выполнения действия ответ сохраняется как временный и показывается только инициатору действия. Обычный ответ очищается, чтобы скрыть его от других пользователей. Они будут видеть только зашифрованный временный ответ. +Если опция включена, то после успешного выполнения действия ответ: + +- сохраняется как временный и отображается **только** пользователю, который запустил действие; +- удаляется из обычного поля ответа, чтобы он не был доступен другим пользователям. + +Другие пользователи вместо содержимого ответа будут видеть только зашифрованный временный ответ. Инициатор действия может удалить временный ответ вручную. {{< alert level="info" >}} -Временный ответ доступен только для инициатора действия. Остальные пользователи не могут просмотреть содержимое временного ответа и не имеют возможности его удалить. +Временный ответ доступен только инициатору действия. Остальные пользователи не могут просмотреть его содержимое и не могут удалить его. {{< /alert >}} #### Количество перезапусков -Если выполнение действия завершается с ошибкой, платформа может автоматически выполнить повторные попытки. Параметр **количество перезапусков** задает максимальное количество автоматических перезапусков действия. +Если выполнение действия завершается с ошибкой, платформа может автоматически выполнить повторные попытки. Параметр «Количество перезапусков» задает максимальное число таких повторных запусков. #### Базовая задержка (сек.) -Параметр **базовая задержка** задает интервал между попытками перезапуска действия. Интервал увеличивается при каждом перезапуске, например, если базовая задержка задана в 2 секунды, то первая попытка перезапуска действия будет через 2 секунды, вторая попытка через 4 секунды, третья - через 8 секунд и так далее. +Параметр «Базовая задержка» задает интервал между повторными попытками. При каждом перезапуске задержка увеличивается (экспоненциально). Например, при базовой задержке 2 секунды перезапуски будут выполняться через 2, 4, 8 секунд и далее. #### Тело запроса -Каждое действие отправляет HTTP-запрос на встроенный бэкенд, либо на URL вебхука бэкенда. -В большинстве случаев запрос должен содержать тело, в котором описывается спецификация данного запроса. +Каждое действие отправляет HTTP-запрос на встроенный бэкенд или на URL вебхука бэкенда. Обычно запрос включает тело, в котором описывается спецификация операции. Для встроенного бэкенда при редактировании действия доступен пример тела запроса. #### Пример тела запроса -В тело запроса действия могут быть подставлены параметры из пользовательской формы в формате [Go template](https://developer.hashicorp.com/nomad/tutorials/templates/go-template-syntax) с использованием синтаксиса YAML. +В тело запроса можно подставлять значения параметров из пользовательской формы с помощью шаблонов [Go template](https://developer.hashicorp.com/nomad/tutorials/templates/go-template-syntax) в YAML. Пример: @@ -114,39 +117,42 @@ weight: 10 project_id: {{ .project_id }} ``` -При подобном теле запроса конструкция `{{ .project_id }}` будет заменена на значение параметра **project_id**, которое, в свою очередь, будет браться из пользовательской формы. +При таком теле запроса выражение `{{ .project_id }}` будет заменено на значение параметра `project_id`, введенное пользователем в форме запуска действия. #### Итоговое тело запроса -Поле **итоговое тело запроса** показывает, как будет выглядеть запрос после форматирования. При валидном JSON будет работать подсветка синтаксиса. При отсутствии подсветки обратите внимание на корректность формирования тела запроса. +Поле «Итоговое тело запроса» показывает, как будет выглядеть запрос после подстановки параметров и форматирования. Если итоговое тело является валидным JSON, в интерфейсе будет доступна подсветка синтаксиса. Если подсветки нет, проверьте корректность сформированного тела запроса. #### URL -Для выполнения любого действия вебхука, в поле **URL** необходимо указать URL внешнего бэкенда, на который будет отправлен запрос. +Для выполнения вебхук-действия в поле **URL** укажите адрес внешнего бэкенда, на который платформа отправит запрос. -Для встроенных действий в поле **URL** может указываться URL инфраструктурного сервиса, с которым будет происходить взаимодействие, либо данное поле может оставаться пустым. Подробности указаны в описании конкретных встроенных действий. +Для встроенных действий поле **URL** может содержать адрес инфраструктурного сервиса, с которым выполняется взаимодействие, или оставаться пустым. Допустимые варианты зависят от конкретного типа встроенного действия и описаны в его документации. #### Выключить проверку SSL -Параметр определяет, будет ли проверяться SSL-сертификат бэкенда при выполнении вебхук-действия либо SSL-сертификат инфраструктурного сервиса, с которым происходит взаимодействие при выполнении встроенного действия. +Параметр определяет, будет ли платформа проверять SSL-сертификат: -При использовании самоподписных и (или) недоверенных сертификатов параметр должен быть активирован. +- вебхук-бэкенда (для вебхук-действий); +- инфраструктурного сервиса (для встроенных действий). + +Включайте эту опцию, если используются самоподписанные или недоверенные сертификаты. #### Метод -HTTP-метод, который будет использоваться при запросе на вебхук бэкенда. Для встроенных действий метод определяется автоматически в зависимости от типа действия. +HTTP-метод запроса к вебхук-бэкенду. Для встроенных действий метод определяется автоматически в зависимости от типа действия. #### Headers -Headers — HTTP-заголовки в формате ключ-значение, которые будут добавлены в запрос к вебхуку бэкенда. Для встроенных действий заголовки добавляются автоматически в зависимости от типа действия. +HTTP-заголовки в формате «ключ: значение», которые будут добавлены в запрос к вебхук-бэкенду. Для встроенных действий заголовки формируются автоматически в зависимости от типа действия. ### Обновление сущности #### Обновление параметров сущности -После выполнения каждого действия результат (как правило, ответ от инфраструктурной системы) записывается в поле **response**. Если включена опция **обновление параметров сущности**, то на основании данных из **response** действие обновляет параметры сущности в соответствии с правилами обновления. +После выполнения действия результат (как правило, ответ инфраструктурной системы) сохраняется в поле `response`. Если включена опция «Обновление параметров сущности», платформа использует данные из `response` и применяет правила обновления, чтобы записать значения в параметры сущности. -Например, при выполнении действия «Создание проекта в GitLab» в поле **response** будет записана спецификация созданного проекта со следующей структурой: +Например, при выполнении действия «Создание проекта в GitLab» в поле `response` будет сохранена спецификация созданного проекта, например: ```json { @@ -155,66 +161,67 @@ Headers — HTTP-заголовки в формате ключ-значение, } ``` -Если после создания проекта в GitLab необходимо сразу заполнить параметр `repository_id` сущности, для которой этот проект был создан, в правилах обновления следует использовать следующую конструкцию: +Если после создания проекта в GitLab нужно сразу заполнить параметр сущности `repository_id`, укажите в правилах обновления: -* Источник: `{{ .response.id }}`. -* Параметр сущности: `repository_id`. +- **Источник:** `{{ .response.id }}` +- **Параметр сущности:** `repository_id` #### Создание связей сущностей -Если опция **создание связей сущностей** включена, то после выполнения действия для выбранной сущности будут автоматически созданы новые связи согласно заданным правилам. Для каждого ресурса можно определить свой набор правил. +Если включена опция «Создание связей сущностей», платформа автоматически создаст новые связи для выбранной сущности по заданным правилам. Набор правил задается отдельно для каждого ресурса. + +В правиле связи указываются **родительский** и **дочерний** ресурсы. Поиск сущностей выполняется по одному идентификатору: либо по родительскому ресурсу, либо по дочернему. -При создании связи задаются родительский и дочерний ресурсы. Поиск сущностей выполняется в зависимости от указанного идентификатора: по родительскому или дочернему ресурсу. -В одном правиле следует указывать только один идентификатор. При одновременном указании родительского и дочернего идентификаторов поиск выполняется по родительскому ресурсу. +В рамках одного правила указывайте **только один** идентификатор. Если заданы и родительский, и дочерний идентификаторы, поиск выполняется по **родительскому** ресурсу. ### Безопасность #### Подтверждение перед запуском -Для действий может быть настроено обязательное подтверждение и количество подтверждающих перед запуском. В этом случае действие не будет выполнено до тех пор, пока не будет получено заданное количество подтверждений от заданных пользователей. +Для действия можно включить обязательное подтверждение и задать количество подтверждающих. В этом случае действие не будет запущено, пока не будет получено указанное число подтверждений от заданных пользователей. -Посмотреть текущее количество подтвердивших и список тех, от кого ожидается подтверждение, можно в таблице запуска действий для каждой сущности. +Текущее число подтверждений и список пользователей, от которых ожидается подтверждение, отображаются в таблице запусков действий для соответствующей сущности. Если подтверждение требуется от конкретного пользователя, ему будет отправлено уведомление в интерфейсе платформы. #### Учетная запись для запуска действия -Для доступа к внешним инфраструктурным сервисам по умолчанию используются учетные данные пользователя, который запустил действие. При этом существует возможность в явном виде указать, что действие будет запускаться с использованием учетных данных конкретной учетной записи. +По умолчанию доступ к внешним инфраструктурным сервисам выполняется с использованием учетных данных пользователя, который запустил действие. При необходимости можно явно указать, что действие должно выполняться от имени конкретной учетной записи. -Для действий, которые предполагается запускать в качестве события автоматизации, указание учетной записи для запуска является обязательным условием. +Для действий, запускаемых как события автоматизации, указание учетной записи для запуска является обязательным. #### Учетные данные -Для встроенных действий платформа заранее определяет перечень необходимых учетных данных. Идентификаторы этих учетных данных подгружаются при выборе встроенного бэкенда. Для каждого из идентификаторов необходимо выбрать, какой тип учетных данных будет использоваться. +Для встроенных действий платформа заранее определяет набор требуемых учетных данных. Их идентификаторы подгружаются при выборе встроенного бэкенда. Для каждого идентификатора необходимо выбрать тип учетных данных, который будет использоваться. -Для вебхук-действий обращение к учетным данным возможно в теле запроса с использованием конструкции `{{ .credentials.<идентификатор типа учетных данных> }}`. +Для вебхук-действий к учетным данным можно обратиться в теле запроса с помощью конструкции `{{ .credentials.<идентификатор типа учетных данных> }}`. ## Запуски действий ### Записи запусков действий -При каждом запуске действия создается запись, в которой указан инициатор запуска, статус выполнения и подробный лог. Записи запущенных действий для каждой сущности можно посмотреть в карточке сущности на вкладке «Запуски действий». Если для запуска действия необходимо подтверждение, оно выполняется в этой же вкладке. +При каждом запуске действия создается запись, содержащая инициатора, статус выполнения и подробный лог. Записи запусков для каждой сущности доступны в карточке сущности на вкладке «Запуски действий». Если для действия требуется подтверждение, оно выполняется на этой же вкладке. -Запись о запуске действия можно удалить, либо перезапустить действие. При перезапуске создается новая запись запуска. +Запись о запуске можно удалить или перезапустить действие. При перезапуске создается новая запись. ### Логирование запусков -Для каждого запуска действия создается запись в БД, содержащая полный лог выполнения. +Для каждого запуска действия в базе данных создается запись, содержащая полный лог выполнения. -Параметр `actions.logging.enabled` в конфигурационном файле DDP позволяет выводить в stdout, либо скрывать логи запуска действия. При значении `true` логи запуска будут выводиться в stdout, при значении `false` логи выводиться не будут. +Параметр `actions.logging.enabled` в конфигурационном файле DDP управляет выводом логов запуска в stdout: при значении `true` логи выводятся, при значении `false` не выводятся. {{< alert level="info" >}} -Записи в БД с полным логом запуска действия создаются независимо от значения параметра `actions.logging.enabled`. +Записи с полным логом запуска в базе данных создаются независимо от значения `actions.logging.enabled`. {{< /alert >}} ### Статусы действий -Для каждого запуска действия создается запись о его статусе. Статусы могут быть следующими: +Для каждого запуска действия создается запись со статусом. Возможные статусы: -- **Created** — запись создана, но действие еще не было запущено. +- **Created** — запись создана, но действие еще не запускалось. - **Unapproved** — действие ожидает подтверждения. - **Running** — действие выполняется. -- **Failed** — действие завершилось неуспешно. +- **Failed** — действие завершилось с ошибкой. - **Update failed** — действие выполнено, но обновить параметры сущности не удалось. -- **Success** — действие завершилось успешно. -- **Retrying** — действие завершилось неуспешно, выполняется попытка перезапуска. +- **Success** — действие выполнено успешно. +- **Retrying** — действие завершилось с ошибкой, выполняется повторная попытка запуска. diff --git a/content/documentation/release-notes/v1.2.0.md b/content/documentation/release-notes/v1.2.0.md new file mode 100644 index 0000000..ef18f47 --- /dev/null +++ b/content/documentation/release-notes/v1.2.0.md @@ -0,0 +1,61 @@ +--- +title: v1.2.0 +weight: 960 +--- + +{{< alert level="info" >}} +The release is expected on 29.01.2026. +{{< /alert >}} + +## Backward-incompatible changes + +### Icons + +Icons are now selected from a centralized catalog (built-in library icons or user-uploaded icons). If you previously used icons specified via a URL, they will no longer be displayed. + +### Database requirements + +Global search requires the PostgreSQL `pg_trgm` extension. When upgrading to v1.2.0, install the extension in the database you use: + +```sql +CREATE EXTENSION IF NOT EXISTS pg_trgm; +``` + +## New features + +### AI agent + +Added a secure storage mechanism for AI provider credentials. + +### Global search + +Added global search across all platform entities: + +- **Quick access** — search is available from the top bar on all platform pages. +- **Fuzzy search** — search works by entity name, ID, and team, tolerating typos. +- **Access control aware** — results include only entities the user has permission to access. +- **Pagination** — results are paginated for easier navigation. +- **Fast navigation** — clicking a result opens the corresponding entity page. + +### Actions + +- Added the `actions.logging.enabled` setting to control action logs output to stdout. +- Added the ability to configure a temporary response for actions. + +### Object ownership + +Added automatic assignment of the current user as the owner of newly created objects. + +### RBAC model + +- Added new global permissions for managing icons: `create:icons` and `delete:icons`. +- Added the `Developer` global role preset. + +## Bug fixes + +- Fixed forced regeneration of an object ID when opening the edit form. +- Fixed RBAC rules for editing team variables. +- Fixed the behavior of the `datasources.logging.enabled` setting. +- Fixed a hang when creating a Vault secret without the `allow_update` parameter. +- Fixed the approve/skip mechanisms for actions in processes. +- Fixed external service selection for actions in processes. diff --git a/content/documentation/release-notes/v1.2.0.ru.md b/content/documentation/release-notes/v1.2.0.ru.md index a01841a..0c418f8 100644 --- a/content/documentation/release-notes/v1.2.0.ru.md +++ b/content/documentation/release-notes/v1.2.0.ru.md @@ -4,40 +4,58 @@ weight: 960 --- {{< alert level="info" >}} -Выпуск релиза планируется 29.01.2026 +Выпуск релиза запланирован на 29.01.2026. {{< /alert >}} ## Изменения, влияющие на обратную совместимость ### Иконки -Иконки теперь выбираются из централизованного каталога (встроенные иконки из библиотек или загруженные пользователями). Если ранее использовались иконки, заданные через URL, они перестанут отображаться. +Иконки теперь выбираются из централизованного каталога (встроенные иконки из библиотек или загруженные пользователями). Если ранее иконки задавались через URL, они больше не будут отображаться. + +### Требования к базе данных + +Для работы глобального поиска требуется расширение PostgreSQL `pg_trgm`. При обновлении до версии v1.2.0 установите расширение в используемой базе данных: + +```sql +CREATE EXTENSION IF NOT EXISTS pg_trgm; +``` ## Новые возможности ### AI-агент -Добавлен механизм безопасного хранения учетных данных для AI-провайдеров ([подробнее](../../user/ai-agent/#учетные-данные-для-провайдеров)). +Добавлен механизм безопасного хранения учетных данных для AI-провайдеров. + +### Глобальный поиск + +Добавлен глобальный поиск по всем сущностям платформы: + +- **Быстрый доступ** — поиск доступен из верхней панели на всех страницах платформы. +- **Нечеткий поиск** — поиск выполняется по названию, идентификатору и команде сущности с учетом возможных опечаток. +- **Учет прав доступа** — в результатах отображаются только сущности, к которым у пользователя есть доступ. +- **Пагинация** — результаты выводятся постранично для удобной навигации. +- **Быстрая навигация** — клик по результату открывает карточку соответствующей сущности. ### Действия -- Добавлен параметр конфигурации `actions.logging.enabled`, позволяющий управлять выводом логов действий в stdout ([подробнее](../../admin/actions/overview/#логирование-запусков)). -- Добавлена возможность настройки временного ответа для действий ([подробнее](../../admin/actions/overview/#временный-ответ)). +- Добавлен параметр `actions.logging.enabled` для управления выводом логов действий в stdout. +- Добавлена возможность настраивать временный ответ для действий. ### Владение объектами -Добавлена автоматическая установка текущего пользователя в качестве владельца создаваемых объектов ([подробнее](../../admin/security/rbac/#автоматическое-назначение-владельца-при-создании)). +Добавлена автоматическая установка текущего пользователя [в качестве владельца создаваемых объектов](../../admin/security/rbac/#автоматическое-назначение-владельца-при-создании). ### Ролевая модель -- Добавлены новые глобальные разрешения для управления иконками: `create:icons` и `delete:icons`. -- Добавлен пресет глобальной роли `Developer` ([подробнее](../../admin/security/rbac/#пресет-developer)). +- Добавлены новые глобальные разрешения для управления иконками `create:icons` и `delete:icons`. +- Добавлен [пресет глобальной роли `Developer`](../../admin/security/rbac/#пресет-developer). ## Исправленные проблемы -- Решена проблема с принудительной перегенерацией идентификатора объекта при открытии формы редактирования. +- Исправлена принудительная перегенерация идентификатора объекта при открытии формы редактирования. - Исправлена ролевая модель для редактирования переменных команд. -- Исправлено поведение параметра конфигурации `datasources.logging.enabled`. +- Исправлено поведение параметра `datasources.logging.enabled`. - Исправлено зависание при создании секрета в Vault без параметра `allow_update`. - Исправлена работа механизмов подтверждения и пропуска действий в процессах. - Исправлен выбор внешних сервисов для действий в процессах. diff --git a/content/documentation/user/interface.md b/content/documentation/user/interface.md new file mode 100644 index 0000000..7c5d1b3 --- /dev/null +++ b/content/documentation/user/interface.md @@ -0,0 +1,30 @@ +--- +title: Interface +weight: 20 +--- + +The Deckhouse Development Platform interface consists of the following sections: + +- **Home**: the platform’s landing page. You can place one or more dashboards with widgets here. +- **Catalog**: a service catalog for viewing resources, entities, and relationships, and for running actions and scenarios. +- **Self-Service**: a section for configuring data sources, actions, webhooks, automations, scenarios, dashboards, and widgets. Access to this section can be restricted by the RBAC model. +- **Administration**: a section for managing teams, users, access policies, and credentials. Access to this section can be restricted by the RBAC model. + +## Global search + +The top navigation bar includes a **Search** button. It lets you quickly find entities across the platform. + +### How to use search + +1. Open search: click **Search** in the top navigation bar. +1. Enter a query: start typing in the search field. +1. Select a result: results appear in a dropdown list under the input field. For each matching entity, the platform shows: + - name; + - ID; + - slug; + - the resource the entity belongs to. + +### Limitations + +- Maximum query length: 255 characters. +- Search works only for entities. Resources, teams, and other platform objects are not included in search results. diff --git a/content/documentation/user/interface.ru.md b/content/documentation/user/interface.ru.md index 1d51e78..3d0a43b 100644 --- a/content/documentation/user/interface.ru.md +++ b/content/documentation/user/interface.ru.md @@ -3,9 +3,28 @@ title: Интерфейс weight: 20 --- -Интерфейс Deckhouse Development Platform включает в себя следующие разделы: +Интерфейс Deckhouse Development Platform состоит из следующих разделов: -- **Главная** — стартовая страница. На неё могут быть прикреплены дашборды с виджетами. -- **Каталог** — сервисный каталог, раздел для отображения ресурсов, сущностей, связей, а также для запуска действий и сценариев. +- **Главная** — стартовая страница платформы. Здесь можно размещать один или несколько дашбордов с виджетами. +- **Каталог** — сервисный каталог для просмотра ресурсов, сущностей и связей, а также для запуска действий и сценариев. - **Самообслуживание** — раздел для настройки источников данных, действий, вебхуков, автоматизаций, сценариев, дашбордов и виджетов. Доступ к разделу может быть ограничен ролевой моделью. -- **Администрирование** — раздел для управления командами, пользователями, политиками доступа и учётными данными. Доступ к разделу может быть ограничен ролевой моделью. +- **Администрирование** — раздел для управления командами, пользователями, политиками доступа и учетными данными. Доступ к разделу может быть ограничен ролевой моделью. + +## Глобальный поиск + +В верхней панели интерфейса доступна кнопка «Поиск». Она позволяет быстро находить сущности по всей платформе. + +### Как пользоваться поиском + +1. Откройте поиск — нажмите кнопку «Поиск» в верхней панели. +1. Введите запрос — начните вводить текст в поле поиска. +1. Выберите результат — результаты отображаются в выпадающем списке под полем ввода. Для каждой найденной сущности показываются: + - название; + - идентификатор; + - slug; + - ресурс, в котором находится сущность. + +### Ограничения + +- Максимальная длина запроса: 255 символов. +- Поиск работает только по сущностям. Ресурсы, команды и другие объекты платформы в результаты не попадают.