diff --git a/.werf/nginx-local.conf b/.werf/nginx-local.conf index cf0ace5..197f56f 100644 --- a/.werf/nginx-local.conf +++ b/.werf/nginx-local.conf @@ -100,12 +100,6 @@ http { } location /products/development-platform/documentation/ { - proxy_cache dcache; - proxy_cache_valid 200 30d; - proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504; - proxy_cache_background_update on; - proxy_cache_lock on; - proxy_redirect off; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; diff --git a/Makefile b/Makefile index 81a6efa..9e47088 100644 --- a/Makefile +++ b/Makefile @@ -6,6 +6,7 @@ BIND ?= 0.0.0.0 SERVE_FLAGS ?= --cleanDestinationDir --bind=$(BIND) HUGOFLAGS ?= --minify MARKDOWNLINT_VERSION ?= v0.45.0 +WERF_PLATFORM ?= linux/amd64 .PHONY: help serve build clean lint-markdown lint-markdown-fix .PHONY: help serve build clean lint-markdown lint-markdown-fix mod @@ -32,7 +33,7 @@ help: up: which werf >/dev/null || source $(trdl use werf 2 beta) - werf compose up --dev + WERF_PLATFORM=$(WERF_PLATFORM) werf compose up --dev serve: $(HUGO) serve $(SERVE_FLAGS) diff --git a/content/documentation/_index.md b/content/documentation/_index.md index f615430..1b1f5e5 100644 --- a/content/documentation/_index.md +++ b/content/documentation/_index.md @@ -1,11 +1,26 @@ --- -title: Deckhouse Development Platform Documentation -description: Documentation for the project, including guides, API references, and tutorials. +title: Overview +description: Documentation for the Deckhouse Development Platform product weight: 10 --- -{{< alert level="warning" >}} -This is the Deckhouse Development Platform alert example. -{{< /alert >}} +Deckhouse Development Platform (DDP) is a comprehensive solution for managing all stages of development through a single interface. -Deckhouse Development Platform is a powerful software designed for the efficient delivery of arbitrary applications in Kubernetes. +The platform helps IT professionals work more efficiently — it automates operations related to the service lifecycle and provides tools to assess the overall system performance. + +## Key features + +- **Unified development standards for teams**. + The platform enables the creation of templates and standard configurations (CI/CD, Kubernetes, etc.) and ensures these standards are propagated across all development teams. +- **Dynamic environments under control**. + Creating, updating, and deleting environments takes just minutes, with stand setup and removal performed automatically. +- **Integration of otherwise incompatible services**. + Interaction can be configured with any infrastructure system that has an API (such as ticket management systems, firewall access management, etc.). +- **Simplified onboarding of developers and teams**. + New team members can start contributing quickly thanks to templates, documentation, and preconfigured project structures provided by the platform. +- **Digitization of development processes and scenarios**. + A BPMN-like process description engine helps automate and optimize all stages of development. +- **Built-in CMDB**. + DDP automatically gathers data from infrastructure services, compiles it into a service catalog, and visualizes the dependencies between them. +- **Service parameter monitoring**. + The solution quickly verifies key service performance indicators using health checks and collects static analysis metrics, vulnerability data, CI/CD pipeline statuses, and more. diff --git a/content/documentation/_index.ru.md b/content/documentation/_index.ru.md index a1a90c6..5b6bc31 100644 --- a/content/documentation/_index.ru.md +++ b/content/documentation/_index.ru.md @@ -1,11 +1,26 @@ --- -title: Документация Deckhouse Development Platform +title: Обзор +description: Документация продукта Deckhouse Development Platform weight: 10 -description: Documentation for the Deckhouse Development Platform project. --- -{{< alert level="warning" >}} -Это пример алерта в документации Deckhouse Development Platform. -{{< /alert >}} +Deckhouse Development Platform (DDP) — это комплексное решение для управления всеми этапами разработки через единое окно. -Deckhouse Development Platform — это мощное программное обеспечение, предназначенное для эффективной доставки произвольных приложений в Kubernetes. +Платформа помогает ИТ-специалистам работать эффективнее — автоматизирует операции, связанные с жизненным циклом сервисов, и предоставляет инструменты для оценки работы всей системы. + +## Основные возможности + +- **Единые стандарты разработки для команд**. + Платформа позволяет подготовить шаблоны и типовые конфигурации (CI/CD, Kubernetes и т. д.) и обеспечивает трансляцию стандартов во все команды разработки. +- **Динамические окружения под контролем**. + Создание, обновление и удаление сред занимает минуты, а подготовка и удаление стендов выполняются автоматически. +- **Интеграция неинтегрируемых сервисов**. + Взаимодействие можно настроить с любой инфраструктурной системой, где есть API (система управления заявками, открытие доступов в firewall и т. д.). +- **Упрощённый онбординг разработчиков и команд**. + Новые сотрудники могут быстро начать работу за счёт шаблонных решений, документации и преднастроенной структуры проектов, которые предоставляет платформа. +- **Оцифровка процессов и сценариев разработки**. + BPMN-подобный механизм описания процессов помогает автоматизировать и оптимизировать все этапы разработки. +- **Встроенная база данных управления конфигурациями (CMDB)**. + DDP автоматически загружает данные из инфраструктурных сервисов, собирает в сервисный каталог и визуализирует зависимости между ними. +- **Контроль параметров сервисов**. + Решение быстро верифицирует ключевые параметры работы сервисов за счёт механизма проверки статуса (health check) и собирает метрики статического анализа, метрики по уязвимостям, статусы выполнения пайплайнов и т. д. diff --git a/content/documentation/admin/_index.md b/content/documentation/admin/_index.md new file mode 100644 index 0000000..05ad3f2 --- /dev/null +++ b/content/documentation/admin/_index.md @@ -0,0 +1,5 @@ +--- +title: Administration guide +weight: 60 +--- + diff --git a/content/documentation/admin/_index.ru.md b/content/documentation/admin/_index.ru.md new file mode 100644 index 0000000..2215ce8 --- /dev/null +++ b/content/documentation/admin/_index.ru.md @@ -0,0 +1,4 @@ +--- +title: Руководство администратора +weight: 60 +--- diff --git a/content/documentation/admin/actions/_index.ru.md b/content/documentation/admin/actions/_index.ru.md new file mode 100644 index 0000000..3b46b3f --- /dev/null +++ b/content/documentation/admin/actions/_index.ru.md @@ -0,0 +1,4 @@ +--- +title: Действия +weight: 30 +--- diff --git a/content/documentation/admin/actions/overview.ru.md b/content/documentation/admin/actions/overview.ru.md new file mode 100644 index 0000000..5599768 --- /dev/null +++ b/content/documentation/admin/actions/overview.ru.md @@ -0,0 +1,194 @@ +--- +title: Обзор +weight: 10 +--- + +Действия - механизм, позволяющий пользователям платформы взаимодействовать с внешними по отношению к платформе инфраструктурными сервисами. Например: + +- Создавать в Gitlab проекты, переменные, ветки либо теги для проектов. +- Создавать ресурсы в Kubernetes. +- Создавать секреты в Deckhouse Stronghold, либо в HashiCorp Vault. +- Создавать проекты в SonarQube, DefectDojo, и других системах. +- Создавать топики и ACL в Kafka. + +Каждое действие может быть привязано к одному или нескольким ресурсам и может быть запущено для любой сущности данных ресурсов. + +## Конфигурация + +### Основная информация + +Для каждого действия при создании или изменении указывается основная информация: + +- **Название** (обязательно) - название действия в произвольном формате. +- **Идентификатор** (обязательно) - идентификатор действия. Генерируется автоматически из названия. +- **Ресурс** (опционально) - один или несколько ресурсов, для которых будет доступен запуск действия. +- **Иконка** (опционально) - иконка, которая будет отображаться в карточке действия. +- **Владелец** (опционально) - учетная запись пользователя, отвечающего за конфигурацию и работоспособность действия. +- **Команда владелец** (опционально) - команда, отвечающая за конфигурацию и работоспособность действия. +- **Теги** (опционально) - теги, которые могут помогать в понимании того, зачем и когда используется действие. +- **Описание** (опционально) - описание действия в Markdown, которое будет отображаться при запуске действия или сценария, содержащего действие. + +### Пользовательская форма + +#### Параметры + +В разделе `Пользовательская форма` указываются параметры действия, которые будут доступны для заполнения при запуске действия. Типы параметров описаны в документации в разделе `Параметры`. + +Для каждого параметра доступен выбор следующих опций: + +* **Редактируемый** - значение редактируемых параметров можно изменять при запуске действия. В случае, если параметр нередактируемый, изменение его значения при запуске действия будет недоступно. +* **Обязательный** - обязательные параметры, значение которых необходимо заполнить при запуске действия. +* **Скрытый** - скрытые параметры не будут появляться в пользовательской форме при запуске действия. + +Для каждого параметра можно задать значение по умолчанию, которое будет подставляться в пользовательскую форму при запуске действия. + +{{< alert level="info" >}} +Для нередактируемых или скрытых параметров рекомендуется всегда указывать значение по умолчанию, так как у пользователя, запускающего действие, нет возможности изменить их значения. +{{< /alert >}} + +Описание каждого параметра будет отображаться при запуске действия при нажатии на кнопку со значком "info". Поэтому рекомендуется всегда заполнять описание параметра для упрощения понимания, зачем он необходим. + +В качестве значений для пользовательской формы возможно использование шаблонных функций [Go template](https://developer.hashicorp.com/nomad/tutorials/templates/go-template-syntax). Например, выражение `{{ .entity.name }}`, заданное в качестве значения параметра, будет означать, что при запуске действия подставится название сущности, для которой запускается действие. + +#### Условия параметров + +Параметры могут быть скрыты или показаны в пользовательской форме в зависимости от значения другого параметра типа Boolean. Настройка скрытия или показа параметров осуществляется в разделе "Условия параметров". + +### Backend + +#### Тип + +Backend для действия может быть одного двух типов: + +* **Встроенный (BuiltIn)** - основная логика действия выполняется внутри платформы. +* **Webhook** - основная логика действия выполняется сторонным сервисом, куда отправляется webhook. + +#### Встроенный Backend + +При выборе встроенного backend будет предложено указать, какой именно встроенный backend должен использоваться. В зависимости от этого будет сгенерирован пример тела запроса действия и учетные данные, которые необходимы для запуска. + +#### Маскировать поля действия + +Для каждого действия можно настроить маскировку полей, содержащих потенциально конфиденциальную информацию. + +При установке флага **маскировать поля действия** в записях действия будут скрыты: + +* Поле `body` (тело запроса). +* Поле `response` (ответ, который генерируется после выполнения действия). +* Значение всех заполненных параметров. + +#### Количество перезапусков + +В случае, если действие завершилось неуспешно, оно может быть автоматически перезапущено. Параметр **количество перезапусков** задает максимальное количество автоматических перезапусков действия. + +#### Базовая задержка (сек.) + +Параметр **базовая задержка** задает интервал между попытками перезапуска действия. Интервал увеличивается при каждом перезапуске, например, если базовая задержка задана в 2 секунды, то первая попытка перезапуска действия будет через 2 секунды, вторая попытка через 4 секунды, третья - через 8 секунд и так далее. + +#### Пример тела запроса + +Каждое действие отправляет HTTP запрос на встроенный backend, либо на URL webhook backend. В подавляющем большинстве случаев запрос должен содержать тело, в котором описывается спецификация данного запроса. + +Для встроенных backend при редактировании действия доступен пример тела запроса. + +#### Тело запроса + +В тело запроса действия могут быть подставлены параметры из пользовательской формы в формате [Go template](https://developer.hashicorp.com/nomad/tutorials/templates/go-template-syntax) с использованием синтаксиса YAML. + +Пример: + +```yaml +project_id: {{ .project_id }} +``` + +При подобном теле запроса конструкция `{{ .project_id }}` будет заменена на значение параметра **project_id**, которое, в свою очередь, будет браться из пользовательской формы. + +#### Итоговое тело запроса + +Поле **итоговое тело запроса** показывает, как будет выглядеть запрос после форматирования. При валидном JSON будет работать подсветка синтаксиса. При отсутствии подсветки синтаксиса рекомендуется обратить внимание на корректность формирования тела запроса. + +#### URL + +Для любого webhook действия в поле **URL** указывается URL стороннего backend, на который будет отправлен запрос. + +Для встроенных действий в поле **URL** может указываться URL инфраструктурного сервиса, с которым будет происходить взаимодействие, либо данное поле может оставаться пустым. Подробности указаны в описании конкретных встроенных действий. + +#### Выключить проверку SSL + +Параметр определяет, будет ли проверяться SSL-сертификат backend при выполнении webhook действия, либо SSL-сертификат инфраструктурного сервиса с которым происходит взаимодействие при выполнении встроенного действия. В случае использования самоподписных и/или недоверенных сертификатов параметр должен быть активирован. + +#### Метод + +HTTP-метод, который будет использоваться при запросе на webhook backend. Для встроенных действий метод определяется автоматически в зависимости от типа действия. + +#### Headers + +HTTP-хедеры в формате ключ-значение, которые будут добавлены в запрос на webhook backend. Для встроенных действий хедеры добавляются автоматически в зависимости от типа действия. + +### Обновление сущности + +#### Обновление параметров сущности + +После выполнения каждого действия результат (как правило, ответ от инфраструктурной системы) записывается в поле **response**. Если включена опция **обновление параметров сущности**, то на основании данных из **response** действие обновляет параметры сущности в соответствии с правилами обновления. + +Например, при выполнении действия «Создание проекта в GitLab» в поле **response** будет записана спецификация созданного проекта со следующей структурой: + +```json +{ + "id": "1", + "...": "..." +} +``` + +Если после создания проекта в GitLab необходимо сразу заполнить параметр `repository_id` сущности, для которой этот проект был создан, в правилах обновления следует использовать следующую конструкцию: + +* Источник: `{{ .response.id }}` +* Параметр сущности: `repository_id` + +#### Создание связей сущностей + +Если опция **создание связей сущностей** включена, то после выполнения действия для выбранной сущности будут автоматически созданы новые связи согласно заданным правилам. Для каждого ресурса можно определить свой набор правил. + +**Важно:** при создании связи ресурсов задаётся родительский и дочерний ресурс. при указании идентификатора родительской сущности, поиск будет произведен только по сущностям из родительского ресурса. Если указать идентификатор дочерней сущности, то поиск будет произведен только по сущностям дочернего ресурса. В рамках создания правила необходимо указывать либо родительский идентификатор, либо дочерний. При одновременном указании в рамках одного правила обоих идентификаторов, поиск будет производиться только по родительскому ресурсу. + +### Безопасность + +#### Подтверждение перед запуском + +Действиям можно назначать подтверждающих и их количество. В случае, если действие необходимо подтвердить, оно не будет выполняться до того момента, пока не будет собрано необходимое количество подтверждающих. + +Посмотреть текущее количество подтвердивших и список тех, от кого ожидается подтверждение, можно в таблице запуска действий для каждой сущности. + +При этом, если подтверждение ожидается от конкретного пользователя, то данному пользователю будет выведено уведомление в верхней панели (иконка колокольчика). + +#### Учетная запись для запуска действия + +Для доступа к внешним инфраструктурным сервисам по умолчанию используются учетные данные пользователя, который запустил действие. При этом существует возможность в явном виде указать, что действие будет запускаться с использованием учетных данных конкретной учетной записи. + +Для действий, которые предполагается запускать в качестве события автоматизации, указание учетной записи для запуска является обязательным условием. + +#### Учетные данные + +Для встроенных действий заранее известно, какие учетные данные понадобятся для их запуска. Идентификаторы этих учетных данных подгружаются при выбора встроенного backend. Для каждого из идентификаторов необходимо выбрать, какой тип учетных данных будет использоваться. + +Для webhook действий обращение к учетным данным возможно в теле запроса с использованием конструкции `{{ .credentials.<идентификатор типа учетных данных> }}`. + +## Запуски действий + +### Записи запусков действий + +При каждом запуске действия создается запись, в которой указан инициатор запуска, статус выполнения и подробный лог запуска. Записи запущенных действий для каждой сущности можно посмотреть в карточке сущности во вкладке `Запуски действий`. Если для запуска действия необходимо подтверждение, то подтвердить запуск также можно во вкладке `Запуски действий`. + +Каждую запись о запуске действия можно удалить, либо перезапустить действие. При этом при перезапуске будет создана новая запись. + +### Статусы действий + +Для каждого запуска действия создается запись, которая может иметь один из следующих статусов: + +* **Created** - запись создана, но действие еще не было запущено. +* **Unapproved** - действие ожидает подтверждения. +* **Running** - действие выполняется. +* **Failed** - действие завершилось неуспешно. +* **Update failed** - действие выполнено, но обновить параметры сущности не удалось. +* **Success** - действие завершилось успешно. +* **Retrying** - действие завершилось неуспешно, выполняется попытка перезапуска. diff --git a/content/documentation/admin/actions/types.ru.md b/content/documentation/admin/actions/types.ru.md new file mode 100644 index 0000000..a4c70c0 --- /dev/null +++ b/content/documentation/admin/actions/types.ru.md @@ -0,0 +1,1346 @@ +--- +title: Типы действий +--- + +## CreateDefectdojoEngagement + +CreateDefectdojoEngagement - создает новый engagements в системе DefectDojo. Действие использует DefectDojo API v2. Поддерживаемые параметры соответствуют спецификации API. + +### Пример запроса + +```yaml +name: example engagement +product: '1' +target_start: '2024-06-01' +target_end: '2024-06-30' +lead: '1' +``` + +### Спецификация запроса + +Список полей соответствует официальному API DefectDojo, `/api/v2/engagements`: [документация](https://demo.defectdojo.org/api/v2/oa3/swagger-ui/) + +### Учетные данные + +* **token** - API v2 Key пользователя, от имени которого будет запускаться выполнение действия + +## CreateDefectdojoProduct + +CreateDefectdojoProduct — создает новый продукт в системе DefectDojo. Действие использует DefectDojo API v2. Поддерживаемые параметры соответствуют спецификации API. + +### Пример запроса + +```yaml +name: example +description: example description +prod_type: 1 +``` + +### Спецификация запроса + +Список полей соответствует официальному API DefectDojo, `/api/v2/products`: [документация](https://demo.defectdojo.org/api/v2/oa3/swagger-ui/) + +### Учетные данные + +* **token** - API v2 Key пользователя, от имени которого будет запускаться выполнение действия + +## CreateGitlabBranches + +CreateGitlabBranches - создает новые ветки в целевом репозитории. + +### Пример запроса + +```yaml +project_id: '0' +branches: + - branch: new-branch + ref: main +``` + +### Спецификация запроса + +| Название | Обязательность | Описание | +|-----------------|-----------------|------------------------------------------------------------------------------| +| project_id | **обязательно** | Идентификатор проекта, в котором необходимо создать ветки | +| branches | **обязательно** | Список создаваемых веток | +| branches.branch | **обязательно** | Название новой ветки | +| branches.ref | **обязательно** | Название существующей ветки или SHA-хеш коммита | + +### Учетные данные + +* **token** - токен пользователя, от имени которого будет запускаться выполнение действия + +### Примечание + +Для выполнения действия необходимо наличие корректных реквизитов с GitLab token. Этот токен передается через механизм учетных данных и используется для аутентификации при вызове GitLab API (HTTP-заголовок "Private-Token"). + +Действие осуществляет POST-запрос по URL: `/api/v4/projects/:id/repository/branches`. В случае успешного создания проекта GitLab возвращает информацию о созданных ветках. + +## CreateGitlabGroupVariables + +CreateGitlabGroupVariables - создает переменные на уровне группы в GitLab. + +### Пример запроса + +```yaml +group_id: '0' +variables: + - key: EXAMPLE_VARIABLE + value: value +``` + +### Спецификация запроса + +| Название | Обязательность | Описание | +|-----------------|-----------------|------------------------------------------------------------------------------| +| group_id | **обязательно** | Идентификатор группы, в котором необходимо создать переменные | +| variables | **обязательно** | Список создаваемых переменных | + +Список полей для variables соответствует официальному GitLab Group-level Variables API, `/groups/:id/variables`: [документация](https://docs.gitlab.com/api/group_level_variables/#create-variable) + +### Учетные данные + +* **token** - токен пользователя, от имени которого будет запускаться выполнение действия + +### Примечание + +Для выполнения действия необходимо наличие корректных реквизитов с GitLab token. Этот токен передается через механизм учетных данных и используется для аутентификации при вызове GitLab API (HTTP-заголовок "Private-Token"). + +Действие осуществляет POST-запрос по URL: `/api/v4/groups/:id/variables`. + +## CreateGitlabMergeRequest + +CreateGitlabMergeRequest - создает новый merge request в целевой репозиторий. В данный merge request добавляются файлы, хранящиеся в репозитории источнике. Файлы могут содержать переменные, значение которых будет подставлено в момент создания MR. + +### Пример запроса + +```yaml +source_project_id: '0' +source_project_branch: example +source_project_tag: v1.0.0 +target_project_id: '0' +merge_request_spec: + source_branch: example + target_branch: '1' + title: example +additionalIgnoreFiles: + - .ignore + - .example +values: + key1: value1 + nested: + enabled: true + subkey: 123 +``` + +### Спецификация запроса + +| Название | Опциональность | Описание | Значение по умолчанию | +|-------------------------|------------------|-------------------------------------------------------------------------------------------------------------------------------|-----------------------| +| source_project_id | **обязательно** | Идентификатор проекта, который служит источником для Merge Request | - | +| target_project_id | **обязательно** | Идентификатор целевого проекта, в котором будет сформирован Merge Request | - | +| merge_request_spec | **обязательно** | Спецификация, соответствующая [GitLab Merge Requests API](https://docs.gitlab.com/ee/api/merge_requests.html#create-mr) | - | +| source_project_tag | опционально | Тег в проекте-источнике, из которого будет сформирован Merge Request. Если не указан, используется ветка в проекте-источнике | - | +| source_project_branch | опционально | Ветка в проекте-источнике, из которой будет сформирован Merge Request | main | +| additionalIgnoreFiles | опционально | Список файлов, содержащих пути для исключения из MR. Заполняется по аналогии с [.templateignore](#templateignore) | - | +| values | опционально | Переменные, используемые при шаблонизации, в формате `ключ: значение` | - | + +### Учетные данные + +* **password** - пароль (токен) пользователя, от имени которого будет запускаться выполнение действия +* **username** - username пользователя, от имени которого будет запускаться выполнение действия + +### Алгоритм работы + +Платформа: + +1. Клонирует шаблонный репозиторий, который является шаблоном для генерации MR, согласно его ID (**source_project_id**). [Подробнее о шаблонизации](#детали-работы) +2. Считывает файл `values.yaml` хранящийся в корне репозитория и определяет переменные по умолчанию для шаблонизации +3. Считывает переменные, передаваемые при запуске действия, и делает их merge с переменными из `values.yaml`. Приоритет при merge отдается переменным, передаваемым при запуске действия +4. Считывает файл `.templateignore` и определяет директории и файлы, исключаемые из шаблонизации +5. Рендерит из шаблонов файлы, учитывая `values.yaml` и переданные в действие переменные +6. Изменяет remote репозитория на целевой, согласно его ID (**target_project_id**), и делает git push в целевую ветку (**source_project_branch**), либо в ветку **main** +7. Создает MR, согласно заданным настройкам, путем отправки POST-запроса в GitLab API + +### Примечание + +Для выполнения действия необходимо наличие корректных реквизитов с GitLab token. Этот токен передается через механизм учетных данных и используется для аутентификации при вызове GitLab API (HTTP-заголовок "Private-Token"). + +Действие осуществляет POST-запрос по URL: `/api/v4/projects/:id/merge_requests`. + +## CreateGitlabProject + +CreateGitlabProject - создает новый проект в GitLab. Действие осуществляет вызов GitLab API для создания проекта с указанными параметрами, такими как имя, путь проекта, описание и другие настройки. Для аутентификации используется GitLab token, который должен быть предоставлен в учетных данных. + +### Пример запроса + +```yaml +name: example +path: example +description: example +default_branch: main +initialize_with_readme: false +namespace_id: '0' +``` + +### Спецификация запроса + +| Название | Обязательность | Описание | Значение по умолчанию | +|------------------------|------------------|--------------------------------------------------------------------------------------------|-----------------------| +| name | **обязательно** | Название проекта, который будет создан в GitLab | - | +| path | **обязательно** | URL-совместимый путь проекта. Обычно совпадает с названием, но может отличаться | - | +| default_branch | **обязательно** | Имя ветки, которая будет использоваться по умолчанию, например, "main" | - | +| namespace_id | **обязательно** | Идентификатор пространства имен (namespace) в GitLab, в котором будет создан проект | - | +| initialize_with_readme | опционально | Флаг, определяющий, нужно ли инициализировать проект с файлом README | false | +| description | опционально | Описание проекта, которое будет видно пользователям | - | + +### Учетные данные + +* **token** - токен пользователя, от имени которого будет запускаться выполнение действия + +### Примечание + +Для выполнения действия необходимо наличие корректных реквизитов с GitLab token. Этот токен передается через механизм учетных данных и используется для аутентификации при вызове GitLab API (HTTP-заголовок "Private-Token"). + +Действие осуществляет POST-запрос по URL: `/api/v4/projects`, передавая параметры запроса в формате JSON. В случае успешного создания проекта GitLab возвращает данные о вновь созданном проекте. + +## CreateGitlabProjectVariables + +CreateGitlabProjectVariables - создает переменные на уровне проекта в GitLab. + +### Пример запроса + +```yaml +project_id: '0' +variables: + - key: EXAMPLE_VARIABLE + value: value +``` + +### Спецификация запроса + +| Название | Обязательность | Описание | +|-----------------|-----------------|------------------------------------------------------------------------------| +| project_id | **обязательно** | Идентификатор проекта, в котором необходимо создать переменные | +| variables | **обязательно** | Список создаваемых переменных | + +Список полей для variables соответствует официальному GitLab Project-level CI/CD variables API, `/projects/:id/variables`: [документация](https://docs.gitlab.com/api/project_level_variables/#create-a-variable) + +### Учетные данные + +* **token** - токен пользователя, от имени которого будет запускаться выполнение действия + +### Примечание + +Для выполнения действия необходимо наличие корректных реквизитов с GitLab token. Этот токен передается через механизм учетных данных и используется для аутентификации при вызове GitLab API (HTTP-заголовок "Private-Token"). + +Действие осуществляет POST-запрос по URL: `/api/v4/projects/:id/variables`. + +## CreateGitlabProjectWebhook + +CreateGitlabProjectWebhook - создает webhook в проекте GitLab. + +### Пример запроса + +```yaml +project_id: '0' +url: https://example.com +push_events: true +issues_events: true +merge_requests_events: true +pipeline_events: true +``` + +### Спецификация запроса + +| Название | Обязательность | Описание | +|----------------------|-----------------|-------------------------------------------------------------------------| +| project_id | **обязательно** | Идентификатор проекта, в котором необходимо создать webhook | +| url | **обязательно** | URL-адрес вебхука | +| push_events | **обязательно** | Запускать вебхук при push в репозиторий | +| issues_events | **обязательно** | Запускать вебхук при создании issue | +| merge_request_events | **обязательно** | Запускать вебхук при создании merge request | +| pipeline_events | **обязательно** | Запускать вебхук при запуске pipeline | + +### Учетные данные + +* **token** - токен пользователя, от имени которого будет запускаться выполнение действия + +### Примечание + +Для выполнения действия необходимо наличие корректных реквизитов с GitLab token. Этот токен передается через механизм учетных данных и используется для аутентификации при вызове GitLab API (HTTP-заголовок "Private-Token"). + +Действие осуществляет POST-запрос по URL: `/api/v4/projects/:id/hooks`. + +## CreateGitlabTag + +CreateGitlabTag - создает новый тег в проекте GitLab. + +### Пример запроса + +```yaml +project_id: '0' +tag_name: v1.0.0 +ref: main +message: Tag description +``` + +### Спецификация запроса + +| Название | Обязательность | Описание | +|----------------------|-----------------|-------------------------------------------------------------------------------| +| project_id | **обязательно** | Идентификатор проекта, в котором необходимо создать тег | +| tag_name | **обязательно** | Имя тега | +| ref | **обязательно** | Название ветки, тег или SHA-хеш коммита, на который будет ссылаться новый тег | +| message | опционально | Описание тега | + +### Учетные данные + +* **token** - токен пользователя, от имени которого будет запускаться выполнение действия + +### Примечание + +Для выполнения действия необходимо наличие корректных реквизитов с GitLab token. Этот токен передается через механизм учетных данных и используется для аутентификации при вызове GitLab API (HTTP-заголовок "Private-Token"). + +Действие осуществляет POST-запрос по URL: `/api/v4/projects/:id/repository/tags`. + +## CreateKafkaACLs + +CreateKafkaACLs - создаёт новый набор ACL в Kafka. + +### Пример запроса + +```yaml +securityProtocol: SASL_PLAINTEXT +saslMechanism: PLAIN +acls: + - topics: + - example_1 + allow: + - User:principal_2 + - Group:principal_3 + deny: + - User:principal_4 + - Group:principal_5 + ops: + - CREATE + - READ + - WRITE + - DELETE + - DESCRIBE + - DESCRIBE_CONFIGS + - ALTER + pattern: LITERAL + - topics: + - example_6 + allow: + - User:principal_7 + allow_hosts: + - 127.0.0.1 + deny: + - User:principal_8 + deny_hosts: + - 127.0.0.1 + ops: + - CREATE + pattern: LITERAL +``` + +### Спецификация запроса + +| Название | Обязательность | Описание | Возможные значения | Значение по умолчанию | +|-------------------------|------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------|------------------------| +| securityProtocol | **обязательно** | Протокол для подключения к Kafka. [Подробнее](https://kafka.apache.org/documentation/#adminclientconfigs_security.protocol) | PLAINTEXT, SASL_PLAINTEXT, SASL_SSL | - | +| saslMechanism | опционально | Механизм аутентификации, который будет использовать SASL. Обязателен при использовании протокола SASL_PLAINTEXT или SASL_SSL. [Подробнее](https://kafka.apache.org/documentation/#security_sasl_mechanism) | PLAIN, SCRAM-SHA-256, SCRAM-SHA-512 | - | +| acls | **обязательно** | Набор ACL, которые необходимо создать | - | - | +| acls.ops | **обязательно** | Список операций, для которых будет создано правило. | См. список возможных операций | - | +| acls.pattern | **обязательно** | Тип шаблона | См. список возможных pattern | - | +| acls.topics | опционально | Список из названий топиков, для которых применять правило | - | - | +| acls.groups | опционально | Список из названий групп, для которых применять правило | - | - | +| acls.transactional_ids | опционально | Список из ID транзакций, для которых применять правило | - | - | +| acls.tokens | опционально | Список токенов, для которых применять правило | - | - | +| acls.allow | опционально | Список принципалов (user, group), для которых разрешить правило | - | - | +| acls.allow_hosts | опционально | Список хостов, для которых разрешить операцию | - | - | +| acls.deny | опционально | Список принципалов (user, group), для которых запретить правило | - | - | +| acls.deny_hosts | опционально | Список хостов, для которых запретить операцию | - | - | + +### Учетные данные + +* **user** - username пользователя, от имени которого будет запускаться выполнение действия +* **password** - пароль пользователя, от имени которого будет запускаться выполнение действия + +### Список возможных pattern + +* ANY +* MATCH +* LITERAL +* PREFIXED + +### Список возможных операций + +[Документация Kafka](https://kafka.apache.org/39/documentation/#operations_resources_and_protocols) + +**Topic:** + +* ALL +* ALTER +* ALTER_CONFIGS +* CREATE +* DELETE +* DESCRIBE +* DESCRIBE_CONFIGS +* READ +* WRITE + +**Group:** + +* ALL +* DELETE +* DESCRIBE +* READ + +**TransactionalID:** + +* ALL +* DESCRIBE +* WRITE + +**Tokens:** + +* DESCRIBE + +## CreateKafkaTopics + +CreateKafkaTopics - создаёт новые топики в Kafka. + +### Пример запроса + +```yaml +securityProtocol: SASL_PLAINTEXT +saslMechanism: PLAIN +partitions: 1 +replication_factor: 1 +configs: {} +topics: + - example_1 + - example_2 +``` + +### Спецификация запроса + +| Название | Обязательность | Описание | Возможные значения | +|-------------------------|------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------| +| securityProtocol | **обязательно** | Протокол для подключения к Kafka. [Подробнее](https://kafka.apache.org/documentation/#adminclientconfigs_security.protocol) | PLAINTEXT, SASL_PLAINTEXT, SASL_SSL | +| saslMechanism | опционально | Механизм аутентификации, который будет использовать SASL. Обязателен при использовании протокола SASL_PLAINTEXT или SASL_SSL. [Подробнее](https://kafka.apache.org/documentation/#security_sasl_mechanism) | PLAIN, SCRAM-SHA-256, SCRAM-SHA-512 | +| partitions | **обязательно** | Количество разделов (партиций), на которые будет разбит топик | - | +| replication_factor | **обязательно** | Количество копий (реплик) каждой партиции топика, которые необходимо разместить на разных брокерах | - | +| configs | **обязательно** | Конфигурация в формате ключ значение для создаваемых топиков | [Документация](https://kafka.apache.org/documentation/#topicconfigs) | +| topics | **обязательно** | Список названий топиков, которые необходимо создать | - | + +### Учетные данные + +* **user** - username пользователя, от имени которого будет запускаться выполнение действия +* **password** - пароль пользователя, от имени которого будет запускаться выполнение действия + +## CreateKafkaUsers + +CreateKafkaUsers - создаёт новых пользователей SASL/SCRAM в Kafka. + +### Пример запроса + +```yaml +securityProtocol: SASL_PLAINTEXT +saslMechanism: PLAIN +users: + - user: example_user_1 + password: example_password_user_1 + mechanism: SCRAM-SHA-256 + iterations: 4096 + - user: example_user_2 + password: example_password_user_2 + mechanism: SCRAM-SHA-256 + iterations: 4096 +``` + +### Спецификация запроса + +| Название | Обязательность | Описание | Возможные значения | +|-------------------|------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------| +| securityProtocol | **обязательно** | Протокол для подключения к Kafka. [Подробнее](https://kafka.apache.org/documentation/#adminclientconfigs_security.protocol) | PLAINTEXT, SASL_PLAINTEXT, SASL_SSL | +| saslMechanism | опционально | Механизм аутентификации, который будет использовать SASL. Обязателен при использовании протокола SASL_PLAINTEXT или SASL_SSL. [Подробнее](https://kafka.apache.org/documentation/#security_sasl_mechanism) | PLAIN, SCRAM-SHA-256, SCRAM-SHA-512 | +| users | **обязательно** | Набор пользователей, которых необходимо создать | - | +| users.user | **обязательно** | Имя создаваемого пользователя | - | +| users.password | **обязательно** | Пароль создаваемого пользователя | - | +| users.mechanism | **обязательно** | Механизм аутентификации создаваемого пользователя | SCRAM-SHA-256, SCRAM-SHA-512 | +| users.iterations | **обязательно** | Количество итераций, которые будут применяться для хэширования пароля | От 4096 до 16384 | + +### Учетные данные + +* **user** - username пользователя, от имени которого будет запускаться выполнение действия +* **password** - пароль пользователя, от имени которого будет запускаться выполнение действия + +## CreateCodeScoringProject + +CreateCodeScoringProject — создает новый проект в системе CodeScoring. Действие использует CodeScoring API для регистрации проекта с указанными параметрами: название проекта, URL репозитория, ID VCS системы и опция автоматического запуска SCA-анализа после клонирования репозитория. + +### Пример запроса + +```yaml +name: example-project +repository: https://gitlab.example.com/group/project.git +vcs_id: 2 +run_sca_after_clone: true +``` + +### Спецификация запроса + +| Название | Обязательность | Описание | +|--------------------|-----------------|--------------------------------------------------------------------------| +| name | **обязательно** | Название проекта в CodeScoring | +| repository | **обязательно** | URL репозитория (например, ) | +| vcs_id | **обязательно** | ID VCS системы в CodeScoring (должен быть больше 0) | +| run_sca_after_clone| опционально | Запускать ли SCA-анализ автоматически после клонирования репозитория | + +### Ответ + +В ответе возвращается объект созданного проекта со следующей информацией: идентификатор проекта (pk), название, тип проекта, описание, информация о репозитории, статус проекта, права доступа, лицензия, количество зависимостей и уязвимостей, языки проекта, статус расписания сканирования и даты первого и последнего SCA-сканирования. + +## DeleteCodeScoringProject + +DeleteCodeScoringProject — удаляет проект в системе CodeScoring по его ID. + +### Пример запроса + +```yaml +id: 1 +``` + +### Спецификация запроса + +| Название | Обязательность | Описание | +|----------|-----------------|-----------------------------| +| id | **обязательно** | ID проекта в CodeScoring | + +## CreateKeycloakClient + +CreateKeycloakClient - создает нового клиента в Keycloak. + +### Пример запроса + +```yaml +realm: master +config: + clientId: example + name: example + enabled: true + clientAuthenticatorType: client-secret + secret: secret + defaultClientScopes: + - roles + - profile + - email + optionalClientScopes: + - address + - phone + - offline_access +``` + +### Спецификация запроса + +| Название | Обязательность | Описание | Возможные значения | +|----------|-----------------|----------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------| +| realm | **обязательно** | Realm в Keycloak, где требуется создать клиента | - | +| config | **обязательно** | Параметры создаваемого клиента в соответствии со спецификацией ClientRepresentation Keycloak | [Документация](https://www.keycloak.org/docs-api/latest/rest-api/index.html#ClientRepresentation) | + +### Учетные данные + +* **username** - username пользователя, от имени которого будет запускаться выполнение действия +* **password** - пароль пользователя, от имени которого будет запускаться выполнение действия + +## CreateKubernetesResource + +CreateKubernetesResource - создает новый ресурс или ресурсы в кластере Kubernetes или обновляет существующие. + +### Пример запроса + +```yaml +manifests: + - apiVersion: v1 + kind: Namespace + metadata: + name: example1 + - apiVersion: v1 + kind: Namespace + metadata: + name: example2 +``` + +### Спецификация запроса + +| Название | Обязательность | Описание | +|----------------------------|------------------|----------------------------------------------------------------------------------------------------| +| manifests | **обязательно** | Манифесты Kubernetes, которые будут применены | + +### Учетные данные + +* **token** - токен сервисного аккаунта в Kubernetes + +## CreateRepositoryFromTemplate + +CreateRepositoryFromTemplate - создает новый репозиторий из шаблона в Gitlab. Механизм рендеринга основан на [Go template](https://developer.hashicorp.com/nomad/tutorials/templates/go-template-syntax) и поддерживает все встроенные методы, а также расширения, добавленные в платформу. + +### Пример запроса + +```yaml +sourceBranch: main +sourceTag: v1.0.0 +templateRepositoryUrl: https://gitlab.example.com/example-1.git +targetRepositoryUrl: https://gitlab.example.com/example-2.git +targetBranch: master +additionalIgnoreFiles: + - .ignore + - .example +values: + key1: value1 + nested: + enabled: true + subkey: 123 +``` + +### Спецификация запроса + +| Название | Опциональность | Описание | Значение по умолчанию | +|--------------------------|--------------------|-----------------------------------------------------------------------------------------------------------------------------------------|-----------------------| +| templateRepositoryUrl | **обязательно** | URL шаблонного репозитория | - | +| targetRepositoryUrl | **обязательно** | URL репозитория, который будет создан в результате выполнения действия | - | +| values | **обязательно** | Переменные, используемые при шаблонизации, в формате `ключ: значение` | - | +| additionalIgnoreFiles | опционально | Список файлов, содержащих пути для для исключения из целевого репозитория. Заполняется по аналогии с [.templateignore](#templateignore) | - | +| sourceTag | опционально | Тег шаблонного репозитория, который будет использоваться при шаблонизации. Если не указан, используется ветка шаблонного репозитория | - | +| sourceBranch | опционально | Ветка шаблонного репозитория, которая будет использоваться при шаблонизации | main | +| targetBranch | опционально | Ветка целевого репозитория, которая будет создана в результате выполнения действия | main | + +### Учетные данные + +* **password** - пароль (токен) пользователя, от имени которого будет запускаться выполнение действия +* **username** - username пользователя, от имени которого будет запускаться выполнение действия + +### Алгоритм работы + +Платформа: + +1. Клонирует шаблонный репозиторий по указанному URL (**templateRepositoryUrl**), используя в качестве ref либо **sourceTag**, либо **sourceBranch**, либо ветку **main**. +2. Считывает файл `values.yaml` хранящийся в корне репозитория и определяет переменные по умолчанию для шаблонизации +3. Считывает переменные, передаваемые при запуске действия, и делает их merge с переменными из `values.yaml`. Приоритет при merge отдается переменным, передаваемым при запуске действия +4. Считывает файл `.templateignore` и определяет директории и файлы, исключаемые из шаблонизации +5. Рендерит из шаблонов файлы, учитывая `values.yaml` и переданные в действие переменные +6. Изменяет remote репозитория на целевой (**targetRepositoryUrl**) и делает git push в целевую ветку (**targetBranch**), либо в ветку **main** + +### Детали работы + +Действие поддерживает шаблонизацию названий директорий и файлов, для этого необходимо в их название добавить выражение в формате [Go template](https://developer.hashicorp.com/nomad/tutorials/templates/go-template-syntax), например директория `src/{{ .module }}/utils` при наличии value **module** со значением **example** будет отрендерена в директорию `src/example/utils` в целевом репозитории. + +Если после рендеринга из шаблона содержимое файла будет отсутствовать, то он не будет создан. Например файл с содержимым: + +```go +{{- if .createContent }} +- Это контент, который будет отображаться, если переменная createContent == true +{{- end }} +``` + +не будет создан, если переменная **createContent** имеет значение **false**. Аналогичным образом, не будут созданы файлы, изначально являющиеся пустыми. + +При отсутствии переменных для шаблонизации одновременно в файле `values.yaml` и в переменных, передаваемых при запуске действия, рендеринг завершится с ошибкой и целевой репозиторий создан не будет. + +### Переменные шаблонного репозитория + +Для добавления переменных по умолчанию, используемых при шаблонизации, необходимо создать в корне репозитория файд values.yaml с соответствующим содержимым. + +Пример файла `values.yaml`: + +```yaml +module: example +createContent: false +``` + +Файл `values.yaml` является опциональным. + + + +### Исключение файлов + +Некоторые файлы могут содержать переменные в формате [Go template](https://developer.hashicorp.com/nomad/tutorials/templates/go-template-syntax), которые необходимо сохранять при рендеринге репозитория из шаблона, например, Helm чарты в директории `helm`. Директория `.git` игнорируется всегда. + +Для исключения подобных файлов из механизма рендеринга следует добавить в корень репозитория файл `.templateignore` с соответствующим содержимым. + +Пример файла `.templateignore` для игнорирования содержимого директорий `helm`, `docs`: + +```sh +helm/** +docs/** +``` + +Файл `.templateignore` является опциональным. + +### Пример структуры директорий шаблонного репозитория + +```sh +├── example-folder-01 +│ ├── example-file-01 +│ └── {{ .example }}-file-02 +├── {{ .example }}-folder-02 +│ └── ... +├── values.yaml +└── .templateignore +``` + +Если переменная **example** при рендере репозитория примет значение **new**, то итоговая структура после рендера будет выглядеть следующим образом: + +```sh +├── example-folder-01 +│ ├── example-file-01 +│ └── new-file-02 +├── new-folder-02 +│ └── ... +├── values.yaml +└── .templateignore +``` + +### Локальная отладка + +Для локальной отладки шаблонов подготовлена утилита **ddp-render-dir**. + +Утилита: + +1. Создает копию исходной директории. +2. Рендерит файлы в созданной директории аналогично тому, как это делает действие по созданию репозиториев из шаблонов. + +Ключи командной строки для запуска: + +* **--source-dir** - исходная директория, которую необходимо отрендерить +* **--target-dir** - директория, в которую будет помещен результат рендеринга +* **--values** (опционально) - путь к файлу `values.yaml` с переменными, которые будут использоваться при рендеринге +* **--ignore-files** (опционально) - cписок файлов, содержащих пути для для исключения из целевого репозитория + +## CreateSonarqubeProject + +CreateSonarqubeProject - создает новый проект в SonarQube. Действие использует SonarQube Web API для создания проекта с указанными параметрами, такими как ключ (project key), имя проекта, главная ветка, параметры определения нового кода (new code definition) и видимость проекта. Аутентификация осуществляется с использованием SonarQube token, который должен быть передан в учетных данных. + +### Пример запроса + +```yaml +project: example-project +name: example-project +mainBranch: develop +newCodeDefinitionType: NUMBER_OF_DAYS +newCodeDefinitionValue: '30' +visibility: public +``` + +### Спецификация запроса + +| Название | Обязательность | Описание | Возможные значения | Значение по умолчанию | +|-------------------------|------------------|-------------------------------------------------------------------------------------------------|----------------------------------------------------|------------------------| +| project | **обязательно** | Уникальный идентификатор проекта (Project Key) в SonarQube | - | - | +| name | **обязательно** | Название проекта, отображаемое в интерфейсе SonarQube | - | - | +| mainBranch | опционально | Название главной ветки проекта | - | master | +| newCodeDefinitionType | опционально | Метод определения «нового кода» | PREVIOUS_VERSION, NUMBER_OF_DAYS, REFERENCE_BRANCH | - | +| newCodeDefinitionValue | опционально | Значение для определения "нового кода" (например, количество дней, если тип - NUMBER_OF_DAYS) | - | - | +| visibility | опционально | Видимость проекта | private, public | private | + +### Учетные данные + +* **token** - токен Sonarqube с типом User Token, сгенерированный пользователем, от имени которого будет запускаться выполнение действия + +## CreateVaultSecret + +CreateVaultSecret - создает секрет с одним или несколькими значениями в HashiCorp Vault. + +### Пример запроса + +```yaml +path: example/data/path +secrets: + - key: key1 + value: value1 + - key: key2 + value: value2 +``` + +### Спецификация запроса + +| Название | Обязательность | Описание | По умолчанию | +|---------------------------|------------------|----------------------------------------------------------------------------------------------------|--------------| +| path | **обязательно** | Путь, по которому будет сохранён секрет в Vault | - | +| allow_update | опционально | Разрешить создание новой версии секрета, если секрет уже существует в Vault | false | +| secrets | **обязательно** | Набор секретов, которые необходимо создать в Vault | - | +| secrets.key | **обязательно** | Имя (идентификатор) секрета | - | +| secrets.value | **обязательно** | Значение секрета | - | + +### Учетные данные + +* **token** - Vault токен, который имеет необходимые права для создания секретов + +## DeleteVaultSecret + +DeleteVaultSecret - удаляет секрет из HashiCorp Vault. + +### Пример запроса + +```yaml +path: example/data/path +``` + +### Спецификация запроса + +| Название | Обязательность | Описание | +|---------------------------|------------------|----------------------------------------------------------------------------------------------------| +| path | **обязательно** | Путь, по которому находится секрет в Vault, который необходимо удалить | + +### Учетные данные + +* **token** - Vault токен, который имеет необходимые права для удаления секретов + +## DeleteDefectdojoProduct + +DeleteDefectdojoProduct - удаляет продукт из DefectDojo. Действие использует DefectDojo API v2. + +### Пример запроса + +```yaml +id: 1 +``` + +### Спецификация запроса + +| Название | Обязательность | Описание | Значение по умолчанию | +|-------------|------------------|----------------------------------------------------|------------------------| +| id | **обязательно** | Идентификатор продукта, который необходимо удалить | - | + +### Учетные данные + +* **token** - API v2 Key пользователя, от имени которого будет запускаться выполнение действия + +## DeleteGitlabProject + +DeleteGitlabProject - удаляет существующий проект в GitLab. Действие осуществляет вызов GitLab API для удаление проекта. Для аутентификации используется GitLab token, который должен быть предоставлен в креденшилах. + +### Пример запроса + +```yaml +project_id: 0 +``` + +### Спецификация запроса + +| Название | Обязательность | Описание | +|---------------------------|------------------|----------------------------------------------------------------------------------------------------| +| project_id | **обязательно** | Идентификатор проекта, который необходимо удалить | + +### Учетные данные + +* **token** - токен пользователя, от имени которого будет запускаться выполнение действия + +### Примечание + +Для выполнения действия необходимо наличие корректных реквизитов с GitLab token. Этот токен передается через механизм учетных данных и используется для аутентификации при вызове GitLab API (HTTP-заголовок "Private-Token"). + +Действие осуществляет DELETE-запрос по URL: `/api/v4/projects/:id`. + +## DeleteKafkaACLs + +DeleteKafkaACLs - удаляет набор ACL в Kafka. + +### Пример запроса + +```yaml +securityProtocol: SASL_PLAINTEXT +saslMechanism: PLAIN +acls: + - topics: + - example_1 + allow: + - User:principal_2 + - Group:principal_3 + allow_hosts: + - 127.0.0.1 + deny: + - User:principal_4 + - Group:principal_5 + deny_host: + - 127.0.0.1 + ops: + - CREATE + - READ + - WRITE + - DELETE + - DESCRIBE + - DESCRIBE_CONFIGS + - ALTER + pattern: LITERAL + - any_topic: true + any_group: true + any_transactional_id: true + any_allow: true + any_allow_hosts: true + any_deny: true + any_deny_hosts: true + ops: + - ANY + pattern: ANY + - any_resource: true + any_allow: true + any_allow_hosts: true + any_deny: true + any_deny_hosts: true + ops: + - ANY + pattern: ANY +``` + +### Спецификация запроса + +| Название | Обязательность | Описание | Возможные значения | Значение по умолчанию | +|---------------------------|------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------|------------------------| +| securityProtocol | **обязательно** | Протокол для подключения к Kafka. [Подробнее](https://kafka.apache.org/documentation/#adminclientconfigs_security.protocol) | PLAINTEXT, SASL_PLAINTEXT, SASL_SSL | - | +| saslMechanism | опционально | Механизм аутентификации, который будет использовать SASL. Обязателен при использовании протокола SASL_PLAINTEXT или SASL_SSL. [Подробнее](https://kafka.apache.org/documentation/#security_sasl_mechanism) | PLAIN, SCRAM-SHA-256, SCRAM-SHA-512 | - | +| acls | **обязательно** | Набор ACL, которые необходимо создать | - | - | +| acls.ops | **обязательно** | Список операций, для которых будет создано правило. | См. список возможных операций | - | +| acls.pattern | **обязательно** | Тип шаблона | См. список возможных pattern | - | +| acls.any_resource | опционально | Все ресурсы | - | false | +| acls.topics | опционально | Список из названий топиков, для которых применять правило | - | - | +| acls.any_topic | опционально | Все топики | - | false | +| acls.groups | опционально | Список из названий групп, для которых применять правило | - | - | +| acls.any_group | опционально | Все топики | - | false | +| acls.transactional_ids | опционально | Список из ID транзакций, для которых применять правило | - | - | +| acls.any_transactional_id | опционально | Любая транзакция | - | false | +| acls.tokens | опционально | Список токенов, для которых применять правило | - | - | +| acls.any_token | опционально | Все токены | - | false | +| acls.allow | опционально | Список принципалов (user, group), для которых разрешить правило | - | - | +| acls.any_allow | опционально | Любой принципал (user, group) | - | false | +| acls.allow_hosts | опционально | Список хостов, для которых разрешить операцию | - | - | +| acls.any_allow_hosts | опционально | Любой хост, с которого разрешено проводить операцию | - | false | +| acls.deny | опционально | Список принципалов (user, group), для которых запретить правило | - | - | +| acls.any_deny | опционально | Любой принципал (user, group) | - | false | +| acls.deny_hosts | опционально | Список хостов, для которых запретить операцию | - | - | +| acls.any_deny_hosts | опционально | Любой хост, с которого запрещено проводить операцию | - | false | + +### Учетные данные + +* **user** - username пользователя, от имени которого будет запускаться выполнение действия +* **password** - пароль пользователя, от имени которого будет запускаться выполнение действия + +### Список возможных pattern + +* ANY +* MATCH +* LITERAL +* PREFIXED + +### Список возможных операций + +[Документация Kafka](https://kafka.apache.org/39/documentation/#operations_resources_and_protocols) + +**Topic:** + +* ALL +* ALTER +* ALTER_CONFIGS +* CREATE +* DELETE +* DESCRIBE +* DESCRIBE_CONFIGS +* READ +* WRITE + +**Group:** + +* ALL +* DELETE +* DESCRIBE +* READ + +**TransactionalID:** + +* ALL +* DESCRIBE +* WRITE + +**Token:** + +* DESCRIBE + +## DeleteKafkaTopics + +DeleteKafkaTopics - удаляет существующие топики в Kafka. + +### Пример запроса + +```yaml +securityProtocol: SASL_PLAINTEXT +saslMechanism: PLAIN +topics: + - example_1 + - example_2 +``` + +### Спецификация запроса + +| Название | Обязательность | Описание | Возможные значения | +|---------------------------|------------------|-----------------------------------------------------|-----------------------------------------| +| auth_type | **обязательно** | Тип авторизации в Kafka | PLAINTEXT, SCRAM-SHA-256, SCRAM-SHA-512 | +| topics | **обязательно** | Список названий топиков, которые необходимо удалить | - | + +### Учетные данные + +* **user** - username пользователя, от имени которого будет запускаться выполнение действия +* **password** - пароль пользователя, от имени которого будет запускаться выполнение действия + +## DeleteKafkaUsers + +DeleteKafkaUsers - удаляет существующих пользователей SASL/SCRAM в Kafka. + +### Пример запроса + +```yaml +securityProtocol: SASL_PLAINTEXT +saslMechanism: PLAIN +users: + - user: example_user_1 + mechanism: SCRAM-SHA-256 + - user: example_user_2 + mechanism: SCRAM-SHA-256 +``` + +### Спецификация запроса + +| Название | Обязательность | Описание | Возможные значения | +|-------------------|------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------| +| securityProtocol | **обязательно** | Протокол для подключения к Kafka. [Подробнее](https://kafka.apache.org/documentation/#adminclientconfigs_security.protocol) | PLAINTEXT, SASL_PLAINTEXT, SASL_SSL | +| saslMechanism | опционально | Механизм аутентификации, который будет использовать SASL. Обязателен при использовании протокола SASL_PLAINTEXT или SASL_SSL. [Подробнее](https://kafka.apache.org/documentation/#security_sasl_mechanism) | PLAIN, SCRAM-SHA-256, SCRAM-SHA-512 | +| users | **обязательно** | Набор пользователей, которых необходимо удалить | - | +| users.user | **обязательно** | Имя удаляемого пользователя | - | +| users.mechanism | **обязательно** | Механизм аутентификации удаляемого пользователя | SCRAM-SHA-256, SCRAM-SHA-512 | + +### Учетные данные + +* **user** - username пользователя, от имени которого будет запускаться выполнение действия +* **password** - пароль пользователя, от имени которого будет запускаться выполнение действия + +## DeleteKubernetesResource + +DeleteKubernetesResource - удаляет существующий ресурс в кластере Kubernetes. + +### Пример запроса + +```yaml +group: apps +version: v1 +resource_type: deployments +resource_name: nginx-deployment +namespace: example +``` + +### Спецификация запроса + +| Название | Обязательность | Описание | Возможные значения | +|---------------------------|------------------|------------------------------------------------------------------------------|----------------------------------------------------------------------| +| group | **обязательно** | API-группа ресурса. Указывает, к какой группе API относится удаляемый объект | См. определение требуемых Group и Version | +| version | **обязательно** | Версия API ресурса | См. определение требуемых Group и Version | +| resource_type | **обязательно** | Тип удаляемого ресурса | pods, services, deployments, statefulsets, daemonsets, replicasets, jobs, cronjobs, nodes, namespaces, configmaps, secrets, persistentvolumes, persistentvolumeclaims, limitranges, resourcequotas, horizontalpodautoscalers, ingresses, networkpolicies, serviceaccounts, roles, clusterroles, rolebindings, clusterrolebindings, podsecuritypolicies, storageclasses, volumeattachments, events, endpoints, customresourcedefinitions | +| resource_name | **обязательно** | Имя конкретного ресурса, который необходимо удалить | - | +| namespace | **обязательно** | Namespace, в котором находится ресурс | - | + +### Учетные данные + +* **token** - токен сервисного аккаунта в Kubernetes + +### Определение требуемых Group и Version + +Каждому типу ресурса соответствует своя версия и группа. Полный список API-ресурсов с их группами и версиями: [документация Kubernetes](https://kubernetes.io/docs/reference/kubernetes-api/) + +Если неизвестно, какие требуются Group и Version, можно попробовать подставить актуальные значения. Есть несколько вариантов как их посмотреть: + +#### С помощью утилиты kubectl + +Команда `kubectl explain` показывает `apiVersion` для ресурса. + +Пример: + +```bash +kubectl explain deployment +``` + +Вывод: + +```yaml +GROUP: apps +KIND: Deployment +VERSION: v1 + +DESCRIPTION: + Deployment enables declarative updates for Pods and ReplicaSets. + +FIELDS: +... +``` + +#### С помощью документации + +Как искать в документации: + +1. Найдите нужный ресурс (например, Deployment). +2. В заголовке будет указана API Group и версия. Пример для Deployment + +```yaml +apiVersion: apps/v1 +``` + +* **API Group** - apps +* **Version** - v1 + +## DeleteSonarqubeProject + +DeleteSonarqubeProject - удаляет проект из SonarQube. + +### Пример запроса + +```yaml +project: example-project +``` + +### Спецификация запроса + +| Название | Обязательность | Описание | Значение по умолчанию | +|------------------|------------------|-----------------------------------------------------------------|------------------------| +| project | **обязательно** | Идентификатор (Project Key) проекта, который необходимо удалить | - | + +### Учетные данные + +* **token** - токен Sonarqube с типом User Token, сгенерированный пользователем, от имени которого будет запускаться выполнение действия + +## DeleteSonarqubeProjects + +DeleteSonarqubeProjects - удаляет один или несколько проектов из SonarQube. + +### Пример запроса + +```yaml +analyzedBefore: 2017-10-19T13:00:00+0200 +onProvisionedOnly: 'false' +projects: example_project,another_project +q: example +qualifiers: TRK +``` + +### Спецификация запроса + +| Название | Обязательность | Описание | Возможные значения | Примеры значений | +|--------------------|------------------|---------------------------------------------------------------------------------|-------------------------------|---------------------------------------| +| analyzedBefore | опционально | Удалить все проекты, в которых последний анализ старше определённой даты | - | 2017-10-19, 2017-10-19T13:00:00+0200 | +| onProvisionedOnly | опционально | Фильтровать проекты по значению `onProvisionedOnly` | true, false, yes, no | - | +| projects | опционально | Список ключей проектов, который необходимо удалить | - | my_project, another_project | +| q | опционально | Удалить все проекты, в названии или ключе которых содержится заданная подстрока | - | example | +| qualifiers | опционально | Фильтровать проекты по указанным квалификаторам | TRK, VW, APP | | + +### Учетные данные + +* **token** - токен Sonarqube с типом User Token, сгенерированный пользователем, от имени которого будет запускаться выполнение действия + +## StartGitlabPipeline + +StartGitlabPipeline - запускает выполнение пайплайна в GitLab. + +### Пример запроса + +```yaml +project_id: 0 +ref: main +variables: + - key: example-key + value: example-value +``` + +### Спецификация запроса + +| Название | Обязательность | Описание | +|---------------------------|------------------|------------------------------------------------------------------------------| +| project_id | **обязательно** | Идентификатор проекта, в котором необходимо запустить пайплайн | +| ref | **обязательно** | Название ветки, тег или SHA-хеш коммита, на котором будет запущен пайплайн | +| variables | опционально | Список переменных, которые необходимо передать в запускаемый пайплайн | +| variables.key | **обязательно** | Название переменной | +| variables.value | **обязательно** | Значение переменной | + +### Учетные данные + +* **token** - токен пользователя, от имени которого будет запускаться выполнение действия + +### Примечание + +Для выполнения действия необходимо наличие корректных реквизитов с GitLab token. Этот токен передается через механизм учетных данных и используется для аутентификации при вызове GitLab API (HTTP-заголовок "Private-Token"). + +Действие осуществляет POST-запрос по URL: `/api/v4/projects/:id/pipeline`. + +## CreateVaultKubernetesAuthRole + +CreateVaultKubernetesAuthRole — создаёт или обновляет роль аутентификации Kubernetes в HashiCorp Vault. + +### Пример запроса + +```yaml +mountPath: kubernetes +role: example +bound_service_account_names: + - default +bound_service_account_namespaces: + - default +optional: + token_ttl: 1h + token_max_ttl: 12h + audience: vault + token_policies: + - default +``` + +### Спецификация запроса + +| Название | Обязательность | Описание | +|-------------------------------------|----------------|-----------------------------------------------------------------------------------| +| mountPath | обязательно | Путь монтирования Kubernetes auth backend в Vault (например, kubernetes) | +| role | обязательно | Название роли, которая создаётся в Vault | +| bound_service_account_names | обязательно | Список имён service account'ов, которым разрешён доступ через данную роль | +| bound_service_account_namespaces | обязательно | Список пространств имён (namespaces), в которых разрешён доступ через данную роль | +| optional | необязательно | Дополнительные параметры роли (см. ниже) | + +Поддерживаемые значения в optional: + +| Поле | Тип | Описание | +|-------------------------|---------------|------------------------------------------------------------------------| +| token_ttl | string | Время жизни (TTL) токена, выданного при логине | +| token_max_ttl | string | Максимальное TTL токена | +| token_policies | []string | Дополнительные политики, назначаемые при логине | +| audience | string | JWT audience (aud), который Vault ожидает от токена | +| token_period | string | Если задано, выдаёт периодический токен | +| token_explicit_max_ttl | string | Устанавливает явный верхний предел TTL токена | +| token_num_uses | int | Ограничение на количество использований токена | +| token_type | string | Тип выдаваемого токена (например, service, batch) | +| alias_name_source | string | Источник alias name для identity | +| token_no_default_policy | bool | Не включать default policy в выданный токен | +| token_bound_cidrs | []string | Ограничение CIDR-диапазонов, откуда можно использовать выданный токен | + +Полный список поддерживаемых параметров см. в [официальной документации](https://developer.hashicorp.com/vault/docs/auth/kubernetes#parameters) HashiCorp Vault. + +### Учетные данные + +* **token** — Vault токен, обладающий правами на создание/обновление ролей Kubernetes auth backend. + +## CreateNexusRepository + +**CreateNexusRepository** — создаёт новый репозиторий любого поддерживаемого типа (maven, docker, npm и др.) в Nexus Repository Manager 3 с помощью REST API. +Параметры формата, типа и другие ключевые настройки полностью настраиваются и соответствуют Nexus API. + +### Пример запроса (Maven hosted) + +```yaml +description: | + Maven hosted repo for internal Java build artifacts. +name: my-maven-repo +format: maven +type: hosted +online: true +storage: + blobStoreName: default + strictContentTypeValidation: true + writePolicy: ALLOW +cleanup: + policyNames: + - maven-cleanup +maven: + versionPolicy: RELEASE + layoutPolicy: PERMISSIVE +``` + +### Пример запроса (Docker group) + +```yaml +description: | + Docker group repo aggregating hosted+proxy. +name: my-docker-group +format: docker +type: group +online: true +storage: + blobStoreName: default + strictContentTypeValidation: true +group: + memberNames: + - docker-hosted + - docker-proxy +docker: + v1Enabled: false + forceBasicAuth: true + httpPort: 5001 +``` + +### Спецификация запроса + +| Поле | Обязательность | Описание | Пример | +|-------------|-----------------|------------------------------------------------------------------------------------------------------|--------------------------| +| `description` | опционально | Документация по назначению этого действия/репозитория. Не используется самим Nexus, только для UI | ... | +| `name` | **обязательно** | Имя создаваемого репозитория. Должно быть уникальным в рамках Nexus | my-maven-repo | +| `format` | **обязательно** | Формат (`maven`, `docker`, `npm`, `raw`, ...) | maven | +| `type` | **обязательно** | Тип: `hosted`, `proxy` или `group` | hosted | +| `online` | **обязательно** | Доступен ли репозиторий (`true`/`false`) | true | +| `storage` | **обязательно** | Объект storage: `blobStoreName`, `strictContentTypeValidation`, `writePolicy` | см. пример выше | +| `cleanup` | опционально | Привязанные политики очистки (`policyNames`) | policyNames: [maven-cleanup] | +| `maven` | для maven | Только для maven: `versionPolicy`, `layoutPolicy` | см. пример выше | +| `proxy` | для proxy | Прокси-репозиторий: `remoteUrl`, `contentMaxAge`, `metadataMaxAge` | ... | +| `group` | для group | Список включенных memberNames | memberNames: [...] | +| `docker` | для docker | docker-specific: `httpPort`, `v1Enabled`, `forceBasicAuth` | см. пример выше | +| `component` | очень редко | Только для некоторых нестандартных сценариев | ... | +| `attributes`| опционально | Любые кастомные поля | ... | + +### Требования + +- Используйте **только те блоки** (`maven`, `group`, `proxy`, `docker` и пр.), которые поддерживаются для вашего типа/формата. +- Для maven hosted обязательно `maven: {versionPolicy, layoutPolicy}`. +- Для group — обязательно `group.memberNames`. +- Для proxy — обязательно `proxy.remoteUrl`. +- Для docker — специфичные поля в `docker`. + +### Учетные данные + +* **token** — строка base64(`admin:password`), используется как Basic Auth при запросах к Nexus. + +### Документация API + +- [Nexus 3 REST API: Repository Management](https://help.sonatype.com/en/repositories-api.html) + +## DeleteNexusRepository + +**DeleteNexusRepository** — удаляет существующий репозиторий из Nexus Repository Manager 3. + +### Пример запроса + +```yaml +name: my-repo-to-delete +``` + +### Спецификация запроса + +| Поле | Обязательность | Описание | +|------|-----------------|------------------------------------------| +| `name` | **обязательно** | Имя репозитория, который требуется удалить | + +### Алгоритм + +- Выполняется `DELETE` по адресу `/service/rest/v1/repositories/{name}`, где `{name}` — это значение поля `name`. +- Если репозиторий найден и удалён — возвращается 204. +- Если не найден — ошибка 404. + +### Учетные данные + +* **token** — строка base64(`admin:password`), используется как Basic Auth при запросах к Nexus. + +### Документация API + +- [Nexus 3 REST API: Repository Management](https://help.sonatype.com/en/repositories-api.html) diff --git a/content/documentation/admin/automations.ru.md b/content/documentation/admin/automations.ru.md new file mode 100644 index 0000000..47b6c50 --- /dev/null +++ b/content/documentation/admin/automations.ru.md @@ -0,0 +1,67 @@ +--- +title: Автоматизации +menuTitle: Автоматизации +d8Edition: ee +moduleStatus: experimental +--- + +Автоматизации - механизм реагирования платформы на изменения спецификации сущностей. + +Каждая автоматизация может подписываться на обновления сущностей какого-либо ресурса по определенным правилам. При возникновении событии обновления автоматизация запускает выполнение действия, сценария или синхронизации источника данных. + +Также механизм автоматизаций позволяется запускать событие по расписанию. + +Автоматизация может запускать выполнение как на сущность, которая вызвала триггер, так и на связанные с ней сущности в соответствии с настройками. **Важно:** если выполнение настроено для связанных сущностей, оно не будет запущено на сущность, вызвавшую событие. При настройке запуска на связанные сущности поддерживается только выполнение действий или сценариев. + +## Интерфейс настройки автоматизации + +Форма создания и редактирования автоматизации разделена на логические секции: + +### Триггеры + +Секция для настройки условий, при которых автоматизация будет запускаться. Каждая автоматизация может содержать произвольное количество триггеров. + +При настройке каждого триггера указываются: + +* **Ресурс** — ресурс, события с сущностями которого будут являться триггером для запуска автоматизации +* **Условие** — условие в формате [Go template](https://developer.hashicorp.com/nomad/tutorials/templates/go-template-syntax), описывающее, изменения какого параметра будет считаться триггером для запуска автоматизации и какое именно значение должен принять измененный параметр + +Примеры условий триггера: + +* `{{ ne .entity.properties.id 0 }}` — автоматизация будет запускаться, если значение параметра `id` изменилось и после изменения стало не равным нулю +* `{{ eq .entity.properties.status "Failed" }}` — автоматизация будет запускаться, если значение параметра `status` изменилось на `Failed` с любого другого + +### Выполнение + +Секция для настройки того, что будет выполняться при срабатывании триггера автоматизации. + +Настраиваются: + +* **Тип выполнения** — тип объекта, который будет выполняться: действие, сценарий или синхронизация источника данных +* **Объект выполнения** — конкретный объект (действие, сценарий или источник данных), который будет выполняться + +Для действий и сценариев доступна дополнительная настройка: + +* **Запускать выполнение для связанных ресурсов** — при включении этой опции выполнение будет автоматически запускаться для всех сущностей, имеющих соответствующую связь с изменённой сущностью. При этом выполнение не будет запущено на сущность, вызвавшую событие + +### Синхронизация + +Секция для настройки периодической синхронизации — автоматического запуска автоматизации по расписанию. + +Настраиваются: + +* **Периодическая синхронизация** — включение/выключение периодической синхронизации +* **Периодичность запуска** — cron-выражение для настройки частоты запуска автоматизации (например, `0 0 * * *` для ежедневного запуска в полночь) + +## Триггеры + +Механизм работы триггеров автоматизаций основан на событиях (event's), которые генерируются при каждом создании, изменении, либо удалении любой сущности любого ресурса. + +Автоматизации: + +1. Прослушивают события указанных в конфигурации триггеров ресурсов +2. Проверяют, изменилось ли значение параметра, указанного в условиях триггера +3. При изменении сравнивают текущее значение параметра с условием +4. При соответствии условию запускают выполнение + +**Важно:** Новые автоматизации обрабатывают только события, которые произошли после их создания. События, произошедшие до создания автоматизации, не будут обработаны. diff --git a/content/documentation/admin/datasets.ru.md b/content/documentation/admin/datasets.ru.md new file mode 100644 index 0000000..a45db9c --- /dev/null +++ b/content/documentation/admin/datasets.ru.md @@ -0,0 +1,96 @@ +--- +title: Наборы данных +menuTitle: Наборы данных +d8Edition: ee +moduleStatus: experimental +--- + +Наборы данных - это предварительно настроенные конфигурации, которые позволяют быстро развернуть готовые интеграции с внешними системами и настроить необходимые компоненты платформы. + +Каждый набор данных содержит: + +- Дашборды для визуализации данных +- Виджеты для отображения информации +- Источники данных для синхронизации +- Внешние сервисы для подключения к API +- Типы учетных данных для аутентификации +- Роли и права доступа +- Другие необходимые компоненты платформы + +## Управление наборами данных + +### Просмотр доступных наборов + +В разделе `Администрирование → Наборы данных` отображается список всех доступных наборов данных. Каждая карточка содержит: + +- **Название** - имя набора данных +- **Краткое описание** - краткая информация о функциональности +- **Кнопка "Описание"** - открывает подробную информацию с двумя вкладками: + - Подробное описание с полной информацией о компонентах + - Список объектов, которые будут созданы при применении +- **Кнопка "Применить"** - запускает процесс установки набора данных +- **Кнопка "Удалить"** - удаляет ранее примененный набор данных + +### Применение набора данных + +1. Нажмите кнопку **"Применить"** на карточке нужного набора данных +2. Если набор данных требует настройки параметров, откроется форма конфигурации +3. Заполните необходимые параметры и нажмите **"Применить"** +4. Если параметры не требуются, появится окно подтверждения +5. После успешного применения все компоненты набора данных будут созданы в системе + +### Удаление набора данных + +1. Нажмите кнопку **"Удалить"** на карточке примененного набора данных +2. Подтвердите удаление в диалоговом окне +3. Все компоненты набора данных будут удалены из системы + +### Настройка после применения + +После применения некоторых наборов данных может потребоваться дополнительная настройка: + +1. Перейдите в **"Профиль"** → **"Учетные данные"** +2. Заполните необходимые учетные данные (токены, пароли и т.д.) +3. Сохраните изменения + +## Доступные наборы данных + +### GitLab + +Набор данных для работы с GitLab репозиториями и анализа CI/CD процессов + +**Дашборды:** + +- **Статистика репозитория** - для анализа статистики пайплайнов +- **Управление репозиторием** - для управления репозиториями + +**Виджеты:** + +- **Статистика пайплайнов GitLab** - для детальной аналитики пайплайнов +- **GitLab пайплайны** - для управления пайплайнами +- **Редактор пайплайнов GitLab** - для редактирования конфигурации пайплайнов + +**Настройка:** + +Набор данных настраивает подключение к GitLab API через внешний сервис, создает типы учетных данных для токена и имени пользователя и подключает источник данных для синхронизации репозиториев GitLab в каталог. + +> **Важно:** После применения необходимо заполнить в профиле супер-администратора учетные данные **GitLab token**. + +**Параметры настройки:** + +- **GitLab URL** - адрес вашего GitLab сервера (по умолчанию: ) + +**Требования:** + +- Доступ к GitLab API +- Токен доступа GitLab с правами на чтение репозиториев и пайплайнов + +**Применение:** + +1. Примените набор данных GitLab +2. Укажите URL вашего GitLab сервера +3. Перейдите в профиль супер-администратора +4. Заполните учетные данные "GitLab token" вашим токеном доступа +5. Сохраните изменения + +После этого в разделе "Каталог" появятся ваши GitLab репозитории, а на дашбордах будет отображаться статистика и управление пайплайнами. diff --git a/content/documentation/admin/datasources/_index.ru.md b/content/documentation/admin/datasources/_index.ru.md new file mode 100644 index 0000000..d4724b9 --- /dev/null +++ b/content/documentation/admin/datasources/_index.ru.md @@ -0,0 +1,4 @@ +--- +title: Источники данных +weight: 40 +--- diff --git a/content/documentation/admin/datasources/overview.ru.md b/content/documentation/admin/datasources/overview.ru.md new file mode 100644 index 0000000..0af3822 --- /dev/null +++ b/content/documentation/admin/datasources/overview.ru.md @@ -0,0 +1,204 @@ +--- +title: Обзор +weight: 10 +--- + + +Источники данных - механизм DDP, который позволяет синхронизировать информацию из внешних инфраструктурных систем (например, GitLab, либо Kubernetes) и преобразовывать данную информацию в параметры той или иной сущности. + +Также источники данных позволяют: + +* Создавать новые сущности +* Удалять сущности, которые были удалены из внешних инфраструктурных систем +* Создавать связи между сущностями + +Каждый источник данных привязан к определенному ресурсу, и, соответственно, может оперировать сущностями только данного ресурса. При этом, связи могут создаваться между сущностями привязанного ресурса и любыми другими сущностями. + +## Типы источников данных + +* Встроенные (BuiltIn) - источники данных, для которых логика опроса инфраструктурных систем поставляется в рамках DDP +* Вебхуки (Webhooks) - см. страницу "Вебхуки" + +## Правила источников данных + +Для каждого источника данных администратором системы настраиваются правила, по которым будут: + +* Создаваться новые сущности +* Создаваться новые связи +* Производиться поиск соответствующих сущностей для обновления их параметров +* Производиться поиск сущностей для удаления + +Правила описываются в формате "source": "target". Для описания правил используется синтаксис [Go template](https://developer.hashicorp.com/nomad/tutorials/templates/go-template-syntax). + +В DDP реализованы 5 типов правил: + +* Правила фильтрации (filter rules) +* Правила создания (create rules) +* Правила сопоставления (match rules) +* Правила обновления (update rules) +* Правила создания связей (create relation rules) + +### Правила фильтрации + +Правила фильтрации позволяют отсеивать по регулярному выражению элементы, которые будут участвовать в дальнейшей обработке. В поле "Источник" указывается поле обрабатываемой структуры в формате [Go template](https://developer.hashicorp.com/nomad/tutorials/templates/go-template-syntax). В поле "Правило" указывается регулярное выражение для фильтрации. + +В случае наличия нескольких правил фильтрации, для дальнейшей обработки необходимо, чтобы элемент соответствовал каждому из них. В случае отсутствия правил фильтрации обрабатываться будут все элементы, полученные от внешней инфраструктурной системы. + +Например, при следующем наборе данных, полученном от внешней инфраструктурной системы: + +```json +[ + { + "name": "first", + "description": "first" + }, + { + "name": "second", + "description": "second" + } +] +``` + +и следующих правилах фильтрации: + +```json +"filterRules": [ + { + "source": "{{ .name }}", + "pattern": "^first" + } +] +``` + +обработка правилами создания, сопоставления и т.д. будет осуществляться только для первого элемента массива, у которого значение поля "name" соответствует "first". + +### Правила создания + +Правила создания определяют, каким образом информация, полученная от бэкенда источника данных, будет использоваться при создании новых сущностей. + +Например, при следующей спецификации одного из ресурсов внешней инфраструктурной системы, полученного через источник данных: + +```yaml +... +metadata: + name: example + namespace: default +... +``` + +и следующих правилах создания: + +```json +"match": [ + { + "source": "{{ .metadata.name }}", + "target": "Name" + }, + { + "source": "{{ .metadata.namespace }}-{{ .metadata.name }}", + "target": "Slug" + } +] +``` + +после синхронизации источника данных будет создана сущность, название (Name) которой будет иметь значение `example`, а идентификатор (Slug) - значение `default-example`. + +### Правила сопоставления + +Правила сопоставления определяют, каким образом производить поиск существующих, либо только что созданных источником данных сущностей для обновления их параметров. + +### Правила обновления + +Правила обновления определяют, какие параметры сущности стоит автоматически заполнять на основе спецификации соответствующего ресурса из внешней системы. Сущность, параметры которой необходимо заполнить, определяется на основе правил сопоставления. + +### Правила создания связей + +Правила создания связей определяют, какие связи создавать для сущности, которая соответствует правилам сопоставления. При задании правил создания связей заполняется: + +* Связь ресурса +* Поле из спецификации ресурса внешней инфраструктурной системы, на основании которого производить поиск связи + +Например, при следующей спецификации одного из ресурсов внешней инфраструктурной системы, полученного через источник данных: + +```yaml +... +metadata: + name: example + namespace: default +... +``` + +и следующем правиле создания связей: + +```json +"createRelations": [ + { + "resourceRelationUuid": "<12345678-1234-5678-1234-567812345678>", + "parentEntitySlug": "{{ .metadata.namespace }}", + "childEntitySlug": "" + } +] +``` + +будет: + +* Среди сущностей, которые при создании связи были указаны как родительские, был произведен поиск той, идентификатор (slug) которой соответствует значению `default`. **Важно:** при создании связи ресурсов задаётся родительский и дочерний ресурс. при указании идентификатора родительской сущности, поиск будет произведен только по сущностям из родительского ресурса. Если указать идентификатор дочерней сущности, то поиск будет произведен только по сущностям дочернего ресурса. В рамках создания правила необходимо указывать либо родительский идентификатор, либо дочерний. При одновременном указании в рамках одного правила обоих идентификаторов, поиск будет производиться только по родительскому ресурсу. + +* В случае существования сущности родительского ресурса с идентификатором `default`, создана связь между данной сущностью, и сущностью ресурса, к которому привязан источник данных, и которая соответствует правилам сопоставления + +## Синхронизация + +Каждый источник данных имеет несколько параметров настройки синхронизации: + +* Периодическая синхронизация (enableSchedule) - включение или выключение периодической синхронизации +* Периодичность запуска (scheduleExpression) - cron-выражение из 6 полей, определяющее интервал запуска периодической синхронизации + +При включенном параметре "Периодическая синхронизация" источник данных будет автоматически обновлять информацию из внешних инфраструктурных систем с интервалом, определенным в параметре "Периодичность запуска". + +Также каждый источник данных может быть синхронизирован вручную в любой момент времени через веб-интерфейс (пункт `Синхронизировать` в меню источника данных), либо через API. + +## Удаление сущностей + +Каждый источник данных имеет несколько параметров удаления сущностей: + +* Удаление несуществующих сущностей (deleteEntities) +* Удаление только сущностей, созданных этим источником данных (deleteOnlyOriginatedEntities) + +При включении параметра "Удаление несуществующих сущностей" источник данных будет сравнивать список ресурсов, полученных из внешней инфраструктурной системы и список существующих сущностей ресурса. При обнаружении в DDP entities, которые отсутствуют в списке полученных, они будут удалены из DDP. + +При включении параметра "Удаление только сущностей, созданных этим источником данных" источник данных будет дополнительно сравнивать, каким образом была создана сущность, которую необходимо удалить. Если сущность была создана этим источником данных, то она будет удалена, если нет, то источник данных перейдет к обработке следующей сущности в списке без удаления текущей. + +Поиск создателя (origin) сущности производится по двум полям в спецификации сущности: + +```json +{ + "origin": { + "type": "" + } +} +``` + +## Логирование запусков + +Для каждого запуска источника данных создается запись в БД, содержащая полный лог выполнения. Максимальное количество подобных записей регулируется параметром "максимальное количество записей" в конфигурации источника данных. При достижении максимального количества старые записи будут удаляться. + +Параметр `datasources.logging.enabled` конфигурационном файле DDP backend позволяет выводить в stdout, либо скрывать логи запуска источника данных. При значении `true` логи запуска будут выводиться в stdout, при значении `false` логи выводиться не будут. + +Записи в БД с полным логом запуска источника данных создаются независимо от значения параметра `datasources.logging.enabled`. + +## Учетная запись для запуска + +При настройке источника данных необходимо выбрать определенную учетную запись для запуска синхронизации. + +Реквизиты данной учетной записи будут использоваться источником данных для доступа к опрашиваемой инфраструктурной системе. + +Помимо учетной записи для запуска необходимо указание того, какие ее реквизиты будут использованы при запуске источника данных. Для этого в секции `Безопасность / Учетные данные` добавляются новые учетные данные с определенным идентификатором. + +Значение данного идентификатора может быть подставлено в конфигурацию источника данных с использованием синтаксиса [Go template](https://developer.hashicorp.com/nomad/tutorials/templates/go-template-syntax). + +Например, если в Header для источника данных необходимо передать секретное значение с идентификатором `token`, то оно может быть указано в следующем виде: + +```go +{{ .credentials.token }} +``` diff --git a/content/documentation/admin/datasources/types.ru.md b/content/documentation/admin/datasources/types.ru.md new file mode 100644 index 0000000..942746c --- /dev/null +++ b/content/documentation/admin/datasources/types.ru.md @@ -0,0 +1,809 @@ +--- +title: Типы источников данных +--- + +## DefectdojoProducts + +Источник данных типа **DefectdojoProducts** возвращает список продуктов в Defectdojo. + +### Авторизация + +Конфигурация авторизации описана в разделе [внешний сервис DefectDojo](../external-services/#defectdojo). + +### Спецификация ответа + +Платформа выполняет GET-запрос по URL: `/api/v2/products`. Возвращаются все доступные значения. [Спецификация ответа](https://demo.defectdojo.org/api/v2/oa3/swagger-ui/). + +### Конфигурация + +* **URL** - URL DefectDojo в формате `https://example.com`. + +### Параметры + +Настраиваемые параметры отсутствуют. + +## GitlabGroups + +Источник данных типа **GitlabGroups** возвращает список групп в GitLab. + +### Авторизация + +Конфигурация авторизации описана в разделе [внешний сервис GitLab](../external-services/#gitlab). + +### Спецификация ответа + +Платформа выполняет GET-запрос к API GitLab по URL: `/api/v4/groups`. Платформа возвращает все доступные значения. [Спецификация ответа](https://docs.gitlab.com/api/groups/#list-groups). + +### Конфигурация + +* **URL** - URL GitLab в формате `https://gitlab.com`, без части `/api/v4`. + +### Параметры + +Настраиваемые параметры отсутствуют. + +## GitlabProjects + +Источник данных типа **GitlabProjects** возвращает список проектов в Gitlab. + +### Авторизация + +Конфигурация авторизации описана в разделе [внешний сервис GitLab](../external-services/#gitlab). + +### Спецификация ответа + +В зависимости от [конфигурации параметров](#gitlabprojectsparameters), платформа выполняет GET-запрос к API GitLab и возвращает соответствующую спецификацию. + +Если значение параметра **all** равно `true`, выполняется GET-запрос по URL: `/api/v4/projects`. Платформа возвращает все доступные значения. [Спецификация ответа](https://docs.gitlab.com/api/projects/#list-all-projects). + +Если значение параметра **all** равно `false`, выполняется GET-запрос по URL: `/api/v4/groups/:id/projects`. Платформа возвращает все доступные значения. [Спецификация ответа](https://docs.gitlab.com/api/projects/#list-all-projects). + +Если значение параметра **tags** равно `true` платформа дополнительно получает git теги. Для получения git тегов, выполняется GET-запрос по URL: `/api/v4/projects/:id/repository/tags`. Платформа получает список всех git тегов и расширяет [спецификацию ответа](https://docs.gitlab.com/api/projects/#list-all-projects) полем `ddp_repository_tags`, которое соответствует [спецификации ответа list-project-repository-tags](https://docs.gitlab.com/api/tags/#list-project-repository-tags). + +### Конфигурация + +* **URL** - URL GitLab в формате `https://gitlab.com`, без части `/api/v4`. + + + +### Параметры + +|Название |Обязательность |Описание |Возможные значения |По умолчанию | +|-----------------|--------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------|------------------------------------------------------------------------------| +|all |опционально |В явном виде указывает, что необходимо собирать репозитории всех групп, к которым есть доступ. |true, false |false | +|group_ids |Обязательно, если **all** в значении `false`|Источник данных будет собирать проекты групп с указанным ID. ID групп указываются через запятую. |Пример: 1001,1002 |\- | +|tags |опционально |Платформа дополнительно получает список всех git тегов и расширяет [спецификацию ответа](https://docs.gitlab.com/api/projects/#list-all-projects) полем `ddp_repository_tags`, которое соответствует [спецификации ответа list-project-repository-tags](https://docs.gitlab.com/api/tags/#list-project-repository-tags). |true, false |false | +|include_subgroups|опционально |Если указан параметр **group_ids**, то параметр **include_subgroups** определяет, собирать ли проекты подгрупп указанных групп. |true, false |false | +|tags_order_by |опционально |Соответствует спецификации [GitLab Tags API order_by](https://docs.gitlab.com/api/tags/#list-project-repository-tags) |[документация](https://docs.gitlab.com/api/tags/#list-project-repository-tags)|[документация](https://docs.gitlab.com/api/tags/#list-project-repository-tags)| +|tags_sort |опционально |Соответствует спецификации [GitLab Tags API sort](https://docs.gitlab.com/api/tags/#list-project-repository-tags) |[документация](https://docs.gitlab.com/api/tags/#list-project-repository-tags)|[документация](https://docs.gitlab.com/api/tags/#list-project-repository-tags)| +|tags_search |опционально |Соответствует спецификации [GitLab Tags API search](https://docs.gitlab.com/api/tags/#list-project-repository-tags) |[документация](https://docs.gitlab.com/api/tags/#list-project-repository-tags)|[документация](https://docs.gitlab.com/api/tags/#list-project-repository-tags)| + +## HarborArtifacts + +Источник данных типа **HarborArtifacts** собирает информацию о всех артефактах в Harbor. + +### Авторизация + +Конфигурация авторизации описана в разделе [внешний сервис Harbor](../external-services/#harbor). + +### Спецификация ответа + +Платформа получает список всех проектов и репозиториев, которые содержатся в этих проектах, затем по каждому из доступных проектов выполняется GET-запрос к API Harbor: `/api/v2.0/projects/{project_name}/repositories/{repository_name}/artifacts`. Спецификация ответа доступна в интерфейса Harbor ([подробнее](https://goharbor.io/docs/main/working-with-projects/using-api-explorer/)). + +### Конфигурация + +* **URL** - URL Harbor в формате `https://example.com` + +### Параметры + +Настраиваемые параметры отсутствуют. + +## HarborProjects + +Источник данных типа **HarborProjects** собирает информацию о всех проектах в Harbor. + +### Авторизация + +Конфигурация авторизации описана в разделе [внешний сервис Harbor](../external-services/#harbor). + +### Спецификация ответа + +Платформа получает список всех доступных проектов выполняя GET-запросы к API Harbor: `/api/v2.0/projects`. пецификация ответа доступна в интерфейса Harbor ([подробнее](https://goharbor.io/docs/main/working-with-projects/using-api-explorer/)). + +### Конфигурация + +* **URL** - URL Harbor в формате `https://example.com`. + +### Параметры + +Настраиваемые параметры отсутствуют. + +## HarborRepositories + +Источник данных типа **HarborRepositories** собирает информацию о всех репозиториях в Harbor. + +### Авторизация + +Конфигурация авторизации описана в разделе [внешний сервис Harbor](../external-services/#harbor). + +### Спецификация ответа + +Платформа получает список всех проектов, затем получает список всех репозиториев в каждом из проектов выполняя GET-запросы к API Harbor: `/api/v2.0/projects/{project_name}/repositories`. Спецификация ответа доступна в интерфейса Harbor ([подробнее](https://goharbor.io/docs/main/working-with-projects/using-api-explorer/)). + +### Конфигурация + +* **URL** - URL Harbor в формате `https://example.com`. + +### Параметры + +Настраиваемые параметры отсутствуют. + +## HarborTags + +Источник данных типа **HarborTags** собирает информацию о всех тегах у артефактов в Harbor. + +### Авторизация + +Конфигурация авторизации описана в разделе [внешний сервис Harbor](../external-services/#harbor). + +### Спецификация ответа + +Платформа получает список всех проектов и репозиториев, которые содержатся в этих проектах, затем по каждому из доступных проектов выполняется GET-запрос к API Harbor: `/api/v2.0/projects/{project_name}/repositories/{repository_name}/artifacts`. Затем происходит сбор всех тегов по всем артефактам (поле `tags`) и результат возвращается в виде массива. Спецификация ответа доступна в интерфейса Harbor ([подробнее](https://goharbor.io/docs/main/working-with-projects/using-api-explorer/)). + +### Конфигурация + +* **URL** - URL Harbor в формате `https://example.com` + +### Параметры + +Настраиваемые параметры отсутствуют. + +## HelmReleases + +Источник данных типа **HelmReleases** возвращает список всех HelmReleases в кластере Kubernetes. + +### Авторизация + +Конфигурация авторизации описана в разделе [внешний сервис Kubernetes](../external-services/#kubernetes). + +Подробнее про аутентификацию в Kubernetes описано в [официальной документации](https://kubernetes.io/docs/reference/access-authn-authz/authentication/). + +### Спецификация ответа + +Платформа возвращает все HelmReleases в кластере Kubernetes. Спецификация: + +```json +[ + { + "name": "string", // Название + "info": { + "first_deployed": "string", // Дата и время первого деплоя + "last_deployed": "string", // Дата и время последнего деплоя + "deleted": "string", // Дата и время удаления (может быть пустой строкой) + "description": "string", // Описание + "status": "string", // Статус + "notes": "string" // Заметки + }, + "chart": { + "metadata": { + "name": "string", // Название чарта + "home": "string", // Домашняя страница + "sources": "array", // Массив строк с URL-адресами источников + "version": "string", // Версия чарта + "description": "string", // Описание чарта + "keywords": "array", // Массив строк с ключевыми словами + "maintainers": "array", // Массив объектов с информацией о мейнтейнерах + "icon": "string", // URL иконки + "apiVersion": "string", // Версия API + "appVersion": "string" // Версия приложения + }, + "templates": [ // Массив объектов с шаблонами + { + "name": "templates/NOTES.txt", + "data": "..." + }, + { + "name": "templates/_helpers.tpl", + "data": "..." + } + // ... другие шаблоны + ], + "values": "object", // Объект с доступными настройками Helm чарта + "schema": "null", // Схема (может быть null) + "files": [ // Массив объектов с файлами + { + "name": ".helmignore", + "data": "..." + }, + { + "name": "LICENSE", + "data": "..." + } + // ... другие файлы + ] + }, + "config": { // Текушая конфигурацию + "caSecretName": "string", + "cache": { + "enabled": "boolean", + "expireHours": "integer" + } + // ... другие настройки + }, + "manifest": "string", // Отрендеренные манифесты + "version": "integer", // Версия helmrelease + "namespace": "string" // Namespace, где развернут релиз + }, + // ... другие helmreleases +] + +``` + +### Конфигурация + +* **URL** - URL Kubernetes API в формате `https://api.example.com`. + +### Параметры + +Настраиваемые параметры отсутствуют. + +## KafkaAcls + +Источник данных типа **KafkaAcls** собирает информацию о достпуных acls. + +### Авторизация + +Платформа поддерживает аутентификацию в Kafka с помощью SASL/PLAIN и SASL/SCRAM. Документация: [Kafka SASL/PLAIN](https://kafka.apache.org/documentation/#security_sasl_plain), [Kafka SASL/SCRAM](https://kafka.apache.org/documentation/#security_sasl_scram). + +### Спецификация ответа + +Платформа запрашивает информацию о настроенных ACL в Kafka. Полученные данные предоставляются в следующем формате: + +```json +[ + { + "Cluster": "string", // Название кластера Kafka + "ResourceType": "string", // Тип ресурса (TOPIC, GROUP и т.д.) + "ResourceName": "string", // Имя ресурса + "PatternType": "string", // Тип паттерна (LITERAL, PREFIXED и т.д.) + "Principal": "string", // Principal пользователя (например: "User:Alice") + "Host": "string", // Хост (обычно "*" для любого хоста) + "Operation": "string", // Операция (READ, WRITE, DESCRIBE и т.д.) + "PermissionType": "string" // Тип разрешения (ALLOW, DENY) + }, + // ... другие записи ACL +] +``` + +### Конфигурация + +* **URL** - URL Kafka в формате `example.com`. + +### Параметры + +|Название |Обязательность |Описание |Возможные значения | +|-----------------|-----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------| +|SecurityProtocol | **обязательно** | Протокол для подключения к Kafka. [Подробнее](https://kafka.apache.org/documentation/#adminclientconfigs_security.protocol) | PLAINTEXT, SASL_PLAINTEXT, SASL_SSL | +|SaslMechanism | опционально | Механизм аутентификации, который будет использовать SASL. Обязателен при использовании протокола SASL_PLAINTEXT или SASL_SSL. [Подробнее](https://kafka.apache.org/documentation/#security_sasl_mechanism) | PLAIN, SCRAM-SHA-256, SCRAM-SHA-512 | +|User | **обязательно** | Username пользователя для подключения к Kafka | - | +|Pass | **обязательно** | Password пользователя для подключения к Kafka | - | + +## KafkaBrokers + +Источник данных типа **KafkaBrokers** собирает информацию о доступных брокерах. + +### Авторизация + +Платформа поддерживает аутентификацию в Kafka с помощью SASL/PLAIN и SASL/SCRAM. Документация: [Kafka SASL/PLAIN](https://kafka.apache.org/documentation/#security_sasl_plain), [Kafka SASL/SCRAM](https://kafka.apache.org/documentation/#security_sasl_scram). + +### Спецификация ответа + +Платформа осуществляет несколько запросов к Kafka с целью получения сведений о доступных топиках. Полученные данные предоставляются в следующем формате: + +```json +{ + "Cluster": "string", // Название кластера Kafka (из kafkaBrokerMetadata.Cluster) + "Leader": "boolean", // Является ли брокер лидером-контроллером (true/false) + "NodeID": "number", // Уникальный ID брокера (из broker.NodeID) + "Port": "number", // Порт брокера (из broker.Port) + "Host": "string", // Хост брокера (из broker.Host) + "Rack": "string|null", // Рек (зона доступности) брокера (из broker.Rack) + "Configs": { // Конфигурации брокера + { + "Name": "number", // Уникальный ID брокера + "Configs": [ // Массив отдельных конфигураций + { + "Key": "listeners", // Ключ конфигурации + "Value": "CLIENT://:9092,INTERNAL://:9094", // Значение конфигурации + "Source": "STATIC_BROKER_CONFIG" // Источник конфигурации + }, + { + "Key": "log.retention.hours", // Ключ конфигурации + "Value": 168, // Значение конфигурации + "Source": "DEFAULT_CONFIG" // Источник конфигурации + }, + { + "...": "..." // Другие параметры + // Полный список параметров см. в официальной документации: + // https://kafka.apache.org/documentation/#brokerconfigs + } + ] + } + } +} +``` + +### Конфигурация + +* **URL** - URL Kafka в формате `example.com`. + +### Параметры + +|Название |Обязательность |Описание |Возможные значения | +|-----------------|-----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------| +|SecurityProtocol | **обязательно** | Протокол для подключения к Kafka. [Подробнее](https://kafka.apache.org/documentation/#adminclientconfigs_security.protocol) | PLAINTEXT, SASL_PLAINTEXT, SASL_SSL | +|SaslMechanism | опционально | Механизм аутентификации, который будет использовать SASL. Обязателен при использовании протокола SASL_PLAINTEXT или SASL_SSL. [Подробнее](https://kafka.apache.org/documentation/#security_sasl_mechanism) | PLAIN, SCRAM-SHA-256, SCRAM-SHA-512 | +|User | **обязательно** | Username пользователя для подключения к Kafka | - | +|Pass | **обязательно** | Password пользователя для подключения к Kafka | - | + +## KafkaTopics + +Источник данных типа **KafkaTopics** собирает информацию о доступных топиках в Kafka. + +### Авторизация + +Платформа поддерживает аутентификацию в Kafka с помощью SASL/PLAIN и SASL/SCRAM. Документация: [Kafka SASL/PLAIN](https://kafka.apache.org/documentation/#security_sasl_plain), [Kafka SASL/SCRAM](https://kafka.apache.org/documentation/#security_sasl_scram). + +### Спецификация ответа + +Платформа осуществляет несколько запросов к Kafka с целью получения сведений о доступных топиках. Полученные данные предоставляются в следующем формате: + +```json +{ + "Cluster": "string", // Название кластера Kafka + "Topic": "string", // Название топика + "ID": "string", // Уникальный идентификатор топика + "IsInternal": "boolean", // Является ли топик внутренним (Пример внутреннего топика: __consumer_offsets) + "Partitions": "number", // Количество партиций в топике + "Configs": { // Конфигурации топика (динамические параметры) + "retention.ms": 604800000, // Пример параметра: время хранения сообщений + "cleanup.policy": "delete", // Пример параметра: политика очистки + "...": "..." // Другие параметры + // Полный список параметров см. в официальной документации: + // https://kafka.apache.org/documentation/#topicconfigs + } +} +``` + +### Конфигурация + +* **URL** - URL Kafka в формате `example.com` + +### Параметры + +|Название |Обязательность |Описание |Возможные значения | +|-----------------|-----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------| +|SecurityProtocol | **обязательно** | Протокол для подключения к Kafka. [Подробнее](https://kafka.apache.org/documentation/#adminclientconfigs_security.protocol) | PLAINTEXT, SASL_PLAINTEXT, SASL_SSL | +|SaslMechanism | опционально | Механизм аутентификации, который будет использовать SASL. Обязателен при использовании протокола SASL_PLAINTEXT или SASL_SSL. [Подробнее](https://kafka.apache.org/documentation/#security_sasl_mechanism) | PLAIN, SCRAM-SHA-256, SCRAM-SHA-512 | +|User | **обязательно** | Username пользователя для подключения к Kafka | - | +|Pass | **обязательно** | Password пользователя для подключения к Kafka | - | + +## KubernetesDeployments + +Источник данных типа **KubernetesDeployments** возвращает список всех Deployment в кластере Kubernetes. + +### Авторизация + +Конфигурация авторизации описана в разделе [внешний сервис Kubernetes](../external-services/#kubernetes). + +### Спецификация ответа + +Платформа возвращает все Deployment в кластере Kubernetes. Спецификация ресурса Deployment доступна в [официальной документации](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/deployment-v1/#DeploymentSpec). + +### Конфигурация + +* **URL** - URL Kubernetes API в формате `https://api.example.com`. + +### Параметры + +Настраиваемые параметры отсутствуют. + +## KubernetesIngresses + +Источник данных типа **KubernetesIngresses** возвращает список всех Ingress в кластере Kubernetes. + +### Авторизация + +Конфигурация авторизации описана в разделе [внешний сервис Kubernetes](../external-services/#kubernetes). + +### Спецификация ответа + +Платформа возвращает все Ingress в кластере Kubernetes. Спецификация ресурса Ingress доступна в [официальной документации](https://kubernetes.io/docs/reference/kubernetes-api/service-resources/ingress-v1/). + +### Конфигурация + +* **URL** - URL Kubernetes API в формате `https://api.example.com`. + +### Параметры + +Настраиваемые параметры отсутствуют. + +## KubernetesNamespaces + +Источник данных типа **KubernetesNamespaces** возвращает список всех Namespace в кластере Kubernetes. + +### Авторизация + +Конфигурация авторизации описана в разделе [внешний сервис Kubernetes](../external-services/#kubernetes). + +### Спецификация ответа + +Платформа возвращает все Namespace в кластере Kubernetes. Спецификация ресурса Namespace доступна в [официальной документации](https://kubernetes.io/docs/reference/kubernetes-api/cluster-resources/namespace-v1/). + +### Конфигурация + +* **URL** - URL Kubernetes API в формате `https://api.example.com`. + +### Параметры + +Настраиваемые параметры отсутствуют. + +## KubernetesResources + +Источник данных типа **KubernetesResources** возвращает список ресурсов Kubernetes. Тип возвращаемых ресурсов задается через параметры источника данных. Поддерживаются как встроенные в Kubernetes типы ресурсов, так и любые кастомные ресурсы. + +### Авторизация + +Конфигурация авторизации описана в разделе [внешний сервис Kubernetes](../external-services/#kubernetes). + +### Спецификация ответа + +Спецификация ответа зависит от типа ресурса, который планируется получить. Для получения точной информации необходимо обратиться к документации. Для встроенных в Kubernetes ресурсов доступна [официальная документация](https://kubernetes.io/docs/reference/kubernetes-api/). + +В случае отсутствия возможности обратиться к документации, можно получить описание спецификации с помощью утилиты `kubectl`. + +Пример для deployment: + +`kubectl explain deployment --recursive` + +Примерный вывод: + +```yaml +GROUP: apps +KIND: Deployment +VERSION: v1 + +DESCRIPTION: + Deployment enables declarative updates for Pods and ReplicaSets. + +FIELDS: + apiVersion + kind + metadata + annotations + creationTimestamp +... +``` + +Описание спецификации находится внутри `FIELDS:`. + +### Конфигурация + +* **URL** - URL Kubernetes API в формате `https://api.example.com`. + +### Параметры + +|Название |Обязательность |Описание |Возможные значения | +|------------|---------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------| +|apiGroup |опционально |API группа ресурса. Для ресурсов в core API группе поле не задается. |[См. определение требуемых Group и Version](#определение-требуемых-group-и-version)| +|version |**обязательно**|Версия API ресурса. |[См. определение требуемых Group и Version](#определение-требуемых-group-и-version)| +|isNamespaced|**обязательно**|Является ли ресурс namespaced или нет. Проверить, является ли ресурс namespaced можно с помощью команды `kubectl api-resources` |true, false | +|namespace |опционально |Namespace из которого будут собираться ресурсы. Если не указан, ресурсы будут собираться из всех namespace. Значение параметра учитывается только если значение **isNamespaced** равно `true`| | +|resource |**обязательно**|Название ресурса. Указывается маленькими буквами во множественном числе, как в поле NAME вывода команды `kubectl api-resources`. | | + +## Примеры конфигурации + +Собрать все ingress ресурсы Kubernetes кластера: + +```yaml +apiGroup: networking.k8s.io +version: v1 +isNamespaced: true +resource: ingresses +``` + +Собрать все pod Kubernetes кластера: + +```yaml +version: v1 +isNamespaced: true +resource: pods +``` + +Собрать все pod Kubernetes кластера в namespace `d8-development-platform`: + +```yaml +version: v1 +isNamespaced: true +resource: pods +namespace: d8-development-platform +``` + +Собрать все namespace Kubernetes кластера: + +```yaml +version: v1 +isNamespaced: false +resource: namespaces +``` + +Собрать все кастомные ресурсы ModuleRelease Kubernetes кластера: + +```yaml +apiGroup: deckhouse.io +version: v1alpha1 +isNamespaced: false +resource: modulereleases +``` + +### Определение требуемых Group и Version + +Каждому типу ресурса соответствует своя версия и группа. Полный список API-ресурсов с их группами и версиями: [документация Kubernetes](https://kubernetes.io/docs/reference/kubernetes-api/) + +Если неизвестно, какие требуются Group и Version, можно попробовать подставить актуальные значения. Есть несколько вариантов как их посмотреть: + +#### С помощью утилиты kubectl + +Команда `kubectl explain` показывает `version` и `apiGroup` для ресурса. + +Пример: + +```bash +kubectl explain deployment +``` + +Вывод: + +```yaml +GROUP: apps +KIND: Deployment +VERSION: v1 + +DESCRIPTION: + Deployment enables declarative updates for Pods and ReplicaSets. + +FIELDS: +... +``` + +## NexusArtifacts + +Источник данных типа **NexusArtifacts** возвращает список артефактов в Nexus. + +### Авторизация + +Конфигурация авторизации описана в разделе [внешний сервис Nexus](../external-services/#nexus). + +### Спецификация ответа + +Платформа формирует список доступных репозиториев, затем по каждому репозиторию выполняется GET-запрос к API Nexus: `/service/rest/v1/components`. [Спецификация ответа](https://help.sonatype.com/en/components-api.html). + +### Конфигурация + +* **URL** - URL Nexus в формате `https://example.com` + +### Параметры + +Настраиваемые параметры отсутствуют. + +## NexusRepositories + +Источник данных типа **NexusRepositories** возвращает список репозиториев в Nexus. + +### Авторизация + +Конфигурация авторизации описана в разделе [внешний сервис Nexus](../external-services/#nexus). + +### Спецификация ответа + +Платформа выполняет GET-запрос к API Nexus: `/service/rest/v1/repositories`. [Спецификация ответа](https://help.sonatype.com/en/repositories-api.html). + +### Конфигурация + +* **URL** - URL Nexus в формате `https://example.com` + +### Параметры + +Настраиваемые параметры отсутствуют. + +## PrometheusMetrics + +Источник данных типа **PrometheusMetrics** возвращает результат запроса PromQL в Prometheus. + +### Авторизация + +Конфигурация авторизации описана в разделе [внешний сервис Prometheus](../external-services/#prometheus). + +### Спецификация ответа + +Платформа выполняет GET-запрос к API Prometheus: `/api/v1/query`. [Спецификация ответа](https://prometheus.io/docs/prometheus/latest/querying/api/#instant-queries). + +### Конфигурация + +* **URL** - URL prometheus API в формате `https://example.com/api/v1/query` +* **Тип query** - Prometheus +* **Query** - запрос в формате PromQL ([подробнее](https://prometheus.io/docs/prometheus/latest/querying/basics/)), на основе которого будет сформирован ответ. + +### Параметры + +Настраиваемые параметры отсутствуют. + +## SonarqubeProjects + +Источник данных типа **SonarqubeProjects** возвращает список проектов в SonarQube. + +### Авторизация + +Конфигурация авторизации описана в разделе [внешний сервис SonarQube](../external-services/#sonarqube). + +### Спецификация ответа + +Платформа выполняет GET-запрос к API SonarQube: `/api/projects/search`. Система собирает все доступные `components` и возвращает их в виде массива. [Спецификация `components`](https://next.sonarqube.com/sonarqube/web_api/api/projects/search). + +### Конфигурация + +* **URL** - URL Sonarqube в формате `https://example.com` + +### Параметры + +Настраиваемые параметры отсутствуют. + +## GenericAPI + +Источник данных типа **GenericAPI** позволяет подключаться к любому REST API и получать данные в формате JSON. Поддерживает различные типы пагинации и настраиваемые параметры запроса. + +### Авторизация + +GenericAPI поддерживает любые типы аутентификации через настройку заголовков HTTP. Наиболее распространенные способы: + +**Bearer Token:** + +```sh +Authorization: Bearer <токен> +``` + +**Basic Authentication:** + +```sh +Authorization: Basic +``` + +**API Key:** + +```sh +X-API-Key: <ключ> +``` + +### Спецификация ответа + +GenericAPI возвращает массив объектов JSON. Структура данных зависит от конкретного API, к которому происходит подключение. + +Пример типичного ответа: + +```json +[ + { + "id": 1, + "name": "Example Item", + "description": "Description of the item", + "created_at": "2023-01-01T00:00:00Z" + }, + { + "id": 2, + "name": "Another Item", + "description": "Another description", + "created_at": "2023-01-02T00:00:00Z" + } +] +``` + +### Конфигурация + +* **URL** - базовый URL API в формате `https://api.example.com` +* **Method** - HTTP метод (GET, POST, PUT, PATCH, DELETE) +* **Query Type** - тип запроса (Generic) +* **Query** - дополнительные query параметры (например, для фильтрации или поиска) + +### Параметры + +| Название | Обязательность | Описание | Возможные значения | Примеры | По умолчанию | +|------------------|----------------|----------------------------------------------------------------------------------|-----------------------------------------|--------------------------------|--------------| +| paginationType | опционально | Тип пагинации для обработки больших объемов данных | none, offset, cursor, page, link_header | none | none | +| path | опционально | Путь к endpoint API, который будет добавлен к базовому URL | Любая строка, начинающаяся с / | /api/v1/users, /projects | "" | +| dataPath | опционально | JSONPath для извлечения массива данных из ответа API | Любая строка | data, results.items, . | . | +| pageParam | опционально | Название параметра для номера страницы (для offset и page пагинации) | Любая строка | page, _page, pageNumber | page | +| limitParam | опционально | Название параметра для количества элементов на странице (для offset пагинации) | Любая строка | limit, per_page,_limit, size | limit | +| sizeParam | опционально | Название параметра для размера страницы (для page пагинации) | Любая строка | size, pageSize, _size | size | +| cursorParam | опционально | Название параметра для курсора (для cursor пагинации) | Любая строка | cursor, after, next | cursor | +| pageSize | опционально | Количество элементов на странице для пагинации | Положительное целое число | 10, 20, 50, 100 | 100 | +| requestBody | опционально | Тело запроса для POST/PUT/PATCH методов | Любая строка | {"query": "example"} | "" | + +### Типы пагинации + +**none** - без пагинации, получает все данные одним запросом + +**offset** - пагинация по номеру страницы и количеству элементов: +- Использует параметры `pageParam` и `limitParam` +- Пример: `?page=1&limit=20` + +**page** - пагинация по номеру страницы и размеру: +- Использует параметры `pageParam` и `sizeParam` +- Пример: `?page=1&size=20` + +**cursor** - пагинация по курсору: +- Использует параметр `cursorParam` +- Пример: `?cursor=eyJpZCI6MTIzfQ==` + +**link_header** - пагинация через заголовок Link: +- Использует заголовок `Link` в ответе для определения следующей страницы +- Стандарт RFC 5988 + +### Примеры конфигурации + +**JSONPlaceholder API (без пагинации):** + +```yaml +url: https://jsonplaceholder.typicode.com +path: /users +paginationType: none +dataPath: . +``` + +**GitLab API (offset пагинация):** + +```yaml +url: https://gitlab.example.com +path: /api/v4/projects +paginationType: offset +pageParam: page +limitParam: per_page +pageSize: 20 +headers: + Authorization: Bearer +``` + +**GitHub API (link header пагинация):** + +```yaml +url: https://api.github.com +path: /repos/owner/repo/issues +paginationType: link_header +headers: + Authorization: Bearer + Accept: application/vnd.github.v3+json +``` + +**API с вложенными данными:** + +```yaml +url: https://api.example.com +path: /data +dataPath: response.data.items +paginationType: offset +pageParam: page +limitParam: limit +query: "filter=active&sort=name" +``` + +**POST запрос с телом:** + +```yaml +url: https://api.example.com +path: /search +method: POST +requestBody: '{"query": "example", "filters": {"status": "active"}}' +query: "include=metadata&format=json" +headers: + Content-Type: application/json + Authorization: Bearer +``` diff --git a/content/documentation/admin/examples/_index.ru.md b/content/documentation/admin/examples/_index.ru.md new file mode 100644 index 0000000..09c0a6a --- /dev/null +++ b/content/documentation/admin/examples/_index.ru.md @@ -0,0 +1,4 @@ +--- +title: Примеры настройки +weight: 20 +--- diff --git a/content/documentation/admin/examples/images/service-autoupdates/workflow.png b/content/documentation/admin/examples/images/service-autoupdates/workflow.png new file mode 100644 index 0000000..0030fc3 Binary files /dev/null and b/content/documentation/admin/examples/images/service-autoupdates/workflow.png differ diff --git a/content/documentation/admin/examples/service-autoupdates.ru.md b/content/documentation/admin/examples/service-autoupdates.ru.md new file mode 100644 index 0000000..2ad150b --- /dev/null +++ b/content/documentation/admin/examples/service-autoupdates.ru.md @@ -0,0 +1,823 @@ +--- +title: Автоматическое обновление сервисов +--- + +Инструкция описывает настройку автоматического механизма обновления всех сервисов, созданных из шаблона, при выпуске новой версии этого шаблона. Новая версия шаблона определяется по новому тегу, добавленному в Git-репозиторий шаблона. + +## Компоненты системы и их назначение + +Для реализации автоматического обновления сервисов используются следующие компоненты платформы DDP: + +- Ресурс + + - В рамках инструкции используются два ресурса: + + - **"Шаблоны"** — хранит информацию о шаблонных репозиториях (URL и ID репозитория, последний тег версии) + + - **"Сервисы"** — хранит информацию о созданных сервисах (URL и ID репозитория, переменные шаблонизации, ветка по умолчанию) + + > Названия могут отличаться, в зависимости от ваших настроек. +- Связь + + - Устанавливает связь между шаблоном и созданными из него сервисами + +- Источник данных + + - В данной настройке источник данных: + + - Периодически синхронизирует информацию о шаблонных репозиториях из GitLab + + - Обновляет список тегов для каждого шаблона + + - Автоматически обновляет параметр "Последний тег" в сущностях ресурса "Шаблоны" + +- Действие + + - В данной настройке используются три действия: + + - **Создание проекта в GitLab** — создает новый проект в GitLab для размещения сервиса + + - **Создание репозитория из шаблона** — клонирует код из шаблонного репозитория в новый репозиторий сервиса с применением переменных шаблонизации + + - **Обновление сервиса из шаблона** — создает Merge Request в репозитории сервиса с изменениями из новой версии шаблона + + > Названия могут отличаться, в зависимости от ваших настроек. +- Процесс + + - В данной настройке процесс объединяет два действия: + + - Последовательно запускает создание проекта в GitLab, а затем создание репозитория из шаблона + + - Обеспечивает интерфейс для пользователя при создании сервиса из шаблона + +- Автоматизация + + - В данной настройке автоматизация: + + - Отслеживает изменения параметра "Последний тег" в сущностях ресурса "Шаблоны" + + - При обнаружении нового тега автоматически запускает действие "Обновление сервиса из шаблона" (название зависит от ваших настроек) для всех связанных сервисов + + - Создает Merge Request в каждом репозитории сервиса с изменениями из новой версии шаблона + +![workflow](../images/service-autoupdates/workflow.png) + +**Последовательность работы:** + +1. **Источник данных** периодически синхронизирует информацию о шаблонах из GitLab и обновляет параметр с идентификатор `repository_last_tag` (может отличаться в зависимости от ваших настроек) в сущностях ресурса "Шаблоны" + +2. **Автоматизация** отслеживает изменения параметра с идентификатором `repository_last_tag` (может отличаться в зависимости от ваших настроек) через триггеры + +3. При обнаружении нового тега **автоматизация** запускает действие "Обновление сервиса из шаблона" (название может отличаться в зависимости от ваших настроек) для всех сервисов, связанных с обновленным шаблоном + +4. **Действие** создает Merge Request в репозитории каждого сервиса, включающий изменения из новой версии шаблона + +Таким образом, при добавлении нового тега в шаблонный репозиторий, все связанные сервисы автоматически получают предложение обновиться через Merge Request. + +--- + +## Настройка компонентов + +В следующих разделах описывается конфигурация каждого компонента системы. При настройке учитывайте, что названия ресурсов и параметров могут отличаться от приведенных в инструкции. В этом случае необходимо обеспечить согласованность названий между всеми компонентами: если вы используете другие названия параметров в ресурсах, их нужно использовать во всех действиях, автоматизациях и источниках данных, которые ссылаются на эти параметры. + +Будет описано: + +1. Требуемые ресурсы в DDP и их параметры. +2. Требуемые [связи](../../user/catalog/#связи) между ресурсами. +3. Требуемые [источники данных](../datasources/overview/) для получения информации о новых версиях шаблонов. +4. Требуемые [действия](../actions/overview/) для создания сервиса из шаблона. +5. Требуемый процесс для реализации последовательного запуска цепочки [действий](../actions/overview/). +6. Требуемая [автоматизация](../automations) для реализации следующей функциональности: + - автоматическая проверка платформой DDP наличия новой версии шаблона + - автоматическое создание в сервисах, созданных из шаблона, Merge Request с изменениями из новой версии + +## Создание ресурсов и связи + +> **Ресурсы** — это элементы модели данных каталога DDP, которые определяют структуру хранения информации. Каждый ресурс может содержать параметры для хранения метаданных сущностей, а также связи с другими ресурсами для отображения зависимостей. + +### Ресурс «Шаблоны» + +У вас должен быть создан ресурс для хранения информации о шаблонных репозиториях. В рамках данной инструкции он назван `Шаблоны`, однако вы можете использовать любое удобное для вас название. Если ресурса еще нет, [создайте его](#создание-ресурса). + +Ресурс должен содержать следующие параметры для хранения данных о шаблонных репозиториях: + +- **Параметр "URL"** типа URL — используется для хранения URL-адреса репозитория шаблона в GitLab. Этот параметр необходим для действий, которые работают с репозиторием шаблона. + +- **Параметр "ID репозитория"** типа Number — хранит внутренний ID репозитория в GitLab. Используется для действий, которые требуют указания ID проекта GitLab. + +- **Параметр "Последний тег"** типа String — содержит название последнего тега (версии) шаблона. Этот параметр используется автоматизацией для отслеживания появления новых версий шаблона. При каждом обновлении этого параметра источником данных автоматизация проверяет изменение и запускает обновление связанных сервисов. + +**Обратите внимание:** убедитесь, что идентификаторы параметров корректно указаны во всех действиях, автоматизациях и источниках данных, которые ссылаются на эти параметры. + +Если параметры отсутствуют, откройте ресурс на редактирование и добавьте их на вкладке «Параметры» ресурса, нажав кнопку `Добавить параметр`. + +### Ресурс «Сервисы» + +У вас должен быть создан второй ресурс для хранения информации о созданных сервисах. В рамках инструкции он называется `Сервисы`, но вы можете выбрать любое удобное для вас название. Если ресурса еще нет, [создайте его](#создание-ресурса). + +Ресурс должен содержать следующие параметры для хранения метаданных о созданных сервисах: + +- **Параметр "URL"** типа URL — ссылка на репозиторий сервиса в GitLab. Используется действиями для работы с репозиторием сервиса. + +- **Параметр "ID репозитория"** типа Number — внутренний ID репозитория в GitLab. Необходим для действий, которые требуют указания ID проекта GitLab. + +- **Параметр "Переменные использованные при шаблонизации"** типа YAML — содержит переменные, которые были применены при клонировании кода из шаблона в сервис. Эти переменные необходимы при обновлении сервиса из шаблона, так как они должны быть применены повторно для корректного рендеринга новых изменений из шаблона. + +- **Параметр "Ветка по умолчанию"** типа String — название основной ветки репозитория (например, `main` или `master`). Используется действием обновления сервиса для определения целевой ветки Merge Request. + +**Обратите внимание:** убедитесь, что идентификаторы параметров корректно указаны во всех действиях, автоматизациях и источниках данных, которые ссылаются на эти параметры. + +Если параметры отсутствуют, откройте ресурс на редактирование добавьте их на вкладке «Параметры» ресурса, нажав кнопку `Добавить параметр`. + +### Создание ресурса + +Для создания ресурсов перейдите в раздел `Каталог`. Создайте новый ресурс. Для этого в левом верхнем углу нажмите кнопку `Создать ресурс`. + +Откроется окно по созданию нового ресурса с различными вкладками. + +**Основная информация:** + +Заполните следующие поля на вкладке "Основная информация": + +- **Название**: [Укажите название ресурса] + +- **Владелец**: [Укажите владельца] + +- **Команда владелец**: [Укажите команду владелец] + +**Параметры:** + +Перейдите на вкладку «Параметры» и добавьте требуемые параметры ресурса. Для добавления нового параметра нажмите кнопку `Добавить параметр`. + +Пример требуемых параметров: + +**Шаблоны:** + +| Название | Идентификатор | Описание | Тип | +|----------------|---------------------|-------------------------------------------|--------| +| URL | web_url | Ссылка на репозиторий сервиса | URL | +| ID репозитория | project_id | Внутренний ID репозитория в GitLab | Number | +| Последний тег | repository_last_tag | Последний созданный тег в git репозитории | String | + +**Сервисы:** + +| Название | Идентификатор | Описание | Тип | +|--------------------------------------------|---------------------|----------------------------------------------------------------|--------| +| URL | web_url | Ссылка на репозиторий сервиса | URL | +| ID репозитория | project_id | Внутренний ID репозитория в GitLab | Number | +| Переменные использованные при шаблонизации | template_values | Переменные, которые были применены при клонировании из шаблона | YAML | +| Ветка по умолчанию | default_branch | Название основной ветки репозитория | String | + +### Связь + +> **Связи** позволяют установить зависимость между ресурсами и обеспечивают возможность автоматического нахождения всех сервисов, связанных с конкретным шаблоном. + +У вас должна быть настроена связь, которая отражает зависимость между шаблонами и созданными из них сервисами. Если связи еще нет, [создайте её](#создание-связи). + +Связь должна быть настроена следующим образом: + +- **Родительский ресурс**: выбран ресурс, хранящий информацию о шаблонах + +- **Дочерний ресурс**: выбран ресурс, хранящий информацию о сервисах + +### Создание связи + +Для создания связи нажмите кнопку `Создать связь` в левом верхнем углу раздела «Каталог». + +Откроется окно по созданию новой [связи](../../user/catalog/#связи). Заполните данные согласно таблице ниже: + +| Параметр | Значение | +|---------------------|------------------------------------------------------| +| Название | [Введите название связи, например `Шаблоны-Сервисы`] | +| Родительский ресурс | [Выберите название ресурса с шаблонами] | +| Дочерний ресурс | [Выберите название ресурса с сервисами] | + +## Источник данных + +> **[Источник данных](../datasources/overview/)** — механизм DDP, который позволяет синхронизировать информацию из внешних инфраструктурных сервисов (например, GitLab) в каталог платформы. Источники данных периодически опрашивают внешние системы, получают актуальную информацию и обновляют соответствующие сущности в каталоге. + +У вас должен быть настроен источник данных, который автоматически получает информацию об актуальном состоянии шаблонов из GitLab. Если источника данных еще нет, [создайте его](#создание-источника-данных). + +Проверьте следующие настройки: + +**Основная информация:** + + **Ресурс**: выбран ресурс "Шаблоны" (или соответствующий ресурс, если он назван иначе) + +**Backend:** + +На вкладке «Backend» проверьте подключение к GitLab, а именно, что происходит автоматическая синхронизация: + +- **Периодическая синхронизация**: должна быть включена, для автоматического обновления информации о шаблонах при их изменении в GitLab + +- **Периодичность запуска**: должно быть указано расписание в формате CRON (например, `1 * * * *` для запуска каждый час). Расписание определяет, как часто источник данных будет проверять наличие новых тегов в репозиториях шаблонов + +**Параметры:** + +В параметрах должны быть заданы следующие ключи: + +| Ключ | Значение | Описание | +|-----------|-------------------------|---------------------------------------------------------------------| +| group_ids | [ID группы с шаблонами] | Указано ID группы GitLab, в которой находятся шаблонные репозитории | +| tags | true | Включено получение информации о тегах для каждого репозитория | + +[Подробнее](../datasources/types/#gitlabprojects) о доступных параметрах. + +**Правила:** + +**Правила обновления:** + +Настройте правила обновления параметров ресурса "Шаблоны" данными, полученными из GitLab: + +- **Параметр "URL"**: необходимо хранить URL репозитория шаблона в GitLab. В качестве источника должен использоваться `{{ .web_url }}`. + +- **Параметр "ID репозитория"**: необходимо хранить внутренний ID репозитория в GitLab. В качестве источника должен использоваться `{{ .id }}`. + +- **Параметр "Последний тег"**: необходимо хранить последний тег git репозитория (в рамках данной инструкции используется как версия шаблона). Используется источник `{{ ( index ( .ddp_repository_tags ) 0 ).name }}`. Данное выражение получает последний тег, созданный в git репозитории, беря первый элемент из массива тегов. Этот параметр критически важен для работы автоматизации, так как изменение его значения является триггером для обновления сервисов. + + - **Примечание**: данный способ получения версии шаблона является лишь примером, а не строгой необходимости. При необходимости способ получения тега можно настроить удобным для вас способом. + +**Примечание**: идентификаторы источников берутся из спецификации [Projects API GitLab](https://docs.gitlab.com/api/projects/#get-a-single-project). + +### Создание источника данных + +Для создания [источников данных](../datasources/overview/) перейдите в раздел `Самообслуживание` в пункт `Источники данных`. В правом верхнем углу нажмите кнопку `Создать`. + +Откроется окно по созданию нового [источника данных](../datasources/overview/) с различными вкладками. + +**Основная информация:** + +- **Название**: укажите название источника данных (например, `Шаблоны сервисов`) + +- **Ресурс**: выберите ресурс, который содержит информацию о шаблонах. + +- **Владелец**: назначьте владельца источника данных + +- **Команда владелец**: укажите команду, ответственную за источник данных + +**Backend:** + +На вкладке «Backend» настройте подключение к GitLab: + +- **Backend**: указывает встроенный тип источника данных. Необходим `GitlabProjects` для работы с проектами GitLab + +- **Периодическая синхронизация**: включите автоматический запуск синхронизации, для автоматического обновления информации о шаблонах при их изменении в GitLab + +- **Периодичность запуска**: укажите расписание в формате CRON (например, `1 * * * *` для запуска каждый час). Расписание определяет, как часто источник данных будет проверять наличие новых тегов в репозиториях шаблонов + +- **URL**: укажите URL вашего экземпляра GitLab (например, `https://gitlab.example.com`) + +**Параметры:** + +Настройте параметры запроса к GitLab API: + +| Ключ | Значение | Описание | +|-----------|-------------------------|---------------------------------------------------------------------| +| group_ids | [ID группы с шаблонами] | Укажите ID группы GitLab, в которой находятся шаблонные репозитории | +| tags | true | Включает получение информации о тегах для каждого репозитория | + +[Подробнее](../datasources/types/#gitlabprojects) о доступных параметрах. + +**Правила:** + +На вкладке «Правила» настройте логику создания и обновления сущностей: + +- **Создание новых сущностей**: включите создание новых сущностей. DDP автоматически будет создавать записи о новых шаблонах, если шаблонный репозиторий обнаружен в GitLab, но еще не существует в каталоге + +- **Владелец создаваемых сущностей**: назначьте владельца для новых сущностей + +- **Команда владелец создаваемых сущностей**: укажите команду-владельца для новых сущностей + +**Правила создания:** + +Настройте правила для создания идентификатора и названия новой сущности в платформе: + +- **Идентификатор**: идентификатор создаваемой сущности. Например, можно использовать выражение `{{ replaceChar .path_with_namespace "/" "-" }}` + + - **Примечание**: является лишь примером, а не строгой необходимостью. Данное выражение преобразует путь с пространством имен (`.path_with_namespace` из спецификации [Projects API GitLab](https://docs.gitlab.com/api/projects/#get-a-single-project)), заменяя слэши на дефисы для получения уникального ID. + +- **Название**: название создаваемой сущность. Например, можно использовать выражение `{{ .name }}` + + - **Примечание**: является лишь примером, а не строгой необходимостью. Данное выражение использует название из GitLab (`.name` из спецификации [Projects API GitLab](https://docs.gitlab.com/api/projects/#get-a-single-project)) + +**Примечание**: При необходимости вы можете задать свои собственные правила на основе Go Template. + +**Правила сопоставления:** + +Настройте правила сопоставления уже существующих сущностей при синхронизации: + +- **Идентификатор**: идентификатор сущности, которую необходимо обновить. Например, можно использовать выражение `{{ replaceChar .path_with_namespace "/" "-" }}` + + - **Примечание**: является лишь примером, а не строгой необходимостью. Данное выражение преобразует путь с пространством имен (`.path_with_namespace` из спецификации [Projects API GitLab](https://docs.gitlab.com/api/projects/#get-a-single-project)), заменяя слэши на дефисы для получения уникального ID. + +- **Название**: название сущности, которую необходимо обновить. Например, можно использовать выражение `{{ .name }}` + + - **Примечание**: является лишь примером, а не строгой необходимостью. Данное выражение использует название из GitLab (`.name` из спецификации [Projects API GitLab](https://docs.gitlab.com/api/projects/#get-a-single-project)). + +**Примечание**: При необходимости вы можете задать свои собственные правила на основе Go Template. Если не планируется вручную создавать сущности ресурса, рекомендуется использовать одинаковые правила для сопоставления и создания. + +**Правила обновления:** + +Настройте правила обновления параметров ресурса "Шаблоны" данными, полученными из GitLab: + +- **Параметр "URL"**: в качестве значения используется URL репозитория шаблона в GitLab. В качестве источника используйте `{{ .web_url }}`. + +- **Параметр "ID репозитория"**: в качестве значения используется внутренний ID репозитория в GitLab. В качестве источника используйте `{{ .id }}`. + +- **Параметр "Последний тег"**: в качестве значения используется тег git репозитория. Используйте источник `{{ ( index ( .ddp_repository_tags ) 0 ).name }}`. Данное выражение получает последний тег, созданный в git репозитории, беря первый элемент из массива тегов. Этот параметр критически важен для работы автоматизации, так как изменение его значения является триггером для обновления сервисов. + + - **Примечание**: данный способ получения версии шаблона является лишь примером, а не строгой необходимости. При необходимости способ получения тега можно настроить удобным для вас способом. + +**Примечание**: идентификаторы источников берутся из спецификации [Projects API GitLab](https://docs.gitlab.com/api/projects/#get-a-single-project). + +**Авторизация:** + +На вкладке «Авторизация» настройте заголовки и учетные данные, необходимые для подключения к GitLab: + +Настройте учетные данные: + +- **Идентификатор**: `token` + +- **Реквизиты**: укажите реквизиты, которые содержат токен GitLab с необходимыми правами доступа к репозиториям. Токен должен иметь права на чтение проектов и информации о тегах в указанной группе GitLab + +Так же необходимо настроить заголовок: + +- **Ключ**: `Private-Token` + +- **Значение**: `{{ .credentials.token }}` — используется значение, которое было настроено для учётных данных. Если в качестве идентификатора учётных данных используется не `token`, необходимо заменить `token` на заданное вами. + +[Подробнее](../datasources/types/#gitlabprojects) о доступных заголовках и [учетной записи для запуска](../datasources/overview/#учетная-запись-для-запуска). + +## Создание действий + +> **Действия** — механизм DDP, который позволяет пользователям платформы взаимодействовать с внешними инфраструктурными сервисами через API. Действия могут создавать проекты в GitLab, создавать секреты в системах управления секретами, развертывать приложения и выполнять другие операции. + +Необходимо настроить три действия, которые будут отвечать за создание сервиса из шаблона и их обновление в случае выпуска новых версий шаблона. + +### Действие "Создать проект в GitLab" + +У вас должно быть создано действие, которое отвечает за инициализацию нового проекта в GitLab. Это действие запускается первым при создании нового сервиса для создания проекта в GitLab, в который будет помещен созданный из шаблона сервис. Если действия еще нет, [создайте его](#создание-действия). + +Проверьте, что действие содержит следующие настройки: + +**Основная информация:** + +- **Ресурс**: выбран ресурс, который содержит информацию о сервисах. + +**Обновление сущности:** + +На вкладке «Обновление сущности» активирована опция `Обновление параметров сущности` и настроены правила обновления, которые записывают ID, URL и ветку по умолчанию только что созданного проекта в сущность, для которой запускалось действие: + +> Ниже указаны примеры названий параметров сущности. В поле `параметр сущности` необходимо указывать идентификатор соответствующего параметра ресурса, который хранит информацию о сервисах. + +- **Параметр "ID репозитория"** используется источник `{{ .response.id }}` — сохраняет ID созданного проекта из ответа GitLab API в параметр сущности + +- **Параметр "URL"**: используется источник `{{ .response.web_url }}` — сохраняет URL проекта в GitLab созданного проекта в параметр сущности + +- **Параметр "Ветка по умолчанию"**: используется источник `{{ .response.default_branch }}` — сохраняет название ветки по умолчанию в параметр сущности + +**Примечание**: идентификаторы источников (`id`, `web_url`, `default_branch`) берутся из спецификации [Projects API GitLab](https://docs.gitlab.com/api/projects/#get-a-single-project). + +### Действие "Создать репозиторий из шаблона" + +У вас должно быть создано действие для клонирования кода из шаблонного репозитория в новый репозиторий сервиса с применением переменных шаблонизации. Это действие будет запускаться после создания проекта в GitLab и заполнять его кодом из шаблона. Если действия еще нет, [создайте его](#создание-действия). + +Проверьте, что действие содержит следующие настройки: + +**Основная информация:** + +- **Ресурс**: выбран ресурс, который содержит информацию о сервисах (действие запускается для сущности сервиса, который нужно обновить). + +**Пользовательская форма:** + +Проверьте наличие следующих полей в пользовательской форме: + +- **Параметр "Идентификатор шаблонного репозитория"** с идентификатором `template_ddp_slug` (или другим, если это необходимо) типа Entities — будет автоматически подставляться идентификатор сущности шаблона внутри DDP, из которого будет клонироваться код. В дополнительных настройках укажите: **Ресурс:** "Шаблоны" (или соответствующий ресурс), **Связь:** "Шаблоны-Сервисы" (или название вашей связи), **Поле:** "Идентификатор". Это позволяет выбрать нужный шаблон из связанных сущностей. Данный параметр можно сделать скрытым + +**Обновление сущности:** + +На вкладке «Обновление сущности» активирована опция `Обновление параметров сущности` и настроено сохранение переменных, использованных при шаблонизации, обратно в сущность, для которой запускалось действие: + +> Ниже указан пример названия параметра сущности. В поле `параметр сущности` необходимо указывать идентификатор соответствующего параметра ресурса, который хранит информацию о сервисах. + +- **Параметр "Переменные использованные при шаблонизации"**: используйте источник `{{ toYAML .response.values.merged }}` — данное выражение сохраняет переменные в формате YAML. Эти переменные критически важны для будущего обновления сервиса из шаблона, так как они должны быть применены повторно. Данные получены в качестве ответа на успешное выполнение действия. + +Активирована опция `Создание связей сущностей`, чтобы действие автоматически устанавливало связь между созданным сервисом и его шаблоном: + +- **Ресурс**: выбран ресурс "Сервисы" (или соответствующий ресурс, если он назван иначе) + +- **Связь**: выбрана связь "Шаблоны-Сервисы" (или название вашей связи, если оно отличается) + +- **Идентификатор родительской сущности**: используйте `{{ .property.template_ddp_slug }}` — идентификатор шаблона из параметра действия + - **Важно**: если идентификатор параметра не `template_ddp_slug`, замените на корректный + +- **Идентификатор дочерней сущности**: оставьте пустым — будет использована текущая сущность, для которой запускается действие + +### Действие "Обновление сервиса из шаблона" + +У вас должно быть создано действие, которое будет использоваться в автоматизации для создания нового Merge Request в репозиторий сервиса. Этот MR будет содержать изменения из новой версии (нового тега) связанного шаблона. Если действия еще нет, [создайте его](#создание-действия). + +Проверьте, что действие содержит следующие настройки: + +**Основная информация:** + +- **Ресурс**: выбран ресурс, который содержит информацию о сервисах. + +**Пользовательская форма:** + +Проверьте наличие следующих полей в пользовательской форме: + +- **Параметр "Переменные используемые при шаблонизации"** с идентификатором `template_values` (или другим, если это необходимо) типа String — он хранит переменные, которые были использованы при изначальной шаблонизации (хранятся в параметре сущности). Значение по умолчанию: `{{ .entity.properties.template_values }}` — использует сохраненные переменные из параметра сущности. Важно: если параметр называется иначе (например, `template_vars`), используйте соответствующий идентификатор + +- **Параметр "Версия"** с идентификатором `version` (или другим, если это необходимо) типа Entities — получает значение нового тега (версии) из сущности шаблона. В дополнительных настройках укажите: **Ресурс:** "Шаблоны" (или соответствующий ресурс, если он назван иначе), **Связь:** "Шаблоны-Сервисы" (или название вашей связи), **Поле:** "Параметр", **Параметр:** "Последний тег" (или аналогичный) + +- **Параметр "Обновляемый репозиторий"** с идентификатором `target_project_id` (или другим, если это необходимо) типа String — это ID репозитория сервиса в GitLab, в который создается MR. Значение по умолчанию: `{{ .entity.properties.project_id }}` — использует ID проекта из параметра сущности. Если идентификатор (`project_id`) параметра, который хранит внутренний ID проекта в GitLab в ресурсе называется иначе, используйте соответствующий идентификатор + +- **Параметр "Шаблонный репозиторий"** с идентификатором `source_project_id` (или другим, если это необходимо) типа Entities — это ID репозитория шаблона в GitLab. В дополнительных настройках укажите: **Ресурс:** "Шаблоны" (или соответствующий ресурс, если он назван иначе), **Связь:** "Шаблоны-Сервисы" (или название вашей связи), **Поле:** "Параметр", **Параметр:** "ID репозитория" (или аналогичный) + +- **Параметр "Ветка обновляемого репозитория"** с идентификатором `target_repo_branch` (или другим, если это необходимо) типа String — это основная ветка репозитория сервиса (например, `master` или `main`), куда будет направлен MR. При необходимости можете указать любую другую. Значение по умолчанию: `{{ .entity.properties.default_branch }}` — использует ветку по умолчанию из параметра сущности. Если идентификатор параметра (`default_branch`) называется иначе, используйте соответствующий идентификатор + +**Backend:** + +**Тело запроса:** + +> В качестве идентификаторов используется те, которые предлагались выше. Если были заданы другие, необходимо так же изменить их ниже в теле запроса + +Тело запроса должно быть настроено примерно таким образом: + +```yaml +merge_request_spec: + source_branch: update-to-{{ .version }} + target_branch: {{ .target_repo_branch }} + title: update-to-{{ .version }} +source_project_tag: {{ .version }} +source_project_id: "{{ .source_project_id }}" +target_project_id: "{{ .target_project_id }}" +values: {{ .template_values | nindent 4 }} +``` + +В теле запроса: + +- `source_branch` — название ветки, содержащая изменения. В качестве примера, используется ветка с названием, включающим версию тега +- `target_branch` — целевая ветка сервиса, куда будет направлен MR +- `title` — заголовок MR с указанием версии +- `source_project_tag` — тег версии шаблона, из которого берутся изменения +- `source_project_id` и `target_project_id` — ID репозиториев шаблона и сервиса +- `values` — переменные шаблонизации применяются повторно для корректного рендеринга изменений + +[Подробнее](../actions/types/#creategitlabmergerequest) о настройках встроенного бэкенда. + +### Создание действия + +Для создания [действия](../actions/overview/) перейдите в раздел `Самообслуживание` пункт `Действия`. Создайте новое действие. Для этого нажмите справа вверху кнопку `Создать`. Откроется окно по созданию нового [действия](../actions/overview/) с различными вкладками. + +Откроется окно по созданию нового действия с различными вкладками. + +**Вкладка «Основная информация»:** + +Заполните следующие поля на вкладке "Основная информация": + +- **Название**: [Укажите название действия] + +- **Ресурс**: выберите ресурс "Сервисы" (или соответствующий ресурс, если он назван иначе) + +- **Владелец**: [Укажите владельца] + +- **Команда владелец**: [Укажите команду владелец] + +**Пользовательская форма:** + +На вкладке «Пользовательская форма» настройте поля для заполнения при запуске действия. Параметры, которые необходимо настроить зависят от действия, которое вы создаёте: + +**Действие "Создать проект в GitLab":** + +- **Параметр "Название"** с идентификатором `name` (или иным при необходимости) типа String — это название нового проекта. Значение по умолчанию: `{{ .entity.name }}` — использует название сущности в DDP + +- **Параметр "Путь"** с идентификатором `path` (или иным при необходимости) типа String — это URL-путь до репозитория в GitLab. Значение по умолчанию: `{{ .entity.slug }}` — использует идентификатор сущности в DDP + +- **Параметр "Группа репозиториев"** с идентификатором `group` (или иным при необходимости) типа String — ID группы GitLab, где будет создан сервис. Значение по умолчанию: укажите ID группы в GitLab, в котором необходимо создать проект + +**Действие "Создать репозиторий из шаблона":** + +- **Параметр "Идентификатор шаблонного репозитория"** с идентификатором `template_ddp_slug` (или иным при необходимости) типа Entities — это идентификатор сущности шаблона внутри DDP, из которого будет клонироваться код. В дополнительных настройках укажите: **Ресурс:** "Шаблоны" (или соответствующий ресурс), **Связь:** "Шаблоны-Сервисы" (или название вашей связи), **Поле:** "Идентификатор". Это позволяет выбрать нужный шаблон из связанных сущностей + +- **Параметр "URL сервисного репозитория"** с идентификатором `service_git_url` (или иным при необходимости) типа URL — это URL репозитория, в который будет помещен отрендеренный шаблон. Значение по умолчанию: `{{ .entity.properties.web_url }}` — использует URL сущности сервиса из каталога. Если параметр URL в ресурсе называется иначе, используйте соответствующий идентификатор (например, `{{ .entity.properties.service_url }}`) + +- **Параметр "URL шаблонного репозитория"** с идентификатором `template_git_url` (или иным при необходимости) типа Entities — это URL репозитория шаблона, который используется бэкендом для клонирования. В дополнительных настройках укажите: **Ресурс:** "Шаблоны" (или соответствующий ресурс), **Связь:** "Шаблоны-Сервисы" (или название вашей связи), **Поле:** "Параметр", **Параметр:** "URL" (или иной аналогичный, в зависимости от ваших настроек) + +> Дополнительные параметры зависят от вашего шаблона и должны быть настроены в соответствии с переменными, используемыми в шаблоне. + +**Действие "Обновление сервиса из шаблона":** + +Необходимо настроить поля для сбора данных, которые нужны бэкенду для создания Merge Request. Эти данные будут автоматически заполняться из сущностей ресурса "Сервисы" или связанной с ним сущности из ресурса "Шаблоны": + +- **Параметр "Переменные используемые при шаблонизации"** с идентификатором `template_values` (или иным при необходимости) типа String — это переменные, которые были использованы при изначальной шаблонизации (хранятся в параметре сущности). Значение по умолчанию: `{{ .entity.properties.template_values }}` — использует сохраненные переменные из параметра сущности. Важно: если параметр называется иначе (например, `template_vars`), используйте соответствующий идентификатор + +- **Параметр "Версия"** с идентификатором `version` (или иным при необходимости) типа Entities — получает значение нового тега (версии) из сущности шаблона. В дополнительных настройках укажите: **Ресурс:** "Шаблоны" (или соответствующий ресурс), **Связь:** "Шаблоны-Сервисы" (или название вашей связи), **Поле:** "Параметр", **Параметр:** "Последний тег" (или аналогичный). + +- **Параметр "Обновляемый репозиторий"** с идентификатором `target_project_id` (или иным при необходимости) типа String — это внутренний ID репозитория сервиса в GitLab, в который создается MR. Значение по умолчанию: `{{ .entity.properties.project_id }}` — использует ID проекта из параметра сущности. Если параметр ID в ресурсе называется иначе, используйте соответствующий идентификатор + +- **Параметр "Шаблонный репозиторий"** с идентификатором `source_project_id` (или иным при необходимости) типа Entities — это внутренний ID репозитория шаблона в GitLab. В дополнительных настройках укажите: **Ресурс:** "Шаблоны" (или соответствующий ресурс), **Связь:** "Шаблоны-Сервисы" (или название вашей связи), **Поле:** "Параметр", **Параметр:** "ID репозитория" (или аналогичный) + +- **Параметр "Ветка обновляемого репозитория"** с идентификатором `target_repo_branch` (или иным при необходимости) типа String — основная ветка репозитория сервиса (например, `master` или `main`), куда будет направлен MR. Значение по умолчанию: `{{ .entity.properties.default_branch }}` — использует ветку по умолчанию из параметра сущности. Если идентификатор параметра называется иначе, используйте свой + +**Backend:** +> В качестве идентификаторов используется те, которые предлагались выше. Если были заданы другие, необходимо так же изменить их ниже в теле запроса + +На вкладке «Backend» настройте логику выполнения действия. Логика зависит от настраиваемого действия. + +**Действие "Создать проект в GitLab":** + +- **Тип**: выберите `BuiltIn` для использования встроенного бэкенда + +- **Встроенный backend**: выберите `CreateGitlabProject` для создания проекта в GitLab + +- **URL**: укажите URL вашего экземпляра GitLab (например, `https://gitlab.example.com`) + +**Тело запроса:** + +```yaml +initialize_with_readme: false +name: '{{ .name }}' +namespace_id: '{{ .group }}' +path: '{{ .path }}' +``` + +Это тело запроса передает в GitLab API название проекта, ID группы и путь репозитория. Подробнее о настройках в [документации](../actions/types/#creategitlabproject). + +**Действие "Создать репозиторий из шаблона":** + +- **Тип**: выберите `BuiltIn` для использования встроенного бэкенда + +- **Встроенный backend**: выберите `CreateRepositoryFromTemplate` для создания репозитория из шаблона + +- **URL**: укажите URL вашего экземпляра GitLab (например, `https://gitlab.example.com`) + +**Тело запроса:** + +```yaml +sourceBranch: "master" +templateRepositoryUrl: "{{ .template_git_url }}" +targetRepositoryUrl: "{{ .service_git_url }}" +values: + зависит от шаблона +``` + +В теле запроса: + +- `sourceBranch` — ветка в репозитории шаблона, из которой будет клонироваться код (обычно `master` или `main`) + +- `templateRepositoryUrl` — URL шаблонного репозитория из параметра действия + +- `targetRepositoryUrl` — URL целевого репозитория сервиса + +- `values` — блок должен содержать пары ключ-значение, которые будут использованы для замены переменных в файлах шаблона. Формат и состав этих переменных полностью зависит от того, как настроен ваш шаблон + +Подробнее о настройках в [документации](../actions/types/#createrepositoryfromtemplate). + +**Действие "Обновление сервиса из шаблона":** + +- **Тип**: выберите `BuiltIn` для использования встроенного бэкенда + +- **Встроенный backend**: выберите `CreateGitlabMergeRequest` для создания Merge Request в GitLab + +- **URL**: укажите URL вашего экземпляра GitLab (например, `https://gitlab.example.com`) + +**Тело запроса:** + +```yaml +merge_request_spec: + source_branch: update-to-{{ .version }} + target_branch: {{ .target_repo_branch }} + title: update-to-{{ .version }} +source_project_tag: {{ .version }} +source_project_id: "{{ .source_project_id }}" +target_project_id: "{{ .target_project_id }}" +values: {{ .template_values | nindent 4 }} +``` + +В теле запроса: + +- `source_branch` — создается новая ветка с названием, включающим версию тега + +- `target_branch` — целевая ветка сервиса, куда будет направлен MR + +- `title` — заголовок MR с указанием версии + +- `source_project_tag` — тег версии шаблона, из которого берутся изменения + +- `source_project_id` и `target_project_id` — ID репозиториев шаблона и сервиса + +- `values` — переменные шаблонизации применяются повторно для корректного рендеринга изменений + +Подробнее о настройках в [документации](../actions/types/#creategitlabmergerequest). + +**Обновление сущности:** + +**Обновление параметров сущности:** + +Для действий "Создать проект в GitLab" и "Создать репозиторий из шаблона" необходимо активировать опцию `Обновление параметров сущности` и настроить правила обновления, которые запишут некоторую информацию (зависит от действия) в сущность, для которой запускалось действие. +Дополнительно необходимо настроить правила обновления сущности. Правила обновления сущности зависят от настраиваемого действия. + +**Действие "Создать проект в GitLab":** +> Используйте идентификаторы соответствующих параметров ресурса + +- **Параметр "ID репозитория"**: используйте источник `{{ .response.id }}` — сохраняет ID созданного проекта из ответа GitLab API + +- **Параметр "URL"**: используйте источник `{{ .response.web_url }}` — сохраняет URL созданного проекта + +- **Параметр "Ветка по умолчанию"**: используйте источник `{{ .response.default_branch }}` — сохраняет название ветки по умолчанию + +**Примечание**: идентификаторы источников (`id`, `.web_url`, `.default_branch`) берутся из спецификации [Projects API GitLab](https://docs.gitlab.com/api/projects/#get-a-single-project). + +**Действие "Создать репозиторий из шаблона":** +> Используйте идентификатор соответствующего параметров ресурса + +- **Параметр "Переменные использованные при шаблонизации"**: используйте источник `{{ toYAML .response.values.merged }}` — данное выражение сохраняет переменные в формате YAML. Эти переменные критически важны для будущего обновления сервиса из шаблона, так как они должны быть применены повторно. Данные получены в качестве ответа на успешное выполнение действия. + +**Создание связей сущностей:** + +Для действия "Создать репозиторий из шаблона" так же должна быть активирована опция `Создание связей сущностей`, чтобы действие автоматически устанавливало связь между созданным сервисом и его шаблоном: + +- **Ресурс**: выберите "Сервисы" (или соответствующий ресурс, если он назван иначе) + +- **Связь**: выберите связь "Шаблоны-Сервисы" (или название вашей связи, если оно отличается) + +- **Идентификатор родительской сущности**: используйте `{{ .property.template_ddp_slug }}` — идентификатор шаблона из параметра действия + + - **Важно**: если идентификатор параметра не `template_ddp_slug`, замените на корректный + +- **Идентификатор дочерней сущности**: оставьте пустым — будет использована текущая сущность, для которой запускается действие + +**Безопасность:** + +На вкладке «Безопасность» настройте учетные данные для выполнения действия. Настройки зависят от действия. + +**Действие "Создать проект в GitLab":** + +- **Идентификатор**: `token` + +- **Реквизиты**: укажите реквизиты, которые содержат токен GitLab с необходимыми правами доступа для создания проектов в указанной группе + +**Действие "Создать репозиторий из шаблона":** + +- **Идентификатор**: `password` — реквизиты, которые содержат пароль (токен) GitLab с необходимыми правами доступа к репозиториям + +- **Идентификатор**: `username` — реквизиты, которые содержат GitLab username + +**Действие "Обновление сервиса из шаблона":** + +- **Идентификатор**: `password` — реквизиты, которые содержат пароль (токен) GitLab с необходимыми правами доступа к репозиториям + +- **Идентификатор**: `username` — реквизиты, которые содержат GitLab username + +## Процесс + +> **Процессы** — механизм автоматизации сложных бизнес-процессов, который позволяет создавать визуальные схемы выполнения действий с поддержкой последовательного или параллельного выполнения. Процессы объединяют несколько действий в единую цепочку выполнения. + +У вас должен быть создан процесс, который объединяет действия по созданию проекта в GitLab и создания сервиса из шаблона в единую последовательную автоматизированную цепочку. Процесс должен последовательно запускать создание проекта в GitLab, а затем создание репозитория из шаблона. Если процесса еще нет, [создайте его](#создание-процесса). + +Проверьте следующие настройки: + +**Основная информация:** + + **Ресурс**: выбран ресурс "Сервисы" (или соответствующий ресурс, если он назван иначе) + +**Конфигурация:** + +> Названия действий могут отличаться в зависимости от ваших настроек + +Действия находится в следующей последовательности: + +1. Start +2. Создать проект в GitLab +3. Создать репозиторий из шаблона +4. End + +### Создание процесса + +Для создания процесса перейдите в раздел `Самообслуживание` пункт `Процессы`. Создайте новый процесс. Для этого справа вверху нажмите кнопку `Создать`. + +Откроется окно по созданию нового процесса с различными вкладками. + +**Основная информация:** + +- **Название**: [Укажите название ресурса] + +- **Ресурс**: выберите ресурс "Сервисы" (или соответствующий ресурс, если он назван иначе) + +- **Владелец**: [Укажите владельца] + +- **Команда владелец**: [Укажите команду владелец] + +**Конфигурация:** +> Названия задач и названия действий указываются в качестве примера. При необходимости укажите ваши + +На вкладке «Конфигурация» настройте шаги процесса и их порядок выполнения: + +1. Добавьте элемент типа "Задача" с названием "Создать проект в GitLab" и выберите действие "Создать проект в GitLab" для запуска +2. Добавьте элемент типа "Задача" с названием "Создать репозиторий из шаблона" и выберите действие "Создать репозиторий из шаблона" для запуска +3. Добавьте элемент типа "Конец" для завершения процесса + +После добавления всех элементов настройте последовательность выполнения: + +1. Start +2. Создать проект в GitLab +3. Создать репозиторий из шаблона +4. End + +## Автоматизация + +> **Автоматизации** — механизм реагирования платформы на изменения спецификации сущностей. Автоматизации подписываются на события обновления сущностей ресурсов по определенным правилам (триггерам) и запускают выполнение действий, процессов или синхронизацию источников данных. + +У вас должна быть настроена автоматизация, которая запускает действие по созданию Merge Request для обновления сервисов при появлении новой версии шаблона. Автоматизация отслеживает изменения параметра "Последний тег" (или аналогичный) в сущностях ресурса "Шаблоны" (или аналогичный) и при обнаружении нового тега автоматически запускает действие "Обновление сервиса из шаблона" (или аналогичный) для всех связанных сервисов. Если автоматизации еще нет, [создайте её](#создание-автоматизации). + +Проверьте следующие настройки: + +**Конфигурация:** + +**Триггеры:** + +- **Ресурс**: выбран "Шаблоны" (или соответствующий ресурс, если он назван иначе) + +- **Условие**: указано `{{ ne .entity.properties.repository_last_tag "v1.0.0" }}` (или аналогичное, если проерка у вас настроена иначе) + +> **Примечание:** данное условие срабатывает каждый раз, когда параметр с идентификатором `repository_last_tag` в сущности ресурса "Шаблоны" (или аналогичным) не равен указанному значению ("v1.0.0"). Условие будет проверяться только один раз при изменении параметра `repository_last_tag`. Важно: если параметр "Последний тег" (или аналогичный) имеет другой идентификатор (например, `last_tag`), используйте его в условии: `{{ ne .entity.properties.last_tag "v1.0.0" }}` + +**Execution:** + +- **Executor**: выбрано "Действия" + +- **Сущность**: выбрано действие "Обновление сервиса из шаблона" (или соответствующее действие, если оно названо иначе) + +**Запускать execution для связанных ресурсов:** + +`Запускать execution для связанных ресурсов` - данный параметр включен и настроены связи ресурса: + +- **Ресурс**: выбрано "Шаблоны" (или соответствующий ресурс) + +- **Связь**: выбрана связь "Шаблоны-Сервисы" (или название вашей связи, если оно отличается) + +### Создание автоматизации + +Для создания [автоматизации](../automations) перейдите в раздел `Самообслуживание` пункт `Автоматизации`. Создайте автоматизацию. Для этого нажмите справа вверху кнопку `Создать`. + +Откроется окно по созданию новой автоматизации с различными вкладками. + +**Основная информация:** + +- **Название**: [Укажите название автоматизации] + +- **Владелец**: [Укажите владельца] + +- **Команда владелец**: [Укажите команду владелец] + +**Конфигурация:** + +На вкладке «Конфигурация» настройте логику запуска автоматизации. + +**Триггеры:** + +Триггер определяет, когда автоматизация должна запускаться. Добавьте новый триггер: + +- **Ресурс**: выберите "Шаблоны" (или соответствующий ресурс, если он назван иначе) + +- **Условие**: укажите `{{ ne .entity.properties.repository_last_tag "v1.0.0" }}`. **Важно:** используется идентификатор параметра ресурса "Шаблоны" (или аналогичного), который хранит информацию о последнем теге git репозитория. Если идентификатор отличается, используйте корректный. + +Данное условие срабатывает каждый раз, когда параметр `repository_last_tag` в сущности ресурса "Шаблоны" (или аналогичном) не равен указанному значению ("v1.0.0"). Условие будет проверяться только один раз при изменении параметра `repository_last_tag`. Важно: если параметр "Последний тег" имеет другой идентификатор (например, `last_tag`), используйте его в условии: `{{ ne .entity.properties.last_tag "v1.0.0" }}` + +> **Примечание:** если планируется создание нескольких автоматизаций, каждая из которых должна реагировать на изменения параметров сущностей одного и того же ресурса, рекомендуется указывать условие в формате `{{ and (ne .entity.properties.repository_last_tag "v1.0.0") (eq .entity.slug "example") }}` для того, чтобы дополнительно фильтровать, какая из автоматизаций будет запускаться в каждом конкретном случае. Без добавления условия `(eq .entity.slug "example")` каждая из автоматизаций будет реагировать на изменения каждой сущности. + +**Execution:** + +Настройте выполнение действия: + +- **Executor**: выберите "Действия" + +- **Сущность**: выберите действие "Обновление сервиса из шаблона" (или соответствующее действие, если оно названо иначе) + +**Запускать execution для связанных ресурсов:** + +Автоматизация просматривает изменения в сущности ресурса "Шаблоны", но действие будет обновлять сущности ресурса "Сервисы", которые связаны с шаблоном, в котором произошло обновление параметра `repository_last_tag`. + +Необходимо включить параметр `Запускать execution для связанных ресурсов` и настроить связи ресурса: + +- **Ресурс**: выберите "Шаблоны" (или соответствующий ресурс) + +- **Связь**: выберите связь "Шаблоны-Сервисы" (или название вашей связи, если оно отличается) + +При обновлении тега в ресурсе "Шаблоны" (или соответствующий ресурс) система найдет все связанные с этим шаблоном сущности ресурса "Сервисы" (или соответствующий ресурс) и запустит для каждой из них действие "Обновление сервиса из шаблона" (или аналогичное), создавая Merge Request с изменениями из новой версии шаблона. + +## Создание сервиса + +Настройка платформы для возможности создания сервисов на основе шаблона и последующим их автоматическим обновлением при выпуске новой версии шаблона завершена. + +Для создания сервиса необходимо следующее: + +1. Перейдите во вкладку `Каталог` в ресурс `Сервисы`. +2. В правом верхнем углу нажмите кнопку `Создать`. +3. В открывшемся окне во вкладке «Основная информация» заполните требуемые поля. Если настройки были произведены в соответствии с данной инструкцией, заполнение данных в других вкладках не требуются. Данные будут заполнены автоматически в дальнейшем. +4. Справа от появившейся записи о новом сервисе, нажмите на синюю кнопку с тремя вертикальными точками и выберите пункт `Запустить процесс`. +5. В выпадающем списке выберите процесс `Создание сервиса из шаблона`. +6. При необходимости заполните переменные шаблона и запустите процесс. +7. При корректных настройках сервис будет создан. При наличии обновлений шаблоны для сервиса будут формироваться MR с изменениями. Проверить корректность создания можно перейдя в него и открыв вкладку «Запуски действий». Все [действия](../actions/overview/) должны быть в статусе `Success`. diff --git a/content/documentation/admin/external-services.ru.md b/content/documentation/admin/external-services.ru.md new file mode 100644 index 0000000..0dc9b49 --- /dev/null +++ b/content/documentation/admin/external-services.ru.md @@ -0,0 +1,276 @@ +--- +title: Внешние сервисы +menuTitle: Внешние сервисы +d8Edition: ee +moduleStatus: experimental +--- + +Внешние сервисы — это механизм, позволяющий настраивать параметра авторизации для внешних инфраструктурных систем (например, GitLab, Kubernetes, DefectDojo и др.). + +Настройка внешних сервисов осуществляется в разделе `Администрирование → Внешние сервисы`. + +## Конфигурация + +Конфигурация внешнего сервиса включает следующие параметры: + +| Название параметра | Описание | +|------------------------------|-------------------------------------------------------------------------------------------------------------------------------| +| **Название** | Название внешнего сервиса — отображается в интерфейсе | +| **Идентификатор** | Уникальный человекочитаемый идентификатор (slug) | +| **Владелец** | Пользователь, ответственный за внешний сервис | +| **Команда владелец** | Команда, которой принадлежит внешний сервис | +| **URL** | Базовый URL для обращения к внешнему сервису | +| **Учётные данные** | Список доступных учетных данных (например, токенов), которые могут быть подставлены в запросы | +| **Заголовки** | HTTP-заголовки, автоматически добавляемые к запросам | +| **Отключить проверку SSL** | Отключить проверку SSL-сертификата внешнего сервиса (например, при использовании self-signed сертификатов) | +| **Системная учётная запись** | Учётная запись, которая будет использоваться для периодически запускаемых заданий: источников данных, проверок статуса и т.д. | + +## Использование внешних сервисов + +Внешние сервисы могут быть подключены к различным объектам платформы: + +- действиям +- виджетам +- источникам данных +- проверкам статуса сущностей + +Подключение сервиса выполняется на вкладке **"Авторизация"** в настройках соответствующего объекта. + +Для каждого объекта можно в явном виде переопределить параметры, заданные во внешнем сервисе. +Например, если внешний сервис содержит токен авторизации, но в конкретном действии используются другие учетные данные — можно указать альтернативные значения. В этом случае будет переопределён **только** указанный параметр, остальные значения будут взяты из конфигурации внешнего сервиса. + +## Особенности подключения к объектам + +### Действия + +- К одному действию можно подключить **несколько внешних сервисов**. +- Можно выбрать сервис **по умолчанию**. +- Параметр **системная учетная запись** не используется в действиях. +- При запуске действия можно выбрать, для какого внешнего сервиса оно будет запускаться. Если ни один сервис не выбран, будет использоваться сервис по умолчанию. Если сервис по умолчанию не задан, то будет использоваться первый внешний сервис в списке. + +### Виджеты + +- Для одного виджета также поддерживается подключение **нескольких внешних сервисов**. +- Один из них может быть выбран как **используемый по умолчанию**. +- В последующих релизах будет добавлена возможность изменения сервиса **во время просмотра** виджета. +- Параметр **системная учетная запись** не используется в виджетах. + +### Источники данных + +- Поддерживается подключение **только одного внешнего сервиса**. +- Если в сервисе задана **системная учётная запись**, она используется по умолчанию при синхронизации. + +### Проверки статуса + +- Проверке может быть назначен **один внешний сервис**. +- Если у него указана системная учётная запись — она используется при запуске автоматических проверок. + +## Заголовки авторизации для внешних сервисов + +При настройке внешних сервисов необходимо указать соответствующие HTTP-заголовки для авторизации. Ниже приведен список внешних сервисов, поддерживаемых платформой, с указанием типа авторизации и необходимых заголовков. + +### CodeScoring + +**Тип авторизации:** API Token + +**Заголовки:** + +| Заголовок | Формат значения | +|-----------|-----------------| +| `Authorization` | `<токен>` | + +**Пример:** + +```sh +Authorization: <ваш-api-token> +``` + +### DefectDojo + +**Тип авторизации:** API v2 Key Token + +**Заголовки:** + +| Заголовок | Формат значения | +|-----------|-----------------| +| `Authorization` | `Token <токен>` | + +**Пример:** + +```sh +Authorization: Token <ваш-defectdojo-api-v2-key> +``` + +Подробнее о том, как получить API v2 Key токен можно узнать в [официальной документации](https://docs.defectdojo.com/en/api/api-v2-docs/). + +### Docker Registry + +**Тип авторизации:** Basic Authentication + +**Заголовки:** + +| Заголовок | Формат значения | +|-----------|-----------------| +| `Authorization` | `Basic ` | + +**Пример:** + +1. Сформируйте строку `username:password` +2. Закодируйте её в Base64: `echo "username:password" | base64` +3. Добавьте заголовок: + +```sh +Authorization: Basic +``` + +### GitLab + +**Тип авторизации:** Personal Access Token или Project Access Token + +**Заголовки:** + +| Заголовок | Формат значения | +|-----------|-----------------| +| `Private-Token` | `<токен>` | + +**Пример:** + +```sh +Private-Token: <ваш-gitlab-token> +``` + +Подробнее о том, как получить GitLab token можно узнать в [официальной документации](https://docs.gitlab.com/api/rest/authentication/). + +### Harbor + +**Тип авторизации:** Basic Authentication + +**Заголовки:** + +| Заголовок | Формат значения | +|-----------|-----------------| +| `Authorization` | `Basic ` | + +**Пример:** + +1. Сформируйте строку `username:password` +2. Закодируйте её в Base64: `echo "username:password" | base64` +3. Добавьте заголовок: + +```sh +Authorization: Basic +``` + +### Kaiten + +**Тип авторизации:** API Token + +**Заголовки:** + +| Заголовок | Формат значения | +|-----------|-----------------| +| `Authorization` | `<токен>` | + +**Пример:** + +```sh +Authorization: <ваш-kaiten-api-token> +``` + +### Kubernetes + +**Тип авторизации:** Bearer Token (Service Account Token или User Token) + +**Заголовки:** + +| Заголовок | Формат значения | +|-----------|-----------------| +| `Authorization` | `Bearer <токен>` | + +**Пример:** + +```sh +Authorization: Bearer <ваш-kubernetes-token> +``` + +### Nexus + +**Тип авторизации:** Basic Authentication + +**Заголовки:** + +| Заголовок | Формат значения | +|-----------|-----------------| +| `Authorization` | `Basic ` | + +**Пример:** + +1. Сформируйте строку `username:password` +2. Закодируйте её в Base64: `echo "username:password" | base64` +3. Добавьте заголовок: + +```sh +Authorization: Basic +``` + +### OpenSearch + +**Тип авторизации:** Basic Authentication + +**Заголовки:** + +| Заголовок | Формат значения | +|-----------|-----------------| +| `Authorization` | `Basic ` | + +**Пример:** + +1. Сформируйте строку `username:password` +2. Закодируйте её в Base64: `echo "username:password" | base64` +3. Добавьте заголовок: + +```sh +Authorization: Basic +``` + +### Prometheus + +**Тип авторизации:** Bearer Token или Basic Authentication + +**Заголовки:** + +| Заголовок | Формат значения | +|-----------|-----------------| +| `Authorization` | `Bearer <токен>` или `Basic ` | + +**Пример Bearer Token:** + +```sh +Authorization: Bearer <ваш-токен> +``` + +**Пример Basic Authentication:** + +```sh +Authorization: Basic +``` + +### SonarQube + +**Тип авторизации:** Basic Authentication (User Token) + +**Заголовки:** + +| Заголовок | Формат значения | +|-----------|-----------------| +| `Authorization` | `Basic ` | + +**Пример:** + +1. Сформируйте строку с User Token: `token:` (где `token` - ваш SonarQube User Token) +2. Закодируйте её в Base64: `echo "token:" | base64` +3. Добавьте заголовок: + +```sh +Authorization: Basic +``` diff --git a/content/documentation/admin/healthchecks/_index.ru.md b/content/documentation/admin/healthchecks/_index.ru.md new file mode 100644 index 0000000..f909a76 --- /dev/null +++ b/content/documentation/admin/healthchecks/_index.ru.md @@ -0,0 +1,4 @@ +--- +title: Проверки статуса +weight: 60 +--- diff --git a/content/documentation/admin/healthchecks/overview.ru.md b/content/documentation/admin/healthchecks/overview.ru.md new file mode 100644 index 0000000..588fb22 --- /dev/null +++ b/content/documentation/admin/healthchecks/overview.ru.md @@ -0,0 +1,35 @@ +--- +title: Обзор +weight: 10 +--- + +Для каждого ресурса можно настроить набор правил, по которым будет определяться статус его сущностей. Возможно добавление произвольного количества правил. Поле `Условие` определяет, должны ли выполняться: + +- все правила (**AllOf**) +- хотя бы одно из них (**AnyOf**). + +> Если хотя бы одна из проверок завершилась с ошибкой, то статус сущности будет выставлен в **error**, независимо от результата остальных проверок и условия. + +Проверка выполнения каждого правила производится раз в минуту. Логи последних нескольких проверок доступны в меню ресурса в разделе `Проверки статуса`. + +Возможны четыре варианта статуса: + +- **healthy** — правила заданы, и параметры сущности соответствуют этим правилам; +- **unhealthy** — правила заданы, но параметры сущности им не соответствуют; +- **unknown** — правила не заданы либо проверка не может быть выполнена по каким-либо причинам; +- **error** — во время выполнения хотя бы одного из правил произошла ошибка. + +Для каждой сущности, при клике на плашку со статусом, открывается таблица с результатами выполнения правил и дополнительной информацией. + +> Событие **ENTITY_UPDATED** генерируется только при изменении статуса сущности. + +### Property + +Правило типа **Property** проверяет, соответствует ли конкретный параметр сущности заданному шаблонному выражению. + +Конфигурация правила состоит из одного параметра — выражения. Для описания выражения используется синтаксис [Go template](https://developer.hashicorp.com/nomad/tutorials/templates/go-template-syntax). + +Примеры выражений: + +- `{{ eq .entity.properties.lifecycle "deployed" }}` — значение свойства `lifecycle` должно быть `"deployed"`; +- `{{ lt .entity.properties.vulnerabilities 10 }}` — значение свойства `vulnerabilities` должно быть меньше `10`. diff --git a/content/documentation/admin/healthchecks/types.ru.md b/content/documentation/admin/healthchecks/types.ru.md new file mode 100644 index 0000000..19d62e3 --- /dev/null +++ b/content/documentation/admin/healthchecks/types.ru.md @@ -0,0 +1,263 @@ +--- +title: Типы проверок статуса +--- + +## Prometheus + +Правило типа **Prometheus** проверяет, соответствует ли указанная метрика заданному пороговому значению. В конфигурации указывается запрос PromQL, который должен возвращать результат типа Scalar или Vector с одним значением. + +Поддерживается шаблонизация, например: + +```go +avg(ingress_nginx_detail_request_seconds_sum{location="/{{ .entity.slug }}"}) +``` + +В данном примере вместо выражения `{{ .entity.slug }}` подставится идентификатор сущности. + +### Параметры конфигурации + +| Название | Описание | Возможные значения | +|---------------------|--------------------------------------------------------------------|----------------------------------------| +| Запрос | Запрос в формате PromQL к метрике в Prometheus | | +| Оператор | Оператор сравнения между результатом запроса и пороговым значением | Equal, NotEqual, LessThan, GreaterThan | +| Порог | Пороговое значение для сравнения с результатом запроса | | + +> Для проверки каждой сущности выполняется отдельный запрос к Prometheus. Рекомендуется учитывать это при планировании нагрузки на систему. + +### Авторизация + +Конфигурация авторизации описана в разделе [внешний сервис Prometheus](../external-services/#prometheus). + +## Gitlab Pipeline + +Правило типа **GitlabPipeline** проверяет, соответствует ли статус последнего pipeline в Gitlab для выбранного Ref (ветка или тег) заданному статусу. + +Во всех текстовых полях поддерживается шаблонизация, например, при подобном выражении в поле `Ref`: + +```go +{{ .entity.properties.mainBranch }} +``` + +во время проверки подставится значение параметра `mainBranch` проверяемой сущности. + +### Параметры конфигурации + +| Название | Описание | Возможные значения | +|---------------------|-------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------| +| ID проекта | ID проекта в Gitlab | | +| Ref | Ветка или тег для которых будет искаться последний pipeline | | +| Статус | Статус pipeline, который будет считаться успешным | created, waiting_for_resource, preparing, pending, running, success, failed, canceled, skipped, manual, scheduled | + +> Для проверки каждой сущности выполняется отдельный запрос к Gitlab. Рекомендуется учитывать это при планировании нагрузки на систему. + +### Авторизация + +Конфигурация авторизации описана в разделе [внешний сервис GitLab](../external-services/#gitlab). + +## DefectDojo Findings + +Правило типа **DefectDojoFindings** выполняет проверку по количеству активных уязвимостей различной критичности (severity) для заданного продукта в DefectDojo. + +Проверка проводится по условиям в блоке `conditions`, где можно указать ожидаемое количество уязвимостей для каждой severity и оператор сравнения (например, Critical < 5). + +Во всех текстовых полях поддерживается шаблонизация. Например, можно подставить название продукта из параметров сущности: + +```go +{{ .entity.properties.defectdojo_product_key }} +``` + +### Параметры конфигурации + +| Название | Описание | Возможные значения | +|---------------------|----------------------------------------------------------|---------------------| +| Название продукта | Идентификатор продукта в DefectDojo | | +| Условия | Условия для сравнения количества уязвимостей по severity | | + +#### Условия + +Каждое условие представляет объект следующей формы: + +```yaml +conditions: + - severity: Critical + operator: "<" + value: "5" + - severity: High + operator: "<=" + value: "10" +``` + +| Поле | Описание | Возможные значения | +|---------------------|--------------------------------|------------------------------------------| +| Уровень критичности | Уровень критичности | Total, Critical, High, Medium, Low, Info | +| Оператор | Оператор сравнения | ==, !=, <, <=, >, >= | +| Значение | Целевое значение для сравнения | | + +### Авторизация + +Конфигурация авторизации описана в разделе [внешний сервис DefectDojo](../external-services/#defectdojo). + +## CodeScoring Vulnerabilities + +Правило типа **CodeScoringVulnerabilities** выполняет проверку по количеству уязвимостей различной критичности (severity) для заданного проекта в CodeScoring. + +Проверка проводится по условиям в блоке `conditions`, где можно указать ожидаемое количество уязвимостей для каждой severity и оператор сравнения. Поддерживается проверка как по CVSS2, так и по CVSS3 метрикам. + +Во всех текстовых полях поддерживается шаблонизация. Например, можно подставить ID проекта из параметров сущности: + +```go +{{ .entity.properties.codescoring_project_id }} +``` + +### Параметры конфигурации + +| Название | Описание | Возможные значения | +|---------------------|----------------------------------------------------------------|--------------------| +| ID проекта | Идентификатор проекта в CodeScoring | | +| Условия | Условия для сравнения количества уязвимостей по severity | | + +#### Условия + +Каждое условие представляет объект следующего формата: + +```yaml +conditions: + - severity: CRITICAL + operator: "<" + value: "5" + cvss: "cvss3" + - severity: HIGH + operator: "<=" + value: "10" + cvss: "cvss2" +``` + +| Поле | Описание | Возможные значения | +|---------------------|--------------------------------|-------------------------------------------------------------------------------------------| +| Уровень критичности | Уровень критичности | Для CVSS3: CRITICAL, HIGH, MEDIUM, LOW, NONE, UNKNOWN. Для CVSS2: HIGH, MEDIUM, LOW, NONE | +| Оператор | Оператор сравнения | ==, !=, <, <=, >, >= | +| Значение | Целевое значение для сравнения | | +| CVSS | Версия CVSS метрики | cvss2, cvss3 | + +### Авторизация + +Конфигурация авторизации описана в разделе [внешний сервис CodeScoring](../external-services/#codescoring). + +## SonarQube Metrics + +Правило типа **SonarqubeMetrics** выполняет проверку по метрикам проекта в SonarQube на основании заданных условий. + +Проверка выполняется с использованием REST API вызова SonarQube `/api/measures/component`, где сравниваются текущие значения указанных метрик c ожидаемыми значениями, заданными в разделе `Условия`. + +Во всех текстовых полях поддерживается шаблонизация, например, можно подставить ключ компонента из параметров сущности: + +```go +{{ .entity.properties.sonarqube_project_key }} +``` + +### Параметры конфигурации + +| Название | Опциональность | Описание | Возможные значения | +|---------------------|-----------------|------------------------------------------------------------|---------------------| +| Ключ проекта | **Обязательно** | Идентификатор проекта в SonarQube | | +| Ветка | Опционально | Ветка проекта для которой будут браться метрики | | +| Условия | **Обязательно** | Условия для сравнения метрик в SonarQube | | + +#### Условия + +Каждое условие представляет объект следующей формы: + +```yaml +conditions: + - metric: coverage + operator: "<" + value: "5" + - metric: bugs + operator: "<=" + value: "10" +``` + +| Поле | Описание | Возможные значения | +|-----------|----------------------------------------------------------|------------------------------------------------------------------------| +| Метрика | Метрика SonarQube. В конфигурации указывается Metric key | См. список метрик в официальной документации SonarQube | +| Оператор | Оператор сравнения | ==, !=, <, <=, >, >= | +| Значение | Целевое значение для сравнения | | + +[Список возможных метрик](https://docs.sonarsource.com/sonarqube-server/latest/user-guide/code-metrics/metrics-definition) для текущей версии SonarQube. + +### Авторизация + +Конфигурация авторизации описана в разделе [внешний сервис SonarQube](../external-services/#sonarqube). + +## SonarQube Quality Gate + +Правило типа **SonarqubeQualityGate** проверяет статус Quality Gate проекта в SonarQube. Проверка выполняется с использованием REST API вызова SonarQube `/api/qualitygates/project_status`. + +Правило возвращает `true` (выполняется), если Quality Gate проекта имеет статус `OK`, и `false` (не выполняется) во всех остальных случаях (статусы `WARN`, `ERROR`, `NONE`). + +Во всех текстовых полях поддерживается шаблонизация, например, можно подставить ключ проекта из параметров сущности: + +```go +{{ .entity.properties.sonarqube_project_key }} +``` + +### Параметры конфигурации + +| Название | Опциональность | Описание | Возможные значения | +|---------------------|-----------------|------------------------------------------------------------|---------------------| +| Ключ проекта | **Обязательно** | Идентификатор проекта в SonarQube | | +| Ветка | Опционально | Ветка проекта для которой будет проверяться Quality Gate. Если не указана, проверяется основная ветка | | + +> Для проверки каждой сущности выполняется отдельный запрос к SonarQube. Рекомендуется учитывать это при планировании нагрузки на систему. + +### Авторизация + +Конфигурация авторизации описана в разделе [внешний сервис SonarQube](../external-services/#sonarqube). + +## URL + +Правило типа **URL** выполняет проверку доступности HTTP/HTTPS-эндпоинта по заданным параметрам. Система формирует HTTP-запрос и сравнивает код ответа с ожидаемым. + +Во всех строковых полях используется шаблонизация с применением сущности, например: + +```go +{{ .entity.slug }} +``` + +Это можно использовать, например, для динамического формирования URL и/или тела запроса. + +### Параметры конфигурации + +| Название | Опциональность | Описание | Примеры | +|--------------------|-----------------|-----------------------------------------------------------|-----------------------| +| URL | **Обязательно** | Полный адрес ресурса, к которому будет выполняться запрос | `https://example.com` | +| Метод | Опционально | HTTP-метод запроса | GET, POST | +| Тело запроса | Опционально | Тело запроса | | +| Ожидаемый статус | **Обязательно** | HTTP статус-код, с которым сравнивается полученный ответ | 200, 204. | + +### Обработка шаблонов + +- Поддерживается шаблонизация в полях, включая `URL` и `Тело запроса`. +- Значения могут браться из .entity, включая вложенные свойства (например, `{{ .entity.properties.id }}`). +- Также поддерживается шаблонизация в заголовках и других текстовых полях. + +### Пример тела запроса + +Поле `Тело запроса` описывается в YAML. После раскодирования и шаблонизации оно будет сериализовано в JSON и отправлено. + +Например: + +```yaml +id: "{{ .entity.id }}" +name: "{{ .entity.name }}" +``` + +### Проверка результата + +Метод сравнивает фактический HTTP статус ответа с ожидаемым значением. В случае несовпадения возвращается ошибка со значением кода ответа. + +Учитывайте, что `URL` также может быть динамическим и шаблонизироваться на основе параметров сущности: + +```go +https://api.example.com/{{ .entity.slug }}/health +``` diff --git a/content/documentation/admin/overview.md b/content/documentation/admin/overview.md new file mode 100644 index 0000000..edf04eb --- /dev/null +++ b/content/documentation/admin/overview.md @@ -0,0 +1,6 @@ +--- +title: Overview +weight: 10 +--- + +This document is the Administrator's Guide for the Deckhouse Development Platform and is part of the operational documentation for the Deckhouse Development Platform. diff --git a/content/documentation/admin/overview.ru.md b/content/documentation/admin/overview.ru.md new file mode 100644 index 0000000..b39574e --- /dev/null +++ b/content/documentation/admin/overview.ru.md @@ -0,0 +1,6 @@ +--- +title: Обзор +weight: 10 +--- + +Данный документ представляет собой руководство администратора Deckhouse Development Platform и является частью эксплуатационной документации продукта Deckhouse Development Platform. diff --git a/content/documentation/admin/processes.ru.md b/content/documentation/admin/processes.ru.md new file mode 100644 index 0000000..fbcb237 --- /dev/null +++ b/content/documentation/admin/processes.ru.md @@ -0,0 +1,166 @@ +--- +title: Процессы +menuTitle: Процессы +d8Edition: ee +moduleStatus: experimental +--- + +Процессы - это механизм автоматизации сложных бизнес-процессов, который позволяет создавать визуальные схемы выполнения действий с поддержкой условной логики, параллельного выполнения и обработки ошибок. + +Процессы предоставляют более гибкий и мощный инструмент по сравнению со сценариями, позволяя создавать сложные workflow с ветвлением, циклами и компенсационными действиями. + +## Основные концепции + +### Элементы процесса + +Процесс состоит из различных типов элементов: + +* **Начало** - точка входа в процесс +* **Задача** - выполнение конкретного действия +* **Эксклюзивный шлюз** - условное ветвление (if-else логика) +* **Параллельный шлюз** - параллельное выполнение веток +* **Конец** - завершение процесса + +### Обработка ошибок + +Каждый элемент процесса может иметь настройки обработки ошибок: + +* **Количество попыток перезапуска** - сколько раз повторить действие при ошибке +* **Задержка перезапуска** - интервал между попытками +* **Время на выполнение** - максимальное время выполнения элемента +* **Перезапуск по тайм-ауту** - автоматический перезапуск при превышении времени + +## Создание процесса + +### Основная информация + +Для создания процесса перейдите в раздел `Самообслуживание` → `Процессы` и нажмите кнопку `Создать`. + +Заполните следующие поля: + +* **Название** - название процесса +* **Описание** - подробное описание назначения процесса +* **Ресурс** - ресурс, для которого доступен процесс +* **Владелец** - пользователь, ответственный за процесс +* **Команда владелец** - команда, ответственная за процесс +* **Теги** - теги для категоризации процесса +* **Иконка** - иконка для отображения в интерфейсе + +### Конфигурация процесса + +На вкладке `Конфигурация` создается визуальная схема процесса: + +#### Добавление элементов + +1. Нажмите кнопку с типом элемента в панели редактора для создания нового элемента +2. Настройте параметры элемента в визуальном редакторе +3. Свяжите элемент с другими элементами процесса + +#### Типы элементов + +##### Задача + +- Связывается с конкретным действием +- Настраивается время выполнения и обработка ошибок +- Может иметь входящие и исходящие связи + +##### Эксклюзивный шлюз + +- Создает условное ветвление процесса +- Настраивается условие для каждой исходящей ветки +- Только одна ветка может быть выполнена + +##### Параллельный шлюз + +- Разделяет процесс на параллельные ветки +- Настраивается ожидание всех или любого входящего элемента +- Все ветки выполняются одновременно + +#### Связывание элементов + +1. Перетащите элемент на схему +2. Создайте связи между элементами, перетаскивая от одного элемента к другому +3. Настройте условия для условных переходов + +### Параметры процесса + +На вкладке `Параметры` настраиваются параметры процесса, которые могут использоваться во всех действиях процесса. + +Конфигурация и использование параметров процесса описаны в разделе [шаблонизация](../user/templating.html#параметры-процесса). + +## Запуск процесса + +### Ручной запуск + +1. Перейдите к сущности, для которой нужно запустить процесс +2. В меню сущности выберите `Запустить процесс` +3. Выберите нужный процесс из списка +4. Заполните параметры процесса +5. Нажмите `Запустить` + +### Параметры запуска + +При запуске процесса доступны: + +* **Общие параметры процесса** - параметры, определенные в конфигурации процесса +* **Параметры действий** - параметры для каждого действия в процессе +* **Переменные окружения** - дополнительные переменные для выполнения + +## Управление выполнением + +### Статусы процесса + +Процесс может находиться в следующих статусах: + +* **Создан** - процесс создан, но не запущен +* **Выполняется** - процесс находится в процессе выполнения +* **Приостановлен** - выполнение процесса приостановлено +* **Завершен** - процесс успешно завершен +* **Неудачно** - процесс завершился с ошибкой +* **Отменен** - выполнение процесса было отменено + +### Управление выполнением + +Для активных процессов доступны следующие операции: + +* **Приостановить** - временно остановить выполнение +* **Возобновить** - продолжить выполнение после приостановки +* **Остановить** - полностью остановить выполнение +* **Принудительный перезапуск** - перезапустить процесс с начала + +### Мониторинг + +В разделе `История запусков` можно просмотреть: + +* Список всех запусков процесса +* Детальную информацию о каждом запуске +* Логи выполнения действий +* Статус каждого элемента процесса + +## Примеры использования + +### Создание проекта с настройкой + +1. **Начало** - запуск процесса +2. **Задача** - создание проекта в GitLab +3. **Эксклюзивный шлюз** - проверка успешности создания +4. **Задача** (при успехе) - настройка переменных проекта +5. **Задача** (при ошибке) - отправка уведомления об ошибке +6. **Конец** - завершение процесса + +### Развертывание приложения + +1. **Начало** - запуск процесса развертывания +2. **Параллельный шлюз** - разделение на ветки +3. **Задача** (ветка 1) - создание namespace в Kubernetes +4. **Задача** (ветка 2) - создание секретов в Vault +5. **Параллельный шлюз** - ожидание завершения обеих веток +6. **Задача** - развертывание приложения +7. **Конец** - завершение процесса + +## Ограничения + +* Процессы не могут содержать более 100 элементов +* Максимальное время выполнения процесса - 24 часа +* Количество одновременных запусков процесса ограничено настройками системы +* Некоторые действия могут быть недоступны для использования в процессах diff --git a/content/documentation/admin/rbac.ru.md b/content/documentation/admin/rbac.ru.md new file mode 100644 index 0000000..aacbed0 --- /dev/null +++ b/content/documentation/admin/rbac.ru.md @@ -0,0 +1,440 @@ +--- +title: Ролевая модель +menuTitle: Ролевая модель +d8Edition: ee +moduleStatus: experimental +--- + +Ролевая модель в DDP — это система управления доступом, которая обеспечивает безопасность и контроль над действиями пользователей в платформе. Ролевая модель позволяет администраторам гибко настраивать права доступа для разных пользователей и команд, обеспечивая принцип минимальных привилегий и централизованное управление безопасностью. + +## Зачем нужна ролевая модель + +Ролевая модель решает следующие задачи: + +- **Безопасность данных** — предотвращает несанкционированный доступ к конфиденциальной информации +- **Контроль действий** — ограничивает возможности пользователей только необходимыми операциями +- **Упрощение управления** — позволяет назначать права группам пользователей через команды +- **Соответствие требованиям** — обеспечивает соблюдение политик безопасности организации + +## Компоненты ролевой модели + +Ролевая модель состоит из следующих компонентов: + +* **Разрешение** - соответствует конкретному действию в DDP. +* **Роль** - объединяет в себе набор тех или иных разрешений. +* **Привязка роли** - связывает роль и пользователей, либо команды. + +Для каждого объекта DDP существует свой набор разрешений, ролей и привязок ролей. Также есть глобальные роли, разрешения и привязки ролей, которые разрешают операции на глобальном уровне. + +**Важно:** Если у пользователя нет соответствующих разрешений, он не сможет выполнять никакие операции на платформе. Система проверяет разрешения для каждой операции. + +## Типы объектов и разрешения + +### Глобальные разрешения + +Глобальные разрешения действуют на уровне всей платформы и предоставляют доступ ко всем объектам определенного типа: + +Ресурсы: +- `create:resources` - создание ресурсов +- `read:resources` - просмотр ресурсов +- `update:resources` - редактирование ресурсов +- `delete:resources` - удаление ресурсов + +Сущности: +- `create:entities` - создание сущностей +- `read:entities` - просмотр сущностей +- `update:entities` - редактирование сущностей +- `delete:entities` - удаление сущностей + +Источники данных: +- `create:datasources` - создание источников данных +- `read:datasources` - просмотр источников данных +- `update:datasources` - редактирование источников данных +- `sync:datasources` - синхронизация источников данных +- `delete:datasources` - удаление источников данных + +Действия: +- `create:actions` - создание действий +- `read:actions` - просмотр действий +- `update:actions` - редактирование действий +- `run:actions` - выполнение действий +- `delete:actions` - удаление действий + +Автоматизации: +- `create:automations` - создание автоматизаций +- `read:automations` - просмотр автоматизаций +- `update:automations` - редактирование автоматизаций +- `delete:automations` - удаление автоматизаций + +Рабочие процессы: +- `create:workflows` - создание рабочих процессов +- `read:workflows` - просмотр рабочих процессов +- `update:workflows` - редактирование рабочих процессов +- `delete:workflows` - удаление рабочих процессов + +Вебхуки: +- `create:webhooks` - создание вебхуков +- `read:webhooks` - просмотр вебхуков +- `update:webhooks` - редактирование вебхуков +- `delete:webhooks` - удаление вебхуков + +Виджеты: +- `create:widgets` - создание виджетов +- `read:widgets` - просмотр виджетов +- `update:widgets` - редактирование виджетов +- `run:widget-actions` - выполнение действий виджетов +- `delete:widgets` - удаление виджетов + +Дашборды: +- `create:dashboards` - создание дашбордов +- `read:dashboards` - просмотр дашбордов +- `update:dashboards` - редактирование дашбордов +- `delete:dashboards` - удаление дашбордов + +Внешние сервисы: +- `create:external-services` - создание внешних сервисов +- `read:external-services` - просмотр внешних сервисов +- `update:external-services` - редактирование внешних сервисов +- `delete:external-services` - удаление внешних сервисов + +Процессы: +- `create:processes` - создание процессов +- `read:processes` - просмотр процессов +- `update:processes` - редактирование процессов +- `delete:processes` - удаление процессов + +#### Разрешения на просмотр страниц + +Разрешения `view:` контролируют доступ к различным разделам интерфейса платформы: + +- `view:admin-page` - доступ к разделу "Администрирование" +- `view:self-service-page` - доступ к разделу "Self Service" + +**Важно:** Без соответствующих `view:` разрешений пользователь не сможет увидеть соответствующие разделы в навигационном меню, даже если у него есть другие разрешения для работы с объектами в этих разделах. + +### Разрешения на уровне объектов + +Для каждого типа объекта существуют разрешения, которые действуют только на конкретный объект: + +Для ресурсов: +- `read:resource` - просмотр конкретного ресурса +- `update:resource` - редактирование конкретного ресурса +- `delete:resource` - удаление конкретного ресурса +- `create:entities` - создание сущностей ресурса +- `read:entities` - просмотр сущностей ресурса +- `update:entities` - редактирование сущностей ресурса +- `delete:entities` - удаление сущностей ресурса +- `run:actions` - выполнение действий для сущностей ресурса +- `control:processes` - управление процессами для сущностей ресурса +- `edit:role-bindings` - редактирование привязок ролей для ресурса + +Для сущностей: +- `read:entity` - просмотр конкретной сущности +- `update:entity` - редактирование конкретной сущности +- `delete:entity` - удаление конкретной сущности +- `run:actions` - выполнение действий для сущности +- `control:processes` - управление процессами для сущности +- `edit:role-bindings` - редактирование привязок ролей для сущности + +Для других объектов (действия, автоматизации, процессы, вебхуки, виджеты, дашборды, внешние сервисы и т.д.): +- `read:[object-type]` - просмотр объекта +- `update:[object-type]` - редактирование объекта +- `delete:[object-type]` - удаление объекта +- `edit:role-bindings` - редактирование привязок ролей для объекта + +## Иерархия проверки разрешений + +Ролевая модель иерархическая, например для того, чтобы проверить, можно ли изменять пользователю конкретную сущность будет выполняться следующая последовательность действий: + +### 1. Супер-администратор + +- Проверка, является ли пользователь супер-администратором. Если пользователь является супер-администратором, то дальнейшие проверки не производятся + +### 2. Глобальные роли + +- Проверка по JWT-токену пользователя в каких группах он состоит +- Поиск глобальных ролей для пользователя и его групп по привязкам глобальных ролей +- Проверка разрешений в глобальных ролях: если в одной из глобальных ролей, привязанных к пользователю, либо его команде, присутствует разрешение `update:entities`, то пользователь будет обладать правами на редактирование любых сущностей в DDP, дальнейшие проверки не производятся + +### 3. Роли ресурса + +- Поиск ролей ресурса для пользователя и его групп по привязкам ролей конкретного ресурса +- Проверка разрешений в ролях ресурса: если в одной из ролей ресурса, привязанных к пользователю, либо его команде, присутствует разрешение `update:entities`, то пользователь будет обладать правами на редактирование любых сущностей данного ресурса, дальнейшие проверки не производятся + +### 4. Роли сущностей + +- Поиск ролей сущностей для пользователя и его групп по привязкам ролей конкретной сущности +- Проверка разрешений в ролях сущности: если в одной из ролей сущности, привязанных к пользователю, либо его команде, присутствует разрешение `update:entity`, то пользователь будет обладать правами на редактирование данной сущности + +### 5. Владение объектом (при включенной опции ownerIsAdmin) + +- Проверка, является ли пользователь владельцем объекта +- Проверка, состоит ли пользователь в команде-владельце объекта +- Если пользователь является владельцем объекта или участником команды-владельца, ему предоставляются все права администратора на объект + +Если ни на одном уровне не было найдено соответствующего разрешения, то действие будет запрещено. + +**Примечание:** Проверка владения включается только если в конфигурации платформы включена опция `ownerIsAdmin`. Подробнее о владении объектами см. раздел [Владение объектами](#владение-объектами). + +## Владение объектами + +Владение объектами — это механизм, который позволяет пользователям и командам становиться владельцами определённых объектов в системе и автоматически получать все права администратора на эти объекты. + +### Кто такой владелец + +**Владелец объекта** — это пользователь или команда, которая была назначена владельцем конкретного объекта. + +### Как владение влияет на права доступа + +Владение объектом предоставляет полные права администратора на этот объект, если включена опция `ownerIsAdmin` в конфигурации платформы. Это означает, что: + +- **Владелец объекта** получает полный доступ для чтения, редактирования и удаления объекта +- **Владелец может редактировать привязки ролей** для объекта, управляя доступом других пользователей +- **Владелец может выполнять любые действия** с объектом + +### Опция OwnerAsAdmin + +В конфигурации платформы доступна опция `ownerIsAdmin`, которая контролирует применение прав владения: + +- **Включена (true)** — владельцы объектов получают полные права администратора на свои объекты +- **Отключена (false)** — владельцы объектов не получают автоматических прав; доступ контролируется только через роли + +**Важно:** Опция `ownerIsAdmin` должна быть настроена администратором платформы в конфигурационном файле. По умолчанию опция выключена. + +### Примеры использования владения + +#### Владение ресурсом + +Если пользователь создаёт ресурс, он автоматически становится его владельцем. При включенной опции `ownerIsAdmin` он получает все права администратора на этот ресурс, включая: +- Управление сущностями ресурса +- Настройку привязок ролей +- Полное редактирование и удаление ресурса + +#### Владение сущностью + +Если пользователь создаёт сущность, он становится её владельцем и может: +- Просматривать и редактировать сущность +- Управлять привязками ролей для сущности +- Удалять сущность + +#### Команда-владелец + +Если объект принадлежит команде, все участники этой команды получают права администратора на объект при включенной опции `ownerIsAdmin`. + +## Роль по умолчанию + +Платформа позволяет назначить одну глобальную роль по умолчанию. Разрешения этой роли применяются ко всем авторизованным пользователям. Роль по умолчанию задается в разделе "Администрирование / Управление доступом" переключателем в таблице "Роли". + +**Важно:** Ролью по умолчанию может быть назначена только глобальная роль. + +## Команды + +Команды позволяют группировать пользователей и назначать им роли коллективно. Пользователь может состоять в нескольких командах, в этом случае его разрешения будут объединены из всех команд, в которых он состоит. + +**Важно:** Команды и их состав синхронизируются из внешней системы аутентификации (Dex). Управление командами через интерфейс DDP недоступно. + +## Настройка ролей и управление доступом + +### Создание роли + +1. Перейдите в раздел `Администрирование -> Управление доступом` +2. Выберите вкладку "Роли" +3. Нажмите кнопку "Создать роль" +4. Заполните форму: + - Название - уникальное имя роли + - Описание - описание назначения роли + - Тип объекта - выберите уровень действия роли: + - `Глобальные` - для глобальных разрешений + - `Ресурсы` - для разрешений на уровне ресурсов + - `Сущности` - для разрешений на уровне сущностей + - `Действия` - для разрешений на уровне действий + - И другие типы объектов + - Разрешения - выберите необходимые разрешения из списка +5. Нажмите "Сохранить" + +### Назначение роли пользователям + +1. Перейдите в раздел `Администрирование -> Управление доступом` +2. Выберите вкладку "Привязки ролей" +3. Нажмите кнопку "Создать привязку роли" +4. Заполните форму: + - Название - имя привязки роли + - Описание - описание назначения привязки + - Роль - выберите созданную роль + - Объект - выберите конкретный объект (если роль не глобальная) + - Пользователи - добавьте пользователей, которым назначается роль + - Команды - добавьте команды, которым назначается роль +5. Нажмите "Сохранить" + +### Настройка роли по умолчанию + +1. Перейдите в раздел `Администрирование -> Управление доступом` +2. Выберите вкладку "Роли" +3. Найдите глобальную роль, которую хотите сделать ролью по умолчанию +4. Включите переключатель "Роль по умолчанию" +5. Подтвердите действие + +**Важно:** Ролью по умолчанию может быть только глобальная роль. + +### Редактирование существующих ролей + +1. Перейдите в раздел `Администрирование -> Управление доступом` +2. Выберите вкладку "Роли" +3. Найдите нужную роль и нажмите "Редактировать" +4. Внесите необходимые изменения: + - Измените название или описание + - Добавьте или удалите разрешения +5. Нажмите "Сохранить" + +### Редактирование привязок ролей + +1. Перейдите в раздел `Администрирование -> Управление доступом` +2. Выберите вкладку "Привязки ролей" +3. Найдите нужную привязку и нажмите "Редактировать" +4. Внесите необходимые изменения: + - Измените название или описание + - Добавьте или удалите пользователей + - Добавьте или удалите команды +5. Нажмите "Сохранить" + +### Удаление ролей и привязок + +1. Перейдите в соответствующий раздел +2. Найдите нужную роль или привязку +3. Нажмите кнопку "Удалить" +4. Подтвердите удаление + +**Внимание:** Удаление роли приведет к удалению всех связанных привязок ролей. + +### Просмотр разрешений пользователя или команды + +#### Для пользователя + +1. Перейдите в раздел `Администрирование -> Пользователи` +2. Откройте профиль нужного пользователя +3. Перейдите на вкладку "Разрешения" +4. Просмотрите: + - Глобальные разрешения + - Разрешения по объектам + - Роли, назначенные пользователю + - Команды, в которых состоит пользователь + +#### Для команды + +1. Перейдите в раздел `Администрирование -> Команды` +2. Откройте профиль нужной команды +3. Перейдите на вкладку "Разрешения" +4. Просмотрите: + - Глобальные разрешения команды + - Разрешения по объектам + - Роли, назначенные команде + - Пользователи, состоящие в команде + +**Примечание:** Состав команды синхронизируется из внешней системы аутентификации (Dex). + +### Пресеты ролей + +Платформа предоставляет готовые пресеты ролей для быстрой настройки типовых сценариев доступа: + +#### Глобальные пресеты + +##### Пресет "Admin" + +- Тип: `global` +- Разрешения: Все глобальные разрешения +- Назначение: Супер-администраторы системы + +##### Пресет "Viewer" + +- Тип: `global` +- Разрешения: + - `read:actions`, `read:automations`, `read:dashboards` + - `read:datasources`, `read:entities`, `read:resources` + - `read:webhooks`, `read:widgets`, `read:workflows` + - `read:resource-relations`, `read:system-alerts` + - `view:admin-page`, `view:self-service-page` + - `read:audit-logs`, `read:processes` +- Назначение: Пользователи с правами только на просмотр + +#### Пресеты для процессов + +##### Пресет "Process admin" + +- Тип: `process-definitions` +- Разрешения: `delete:process`, `edit:role-bindings`, `read:process`, `update:process` +- Назначение: Администраторы процессов + +##### Пресет "Process viewer" + +- Тип: `process-definitions` +- Разрешения: `read:process` +- Назначение: Пользователи с правами на просмотр процессов + +#### Пресеты для ресурсов + +##### Пресет "Resource admin" + +- Тип: `resources` +- Разрешения: Все разрешения для ресурсов +- Назначение: Администраторы конкретных ресурсов + +#### Использование пресетов + +1. Перейдите в раздел `Администрирование -> Управление доступом` +2. Выберите вкладку "Роли" +3. Нажмите "Создать роль" +4. Выберите тип объекта +5. В разделе "Пресеты" нажмите на нужный пресет +6. Настройте параметры роли: + - Измените название и описание при необходимости + - Добавьте или удалите разрешения +7. Нажмите "Сохранить" + +### Примеры настройки ролей + +#### Роль "Администратор системы" + +- Тип: `global` +- Разрешения: Все глобальные разрешения (используйте пресет "Admin") +- Назначение: Супер-администраторы + +#### Роль "Просмотрщик" + +- Тип: `global` +- Разрешения: Только права на чтение (используйте пресет "Viewer") +- Назначение: Пользователи с ограниченными правами + +#### Роль "Администратор ресурса" + +- Тип: `resources` +- Разрешения: Все разрешения для ресурсов (используйте пресет "Resource admin") +- Назначение: Конкретный ресурс, команда "Администраторы" + +#### Роль "Оператор процессов" + +- Тип: `process-definitions` +- Разрешения: `delete:process`, `edit:role-bindings`, `read:process`, `update:process` (используйте пресет "Process admin") +- Назначение: Команда "Операторы процессов" + +## Практические рекомендации + +### Создание ролей + +1. Определите уровень доступа: решите, нужна ли глобальная роль или роль для конкретного объекта +2. Выберите необходимые разрешения: используйте принцип минимальных привилегий +3. Создайте роль в соответствующем разделе администрирования +4. Назначьте роль пользователям или командам через привязки ролей + +### Управление доступом + +1. Используйте команды для группового управления доступом +2. Применяйте роли по умолчанию для базовых разрешений всех пользователей +3. Используйте иерархию - глобальные роли для широких прав, роли объектов для специфических прав +4. Регулярно пересматривайте назначенные роли и привязки + +### Безопасность + +1. Принцип минимальных привилегий: предоставляйте только необходимые разрешения +2. Регулярный аудит: проверяйте назначенные роли и их использование +3. Используйте команды вместо индивидуальных назначений для упрощения управления +4. Документируйте роли - используйте описания для понимания назначения ролей diff --git a/content/documentation/admin/webhooks.ru.md b/content/documentation/admin/webhooks.ru.md new file mode 100644 index 0000000..7751e88 --- /dev/null +++ b/content/documentation/admin/webhooks.ru.md @@ -0,0 +1,12 @@ +--- +title: Вебхуки +menuTitle: Вебхуки +d8Edition: ee +moduleStatus: experimental +--- + +По механизму действия вебхуки похожи на источники данных. При этом, если источник данных работает по pull-модели, то есть сам опрашивает инфраструктурные системы и пытается загрузить из них данные, то вебхуки ожидают, что данные будут отправлены извне, то есть работают по push-модели. + +При этом настройка правил обработки (создание, сопоставление, обновление, создание связей) аналогична настройке подобных правил в источниках данных. + +Каждый webhook обладает собственным URL, который формируется следующим образом `/webhooks/`. На данном URL вебхук принимает POST запросы с массивом данных любого формата, который обрабатывается на основе правил вебхука. diff --git a/content/documentation/admin/widgets/_index.ru.md b/content/documentation/admin/widgets/_index.ru.md new file mode 100644 index 0000000..8d4d4c8 --- /dev/null +++ b/content/documentation/admin/widgets/_index.ru.md @@ -0,0 +1,4 @@ +--- +title: Виджеты +weight: 50 +--- diff --git a/content/documentation/admin/widgets/overview.ru.md b/content/documentation/admin/widgets/overview.ru.md new file mode 100644 index 0000000..ab88f68 --- /dev/null +++ b/content/documentation/admin/widgets/overview.ru.md @@ -0,0 +1,26 @@ +--- +title: Обзор +weight: 10 +--- + +Виджеты - карточки для визуализации каких-либо данных, хранящихся в платформе, а также информации из инфраструктурных сервисов. В отличие от источников данных, виджеты получают информацию из инфраструктурных сервисов непосредственно в момент их отображения в интерфейсе. + +Виджеты могут быть добавлены на дашборды, дашборды в свою очередь могут быть привязаны либо к статическим страницам: каталог, самообслуживание, главная страница, администрирование, либо к карточкам сущностей. + +## Конфигурация + +Конфигурация каждого виджета содержит как общие поля, так и специфичные поля, характерные для каждого типа виджетов. + +В конфигурации виджетов допустимо использование синтаксиса [Go template](https://developer.hashicorp.com/nomad/tutorials/templates/go-template-syntax) для шаблонизации, например: + +* `{{ .entity.name }}` - подставить при обработке виджета параметр сущности "name". +* `{{ .credentials.token }}` - подставить при обработке виджета учетные данные с названием "token" + +У каждого виджета доступно задание области видимости: + +* **Global** - виджет не поддерживает получение параметров сущности через механизм [Go template](https://developer.hashicorp.com/nomad/tutorials/templates/go-template-syntax); +* **Resource** - виджет поддерживает получение параметров сущности через механизм [Go template](https://developer.hashicorp.com/nomad/tutorials/templates/go-template-syntax). Виджеты с областью видимости Resource можно прикрепить только к страницам сущности. + +В конфигурации виджетов возможно задание учетной записи, с данными которой виджет будет взаимодействовать с инфраструктурными системами, а также выбрать тип учетных данных, который будет использоваться. + +В случае, если учетная запись не задана, виджет будет использовать учетные данные пользователя, взаимодействующего с платформой в текущий момент. diff --git a/content/documentation/admin/widgets/types.ru.md b/content/documentation/admin/widgets/types.ru.md new file mode 100644 index 0000000..5583c0d --- /dev/null +++ b/content/documentation/admin/widgets/types.ru.md @@ -0,0 +1,1049 @@ +--- +title: Типы виджетов +--- + +## API + +Виджет позволяет вывести спецификацию API из файла в Gitlab репозитории или по ссылке в формате OpenAPI (Swagger) или Protobuf. При выводе спецификации OpenAPI из файла в формате YAML или JSON виджет отображает интерфейс Swagger. Во всех остальных случаях виджет отображает спецификацию в виде текста. + +### Общая конфигурация + +| Название | Опциональность | Описание | Возможные значения | Значение по умолчанию | +|-------------------|-----------------|--------------------------------------------------------------------|--------------------------------------|-----------------------| +| Тип спецификации | **обязательно** | Тип спецификации | OpenAPI (Swagger), Protocol Buffers | - | +| Тип источника | **обязательно** | Тип источника, из которого будет загружаться файл со спецификацией | URL, Gitlab | - | + +### Конфигурация типа источника: URL + +| Название | Опциональность | Описание | Значение по умолчанию | +|-----------|-----------------|------------------------------------------------|-----------------------| +| URL | **обязательно** | Ссылка на файл со спецификацией | - | +| Заголовки | опционально | Заголовки для доступа к файлу со спецификацией | - | + +### Конфигурация типа источника: Gitlab + +| Название | Опциональность | Описание | Значение по умолчанию | +|--------------|-----------------|------------------------------------------------------------------------|-----------------------| +| Gitlab URL | **обязательно** | URL Gitlab | - | +| ID проекта | **обязательно** | Идентификатор проекта, из которого будет браться файл со спецификацией | - | +| Ветка | **обязательно** | Ветка, из которой будет браться файл со спецификацией | - | +| Путь к файлу | **обязательно** | Путь к файлу со спецификацией относительно корня репозитория | - | + +### Авторизация + +Конфигурация авторизации описана в разделе [внешний сервис GitLab](../external-services/#gitlab). + +## CodeScoring. Зависимости + +Виджет позволяет вывести таблицу с зависимостями продукта на основе информации из CodeScoring с указанием названия зависимости, версии, лицензии, количество уязвимостей и другой информацией для каждой зависимости. + +### Авторизация + +Конфигурация авторизации описана в разделе [внешний сервис CodeScoring](../external-services/#codescoring). + +### Конфигурация + +| Название | Опциональность | Описание | Значение по умолчанию | +|-------------------|-----------------|-------------------------------------|-----------------------| +| URL | **обязательно** | URL CodeScoring | - | +| ID проекта | **обязательно** | Идентификатор проекта в CodeScoring | - | + +## CodeScoring. Уязвимости + +Виджет позволяет вывести таблицу с уязвимостями продукта на основе информации из CodeScoring с указанием кода уязвимости, уровня критичности, наличия эксплойта, исправленной версии для каждой уязвимости. + +### Авторизация + +Конфигурация авторизации описана в разделе [внешний сервис CodeScoring](../external-services/#codescoring). + +### Конфигурация + +| Название | Опциональность | Описание | Значение по умолчанию | +|-------------------|-----------------|-------------------------------------|-----------------------| +| URL | **обязательно** | URL CodeScoring | - | +| ID проекта | **обязательно** | Идентификатор проекта в CodeScoring | - | + +## DefectDojo. Уязвимости в продукте (детали) + +Виджет позволяет вывести таблицу с уязвимостями продукта на основе информации из DefectDojo с указанием уровня критичности, описания и даты обнаружения для каждой уязвимости. + +### Авторизация + +Конфигурация авторизации описана в разделе [внешний сервис DefectDojo](../external-services/#defectdojo). + +### Конфигурация + +| Название | Опциональность | Описание | Значение по умолчанию | +|-------------------|-----------------|--------------------------------------------------------|-----------------------| +| URL | **обязательно** | URL DefectDojo. Указывается без пути к API (`/api/v2`) | - | +| Название продукта | **обязательно** | Название продукта в DefectDojo | - | + +### Дополнительные возможности виджета + +При просмотре виджета доступна настройка следующих параметров: + +* **Активные уязвимости** - если включено, то загружаются уязвимости продукта с флагом ‘Active’ = true. Если отключено, то загружаются уязвимости продукта с флагом ‘Active’ = false. Включено по умолчанию. +* **Дублирующиеся уязвимости** - если включено, то загружаются уязвимости продукта с флагом ‘Duplicate’ = true. Если отключено, то загружаются уязвимости продукта с флагом ‘Duplicate’ = false. Отключено по умолчанию. + +## DefectDojo. Уязвимости в продукте (общая статистика) + +Виджет позволяет вывести график с общим количеством уязвимостей продукта на основе информации из DefectDojo с разбивкой по уровням критичности. + +### Авторизация + +Конфигурация авторизации описана в разделе [внешний сервис DefectDojo](../external-services/#defectdojo). + +### Конфигурация + +| Название | Опциональность | Описание | Значение по умолчанию | +|-------------------|-----------------|----------------------------------------------------------------------------------------------------------------------------------|-----------------------| +| URL | **обязательно** | URL DefectDojo. Указывается без пути к API (`/api/v2`) | - | +| Название продукта | **обязательно** | Название продукта в DefectDojo | - | + +### Дополнительные возможности виджета + +При просмотре виджета доступна настройка следующих параметров: + +* **Активные уязвимости** - если включено, то загружаются уязвимости продукта с флагом ‘Active’ = true. Если отключено, то загружаются уязвимости продукта с флагом ‘Active’ = false. Включено по умолчанию. +* **Дублирующиеся уязвимости** - если включено, то загружаются уязвимостиля продукта с флагом ‘Duplicate’ = true. Если отключено, то загружаются уязвимости продукта с флагом ‘Duplicate’ = false. Отключено по умолчанию. + +## Docker образы + +Виджет позволяет отображать данные о доступных образах в docker registry. На виджет выводятся все доступные теги и команда docker pull. Поддерживается поиск. + +### Авторизация + +Конфигурация авторизации описана в разделе [внешний сервис Docker Registry](../external-services/#docker-registry). + +### Конфигурация + +| Название | Опциональность | Описание | Значение по умолчанию | +|------------|-----------------|--------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------| +| URL | **обязательно** | URL Docker Registry. Используется для получения данных о доступных образах | - | +| Название | опционально | Название репозитория, из которого будут загружаться данные в виджет. Пример: `repo`. Без указания названия, будут получены все доступные образы | - | + +## Gitlab. Запросы слияния + +Виджет позволяет отображать данные о Merge Requests в платформе GitLab и выполнять действия с ними. + +### Авторизация + +Конфигурация авторизации описана в разделе [внешний сервис GitLab](../external-services/#gitlab). + +### Конфигурация + +| Название | Опциональность | Описание | Значение по умолчанию | +|------------|-----------------|----------------------------------------------------------------------------|-----------------------| +| URL | **обязательно** | URL GitLab API. Используется для получения данных из GitLab | - | +| ID проекта | **обязательно** | ID проекта, из которого будут загружаться данные в виджет. Пример: `12345` | - | + +### Фильтрация по статусу + +Виджет позволяет фильтровать отображаемые Merge Requests по статусу. В настройках запроса виджета можно выбрать один из следующих статусов: + +- **Открытые** - показывает только открытые MR +- **Закрытые** - показывает только закрытые MR +- **Слитые** - показывает только слитые MR +- **Заблокированные** - показывает только заблокированные MR + +По умолчанию отображаются только открытые MR. + +### Дополнительные возможности виджета + +При активированной функции действий в настройках виджет позволяет выполнять следующие действия с Merge Requests: + +- **Слить** - слияние открытого запроса на слияние (доступно только для открытых MR) +- **Закрыть** - закрытие запроса на слияние +- **Отметить как черновик/готово** - изменение статуса черновика запроса на слияние +- **Просмотр изменений** - просмотр диффа (изменений) в запросе на слияние + +**Важно:** для выполнения действий с MR требуются соответствующие права доступа в GitLab репозитории. + +## Gitlab. Пайплайны + +Виджет позволяет отображать данные о пайплайнах в платформе GitLab. + +### Авторизация + +Конфигурация авторизации описана в разделе [внешний сервис GitLab](../external-services/#gitlab). + +### Конфигурация + +| Название | Опциональность | Описание | Значение по умолчанию | +|------------|-----------------|----------------------------------------------------------------------------|-----------------------| +| URL | **обязательно** | URL GitLab API. Используется для получения данных из GitLab | - | +| ID проекта | **обязательно** | ID проекта, из которого будут загружаться данные в виджет. Пример: `12345` | - | + +### Дополнительные возможности виджета + +#### Запуск пайплайнов + +Виджет позволяет запускать пайплайны в GitLab напрямую из платформы DDP. + +##### Конфигурация + +| Название | Обязательность | Описание | Значение по умолчанию | +|------------|-----------------|------------------------------------------------------------------------------------|-----------------------| +| Ref | **обязательно** | Целевая ветка или тег для запуска пайплайна. | - | +| Переменные | опционально | Переменные в формате ключ-значение, которые будут переданы в запускаемый пайплайн. | - | + +## GitLab. Редактор пайплайна + +Виджет позволяет редактировать конфигурацию пайплайна GitLab CI/CD (файл `.gitlab-ci.yml`) и создавать запросы на слияние с изменениями. + +### Авторизация + +Конфигурация авторизации описана в разделе [внешний сервис GitLab](../external-services/#gitlab). + +### Конфигурация + +| Название | Опциональность | Описание | Значение по умолчанию | +|------------|-----------------|----------------------------------------------------------------------------|-----------------------| +| URL | **обязательно** | URL GitLab API. Используется для получения данных из GitLab | - | +| ID проекта | **обязательно** | ID проекта, из которого будут загружаться данные в виджет. Пример: `12345` | - | + +### Отображаемые данные + +Виджет отображает: + +* **Редактор кода** - Monaco Editor для редактирования файла `.gitlab-ci.yml` +* **Дифф-просмотр** - отображение изменений между оригинальной и редактируемой версией конфигурации + +### Дополнительные возможности виджета + +#### Создание запроса на слияние + +Виджет позволяет создавать запросы на слияние с изменениями конфигурации пайплайна. + +##### Параметры запроса на слияние + +| Название | Обязательность | Описание | Значение по умолчанию | +|-------------------|-----------------|------------------------------------------------------------------------------------|-----------------------| +| Заголовок MR | **обязательно** | Краткий заголовок, описывающий цель запроса на слияние. | - | +| Описание MR | опционально | Подробное описание запроса на слияние и изменений. | - | +| Название новой ветки | **обязательно** | Название новой ветки, которая будет содержать ваши изменения. | - | +| Целевая ветка | **обязательно** | Ветка, в которую будет выполнен запрос на слияние. | main | +| Сообщение коммита | **обязательно** | Описание изменений, внесенных в конфигурацию пайплайна. | - | + +#### Ограничения + +* Виджет работает только с файлом `.gitlab-ci.yml` в корне проекта +* Для создания запроса на слияние требуются права на запись в репозиторий +* Максимальный размер файла конфигурации ограничен возможностями GitLab API + +## GitLab. Статистика пайплайнов + +Виджет позволяет отображать статистику пайплайнов в платформе GitLab, включая общую статистику, распределение по статусам, источникам, участникам и веткам. + +### Авторизация + +Конфигурация авторизации описана в разделе [внешний сервис GitLab](../external-services/#gitlab). + +### Конфигурация + +| Название | Опциональность | Описание | Значение по умолчанию | +|------------|-----------------|----------------------------------------------------------------------------|-----------------------| +| URL | **обязательно** | URL GitLab API. Используется для получения данных из GitLab | - | +| ID проекта | **обязательно** | ID проекта, из которого будут загружаться данные в виджет. Пример: `12345` | - | + +### Отображаемые данные + +Виджет отображает следующую статистику: + +#### Основные метрики + +* **Общее количество пайплайнов** - общее число пайплайнов за выбранный период +* **Процент успеха** - процент успешно выполненных пайплайнов +* **Процент неудач** - процент неудачно выполненных пайплайнов +* **Средняя длительность** - среднее время выполнения пайплайнов + +#### Распределение по статусам + +* Успешные пайплайны +* Неудачные пайплайны +* Отмененные пайплайны +* Пропущенные пайплайны +* Ручные пайплайны + +#### Распределение по источникам + +* Push (коммиты) +* Merge requests (запросы слияния) +* Schedule (по расписанию) +* Web (через веб-интерфейс) + +#### Топ участников + +* Список участников с наибольшим количеством запущенных пайплайнов +* Аватары участников (при наличии) +* Количество пайплайнов для каждого участника + +#### Активность веток + +* Список веток с наибольшим количеством пайплайнов +* Количество пайплайнов для каждой ветки + +### Параметры запроса + +| Название | Опциональность | Описание | Значение по умолчанию | +|-------------|-----------------|------------------------------------------------------------------------------------|-----------------------| +| Начальная дата | **обязательно** | Начальная дата для анализа пайплайнов в формате ISO 8601. Пример: `2024-01-01T00:00:00Z` | - | +| Конечная дата | **обязательно** | Конечная дата для анализа пайплайнов в формате ISO 8601. Пример: `2024-01-31T23:59:59Z` | - | +| Ветка | опционально | Фильтр по конкретной ветке. Если не указана, анализируются все ветки. | - | + +### Ограничения + +* Виджет анализирует максимум 100 пайплайнов за один запрос для оптимизации производительности +* Статистика рассчитывается только для пайплайнов с валидными данными (имеющими статус и время выполнения) +* Данные обновляются при каждом обновлении виджета + +## Gitlab. Теги + +Виджет позволяет отображать данные о тегах проекта в платформе GitLab. + +### Авторизация + +Конфигурация авторизации описана в разделе [внешний сервис GitLab](../external-services/#gitlab). + +### Конфигурация + +| Название | Опциональность | Описание | Значение по умолчанию | +|------------|-----------------|----------------------------------------------------------------------------|-----------------------| +| URL | **обязательно** | URL GitLab API. Используется для получения данных из GitLab | - | +| ID проекта | **обязательно** | ID проекта, из которого будут загружаться данные в виджет. Пример: `12345` | - | + +### Дополнительные возможности виджета + +#### Создание тегов + +Виджет позволяет создать теги в GitLab напрямую из платформы DDP. + +##### Конфигурация + +| Название | Обязательность | Описание | Значение по умолчанию | +|------------|-----------------|------------------------------------------------------------------------------------|-----------------------| +| Название | **обязательно** | Название создаваемого тега. | - | +| Создать из | **обязательно** | Целевая ветка или тег для запуска пайплайна. | - | +| Описание | опционально | Описание создаваемого тега. | - | + +## GitLab. Участники + +Виджет позволяет отображать данные об участников проекта в GitLab. [Подробнее об участниках](https://docs.gitlab.com/user/project/members/). + +### Авторизация + +Конфигурация авторизации описана в разделе [внешний сервис GitLab](../external-services/#gitlab). + +### Конфигурация + +| Название | Опциональность | Описание | Значение по умолчанию | +|------------|-----------------|----------------------------------------------------------------------------|-----------------------| +| URL | **обязательно** | URL GitLab API. Используется для получения данных из GitLab | - | +| ID проекта | **обязательно** | ID проекта, из которого будут загружаться данные в виджет. Пример: `12345` | - | + +## Helm. Релизы + +Виджет позволяет отображать данные о Helm Releases в Kubernetes и производить rollback на предыдущие версии. + +Данные, отображаемые на виджете: + +* **Список релизов Helm**: информация о текущих релизах, созданных с помощью Helm в указанном Kubernetes пространстве. +* **Манифесты релизов**: манифесты, связанные с Helm-релизами в указанном Kubernetes пространстве. Это включает в себя файлы YAML, которые определяют конфигурацию и состояние ресурсов. +* **Values**: переменные, которые использовались для развертывания Helm-релизов. + +### Авторизация + +Конфигурация авторизации описана в разделе [внешний сервис Kubernetes](../external-services/#kubernetes). + +### Конфигурация + +| Название | Опциональность | Описание | Значение по умолчанию | +|----------------|-----------------|-------------------------------------------------------------------------------------|-----------------------| +| Kubernetes API | **обязательно** | URL Kubernetes API. Используется для получения данных из Kubernetes. | - | +| Namespace | опционально | Пространство имен, из которого будут загружаться данные в виджет. Пример: `default` | - | +| Релиз | опционально | Имя релиза, из которого будут загружаться данные в виджет. Пример: `my-release` | - | + +## Iframe + +Виджет позволяет отображать данные из внешнего источника. + +### Конфигурация + +| Название | Опциональность | Описание | Значение по умолчанию | +|------------|-----------------|----------------------------------------------------------------------------|-----------------------| +| URL | **обязательно** | URL внешнего источника. Используется для отображения данных в виджете. | - | + +## Kafka. ACLs + +Виджет позволяет отображать список ACLs кластера Kafka. + +Для каждого ACL отображается следующая информация: + +* Субъект +* Тип ресурса +* Шаблон +* Тип шаблона +* Хост +* Операция +* Тип разрешения + +### Аутентификация + +Для работы с виджетом требуется учётная запись пользователя. Система поддерживает следующие методы аутентификации: + +* PLAINTEXT +* SCRAM-SHA-256 +* SCRAM-SHA-512 + +### Конфигурация + +| Название | Опциональность | Описание | Значение по умолчанию | +|-------------------------|-----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------| +| URL | **обязательно** | URL Kafka кластера | - | +| Протокол аутентификации | **обязательно** | Протокол для подключения к Kafka. [Подробнее](https://kafka.apache.org/documentation/#adminclientconfigs_security.protocol) | - | +| Механизм SASL | опционально | Механизм аутентификации, который будет использовать SASL. Обязателен при использовании протокола SASL_PLAINTEXT или SASL_SSL. [Подробнее](https://kafka.apache.org/documentation/#security_sasl_mechanism) | - | +| Пользователь Kafka | **обязательно** | Username учётной записи для взаимодействия с Kafka | - | +| Пароль | **обязательно** | Пароль учётной записи для взаимодействия с Kafka | - | +| Типы ресурсов | опционально | Фильтр по типам ресурсов | - | +| Типы шаблонов | опционально | Фильтр по типам шаблонов | - | +| Операции | опционально | Фильтр по операциям | - | +| Типы разрешений | опционально | Фильтр по типам разрешений | - | +| Субъекты | опционально | Фильтр по субъектам. Поддерживается шаблонизация и регулярные выражения | - | +| Хосты | опционально | Фильтр по хостам. Поддерживается шаблонизация и регулярные выражения | - | + +### Дополнительные возможности виджета + +При активированной функции действий в настройках виджет позволяет: + +* Создавать новые правила ACL +* Удалять существующие правила ACL + +## Kafka. Топики + +Виджет позволяет отображать различные данные о Kafka топиках. + +Для каждого топика доступно: + +* Общая информация о топике: основные параметры, конфигурация и статус +* Информация о партициях:информацию о лидере, оффсетах +* Информация о консьюмерах: список активных потребителей, их группы, текущие офсеты и лаги +* Сообщения: просмотр содержимого сообщений топиков в удобном формате +* Поиск сообщений: фильтрация сообщений по timestamp и offset + +### Аутентификация + +Для работы с виджетом требуется учётная запись пользователя. Система поддерживает следующие методы аутентификации: + +* PLAINTEXT +* SCRAM-SHA-256 +* SCRAM-SHA-512 + +**Важно:** доступность информации в виджете определяется уровнем прав подключённой учётной записи. + +### Конфигурация + +| Название | Опциональность | Описание | Значение по умолчанию | +|-------------------------|-----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------| +| URL | **обязательно** | URL Kafka кластера | - | +| Протокол аутентификации | **обязательно** | Протокол для подключения к Kafka. [Подробнее](https://kafka.apache.org/documentation/#adminclientconfigs_security.protocol) | - | +| Механизм SASL | опционально | Механизм аутентификации, который будет использовать SASL. Обязателен при использовании протокола SASL_PLAINTEXT или SASL_SSL. [Подробнее](https://kafka.apache.org/documentation/#security_sasl_mechanism) | - | +| Пользователь Kafka | **обязательно** | username учётной записи для взаимодействия с Kafka | - | +| Пароль | **обязательно** | пароль учётной записи для взаимодействия с Kafka | - | +| Топики Kafka | опционально | Название топика или регулярное выражение для фильтрации отображаемых топиков в виджете; при пустом значении отображаются все доступные пользователю топики. | - | + +### Дополнительные возможности виджета + +При активированной функции действий в настройках виджет позволяет: + +* Создавать новые топики +* Удалять существующие топики +* Отправлять сообщение в топик +* Очищать топик от сообщений + +## Kubernetes deployments + +Виджет Kubernetes deployments позволяет выводить основную информацию обо всех deployments в Kubernetes кластере. Доступна фильтрация по namespace и/или по label selector. + +Для каждого deployment доступны: + +* Просмотр спецификации deployment и его статуса. +* Масштабирование количества реплик в deployment. Для применения масштабирования после выбора целевого количества реплик необходимо нажать на кнопку "сохранить" с иконкой дискеты. +* Просмотр информации о подах, которыми управляет deployment, и контейнерах данных подов, в том числе вывод логов каждого из контейнеров. +* Просмотр и редактирование ресурсов контейнеров. Виджет отображает все настроенные ресурсы контейнеров, включая CPU, Memory, ephemeral-storage и другие типы ресурсов. Редактирование доступно только для CPU и Memory в секциях requests и limits. Редактирование доступно на уровне deployment и применяется ко всем подам, управляемым deployment. При очистке полей CPU или Memory соответствующие ресурсы удаляются из конфигурации контейнера. Остальные ресурсы (например, ephemeral-storage) отображаются, но не могут быть отредактированы через виджет. + +### Авторизация + +Конфигурация авторизации описана в разделе [внешний сервис Kubernetes](../external-services/#kubernetes). + +### Конфигурация + +| Название | Опциональность | Описание | Значение по умолчанию | +|---------------------|-----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------| +| Kubernetes API | **обязательно** | URL API сервера Kubernetes. Используется для получения данных из Kubernetes | - | +| Namespace | опционально | Kubernetes namespace из которого будут загружаться deployment. В случае, если namespace не указан, виджет будет пытаться загрузить все deployment кластера. Пример: `default` | - | +| Label selector | опционально | Селекторы для фильтрации получаемых deployment. Перечисляются через запятую. Пример: `app.kubernetes.io/name=example` | - | + +## Kubernetes ingresses + +Виджет позволяет отображать данные о Ingress в платформе Kubernetes. + +Для каждого ingress доступны: + +* Просмотр спецификации ingress в виде yaml конфигурации +* Правила ingress +* Настройки TLS + +### Авторизация + +Конфигурация авторизации описана в разделе [внешний сервис Kubernetes](../external-services/#kubernetes). + +### Конфигурация + +| Название | Опциональность | Описание | Значение по умолчанию | +|----------------|-----------------|---------------------------------------------------------------------------------------------------------------------|-----------------------| +| URL | **обязательно** | URL API сервера Kubernetes. Используется для получения данных из Kubernetes | - | +| Namespace | опционально | Kubernetes namespace из которого будут загружаться ingresses. В случае, если namespace не указан, виджет будет пытаться загрузить все ingress кластера. Пример: `default` | - | +| Label selector | опционально | Селекторы для фильтрации получаемых ingress. Перечисляются через запятую. Пример: `app.kubernetes.io/name=example` | - | + +## Kubernetes pods + +Виджет позволяет отображать данные о pod в платформе Kubernetes. + +Для каждого pod доступны: + +* Просмотр спецификации pod в виде yaml конфигурации +* Логи контейнеров +* Различная информация о состоянии пода: статус, количество перезапусков и др. + +### Авторизация + +Конфигурация авторизации описана в разделе [внешний сервис Kubernetes](../external-services/#kubernetes). + +### Конфигурация + +| Название | Опциональность | Описание | Значение по умолчанию | +|----------------|-----------------|-----------------------------------------------------------------------------------------------------------------|-----------------------| +| URL | **обязательно** | URL API сервера Kubernetes. Используется для получения данных из Kubernetes | - | +| Namespace | опционально | Пространство имен, из которого будут загружаться данные в виджет. Пример: `default` | - | +| Label selector | опционально | Селекторы для фильтрации получаемых pod. Перечисляются через запятую. Пример: `app.kubernetes.io/name=example` | - | + +## Markdown + +Виджет обеспечивает отображение текста, написанного в формате Markdown. + +### Конфигурация + +| Название | Опциональность | Описание | Значение по умолчанию | +|------------|-----------------|---------------------------------------------------------------------------------------|-----------------------| +| Markdown | **обязательно** | Текст в формате Markdown. Отображается в виджете в отформатированном виде | - | + +## Nexus artifacts + +Виджет позволяет выводить список артефактов в репозитории Nexus. + +### Авторизация + +Конфигурация авторизации описана в разделе [внешний сервис Nexus](../external-services/#nexus). + +### Конфигурация + +| Название | Опциональность | Описание | Значение по умолчанию | +|------------|-----------------|-------------------------------------------------------------------------------------|-----------------------| +| URL | **обязательно** | URL Nexus API. Используется для получения данных из Nexus | - | +| Repository | **обязательно** | Имя репозитория, данные из которого будут отображаться в виджете. Пример: `my-repo` | - | +| Name | опционально | Имя артефакта, данные о котором будут отображаться в виджете | - | + +## Opensearch index + +Виджет Opensearch index позволяет отобразить данные из определенного index или index pattern в платформе. Данные по умолчанию сортируются от более новых к более старым. Доступен полнотекстовый поиск для фильтрации отображаемых данных. Для каждой записи (строки таблицы) доступно отображение в формате "ключ-значение", либо в JSON. При указании index pattern в виджете будет выводиться ссылка на страницу Discover в OpenSearch Dashboards. + +### Авторизация + +Конфигурация авторизации описана в разделе [внешний сервис OpenSearch](../external-services/#opensearch). + +### Конфигурация + +| Название | Опциональность | Описание | Значение по умолчанию | +|--------------------------|-----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------| +| API URL | **обязательно** | URL Opensearch API. Используется для получения данных из Opensearch | - | +| Dashboards URL | **обязательно** | URL Opensearch Dashboards. Используется при генерации ссылки для перехода в Opensearch и просмотра данных непосредственно в системе | - | +| Index pattern | **обязательно** | Название index pattern из которого будут загружаться данные в виджет. Может содержать символ "*". Примеры: `security-auditlog`, `security-auditlog-*` | - | +| Timestamp field | опционально | Название поля с timestamp. Значение поля выводится в таблице с данными в отдельной колонке | @timestamp | + +## Prometheus metrics (range) + +Виджет позволяет построить график из диапазона значений на основе метрики из Prometheus, задать для него единицу измерения и выбрать пороговое значение. Query, указанная в виджете, должна возвращать тип Scalar или тип Vector с одним значением. + +Пример корректной query для виджета: + +```sh +rate(nginx_ingress_controller_nginx_process_connections[5m]) +``` + +### Конфигурация + +| Название | Опциональность | Описание | Значение по умолчанию | +|-----------------------|-----------------|--------------------------------------------------------------------------------------------------------------------------------------|-----------------------| +| URL | **обязательно** | URL Prometheus | - | +| Query | **обязательно** | Query для запроса метрики из Prometheus в формате PromQL | - | +| Шаг разрешения (сек.) | **обязательно** | Интервал между отсчетами на горизонтальной оси (в секундах) | 60 | +| Метка | **обязательно** | Метка в результатах запроса, чье уникальное значение присваивается в качестве названий соответствующих линий на графике визуализации | - | +| Порог | опционально | Порог, отображаемый в виде горизонтальной красной полосы на графике | - | +| Минимальное значение | опционально | Начальная точка отсчета для вертикальной линии на графике | - | +| Максимальное значение | опционально | Предельная точка отсчета для вертикальной линии на графике | - | +| InsecureSkipVerify | опционально | Отключить проверку подлинности TLS/SSL-сертификата Prometheus | false | + +### Авторизация + +Конфигурация авторизации описана в разделе [внешний сервис Prometheus](../external-services/#prometheus). + +### Дополнительные возможности виджета + +При просмотре виджета возможно настроить диапазон отображаемых значений. Доступные параметры отображения диапазона: + +* Интервал +* Минимальное значение (начальная точка отсчета для вертикальной линии на графике) +* Максимальное значение (предельная точка отсчета для вертикальной линии на графике) + +## Prometheus metrics (single) + +Виджет позволяет вывести одно число на основе метрики из Prometheus, задать для него единицу измерения и выбрать пороговое значение. Query, указанная в виджете, должна возвращать тип Scalar или тип Vector с одним значением. + +Пример корректной query для виджета: + +```sh +sum(ingress_nginx_detail_requests_total) +``` + +### Конфигурация + +| Название | Опциональность | Описание | Значение по умолчанию | +|----------------------------------|-----------------|-------------------------------------------------------------------------------------------------------------------------------|-----------------------| +| URL | **обязательно** | URL Prometheus | - | +| Query | **обязательно** | Query для запроса метрики из Prometheus в формате PromQL | - | +| Количество цифр после запятой | опционально | Точность, с которой будет выводиться полученное значение | - | +| Единица измерения | опционально | Постфикс, с которым будет выводиться полученное значение | - | +| Отображать пороговое значение | опционально | Отображать пороговое значение в формате <значение метрики> / <пороговое значение> | false | +| Пороговое значение | опционально | Пороговое значение | - | +| Меньшее значение считается лучше | опционально | Метрика считается «хорошей», когда её значение ниже заданного порогового значения | false | +| Порог предупреждения (%) | опционально | Граница между красным и оранжевым цветами. Если значение метрики превышает этот процент от порога, оно получит оранжевый цвет | 60 | +| Порог успеха (%) | опционально | Граница между оранжевым и зелёным цветами. Если значение метрики превышает этот процент от порога, оно получит зеленый цвет | 90 | +| InsecureSkipVerify | опционально | Отключить проверку подлинности TLS/SSL-сертификата Prometheus | false | + +### Авторизация + +Конфигурация авторизации описана в разделе [внешний сервис Prometheus](../external-services/#prometheus). + +## Sonarqube + +Виджет позволяет отображать данные о метриках в платформе SonarQube. + +### Авторизация + +Конфигурация авторизации описана в разделе [внешний сервис SonarQube](../external-services/#sonarqube). + +### Конфигурация + +| Название | Опциональность | Описание | Значение по умолчанию | +|--------------|-----------------|--------------------------------------------------------------------------------------------|-----------------------------------------| +| URL | **обязательно** | Адрес SonarQube, например, `https://sonarqube.example.com` | - | +| Ключ проекта | **обязательно** | Идентификатор проекта в SonarQube | - | +| Ветка | опционально | Ветка проекта для которой будут браться метрики | Согласно настройкам проекта в Sonarqube | +| Метрики | **обязательно** | Метрики проекта, которые будут выводиться в виджете. В конфигурации указывается Metric key | | + +[Список возможных метрик](https://docs.sonarsource.com/sonarqube-server/latest/user-guide/code-metrics/metrics-definition) для текущей версии SonarQube. + +### Дополнительные возможности виджета + +Виджет позволяет просматривать данные не только для ветки по умолчанию, но и для любой другой ветки. + +## S3 bucket + +Виджет позволяет просматривать содержимое S3-совместимых хранилищ объектов, таких как Amazon S3, Yandex Object Storage, MinIO и другие. + +Для каждого объекта доступно: + +* Просмотр списка объектов в bucket с информацией о размере, дате изменения и классе хранения +* Поиск объектов по префиксу (пути) +* Загрузка файлов из bucket +* Просмотр детальной метаинформации объектов (размер, тип контента, метаданные, настройки кэширования и т.д.) +* Навигация по папкам bucket + +### Аутентификация + +Для работы с виджетом требуется учётная запись с правами доступа к S3 bucket. Система поддерживает следующие методы аутентификации: + +* Access Key ID и Secret Access Key +* Поддержка различных S3-совместимых провайдеров через настройку endpoint + +**Важно:** в отличие от других виджетов, S3 Bucket виджет не поддерживает использование внешних сервисов для передачи учётных данных. Все параметры аутентификации указываются непосредственно в конфигурации виджета. + +### Использование шаблонов для учётных данных + +Для повышения безопасности можно использовать механизм шаблонизации с учётными данными: + +* `{{ .credentials.accessKeyId }}` - подставить Access Key ID из учётных данных +* `{{ .credentials.secretAccessKey }}` - подставить Secret Access Key из учётных данных + +**Важно:** доступность информации в виджете определяется уровнем прав подключённой учётной записи. + +### Конфигурация + +| Название | Опциональность | Описание | Значение по умолчанию | +|--------------------|-----------------|---------------------------------------------------------------------------------------|-----------------------| +| Название bucket | **обязательно** | Название S3 bucket для просмотра | - | +| Endpoint | **обязательно** | URL endpoint S3-совместимого хранилища (например, `https://storage.yandexcloud.net`) | - | +| Регион | **обязательно** | Регион, в котором находится bucket | - | +| Access Key ID | **обязательно** | Идентификатор ключа доступа для аутентификации | - | +| Secret Access Key | **обязательно** | Секретный ключ доступа для аутентификации | - | +| Префикс | опционально | Префикс (путь) для фильтрации объектов при первоначальной загрузке | - | +| Максимум объектов | опционально | Максимальное количество объектов для отображения за один запрос (по умолчанию 100) | 100 | + +### Дополнительные возможности виджета + +### Поиск объектов + +Виджет позволяет искать объекты по префиксу (пути). При поиске список объектов обновляется в соответствии с заданным префиксом. + +**Важно:** поиск работает только если вводить символы с начала названия объекта. Поиск по символам из середины названия не поддерживается. + +**Ограничение поиска:** если в конфигурации виджета задан изначальный префикс, то поиском в самом виджете уже не получится подгрузить файлы с другим префиксом. Поиск будет работать только в рамках заданного изначального префикса. + +### Загрузка файлов + +Виджет позволяет загружать файлы из bucket напрямую в браузер. Для каждого файла доступна кнопка загрузки. + +### Детальная информация об объектах + +При клике на иконку документа для каждого объекта отображается детальная информация: + +* Основные параметры: ключ, размер, дата изменения, класс хранения, тип контента, ETag +* Информация о контенте: кодировка, язык, диспозиция +* Настройки кэширования: Cache-Control, срок действия +* Безопасность: серверное шифрование +* Пользовательские метаданные + +### Подгрузка дополнительных объектов + +При наличии большого количества объектов в bucket доступна функция "Загрузить еще" для пошаговой загрузки объектов без потери производительности. + +## График + +Виджет позволяет выводить информацию об объектах DDP в виде одного из следующих типов графиков: + +* Столбчатая диаграмма +* Кольцевая диаграмма +* Круговая диаграмма +* Полярная диаграмма +* Радарная диаграмма + +### Конфигурация + +| Название | Опциональность | Описание | Значение по умолчанию | +|---------------------|-----------------|--------------------------------------------------------------------------------------------|------------------------| +| Тип графика | **обязательно** | Тип визуализации графика | - | +| Название таблицы | **обязательно** | Название таблицы в базе данных, из которой будут браться записи для визуализации | - | +| Название поля | **обязательно** | Название поля, по которому будет происходить агрегация записей | - | +| Фильтры | опционально | Поля, по которым будут фильтроваться полученные записи, и их значения | - | +| Тип агрегации | **обязательно** | Принцип, по которому будут группироваться полученные записи | - | +| Параметры агрегации | опционально | Выбор временного периода и шага группировки при агрегации записей по дате | - | + +При настройке виджета следует учитывать, что названия полей в базе данных могут отличаться от названий полей в спецификации объектов. Общий принцип таков: формат camelCase в спецификации объектов при сохранении структур в базу данных преобразуется в snake_case. Например: + +* Поле `createdAt` в спецификации следует указывать в конфигурации виджета как `created_at` +* Поле `resourceUuid` в спецификации следует указывать в конфигурации виджета как `resource_uuid` + +Доступно обращение к вложенным значениям. В таком случае разделителем для вложенности служит символ точки. Например, чтобы выполнить агрегацию по статусу сущностей, виджет следует настроить следующим образом: + +| Название таблицы | Название поля | +|-------------------|-------------------| +| `entities` | `health.status` | + +### Типы агрегации + +#### Дата + +Данные на графике будут отсортированы и сгруппированы по выбранным временным интервалам. + +В параметрах агрегации можно задать: + +- **Единицу измерения шага** — например: секунды, минуты, часы, дни и т.д. +- **Количество единиц в одном шаге** — например: 5 минут, 2 часа, 1 день и т.п. + +Это позволяет управлять детализацией отображения данных во времени и адаптировать график под нужный масштаб анализа. + +#### Значение + +Данные на графике отображаются в отсортированном порядке — по значениям. +Для каждого уникального значения в исходном наборе данных: + +- Выполняется подсчёт количества вхождений. +- На графике отображается пара: **значение - количество**. + +Это позволяет быстро увидеть распределение и частоту повторения различных значений. + +#### Разбивка по интервалам + +Тип агрегации **«Разбивка по интервалам»** позволяет гибко настроить отображение данных на графике, разделяя значения по заданным числовым диапазонам (интервалам). Это удобно для построения гистограмм и анализа распределения данных. + +Доступны два режима настройки интервалов: + +1. **Автоматическая разбивка по количеству интервалов** + + Указывается только количество интервалов, на которые нужно разделить доступные данные. + Интервалы будут рассчитаны автоматически — равномерно от минимального до максимального значения. + +2. **Ручное задание границ интервалов** + + Указывается массив числовых границ интервалов. + Например: `0, 10, 20, 50` + + В этом случае: + + - Числа будут автоматически отсортированы по возрастанию. + - Интервалы сформируются на основе отсортированных значений: + `[0, 10)`, `[10, 20)`, `[20, 50]` + +В параметрах агрегации должно быть указано хотя бы одно из двух: + +- `Количество` — количество интервалов, +- `Границы` — границы интервалов. + +Примеры: + +- `Количество = 5` - построится 5 равных интервалов на основании данных. +- `Границы = 100, 0, 50` - после сортировки: `[0, 50, 100]`, график будет построен по интервалам `[0, 50)`, `[50, 100]`. + +## Квоты ресурсов Kubernetes + +Виджет позволяет отображать данные о квотах ресурсов в платформе Kubernetes. + +Для каждой квоты происходит визуализация занятых ресурсов. + +### Авторизация + +Конфигурация авторизации описана в разделе [внешний сервис Kubernetes](../external-services/#kubernetes). + +### Конфигурация + +| Название | Опциональность | Описание | Значение по умолчанию | +|----------------|-----------------|-----------------------------------------------------------------------------------------------------------------|-----------------------| +| URL | **обязательно** | URL API сервера Kubernetes. Используется для получения данных из Kubernetes | - | +| Namespace | **обязательно** | Пространство имен, из которого будут загружаться данные в виджет. Пример: `default` | - | + +## Процентное значение + +Виджет позволяет отображать заданное процентное значение. + +### Конфигурация + +| Название | Опционально | Описание | Значение по умолчанию | +|---------------------|-------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------| +| Ресурс | опционально | Ресурс, из которого извлекаются необходимые значения при обработке шаблона | - | +| Процентное значение | опционально | Значение, которое будет выводиться на виджет. Шаблонизация поддерживается. Пример без шаблонизации: `100`. Пример с шаблонизацией: `{{ .entity.propeties.id }}` | - | + +## Таблицы сущностей + +Виджет позволяет отображать сущности, созданные в платформе DDP, в виде таблицы. + +### Конфигурация + +| Название | Опционально | Описание | Значение по умолчанию | +|---------------------|-------------|-----------------------------------------------------------------------------------------------------------------------|-----------------------| +| Источник | опционально | Сущности, которые необходимо отобразить в виде таблицы | - | +| Показывать действия | опционально | Необходимость отображения действия с сущностями (возможность запуска действий, сценарием, возможность удаления и др.) | false | + +## Статистика событий + +Виджет отображает статистику событий, происходящих с сущностями в платформе DDP. Виджет содержит три таба: + +1. **Статистика событий** - график, показывающий количество событий по типам за выбранный временной период с настраиваемой группировкой по времени +2. **Топ сущностей** - таблица с сущностями, для которых было сгенерировано максимальное количество событий +3. **События в Redis** - таблица со стримами событий из Redis, показывающая для каждого стрима: + - Название стрима (кликабельное для просмотра всех событий) + - Ресурс, к которому относится стрим + - Количество событий в стриме + - Информацию о последнем событии (сущность, ресурс, тип события, время) + +### Параметры запроса + +| Название | Опционально | Описание | Значение по умолчанию | +|-----------------|-------------|--------------------------------------------------------------------------------------------|-----------------------| +| Дата от | обязательно | Начальная дата для выборки событий | 3 дня назад | +| Дата до | обязательно | Конечная дата для выборки событий | текущая дата | +| Интервал | опционально | Интервал группировки событий на графике (секунды, минуты, часы, дни, недели, месяцы, годы) | час | +| Шаг интервала | опционально | Количество единиц интервала для группировки | 1 | +| Топ сущностей | опционально | Количество сущностей с максимальным количеством событий для отображения в таблице | 10 | + +### Типы событий + +Виджет поддерживает следующие типы событий: + +- **ENTITY_CREATED** - создание сущности +- **ENTITY_UPDATED** - обновление сущности +- **ENTITY_DELETED** - удаление сущности + +#### Особенности + +- График показывает события за выбранный временной период с настраиваемой группировкой по времени (по умолчанию - по часам) +- Таблица отображает все события для каждой сущности (без фильтрации по дате) +- Для удаленных сущностей отображается их имя, извлеченное из спецификации события +- Таб "События в Redis" позволяет отслеживать события, хранящиеся в Redis Streams: + - Для каждого стрима отображается количество событий и информация о последнем событии + - При клике на название стрима открывается диалог со всеми событиями из этого стрима + - Стримы автоматически привязываются к ресурсам по UUID, указанному в названии стрима + - При просмотре событий из стрима отображаются последние 1000 событий (новые первыми). Если в стриме больше 1000 событий, более старые события не отображаются +- Каждая строка в таблице содержит информацию о последнем событии для сущности +- Доступен просмотр детальной истории изменений для каждой сущности +- События для удаленных ресурсов не отображаются (удаляются из БД при удалении ресурса) + +## Числовое значение + +Виджет позволяет отображать заданное числовое значение. + +### Конфигурация + +| Название | Опционально | Описание | Значение по умолчанию | +|-------------------|-------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------| +| Ресурс | опционально | Ресурс, из которого извлекаются необходимые значения при обработке шаблона | - | +| Числовое значение | опционально | Значение, которое будет выводиться на виджет. Шаблонизация поддерживается. Пример без шаблонизации: `100`. Пример с шаблонизацией: `{{ .entity.propeties.id }}` | - | + +## Kaiten. Карточки пространства + +Виджет позволяет отображать структуру задач в пространстве Kaiten в виде многоуровневой таблицы **Доска → Карточки**, просматривать задачи на всех уровнях организации работы и получать информацию о критичных параметрах карточек (статус, срочность, блокировки, исполнители и др.). + +### Конфигурация + +| Название | Опциональность | Описание | Значение по умолчанию | +|-----------------|-----------------|-------------------------------------|-----------------------| +| ID пространства | **обязательно** | Идентификатор пространства в Kaiten | - | + +### Параметры запроса + +| Название | Опциональность | Описание | Значение по умолчанию | +|---------------|-----------------|---------------------------------|-----------------------| +| Мои задачи | опционально | Фильтр по текущему пользователю | false | +| Создано после | **обязательно** | Начальная дата для выборки | 1 месяц назад | +| Создано до | **обязательно** | Конечная дата для выборки | сейчас | + +### Авторизация + +Конфигурация авторизации описана в разделе [внешний сервис Kaiten](../external-services/#kaiten). + +### Отображаемые данные + +Каждая карточка содержит: +- Название карточки +- Колонка (статус в доске) +- Статус (очередь,в работе, готово) +- Линия +- Владелец (аватар, имя, email) +- Участники +- Срок (дата дедлайна, срочность) +- Блокированная/незаблокированная + +## Kaiten. Статистика пространства + +Виджет предоставляет агрегированные метрики и статистику карточек пространства Kaiten за выбранный период. Позволяет анализировать эффективность работы команды и выявлять узкие места в бизнес-процессах. + +### Конфигурация + +| Название | Опциональность | Описание | Значение по умолчанию | +|-----------------|-----------------|------------------------------------ |-----------------------| +| ID пространства | **обязательно** | Идентификатор пространства в Kaiten | - | + +### Параметры запроса + +| Название | Опциональность | Описание | Значение по умолчанию | +|---------------|-----------------|----------------------------|-----------------------| +| Создано после | **обязательно** | Начальная дата для анализа | 1 месяц назад | +| Создано до | **обязательно** | Конечная дата для анализа | сейчас | + +### Авторизация + +Конфигурация авторизации описана в разделе [внешний сервис Kaiten](../external-services/#kaiten). + +### Отображаемые данные + +Виджет содержит четыре вкладки: + +#### Общие показатели + +Основные метрики: + +- В очереди: задачи в очереди на выполнение +- Выполнено: завершенные задачи +- В работе: активные задачи + +Дополнительные метрики: + +- Заблокировано: количество заблокированных задач +- Блокирующих: количество задач, блокирующих другие +- Архивировано: количество задач в архиве +- Срочных: количество срочных задач +- В среднем на выполнение: среднее время выполнения (в минутах) + +Статистика по чеклистам: + +- Всего с чеклистом: общее количество задач с чеклистами +- Чеклист полностью выполнен: задачи с полностью выполненными чеклистами +- Чеклист не выполнен: задачи с невыполненными чеклистами + +#### По пользователю + +- Список пользователей с количеством назначенных задач +- Визуализация в виде прогресс-баров +- Количество задач на каждого пользователя + +#### Забытые задачи + +Карточки, которые не обновлялись с момента создания + +#### Последние обновленные + +Десять последних обновленных карточек + +## Очередь задач + +Виджет позволяет отслеживать состояние очереди задач и работу воркеров, обрабатывающих задачи в фоновом режиме. Виджет отображает статистику очереди, информацию о воркерах (консьюмерах) и детали всех задач в очереди. + +### Отображаемые данные + +Виджет состоит из трех основных разделов: + +#### Статистика очереди + +В верхней части виджета отображаются четыре ключевых показателя: + +- **Размер очереди** — общее количество задач в очереди +- **Ожидающие задачи** — количество задач, ожидающих обработки +- **Активные воркеры** — количество активных воркеров (консьюмеров), обрабатывающих задачи +- **Задачи в очереди** — общее количество задач, включая новые и обрабатываемые + +#### Таблица воркеров + +Таблица содержит информацию о каждом активном воркере: + +- **Имя воркера** — идентификатор воркера (консьюмера) +- **Ожидающие задачи** — количество задач, назначенных данному воркеру и ожидающих обработки +- **Время простоя** — время с момента последней активности воркера + +**Важно:** В таблице отображаются только активные воркеры. Воркеры, которые не обрабатывают задачи и неактивны более 5 минут, автоматически скрываются из списка. + +#### Таблица задач + +Таблица содержит детальную информацию о всех задачах в очереди: + +- **UUID задачи** — уникальный идентификатор задачи +- **Тип** — тип задачи (например, `health_check`) +- **UUID ресурса** — идентификатор ресурса или сущности, к которой относится задача +- **Воркер** — имя воркера, обрабатывающего задачу (если задача назначена воркеру) +- **Время простоя** — время с момента доставки задачи воркеру +- **Время доставки** — время, когда задача была доставлена воркеру +- **Статус** — текущий статус задачи: + - **Новая** — задача добавлена в очередь, но еще не назначена воркеру + - **В обработке** — задача назначена воркеру и обрабатывается + +### Конфигурация + +Виджет не требует дополнительной конфигурации и работает сразу после добавления на дашборд. diff --git a/content/documentation/admin/workers.ru.md b/content/documentation/admin/workers.ru.md new file mode 100644 index 0000000..ddb365f --- /dev/null +++ b/content/documentation/admin/workers.ru.md @@ -0,0 +1,109 @@ +--- +title: Воркеры +--- + +Воркеры — это компоненты платформы, которые обрабатывают задачи из очереди в фоновом режиме. Они обеспечивают асинхронное выполнение различных операций, таких как: + +- Синхронизация данных из источников данных +- Выполнение действий +- Проверки здоровья сущностей (health checks) + +Воркеры работают независимо от основного приложения и позволяют разгрузить основной сервер, перенося длительные операции в фоновый режим. + +## Конфигурация + +Воркеры настраиваются через конфигурацию платформы. Доступны следующие параметры: + +### Количество реплик + +Параметр `workers.replicas` определяет количество одновременно работающих воркеров. Каждый воркер может обрабатывать задачи независимо от других. + +### Максимальное количество параллельных задач + +Параметр `workers.maxTasks` определяет, сколько задач может обрабатываться параллельно каждым воркером. + +**Важно:** Общее количество задач, обрабатываемых одновременно всей системой, рассчитывается как `workers.replicas × workers.maxTasks`. Например, при 2 воркерах и 10 задачах на воркер система может обрабатывать до 20 задач одновременно. + +## Мониторинг + +Для мониторинга работы воркеров и очереди задач доступен виджет **Очередь задач** ([подробнее](./widgets/types#очередь-задач)), который отображает: + +- Размер очереди (общее количество задач) +- Количество ожидающих задач +- Количество активных воркеров (консьюмеров) +- Детальную информацию о задачах в очереди +- Статус каждой задачи (новая, в обработке) + +## Настройка через переменные окружения + +Параметры воркеров также можно настроить через переменные окружения: + +- `WORKER_MAX_TASKS` — максимальное количество параллельных задач на воркер (по умолчанию: 10) + +**Пример:** + +```bash +export WORKER_MAX_TASKS=15 +``` + +**Приоритет настроек:** +1. Значение из конфигурационного файла +2. Значение из переменной окружения +3. Значение по умолчанию + +## Типы обрабатываемых задач + +Воркеры обрабатывают следующие типы задач: + +### Health Check задачи + +Задачи проверки здоровья сущностей выполняются воркерами для определения статуса сущностей на основе настроенных правил. Это позволяет: + +- Разгрузить основной сервер от выполнения проверок +- Обеспечить стабильность работы при большом количестве сущностей +- Гарантировать выполнение проверок даже при высокой нагрузке на основное приложение + +### Задачи синхронизации источников данных + +Воркеры обрабатывают задачи синхронизации данных из внешних источников, что позволяет: + +- Выполнять синхронизацию в фоновом режиме +- Не блокировать интерфейс пользователя +- Обрабатывать большие объемы данных + +### Задачи выполнения действий + +Действия, требующие длительного выполнения, обрабатываются воркерами, что обеспечивает: + +- Асинхронное выполнение действий +- Возможность отслеживания прогресса выполнения +- Стабильность работы интерфейса + +## Масштабирование + +При необходимости увеличения производительности системы можно: + +1. **Увеличить количество реплик воркеров** — это позволит обрабатывать больше задач одновременно +2. **Увеличить количество параллельных задач на воркер** — это повысит утилизацию каждого воркера + +**Важно:** При увеличении нагрузки на воркеры необходимо убедиться, что у кластера достаточно ресурсов (CPU, память) для обработки всех задач. + +## Устранение проблем + +### Воркеры не обрабатывают задачи + +Если задачи накапливаются в очереди и не обрабатываются: + +1. Проверьте, что воркеры развернуты и работают (через виджет Task Queue) +2. Убедитесь, что количество реплик воркеров больше 0 +3. Проверьте логи воркеров на наличие ошибок +4. Убедитесь, что у воркеров достаточно ресурсов (CPU, память) + +### Медленная обработка задач + +Если задачи обрабатываются медленно: + +1. Увеличьте количество реплик воркеров +2. Увеличьте количество параллельных задач на воркер (если позволяет ресурсная база) +3. Проверьте производительность внешних систем, с которыми работают воркеры +4. Убедитесь, что нет узких мест в сети или базе данных diff --git a/content/documentation/admin/workflows.ru.md b/content/documentation/admin/workflows.ru.md new file mode 100644 index 0000000..85df7e1 --- /dev/null +++ b/content/documentation/admin/workflows.ru.md @@ -0,0 +1,31 @@ +--- +title: Сценарии +menuTitle: Сценарии +d8Edition: ee +moduleStatus: experimental +--- + +Сценарии - механизм, позволяющий объединять действия в цепочку, управляя ходом выполнения. + +Сценарии, как и действия привязываются к конкретным ресурсам и могут быть запущены только для сущностей того ресурса, к которому они привязаны. + +### Тип запуска действий + +Действия в одном сценарии могут запускаться параллельно, либо последовательно. + +При выборе параллельного запуска все действия запустятся одновременно. При выборе последовательного запуска, действия будут запускаться в порядке их расположения в списке действий сценария. При этом, если одно из действий выполнилось неуспешно, все последующие будут созданы, но не будут запущены. + +> При выборе последовательного запуска и в случае, если какое-либо из вышестоящих действий требует подтверждения, следующие за ним запустятся сразу после того, как данное действие перейдет в статус "Unapproved". + +Каждое действие сценария может быть обязательным, либо опциональным: + +* Если действие является обязательным для сценария, то пользователь, запускающий сценарий, не может выключить выполнение данного действия. +* Если действие является опциональным, то при запуске сценария пользователь может отключить его и действие не запустится. + +### Запуск сценария + +При запуске сценария пользователю будет предложена форма, в которой он сможет заполнить параметры запуска каждого действия, входящего в сценарий. При этом, если действие является опциональным, оно может быть выключено. + +### Параметры сценария + +Конфигурация и использование параметров сценария описаны в разделе [шаблонизация](../user/templating.html#параметры-сценария). diff --git a/content/documentation/release-notes.ru.md b/content/documentation/release-notes.ru.md new file mode 100644 index 0000000..23c8e70 --- /dev/null +++ b/content/documentation/release-notes.ru.md @@ -0,0 +1,232 @@ +--- +title: История изменений +--- + +## v1.1.0 + +### Новые возможности + +#### Виджеты + +##### Kubernetes deployments + +Обновлен виджет Kubernetes deployments ([подробнее](../admin/widgets/types/#kubernetes-deployments)): + +* Добавлена возможность просмотра и редактирования ресурсов контейнеров (CPU и Memory для requests и limits) + +##### Статистика событий + +Обновлен виджет Статистика событий ([подробнее](../admin/widgets/types/#статистика-событий)): + +* Добавлен таб "События в Redis" для отслеживания событий, хранящихся в Redis Streams + +##### CodeScoring виджеты + +Добавлены виджеты для интеграции с платформой анализа безопасности кода CodeScoring: + +- **CodeScoring. Зависимости** — просмотр зависимостей продукта с информацией о версиях, лицензиях и количестве уязвимостей ([подробнее](../admin/widgets/types/#codescoring-зависимости)) +- **CodeScoring. Уязвимости** — таблица уязвимостей с уровнем критичности (CVSS2/CVSS3), наличием эксплойта и исправленными версиями ([подробнее](../admin/widgets/types/#codescoring-уязвимости)) + +Оба виджета поддерживают запуск и отмену SCA-анализа, пагинацию и фильтрацию данных. + +##### Очередь задач + +Добавлен виджет **Очередь задач** для мониторинга очереди задач и работы воркеров ([подробнее](../admin/widgets/types/#очередь-задач)): + +- **Статистика очереди** — размер очереди, количество ожидающих задач, активных воркеров +- **Таблица воркеров** — информация о каждом активном воркере (имя, ожидающие задачи, время простоя) +- **Таблица задач** — детальная информация о всех задачах в очереди с их статусами +- **Фильтрация неактивных воркеров** — автоматическое скрытие воркеров, неактивных более 5 минут + +Виджет не требует дополнительной конфигурации и может быть добавлен на любой дашборд. + +#### Воркеры + +Добавлена поддержка воркеров для асинхронной обработки задач ([подробнее](../admin/workers/)): + +- **Фоновая обработка задач** — задачи выполняются в фоновом режиме, не блокируя основной сервер +- **Масштабируемость** — настраиваемое количество реплик воркеров и параллельных задач + +**Параметры конфигурации:** +- `workers.replicas` — количество реплик воркеров (по умолчанию: 2) +- `workers.maxTasks` — максимальное количество параллельных задач на воркер (по умолчанию: 10) + +#### Проверки статуса + +##### CodeScoring Vulnerabilities + +Добавлена проверка статуса для CodeScoring ([подробнее](../admin/healthchecks/types/#codescoring-vulnerabilities)): + +- **CodeScoring Vulnerabilities** — проверка количества уязвимостей по CVSS2 и CVSS3 метрикам для проекта в CodeScoring с настраиваемыми пороговыми значениями для каждого уровня критичности + +##### SonarQube Quality Gate + +Добавлена проверка статуса для SonarQube Quality Gate ([подробнее](../admin/healthchecks/types/#sonarqube-quality-gate)): + +- **SonarQube Quality Gate** — проверка статуса Quality Gate проекта в SonarQube + +#### Действия + +##### CodeScoring + +Добавлены действия для работы с CodeScoring: + +- **CreateCodeScoringProject** — регистрирует новый проект в CodeScoring с указанием репозитория, VCS системы и опцией автоматического запуска SCA-анализа ([подробнее](../admin/actions/types/#createcodescoringproject)) +- **DeleteCodeScoringProject** — удаляет проект в CodeScoring по его ID ([подробнее](../admin/actions/types/#deletecodescoringproject)) + +## v1.0.1 + +### Новые возможности + +#### Действия + +##### HashiCorp Vault + +Обновлено действие: +- **CreateVaultSecret** — добавлен параметр `allow_update`. При значении `true` действие создаст новую версию секрета, если секрет с таким именем уже существует. При значении `false` действие вернёт ошибку, если секрет уже существует + +Добавлено новое действие: +- **DeleteVaultSecret** - удаляет секрет из HashiCorp Vault + +### Исправленные проблемы + +- Исправлена ошибка с датой создания действия при его перезапуске + +## v1.0.0 + +### Новые возможности + +#### Виджеты + +##### Kaiten виджеты + +Добавлены два виджета для интеграции с платформой управления проектами Kaiten ([подробнее](../admin/widgets/types/#kaiten-карточки-пространства)): + +- **Kaiten. Карточки пространства** — позволяет просматривать задачи в пространстве + - Многоуровневое отображение: Доска → Карточки + - Фильтрация по текущему пользователю и диапазону дат создания + - Отображение статусов, владельцев, участников, сроков и блокировок + +- **Kaiten. Статистика пространства** — аналитика и метрики по задачам + - Общие показатели (в очереди, в работе, выполнено) + - Статистика по пользователям и чеклистам + - Забытые и последние обновленные карточки + - Среднее время выполнения задач + +##### Kafka виджеты + +Расширены возможности работы с Kafka ([подробнее](../admin/widgets/types/#kafka-acls)): + +- **Действия для виджета Kafka Topics** — добавлена возможность: + - Создавать новые топики + - Удалять существующие топики + - Отправлять сообщения в топик + - Очищать топик от сообщений + +- **Виджет Kafka ACLs** — управление доступом в Kafka кластере + - Просмотр списка правил доступа (ACL) кластера Kafka + - Фильтрация по типам ресурсов, шаблонам, операциям и разрешениям + - Создание и удаление правил доступа + +##### GitLab виджеты + +Новые возможности для работы с GitLab: + +- **Редактор пайплайна** — редактирование `.gitlab-ci.yml` ([подробнее](../admin/widgets/types/#gitlab-редактор-пайплайна)) + - Редактирование конфигурации пайплайнов + - Просмотр различий между версиями + - Создание Merge Requests с изменениями + +- **Статистика пайплайнов** — аналитика по пайплайнам ([подробнее](../admin/widgets/types/#gitlab-статистика-пайплайнов)) + - Общие метрики (количество, процент успеха/неудач, средняя длительность) + - Распределение по статусам и источникам + - Статистика по участникам и веткам + +Расширены возможности виджета **Запросы слияния** ([подробнее](../admin/widgets/types/#gitlab-запросы-слияния)): +- **Действия виджета** — добавлена возможность выполнения действий с Merge Requests: + - Слияние и закрытие MR + - Изменение статуса черновика + - Просмотр изменений в дифф-редакторе + +##### S3 bucket виджет + +Добавлен виджет для работы с S3-совместимыми хранилищами ([подробнее](../admin/widgets/types/#s3-bucket)): +- Просмотр содержимого бакета +- Поиск объектов по префиксу +- Загрузка файлов из бакета +- Просмотр детальной информации об объектах (метаданные, кэширование, шифрование) +- Поддержка AWS S3, Yandex Object Storage, MinIO + +##### Виджет статистики событий + +Виджет для анализа событий сущностей в системе ([подробнее](../admin/widgets/types/#статистика-событий)): +- График событий по типам за выбранный период +- Топ сущностей по количеству событий +- Настраиваемая группировка по времени +- История изменений для каждой сущности + +#### Источники данных + +##### GenericAPI + +Добавлен тип источника данных **Generic API** для работы с произвольными инфраструктурными сервисами ([подробнее](../admin/datasources/types/#genericapi)): +- Подключение к любому сервису, имеющему REST API +- Поддержка разных типов пагинации для получения больших объемов данных +- Настраиваемые параметры запросов (заголовки, авторизация, query параметры) + +#### Действия + +##### Nexus + +Добавлены действия для работы с репозиториями Nexus ([подробнее](../admin/actions/types/#createnexusrepository)): +- **CreateNexusRepository** — создает репозитории любого поддерживаемого типа (maven, docker, npm и др.) в Nexus Repository Manager 3 +- **DeleteNexusRepository** — удаляет репозитории из Nexus Repository Manager 3 + +#### Наборы данных + +##### GitLab + +Добавлен набор данных **GitLab** для быстрого подключения к GitLab и начала сбора и анализа репозиториев ([подробнее](../admin/datasets/#gitlab)): +- Преднастроенные дашборды для статистики и управления репозиториями +- Готовые виджеты для аналитики пайплайнов +- Автоматическая настройка внешнего сервиса и источника данных +- Синхронизация репозиториев GitLab в каталог платформы + +#### Улучшения функциональности + +##### Внешние сервисы + +Добавлен механизм внешними сервисами ([подробнее](../admin/external-services/)): +- Централизованная настройка подключений к инфраструктурным сервисам +- Переиспользование настроек подключений для виджетов, действий, источников данных и проверок статуса + +#### Ролевая модель + +Добавлены новые разрешения: +- `control:processes` - управление процессами: запуск, остановка и удаление запущенных процессов +- `run:widget-actions` - выполнение действий виджетов + +### Исправленные проблемы + +#### Виджеты + +- Исправлена кнопка перезагрузки виджета на карточке сущности +- Исправлена ошибка с отображением логов действий виджетов + +#### Сущности и таблицы + +- Исправлена функция массового удаления в таблице сущностей +- Исправлена кнопка удаления нескольких сущностей, теперь она отключается, когда не выбрано ни одной сущности +- Исправлено удаление сущности с глобальными правами доступа + +#### Процессы и автоматизации + +- Добавлен статус "Частично завершено" для задач в процессах +- Исправлены ошибки с историей процессов +- Добавлена информация о запусках действий в истории процесса +- Исправлена потоковая передача логов через WebSocket при запуске действий +- Исправлено удаление связей сущностей после выполнения автоматизации + +#### Самообслуживание и каталог + +- Исправлена сортировка по ресурсу на страницах раздела `Самообслуживание` diff --git a/content/documentation/section1/DOC.md b/content/documentation/section1/DOC.md deleted file mode 100644 index 293c591..0000000 --- a/content/documentation/section1/DOC.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: Doc 1 ---- - -{{< alert level="warning" >}} -Example -{{< /alert >}} - -This is doc 1 diff --git a/content/documentation/section1/DOC.ru.md b/content/documentation/section1/DOC.ru.md deleted file mode 100644 index 9f217ac..0000000 --- a/content/documentation/section1/DOC.ru.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: Документ 1 ---- - -{{< alert level="warning" >}} -Пример -{{< /alert >}} - -Это пример документа. diff --git a/content/documentation/section1/_index.md b/content/documentation/section1/_index.md deleted file mode 100644 index 7ad2972..0000000 --- a/content/documentation/section1/_index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Section1 -weight: 60 ---- - -Section 1 diff --git a/content/documentation/section1/_index.ru.md b/content/documentation/section1/_index.ru.md deleted file mode 100644 index 845f816..0000000 --- a/content/documentation/section1/_index.ru.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Раздел 1 -weight: 60 ---- - -Раздел 1 diff --git a/content/documentation/section2/_index.md b/content/documentation/section2/_index.md deleted file mode 100644 index 91a9717..0000000 --- a/content/documentation/section2/_index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Section2 -weight: 20 ---- - -Section 2 diff --git a/content/documentation/section2/_index.ru.md b/content/documentation/section2/_index.ru.md deleted file mode 100644 index c459316..0000000 --- a/content/documentation/section2/_index.ru.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Раздел 2 -weight: 20 ---- - -Раздел 2 diff --git a/content/documentation/user/_index.md b/content/documentation/user/_index.md new file mode 100644 index 0000000..a9d2f02 --- /dev/null +++ b/content/documentation/user/_index.md @@ -0,0 +1,5 @@ +--- +title: User guide +weight: 70 +--- + diff --git a/content/documentation/user/_index.ru.md b/content/documentation/user/_index.ru.md new file mode 100644 index 0000000..f8b1206 --- /dev/null +++ b/content/documentation/user/_index.ru.md @@ -0,0 +1,4 @@ +--- +title: Руководство пользователя +weight: 70 +--- diff --git a/content/documentation/user/catalog.ru.md b/content/documentation/user/catalog.ru.md new file mode 100644 index 0000000..af3aa2f --- /dev/null +++ b/content/documentation/user/catalog.ru.md @@ -0,0 +1,54 @@ +--- +title: Каталог +--- + +Каталог — раздел платформы, который содержит список всех ресурсов, их параметров и связей, а также позволяет пользователями запускать сценарии для сущностей ресурсов. + +Наполнение каталога может производиться в ручном режиме, либо автоматизированно с использованием источников данных или вебхуков. + +## Модель данных + +Основной принцип, заложенный в платформу, заключается в том, что модель данных настраивается администратором платформы. + +Администратор платформы может самостоятельно создавать те ресурсы, которые ему необходимы. Для группировки ресурсов необходимо, чтобы они были названы с одинаковым префиксом с разделителем ":". Например, ресурсы с названиями "Gitlab: группы" и "Gitlab: проекты" будут сгруппированы в общую вкладку Gitlab в интерфейсе. + +## Сущности + +Если ресурс — это элемент модели данных, то сущность — это конкретная единица каждого ресурса. Например, если ресурс называется "Gitlab: группы", то каждая группа в Gitlab, зарегистрированная в платформе, является сущностью данного ресурса. Сущности наследуют параметры ресурсов, при этом возможно задание параметров отдельно для каждой сущности. + +### События + +При создании, удалении, либо изменении спецификации любой сущности генерируется событие (event) соответствующего типа: **ENTITY_CREATED**, **ENTITY_DELETED**, **ENTITY_UPDATED**. Данные события нужны для: + +* Аудита - какие изменения происходили с сущностью в течение ее жизненного цикла +* Настройки автоматизированных реакций на изменения спецификации сущности + +Время хранения событий ограничено и может быть настроено через файл конфигурации платформы. + +## Карточка ресурса + +По умолчанию после создания ресурса в его карточке будет отображаться таблица с сущностями данного ресурса. При клике на сущность в таблице можно перейти на ее карточку. + +Если в поле "Использовать дашборд" выбран дашборд, то он будет выводиться в карточке ресурса вместо таблицы сущностей. + +## Карточка сущности + +Карточка сущности состоит из встроенных панелей и пользовательских панелей. Встроенные панели: + +* **Обзор** - содержит блоки с указанием владельца сущности, описанием сущности, параметрами и связями сущности +* **Запуски действий** - содержит список действий, которые запускались для данной сущности +* **События** - содержит список событий (event'ов), сгенерированных для данной сущности + +В карточке каждой сущности поддерживается добавление новых панелей (дашбордов). + +Добавление дашбордов для одной из сущностей ресурса применяется ко всем сущностям данного ресурса. + +## Связи + +Каждый ресурс может быть связан с другим ресурсом или сам с собой двусторонней связью. Связи настраиваются администратором платформы. После настройки связей для ресурса, каждая сущность данного ресурса может быть связана с одной, либо несколькими сущностями другого ресурса. + +Допускается создание как вертикальных связей (сущность из одного ресурса связывается с сущностью из другого ресурса), так и горизонтальных связей (связываются сущности в рамках одного ресурса). + +Также возможно автоматическое создание связей между сущностями при наполнении каталога с использованием источников данных или при запуске действий. + +Связи для каждой сущности отображаются в карточке сущности в виде таблицы. diff --git a/content/documentation/user/credentials.ru.md b/content/documentation/user/credentials.ru.md new file mode 100644 index 0000000..c151124 --- /dev/null +++ b/content/documentation/user/credentials.ru.md @@ -0,0 +1,40 @@ +--- +title: Учетные данные +menuTitle: Учетные данные +d8Edition: ee +moduleStatus: experimental +--- + +Механизм учетных данных позволяет определять, какие реквизиты будут использоваться для доступа к инфраструктурным сервисам в источниках данных, действиях и виджетах. + +Все взаимодействие с инфраструктурными сервисами в DDP происходит с использованием учетных данных конкретного пользователя. + +Понятие "системные учетные данные", то есть реквизиты, задаваемые на уровне системы в конфигурации, отсутствует в платформе, однако, если требуется использование общих учетных данных, можно создать системную учетную запись и указать для неё общие реквизиты. + +## Типы учетных данных + +Типы учетных данных задаются администратором платформы в разделе `Администрирование / Учетные данные`. + +### Обязательные поля + +- **Название** +- **Идентификатор** + +Поле **"Описание"** является опциональным. Его содержимое будет выводиться в профиле пользователя в качестве подсказки к конкретному типу учетных данных. + +## Учетные данные пользователя + +Для каждого типа учетных данных пользователь может указать свои персональные реквизиты в разделе **`Профиль / Учетные данные`**. + +Например, если администратор создал тип учетных данных **"Kubernetes token"**, то пользователь в своем профиле сможет добавить персональный токен для доступа в Kubernetes. + +Все учетные данные шифруются перед сохранением в базе данных и расшифровываются непосредственно при запросе к конкретной инфраструктурной системе. +Ключ для шифрования задаётся в конфигурации DDP в поле **`security.secretKey`**. + +{{< alert level="warning" >}} +При изменении ключа шифрования в конфигурации все текущие учетные данные станут невалидными. +{{< /alert >}} + +После того как пользователь задаст свои учетные данные, он не сможет посмотреть их значение, только обновить его. Тем не менее, в профиле будет отображаться информация о том, заполнены ли те или иные учетные данные. + +Подход к использованию учетных данных в действиях, источниках данных и виджетах описан в соответствующих разделах документации. diff --git a/content/documentation/user/interface.ru.md b/content/documentation/user/interface.ru.md new file mode 100644 index 0000000..d032f04 --- /dev/null +++ b/content/documentation/user/interface.ru.md @@ -0,0 +1,10 @@ +--- +title: Интерфейс +--- + +Интерфейс Deckhouse Development Platform включает в себя следующие разделы: + +- **Главная** — стартовая страница. На неё могут быть прикреплены дашборды с виджетами. +- **Каталог** — сервисный каталог, раздел для отображения ресурсов, сущностей, связей, а также для запуска действий и сценариев. +- **Самообслуживание** — раздел для настройки источников данных, действий, вебхуков, автоматизаций, сценариев, дашбордов и виджетов. Доступ к разделу может быть ограничен ролевой моделью. +- **Администрирование** — раздел для управления командами, пользователями, политиками доступа и учётными данными. Доступ к разделу может быть ограничен ролевой моделью. diff --git a/content/documentation/user/overview.md b/content/documentation/user/overview.md new file mode 100644 index 0000000..5951827 --- /dev/null +++ b/content/documentation/user/overview.md @@ -0,0 +1,6 @@ +--- +title: Overview +weight: 10 +--- + +This document is the User's Guide for the Deckhouse Development Platform and is part of the operational documentation for the Deckhouse Development Platform. diff --git a/content/documentation/user/overview.ru.md b/content/documentation/user/overview.ru.md new file mode 100644 index 0000000..77843b0 --- /dev/null +++ b/content/documentation/user/overview.ru.md @@ -0,0 +1,6 @@ +--- +title: Обзор +weight: 10 +--- + +Данный документ представляет собой руководство пользователя Deckhouse Development Platform и является частью эксплуатационной документации продукта Deckhouse Development Platform. diff --git a/content/documentation/user/properties.ru.md b/content/documentation/user/properties.ru.md new file mode 100644 index 0000000..26b30a4 --- /dev/null +++ b/content/documentation/user/properties.ru.md @@ -0,0 +1,72 @@ +--- +title: Параметры +--- + +Для каждого ресурса, действия или сценария администратор платформы может добавить неограниченное количество параметров одного из следующих типов: + +* **Array** - список значений +* **Boolean** - булево значение +* **Date** - дата +* **JSON** - текст в JSON формате +* **Entities** - сущность, один из параметров которой можно выбрать в качестве значения +* **List** - список значений с возможностью выбора одного из них +* **Markdown** - текст в Markdown формате +* **Number** - число +* **Object** - произвольный объект в JSON формате +* **Percentage** - процент +* **String** - строка +* **YAML** - текст в YAML формате +* **Teams** - команды +* **URL** - строка в формате URL +* **Users** - пользователи + +## Ресурсы + +После добавления параметра для ресурса он будет отображаться у всех сущностей данного ресурса в их карточках и в таблице каталога. Для каждого параметра можно задать значение по умолчанию. Значение каждого параметра можно изменить для каждой сущности по отдельности. + +Заполненность параметров проверяется для каждой сущности, результат проверки выводится в карточке сущности в заголовке. + +### Синхронизация параметров ресурса + +По различным причинам у сущностей могут появиться параметры, которых нет у ресурса. Для того, чтобы удалить подобные параметры доступна кнопка "Синхронизировать параметры" в меню ресурса. + +При синхронизации параметров: + +* Для каждого параметра ресурса будет получен его идентификатор. +* Для каждой сущности ресурса будут получен список ее параметров. +* Те параметры сущности, название которых не соответствует ни одному из идентификаторов параметров ресурса, будут удалены из спецификации сущности. + +## Действия и сценарии + +Для каждого действия и сценария задается пользовательская форма, состоящая из параметров, которые пользователь должен заполнить при запуске. + +## Ограничения + +Идентификатор кажого параметра должен: + +* Содержать символы `a-z`, `A-Z`, цифры, либо подчеркивания +* Не начинаться с цифры + +## Конфигурация + +* **Редактируемый параметр** - для каждого параметра можно настроить разрешение, либо запрет редактирования пользователем. В случае запрета редактирования пользователь при запуске действий или сценариев не сможет изменить значение параметра, то есть всегда будет использоваться значение по умолчанию. +* **Обязательный параметр** - каждый параметр может быть обязательным, либо опциональным. Значение обязательного параметра не может быть пустым при запуске действий или сценариев. При этом значение опционального параметра может оставаться пустым без влияния на работоспособность действия. +* **Скрытый параметр** - скрытый параметр не отображается в таблицах и карточках сущностей, а также при запуске действий и сценариев. + +## Типы параметров + +### Дата + +Параметр типа "дата" может принимать значение даты с определенным пользователем форматом. При этом в спецификации значение всегда хранится в формате ISO 8601 (`YYYY-MM-DDTHH:mm:ss.sssZ`). + +Конфигурация параметра: + +* Формат - настройка отображения даты. Если формат не задан явно, то используется формат по умолчанию: `YYYY-MM-DDTHH:mm:ss.sssZ`. Описание конфигурации формата доступно по [ссылке](https://day.js.org/docs/en/display/format). Настройка формата влияет на: + * отображение даты в таблицах и карточках сущностей; + * значение параметра при запуске действий или сценариев. +* Текущая дата по умолчанию - подстановка текущей даты в качестве значения по умолчанию при редактировании сущностей, а также при запуске действий или сценариев. +* Значение по умолчанию - заранее заданное значение по умолчанию. Не применяется, если активирован переключатель "Текущая дата по умолчанию". + +> При запуске действий или сценариев и использовании текущей даты по умолчанию параметр не должен быть скрытым в пользовательской форме. В противном случае текущая дата подставлена не будет. + +При запуске действий или сценариев в параметр типа "дата" нельзя подставить значения с использованием [Go template](https://developer.hashicorp.com/nomad/tutorials/templates/go-template-syntax). diff --git a/content/documentation/user/teams-users.ru.md b/content/documentation/user/teams-users.ru.md new file mode 100644 index 0000000..06c2b6e --- /dev/null +++ b/content/documentation/user/teams-users.ru.md @@ -0,0 +1,24 @@ +--- +title: Команды и пользователи +menuTitle: Команды и пользователи +d8Edition: ee +moduleStatus: experimental +--- + +В платформе существует две встроенных сущности - команды и пользователи. Основным источником данных для авторизации является Dex, установленный в Deckhouse Kubernetes Platform. Создание встроенных пользователей и команд не поддерживается. + +Принадлежность пользователя к командам определяется на основе информации из Dex и обновляется при каждой аутентификации пользователя. + +Каждый пользователь может состоять в произвольном количестве команд. Принадлежность пользователя к командам определяется на основе групп в Dex. + +## Сихронизация + +При первой авторизации пользователя в платформу для него создается внутренняя учетная запись. Команды пользователя синхронизируются при первой и каждой последующей авторизации пользователя. + +## Параметры пользователей + +### Последняя активность + +Время последней активности пользователя в платформе. Отображается в таблице пользователей в разделе `Администрирование / Пользователи`. Обновляется при авторизации, либо при автоматической ротации JWT токена пользователя (интервал ротации зависит от конфигурации Dex и по умолчанию равен 10 минутам). + +> Время последней активности не обновляется при использовании API токена, выписанного пользователем, либо при каких-либо действиях пользователя в платформе в интервале между автоматическими ротациями JWT токена. diff --git a/content/documentation/user/templating.ru.md b/content/documentation/user/templating.ru.md new file mode 100644 index 0000000..5fbaf5b --- /dev/null +++ b/content/documentation/user/templating.ru.md @@ -0,0 +1,460 @@ +--- +title: Шаблонизация +--- + +Платформа поддерживает использование [Go template](https://developer.hashicorp.com/nomad/tutorials/templates/go-template-syntax) для шаблонизации. Подробности и примеры использования описаны в соответствующих разделах документации. + +Помимо стандартных функций библиотеки возможно использование: + +* Функций, встроенных в платформу. +* Функций из библиотеки [sprig](https://masterminds.github.io/sprig/). + +> Функции из библиотеки [sprig](https://masterminds.github.io/sprig/) не поддерживаются в источниках данных. + +## Встроенные функции + +### extractPart + +`extractPart` разделяет входную строку `s` по указанному разделителю `delimiter` и возвращает часть по указанному индексу `index`. Если индекс выходит за пределы массива, возвращается ошибка. + +Параметры: + +* s: входная строка, которую нужно разделить. +* delimiter: разделитель, используемый для разделения входной строки. +* index: индекс части, которую нужно вернуть после разделения. + +Возвращает: + +* Строку, представляющую часть с указанным индексом после разделения входной строки. +* Если индекс выходит за пределы, возвращается ошибка. + +Пример в шаблоне: + +```go +{{ extractPart "ddp/demo-service" "/" 1 }} // Вывод: "demo-service" +``` + +### extractLastPart + +`extractLastPart` разделяет входную строку `s` по указанному разделителю `delimiter` и возвращает последнюю часть. Если строка пустая или разделитель не найден, возвращается оригинальная строка. + +Параметры: + +* s: входная строка, которую нужно разделить. +* delimiter: разделитель, используемый для разделения входной строки. + +Возвращает: + +* Строку, представляющую последнюю часть после разделения входной строки. + +Пример в шаблоне: + +```go +{{ extractLastPart "ddp/demo-service" "/" }} // Вывод: "demo-service" +``` + +### toJSON + +`toJSON` сериализует заданное значение в строку JSON. Принимает любой тип данных. Если сериализация не удалась, возвращается ошибка. + +Параметры: + +* v: Значение, которое нужно сериализовать в JSON. + +Возвращает: + +* JSON строку, представляющую входное значение. +* Ошибку, возникшую в ходе сериализации. + +Пример в шаблоне: + +```go +{{ toJSON . }} // Вывод: JSON-представление объекта в контексте +``` + +### replaceChar + +`replaceChar` заменяет все вхождения указанного символа в строке на другой указанный символ. + +Параметры: + +* s: Исходная строка, в которой нужно выполнить замену. +* oldChar: Символ, который нужно заменить. +* newChar: Символ, на который нужно заменить. + +Возвращает: + +* Изменённая строка, где все вхождения `oldChar` заменены на `newChar`. + +Пример в шаблоне: + +```go +{{ replaceChar "hello/world" "/" "-" }} // Вывод: "hello-world" +``` + +### filteredItems + +`filteredItems` фильтрует массив элементов (maps) по запрашиваемому значению ключа. Возвращает массив элементов, у которых значение по заданному ключу соответствует целевому значению. + +Параметры: + +* data: Массив данных, в котором выполняется фильтрация. +* key: Ключ, по которому будет выполнена проверка значения. +* value: Целевое значение для сравнения. + +Возвращает: + +* Массив элементов, у которых значение по заданному ключу соответствует целевому значению. +* Ошибку, если возникает проблема во время фильтрации. + +Пример в шаблоне: + +```go +{{ filteredItems .items "name" "Alice" }} // Вывод: [{"name": "Alice", "age": 30}] +``` + +### anyOf + +`anyOf` проверяет, соответствует ли хотя бы один элемент массива условию сравнения. + +Параметры: + +* operator: Оператор сравнения (eq, ne, lt, le, gt, ge). +* value: Целевое значение для сравнения. +* key: Ключ, по которому будет извлечено значение для сравнения. +* data: Массив данных (maps). + +Возвращает: + +* `true`, если хотя бы одно значение из массива данных соответствует условию. + +Пример в шаблоне: + +```go +{{ anyOf "eq" "value" "key" .data }} // Вывод: true, если хотя бы одна запись удовлетворяет условию +``` + +### allOf + +`allOf` проверяет, соответствуют ли все элементы массива условию сравнения. + +Параметры: + +* operator: Оператор сравнения (eq, ne, lt, le, gt, ge). +* value: Целевое значение для сравнения. +* key: Ключ, по которому будет извлечено значение для сравнения. +* data: Массив данных (maps). + +Возвращает: + +* `true`, только если все значения соответствуют условию. + +Пример в шаблоне: + +```go +{{ allOf "gt" 10 "age" .users }} // Вывод: true, если все пользователи старше 10 лет +``` + +### getFieldValue + +`getFieldValue` получает значение поля по ключу из структуры, представленной в виде map. + +Параметры: + +* items: Структура данных в виде карты. +* key: Ключ, по которому нужно получить значение. + +Возвращает: + +* Значение, полученное по ключу. +* Ошибку, если структура отсутствует или ключ не найден. + +Пример в шаблоне: + +```go +{{ getFieldValue .item "name" }} // Вывод: Значение поля "name" из структуры .item +``` + +### findValueInDictArray + +`findValueInDictArray` ищет в массиве словарей элемент, где значение по заданному ключу соответствует указанному значению, и возвращает значение другого ключа. + +Параметры: + +* data: Массив словарей (map[string]interface{}), в которых выполняется поиск. +* filterKey: Ключ, по которому выполняется фильтрация. +* filterValue: Значение, с которым должно совпадать значение по filterKey. +* targetKey: Ключ, значение которого требуется получить из найденного элемента. + +Возвращает: + +* Значение, соответствующее targetKey в найденном словаре. +* Ошибку, если элемент не найден или targetKey отсутствует. + +Пример в шаблоне: + +```go +{{ findValueInDictArray .items "environment" "test" "url" }} // Вывод: Значение ключа "url" из первого найденного словаря, где "environment" равно "test". +``` + +### generatePassword + +`generatePassword` генерирует случайный пароль с заданными параметрами. + +Параметры: + +* length: Длина пароля (по умолчанию: 16). +* includeUppercase: Включать заглавные буквы A-Z (по умолчанию: true). +* includeLowercase: Включать строчные буквы a-z (по умолчанию: true). +* includeNumbers: Включать цифры 0-9 (по умолчанию: true). + +Возвращает: + +* Строку с сгенерированным паролем. +* Ошибку, если невозможно сгенерировать пароль с заданными параметрами. + +Примеры в шаблоне: + +```go +{{ generatePassword }} // Вывод: Случайный пароль длиной 16 символов +{{ generatePassword 12 }} // Вывод: Случайный пароль длиной 12 символов +{{ generatePassword 8 true true true }} // Вывод: Пароль длиной 8 символов +{{ generatePassword 10 false true true }} // Вывод: Пароль длиной 10 символов только из строчных букв и цифр +``` + +## Глобальные переменные + +Глобальные переменные - общие переменные, которые могут быть переиспользованы в шаблонизации при запуске действий. + +Для получения значения глобальной переменной необходимо указать подобную строку в соответствующих полях: + +```go +{{ .global.. }} +``` + +где: + +- **global** - указывает на то, что идет обращение к глобальным переменным +- **slug** - идентификатор набора глобальных переменных +- **key** - ключ переменной, значение которой необходимо подставить + +> Глобальные переменные хранятся в базе данных DDP в открытом виде, их значение может быть получено пользователями через веб-интерфейс. Не рекомендуется помещать конфиденциальные данные в глобальные переменные. + +### Настройка глобальных переменных + +Настройка глобальных переменных происходит в разделе `Самообслуживание -> Глобальные переменные`. + +Существуют следующие правила именования: + +- Название набора глобальных переменных не должно быть пустым +- Идентификатор набора глобальных переменных не может быть пустым и должен соответствовать следующим условиям: + - Содержать символы `a-z`, `A-Z`, цифры, либо подчеркивания + - Не начинаться с цифры +- Ключ каждой переменной набора не должен быть пустым и должен соответствовать следующим условиям: + - Содержать символы `a-z`, `A-Z`, цифры, либо подчеркивания + - Не начинаться с цифры +- Значение каждой переменной набора не должно быть пустым + +## Командные переменные + +Во всех действиях, сценариях и процессах можно использовать командные переменные. + +Командные переменные настраиваются в разделе `Администрирование -> Команды` в меню редактирования команды. +Каждый пользователь может редактировать переменные тех команд, в которые он входит - это можно сделать в профиле пользователя. + +Чтобы получить значение командной переменной, используйте следующую конструкцию: + +```go +{{ .team. }} +``` + +При запуске действия пользователь должен выбрать команду, чьи переменные будут подставлены. +При запуске сценария или процесса команда выбирается один раз - и её переменные используются во всех действиях внутри. + +## Переменные действий + +### Параметры действия + +Параметры действия доступны через контекст `{{ .property.* }}` и содержат значения, переданные при запуске действия. + +Для получения значения параметра действия используйте следующую конструкцию: + +```go +{{ .property. }} +``` + +где: + +- **property** - указывает на то, что идет обращение к параметрам действия +- **property_slug** - идентификатор параметра, значение которого необходимо подставить + +Идентификаторы параметров можно посмотреть на вкладке `Пользовательская форма` в окне конфигурации действия. + +Примеры использования: + +```go +{{ .property.environment }} // Значение параметра "environment" +{{ .property.count }} // Значение параметра "count" +{{ .property.url }} // Значение параметра "url" +``` + +### Ответ действия + +Ответ действия доступен через контекст `{{ .response.* }}` и содержит данные, возвращенные после выполнения действия. + +Для получения значения из ответа действия используйте следующую конструкцию: + +```go +{{ .response. }} +``` + +где: + +- **response** - указывает на то, что идет обращение к ответу действия +- **field_name** - имя поля в ответе, значение которого необходимо подставить + +Посмотреть формат возвращаемого действием ответа можно либо в документации, описывающей действие, либо в записи действия в интерфейсе DDP: + +1. Открыть меню действия (кнопка с тремя точками в карточке действия) +2. Выбрать пункт `Запуски действия` +3. Открыть конфигурацию одного из запусков действия +4. Найти в таблице колонку **Response** + +Примеры использования: + +```go +{{ .response.status }} // Статус ответа +{{ .response.data.id }} // ID из данных ответа +{{ .response.headers.auth }} // Значение заголовка авторизации +``` + +> **Важно:** Контекст `{{ .response.* }}` может использоваться только в полях, описывающих правила обновления сущности после запуска действия. + +## Учётные данные + +Учётные данные доступны во всех действиях, сценариях, процессах, виджетах, источниках данных и внешних сервисах через контекст `{{ .credentials.* }}`. + +Для получения значения учётных данных используйте следующую конструкцию: + +```go +{{ .credentials. }} +``` + +где: + +- **credentials** - указывает на то, что идет обращение к учётным данным +- **credentials_slug** - идентификатор учётных данных, значение которого необходимо подставить + +В данном случае идентификаторы учетных данных - это те идентификаторы, которые задается во вкладке `Авторизация` в разделе `Учетные данные` в диалогах конфигурации объектов DDP. + +Примеры использования: + +```go +{{ .credentials.token }} // Токен доступа +{{ .credentials.username }} // Имя пользователя +{{ .credentials.password }} // Пароль +{{ .credentials.accessKeyId }} // Access Key ID для S3 +{{ .credentials.secretAccessKey }} // Secret Access Key для S3 +{{ .credentials.apiKey }} // API ключ +{{ .credentials.bearerToken }} // Bearer токен +``` + +## Сущность (entity) + +Сущность доступна в виджетах с областью видимости `Resource`, действиях, процессах и сценариях через контекст `{{ .entity.* }}`. + +Для получения значения поля сущности используйте следующую конструкцию: + +```go +{{ .entity. }} +``` + +где: + +- **entity** - указывает на то, что идет обращение к сущности +- **field_name** - имя поля сущности, значение которого необходимо подставить + +### Основные поля сущности + +```go +{{ .entity.uuid }} // UUID сущности +{{ .entity.slug }} // Идентификатор сущности +{{ .entity.name }} // Название сущности +{{ .entity.description }} // Описание сущности +``` + +### Параметры сущности + +Параметры сущности доступны через контекст `{{ .entity.properties.* }}` и содержат пользовательские параметры, настроенные для конкретной сущности. + +Для получения значения параметра сущности используйте следующую конструкцию: + +```go +{{ .entity.properties. }} +``` + +где: + +- **entity** - указывает на то, что идет обращение к сущности +- **properties** - указывает на параметры сущности +- **property_slug** - идентификатор параметра сущности, значение которого необходимо подставить + +Примеры использования: + +```go +{{ .entity.properties.projectId }} // ID проекта из параметров сущности +{{ .entity.properties.branch }} // Ветка Git из параметров сущности +{{ .entity.properties.environment }} // Окружение из параметров сущности +{{ .entity.properties.apiUrl }} // URL API из параметров сущности +{{ .entity.properties.version }} // Версия из параметров сущности +``` + +## Параметры процесса + +Для каждого процесса доступно задание общих параметров, значения которых могут быть использованы во всех действиях, входящих в сценарий. + +Для получения значения параметра процесса используйте следующую конструкцию: + +```go +{{ .process. }} +``` + +где: + +- **process** - указывает на то, что идет обращение к процессу +- **property_slug** - идентификатор параметра процесса, значение которого необходимо подставить + +Тип и значение по умолчанию параметров задаются в интерфейсе редактирования процесса. При этом, для каждого конкретного параметра пользователь может при запуске процесса переопределить значение по умолчанию в случае, если редактирование параметра разрешено. + +Примеры использования: + +```go +{{ .process.deploymentUrl }} // URL для деплоя из параметров процесса +{{ .process.branch }} // Ветка Git из параметров процесса +{{ .process.environment }} // Окружение из параметров процесса +``` + +## Параметры сценария + +Для каждого сценария доступно задание общих параметров, значения которых могут быть использованы во всех действиях, входящих в сценарий. + +Для получения значения параметра сценария используйте следующую конструкцию: + +```go +{{ .workflow. }} +``` + +где: + +- **workflow** - указывает на то, что идет обращение к сценарию +- **property_slug** - идентификатор параметра сценария, значение которого необходимо подставить + +Тип и значение по умолчанию параметров задаются в интерфейсе редактирования сценария. При этом, для каждого конкретного параметра пользователь может при запуске сценария переопределить значение по умолчанию в случае, если редактирование параметра разрешено. + +Примеры использования: + +```go +{{ .workflow.apiEndpoint }} // API endpoint из параметров сценария +{{ .workflow.notificationEmail }} // Email для уведомлений из параметров сценария +{{ .workflow.retryAttempts }} // Количество попыток повтора из параметров сценария +``` diff --git a/go.sum b/go.sum index aeb35c3..ff8ec70 100644 --- a/go.sum +++ b/go.sum @@ -1,2 +1,4 @@ github.com/deckhouse/hugo-web-product-module v0.1.1 h1:N0KEjvjJaZ5+rCxQTNbcHX5+lVW1qjOoy/xM97lpGf8= github.com/deckhouse/hugo-web-product-module v0.1.1/go.mod h1:iLVlLSCkbOoi7RjYm5RjwAQi+Whs6DjSumhaH1GBjqw= +github.com/deckhouse/hugo-web-product-module v0.1.2 h1:c0XlWZJoJZsMKiFnwA/t4YLzQQgtymCXVysmAHNHopI= +github.com/deckhouse/hugo-web-product-module v0.1.2/go.mod h1:iLVlLSCkbOoi7RjYm5RjwAQi+Whs6DjSumhaH1GBjqw=