From c7360c1ac6e8bb0ba24ce4deaba7828edb690ef7 Mon Sep 17 00:00:00 2001 From: Nikita Velgin Date: Wed, 30 Sep 2026 18:04:52 +0300 Subject: [PATCH 1/2] new main page docs --- .../admin/actions/debug/debug.ru.md | 6 +- .../creategitlabmergerequestreview.ru.md | 67 ++++ .../createrepositoryfromtemplatepack.ru.md | 69 ++++ .../actions/gitlab/getgitlabpipeline.ru.md | 34 ++ .../actions/gitlab/startgitlabpipeline.ru.md | 4 + .../upgraderepositoryfromtemplatepack.ru.md | 80 ++++ .../kubernetes/deletekubernetesresource.ru.md | 6 + .../kubernetes/getkubernetesresource.ru.md | 5 +- .../admin/actions/overview.ru.md | 14 + content/documentation/admin/datasets.ru.md | 109 +++--- .../admin/datasources/types.ru.md | 45 +++ .../admin/examples/home-custom-catalog.ru.md | 101 +++++ .../admin/examples/home-custom-process.ru.md | 96 +++++ .../admin/examples/home-quick-start.ru.md | 127 ++++++ .../admin/examples/home-widget-slot.ru.md | 61 +++ .../examples/microservice-lifecycle.ru.md | 91 +++++ .../admin/examples/template-first-pack.ru.md | 208 ++++++++++ .../examples/template-release-update.ru.md | 119 ++++++ content/documentation/admin/home/_index.ru.md | 4 + .../documentation/admin/home/mapping.ru.md | 361 ++++++++++++++++++ .../documentation/admin/home/overview.ru.md | 148 +++++++ .../documentation/admin/home/processes.ru.md | 155 ++++++++ content/documentation/admin/home/setup.ru.md | 135 +++++++ .../admin/processes/overview.ru.md | 30 +- .../security/encryption-key-rotation.ru.md | 1 + .../documentation/admin/security/rbac.ru.md | 20 +- .../admin/templates/_index.ru.md | 4 + .../admin/templates/overview.ru.md | 88 +++++ .../documentation/admin/templates/packs.ru.md | 305 +++++++++++++++ .../admin/templates/registry.ru.md | 223 +++++++++++ .../admin/templates/updates.ru.md | 239 ++++++++++++ .../admin/widgets/gitlab/merge-requests.ru.md | 63 ++- .../admin/widgets/gitlab/pipelines.ru.md | 49 ++- .../admin/widgets/overview.ru.md | 5 +- .../documentation/release-notes/v1.7.0.ru.md | 63 ++- content/documentation/user/ai-assistant.ru.md | 8 +- content/documentation/user/home/_index.ru.md | 4 + .../user/home/architecture.ru.md | 82 ++++ .../documentation/user/home/deployment.ru.md | 203 ++++++++++ .../user/home/microservices.ru.md | 147 +++++++ .../documentation/user/home/overview.ru.md | 99 +++++ content/documentation/user/home/teams.ru.md | 41 ++ content/documentation/user/interface.ru.md | 9 +- content/documentation/user/properties.ru.md | 1 + content/documentation/user/templating.ru.md | 36 +- 45 files changed, 3662 insertions(+), 103 deletions(-) create mode 100644 content/documentation/admin/actions/gitlab/creategitlabmergerequestreview.ru.md create mode 100644 content/documentation/admin/actions/gitlab/createrepositoryfromtemplatepack.ru.md create mode 100644 content/documentation/admin/actions/gitlab/getgitlabpipeline.ru.md create mode 100644 content/documentation/admin/actions/gitlab/upgraderepositoryfromtemplatepack.ru.md create mode 100644 content/documentation/admin/examples/home-custom-catalog.ru.md create mode 100644 content/documentation/admin/examples/home-custom-process.ru.md create mode 100644 content/documentation/admin/examples/home-quick-start.ru.md create mode 100644 content/documentation/admin/examples/home-widget-slot.ru.md create mode 100644 content/documentation/admin/examples/microservice-lifecycle.ru.md create mode 100644 content/documentation/admin/examples/template-first-pack.ru.md create mode 100644 content/documentation/admin/examples/template-release-update.ru.md create mode 100644 content/documentation/admin/home/_index.ru.md create mode 100644 content/documentation/admin/home/mapping.ru.md create mode 100644 content/documentation/admin/home/overview.ru.md create mode 100644 content/documentation/admin/home/processes.ru.md create mode 100644 content/documentation/admin/home/setup.ru.md create mode 100644 content/documentation/admin/templates/_index.ru.md create mode 100644 content/documentation/admin/templates/overview.ru.md create mode 100644 content/documentation/admin/templates/packs.ru.md create mode 100644 content/documentation/admin/templates/registry.ru.md create mode 100644 content/documentation/admin/templates/updates.ru.md create mode 100644 content/documentation/user/home/_index.ru.md create mode 100644 content/documentation/user/home/architecture.ru.md create mode 100644 content/documentation/user/home/deployment.ru.md create mode 100644 content/documentation/user/home/microservices.ru.md create mode 100644 content/documentation/user/home/overview.ru.md create mode 100644 content/documentation/user/home/teams.ru.md diff --git a/content/documentation/admin/actions/debug/debug.ru.md b/content/documentation/admin/actions/debug/debug.ru.md index 1375cab4..52d5ef5c 100644 --- a/content/documentation/admin/actions/debug/debug.ru.md +++ b/content/documentation/admin/actions/debug/debug.ru.md @@ -18,6 +18,8 @@ extra: | Название | Обязательность | Описание | Значение по умолчанию | | --------------- | ---------------- | ----------------------------------------------------------------------------------------------------- | ----------------------- | -| sleep_time | Нет | Длительность одного цикла ожидания в секундах | `1` | -| sleep_count | Нет | Число циклов ожидания | `1` | +| sleep_time | Нет | Длительность одного цикла ожидания в секундах | `0` | +| sleep_count | Нет | Число циклов ожидания | `0` | | extra | Нет | Произвольный набор пар «ключ–значение», который записывается в лог и возвращается в ответе действия | - | + +При значениях `0` действие завершается сразу. Отрицательные значения не допускаются: `sleep_time and sleep_count must not be negative`. diff --git a/content/documentation/admin/actions/gitlab/creategitlabmergerequestreview.ru.md b/content/documentation/admin/actions/gitlab/creategitlabmergerequestreview.ru.md new file mode 100644 index 00000000..10e44be5 --- /dev/null +++ b/content/documentation/admin/actions/gitlab/creategitlabmergerequestreview.ru.md @@ -0,0 +1,67 @@ +--- +title: CreateGitlabMergeRequestReview +weight: 75 +--- + +{{< alert level="info" >}} +Для выполнения действия необходимы учётные данные `password` — токен GitLab пользователя, от имени которого будет выполнено действие. +{{< /alert >}} + +CreateGitlabMergeRequestReview — создаёт merge request в GitLab из уже существующей ветки. В интерфейсе действие называется «Создать MR в Gitlab для существующей ветки». + +В отличие от [CreateGitlabMergeRequest](creategitlabmergerequest/), действие не создаёт ветку и не записывает файлы, а перед созданием проверяет открытые merge request проекта. Действие используется процессом [обновления микросервиса из шаблона](../../templates/updates/). + +### Пример запроса + +```yaml +skipReview: false +sourceBranch: ddp/template-upgrade-1.2.0 +targetBranch: main +dedupBranchPrefix: ddp/template-upgrade- +repositoryRef: + gitlabProjectId: "0" +mergeRequestSpec: + title: Upgrade template + description: Apply template upgrade changes +``` + +### Спецификация запроса + +| Название | Обязательность | Описание | Значение по умолчанию | +| ----------------------------- | -------------- | ----------------------------------------------------------------------------------------------------- | --------------------- | +| skipReview | Нет | При значении `true` действие завершается успешно без создания merge request | `false` | +| sourceBranch | Да | Существующая ветка с изменениями | - | +| targetBranch | Нет | Ветка, в которую предлагаются изменения. Если не задана и действие выполняется для сущности микросервиса, используется значение роли маппинга `microservice_default_branch` | `main` | +| dedupBranchPrefix | Нет | Префикс веток для поиска открытых merge request | Значение «Префикс ветки обновления» реестра шаблонов, иначе `ddp/template-upgrade-` | +| repositoryRef.gitlabProjectId | Да | Идентификатор проекта GitLab. Если не задан и действие выполняется для сущности микросервиса, используется ID проекта микросервиса | - | +| mergeRequestSpec.title | Нет | Заголовок merge request | `Upgrade template ()` | +| mergeRequestSpec.description | Нет | Описание merge request | - | + +### Алгоритм работы + +DDP: + +1. Запрашивает открытые merge request проекта, ветки которых начинаются с префикса `dedupBranchPrefix`. +1. Если открыт merge request из ветки `sourceBranch`, завершает действие успешно и возвращает этот merge request. +1. Если открыт merge request из другой ветки с тем же префиксом, завершает действие ошибкой `review_already_open: open review for branch blocks `. +1. Иначе создаёт merge request из `sourceBranch` в `targetBranch`. + +Проверяется одна страница из 100 открытых merge request проекта. + +### Ответ + +Ответ действия содержит поля: + +| Поле | Описание | +| -------------- | --------------------------------------------------------------- | +| `skipped` | `true`, если действие завершилось без создания merge request по `skipReview` | +| `deduplicated` | `true`, если возвращён уже открытый merge request | +| `provider` | Провайдер системы контроля версий, `gitlab` | +| `reviewId` | Номер merge request (`iid`) в проекте | +| `reviewUrl` | Ссылка на merge request | +| `sourceBranch` | Ветка-источник | +| `targetBranch` | Целевая ветка | + +### Примечание + +Действие осуществляет GET- и POST-запросы по URL: `/api/v4/projects/:id/merge_requests`. Ошибка создания merge request возвращается с кодом `review_create_failed`. diff --git a/content/documentation/admin/actions/gitlab/createrepositoryfromtemplatepack.ru.md b/content/documentation/admin/actions/gitlab/createrepositoryfromtemplatepack.ru.md new file mode 100644 index 00000000..2abad4b3 --- /dev/null +++ b/content/documentation/admin/actions/gitlab/createrepositoryfromtemplatepack.ru.md @@ -0,0 +1,69 @@ +--- +title: CreateRepositoryFromTemplatePack +weight: 12 +--- + +{{< alert level="info" >}} +Для выполнения действия необходимы учётные данные: + +- `password` — пароль (токен) пользователя, от имени которого будет выполнено действие; +- `username` — имя пользователя, от имени которого будет выполнено действие. +{{< /alert >}} + +CreateRepositoryFromTemplatePack — заполняет репозиторий файлами [пакета шаблона](../../templates/packs/) из реестра шаблонов. В интерфейсе действие называется «Создать репозиторий из пакета шаблонов». + +Действие загружает версию пакета, отрисовывает файлы с переданными значениями параметров, записывает в репозиторий lock-файл `.ddp/template.lock.yaml` и отправляет коммит в целевую ветку. По lock-файлу портал затем [обновляет репозиторий](../../templates/updates/) до новых версий шаблона. + +### Пример запроса + +```yaml +targetRepositoryUrl: https://gitlab.example.com/group/billing-api.git +targetBranch: main +templateId: go-service +templateVersion: 1.2.0 +templatePackSource: company +values: + port: 8080 +``` + +### Спецификация запроса + +| Название | Обязательность | Описание | Значение по умолчанию | +| ------------------------ | -------------- | -------------------------------------------------------------------------------------------------- | --------------------- | +| targetRepositoryUrl | Да | HTTPS-адрес репозитория. Хост должен совпадать с хостом внешнего сервиса действия | - | +| targetBranch | Нет | Ветка, в которую отправляется коммит | Значение «Ветка по умолчанию» реестра шаблонов, иначе `main` | +| templateId | Да | Идентификатор шаблона | - | +| templatePackSource | Да | Название подключения в [реестре шаблонов](../../templates/registry/), из которого берётся шаблон | - | +| templateVersion | Нет | Версия шаблона в формате semver | Последняя версия шаблона | +| values | Нет | Значения параметров шаблона. Состав параметров задаёт файл `values.yaml` пакета | - | +| additionalIgnorePatterns | Нет | Дополнительные glob-шаблоны путей, которые не отрисовываются и не копируются в репозиторий | - | +| commitMessage | Нет | Сообщение коммита | `chore(template): scaffold from @` | + +### Алгоритм работы + +DDP: + +1. Выбирает версию шаблона в реестре `templatePackSource`. Версия должна иметь статус «доступна». +1. Загружает пакет и заполняет параметры с аннотацией `x-ddp-from` из [контекста запуска процесса](../../home/processes/#создание-микросервиса). +1. Проверяет значения параметров по схеме `values.yaml` и отрисовывает файлы пакета. +1. Клонирует целевую ветку репозитория. Пустой репозиторий инициализируется. +1. Копирует отрисованные файлы, записывает lock-файл `.ddp/template.lock.yaml` с идентификатором, версией шаблона и значениями параметров. +1. Создаёт коммит и отправляет его в целевую ветку. + +### Ответ + +Ответ действия содержит поля `templateId`, `templateVersion`, `templateSource`, `targetBranch`, `commitSha`, а также `values.request` — переданные значения параметров и `values.merged` — итоговые значения с учётом значений по умолчанию. + +### Ошибки + +Сообщение об ошибке начинается с кода. Основные коды: + +| Код | Причина | +| --- | --- | +| `invalid_request` | Не заданы `templateId`, `templatePackSource` или версия не в формате semver | +| `pack_unavailable` | Подключение `templatePackSource` не найдено или версия недоступна | +| `pack_not_found` | Версия шаблона не найдена | +| `pack_deprecated` | Версия шаблона отозвана | +| `values_invalid` | Значения параметров не соответствуют схеме `values.yaml` или не найден путь `x-ddp-from` в контексте запуска | +| `render_failed` | Ошибка шаблонизации файлов пакета | +| `clone_failed`, `push_failed` | Ошибка клонирования репозитория или отправки коммита | diff --git a/content/documentation/admin/actions/gitlab/getgitlabpipeline.ru.md b/content/documentation/admin/actions/gitlab/getgitlabpipeline.ru.md new file mode 100644 index 00000000..5bef2221 --- /dev/null +++ b/content/documentation/admin/actions/gitlab/getgitlabpipeline.ru.md @@ -0,0 +1,34 @@ +--- +title: GetGitlabPipeline +weight: 105 +--- + +{{< alert level="info" >}} +Для выполнения действия требуется токен пользователя, от имени которого оно будет выполнено. +{{< /alert >}} + +GetGitlabPipeline — возвращает состояние пайплайна GitLab. + +Действие используется в процессах, которые запускают пайплайн действием [StartGitlabPipeline](startgitlabpipeline/) и ожидают его завершения, периодически запрашивая состояние. + +### Пример запроса + +```yaml +project_id: "0" +pipeline_id: "0" +``` + +### Спецификация запроса + +| Название | Обязательность | Описание | +| ----------- | -------------- | ------------------------------------------------------------------------------------------------- | +| project_id | Да | Идентификатор проекта GitLab или путь проекта, например `group/project` | +| pipeline_id | Да | Идентификатор пайплайна — поле `id` ответа GitLab, например `{{ .response.id }}` действия StartGitlabPipeline | + +### Ответ + +Ответ действия — объект пайплайна GitLab с полями `id`, `iid`, `status`, `ref`, `sha`, `web_url` и другими. Состояние пайплайна доступно в последующих элементах процесса как `{{ .response.status }}`. + +### Примечание + +Действие осуществляет GET-запрос по URL: `/api/v4/projects/:id/pipelines/:pipeline_id`. diff --git a/content/documentation/admin/actions/gitlab/startgitlabpipeline.ru.md b/content/documentation/admin/actions/gitlab/startgitlabpipeline.ru.md index bb3e7869..c1c80677 100644 --- a/content/documentation/admin/actions/gitlab/startgitlabpipeline.ru.md +++ b/content/documentation/admin/actions/gitlab/startgitlabpipeline.ru.md @@ -29,6 +29,10 @@ variables: | variables.key | Да | Название переменной | | variables.value | Да | Значение переменной | +### Ответ + +Ответ действия — объект созданного пайплайна GitLab с полями `id`, `iid`, `status`, `ref`, `web_url` и другими. Идентификатор `{{ .response.id }}` используется для отслеживания состояния пайплайна действием [GetGitlabPipeline](getgitlabpipeline/). + ### Примечание Действие осуществляет POST-запрос по URL: `/api/v4/projects/:id/pipeline`. diff --git a/content/documentation/admin/actions/gitlab/upgraderepositoryfromtemplatepack.ru.md b/content/documentation/admin/actions/gitlab/upgraderepositoryfromtemplatepack.ru.md new file mode 100644 index 00000000..2563ca9a --- /dev/null +++ b/content/documentation/admin/actions/gitlab/upgraderepositoryfromtemplatepack.ru.md @@ -0,0 +1,80 @@ +--- +title: UpgradeRepositoryFromTemplatePack +weight: 14 +--- + +{{< alert level="info" >}} +Для выполнения действия необходимы учётные данные: + +- `password` — пароль (токен) пользователя, от имени которого будет выполнено действие; +- `username` — имя пользователя, от имени которого будет выполнено действие. +{{< /alert >}} + +UpgradeRepositoryFromTemplatePack — переносит в репозиторий микросервиса изменения новой версии [пакета шаблона](../../templates/packs/). В интерфейсе действие называется «Обновить репозиторий из пакета шаблонов». + +Действие не изменяет основную ветку: оно создаёт ветку обновления с изменениями, которые затем предлагаются в merge request действием [CreateGitlabMergeRequestReview](creategitlabmergerequestreview/). Механизм обновления описан в разделе [«Обновление из шаблона»](../../templates/updates/). + +Действие выполняется для сущности микросервиса. + +### Пример запроса + +```yaml +templateVersion: 1.3.0 +upgradeStrategy: selective +updateOverwrite: + - .gitlab-ci.yml +updateAddIfMissing: + - docs/CONTRIBUTING.md +``` + +### Спецификация запроса + +Незаданные поля `templateId`, `templatePackSource`, `targetRepositoryUrl` и `targetBranch` заполняются из параметров сущности микросервиса по ролям [правил маппинга](../../home/mapping/#микросервисы). + +| Название | Обязательность | Описание | Значение по умолчанию | +| ------------------------ | -------------- | ---------------------------------------------------------------------------------------- | --------------------- | +| targetRepositoryUrl | Да | HTTPS-адрес репозитория микросервиса | Роль `microservice_repository` | +| targetBranch | Нет | Ветка, от которой создаётся ветка обновления | Роль `microservice_default_branch`, затем «Ветка по умолчанию» реестра шаблонов, затем `main` | +| sourceBranch | Нет | Ветка, в которую записываются изменения | `<префикс ветки обновления><версия>`, например `ddp/template-upgrade-1.3.0` | +| templateId | Да | Идентификатор шаблона | Роль `microservice_binding_template_id` | +| templatePackSource | Да | Название подключения в реестре шаблонов | Роль `microservice_binding_template_source` | +| templateVersion | Нет | Целевая версия шаблона в формате semver | Последняя версия шаблона | +| upgradeStrategy | Нет | Стратегия обновления: `selective`, `additive`, `selective_additive`, `full` или `merge` | Параметр микросервиса, затем стратегия пакета, затем `selective` | +| updateOverwrite | Нет | Glob-шаблоны перезаписываемых путей | Параметр микросервиса, затем список пакета | +| updateAddIfMissing | Нет | Glob-шаблоны путей, добавляемых при отсутствии | Параметр микросервиса, затем список пакета | +| values | Нет | Значения параметров шаблона. Объединяются со значениями из lock-файла | - | +| additionalIgnorePatterns | Нет | Дополнительные glob-шаблоны путей, которые не отрисовываются и не копируются | - | +| commitMessage | Нет | Сообщение коммита | `chore(template): upgrade -> ` | + +Стратегии и обязательные для них списки путей описаны в разделе [«Стратегии обновления»](../../templates/updates/#стратегии-обновления). + +### Алгоритм работы + +DDP: + +1. Клонирует ветку `targetBranch` и читает lock-файл `.ddp/template.lock.yaml`. Если версия в каталоге отличается от версии в lock-файле, исправляет параметр версии шаблона микросервиса. +1. Если версия в lock-файле не ниже целевой, завершает действие успешно без изменений. +1. Отрисовывает целевую версию пакета со значениями из lock-файла и из поля `values`. +1. Создаёт ветку `sourceBranch` и применяет изменения по стратегии обновления. Файлы не удаляются. +1. Записывает в lock-файл новую версию и значения параметров, создаёт коммит и отправляет ветку `sourceBranch`. + +При конфликте слияния в стратегии `merge` в репозиторий ничего не записывается. + +### Ответ + +Ответ действия содержит поля: + +| Поле | Описание | +| ----------------- | ----------------------------------------------------------- | +| `templateId` | Идентификатор шаблона | +| `templateSource` | Название подключения реестра | +| `previousVersion` | Версия шаблона до обновления | +| `targetVersion` | Целевая версия | +| `sourceBranch` | Ветка обновления | +| `targetBranch` | Ветка, от которой создана ветка обновления | +| `strategy` | Применённая стратегия | +| `commitSha` | SHA коммита обновления | +| `upgradeSkipped` | `true`, если репозиторий уже на целевой версии | +| `versionDrift` | Сведения об исправлении версии в каталоге по lock-файлу | + +Коды ошибок описаны в разделе [«Устранение ошибок»](../../templates/updates/#устранение-ошибок). diff --git a/content/documentation/admin/actions/kubernetes/deletekubernetesresource.ru.md b/content/documentation/admin/actions/kubernetes/deletekubernetesresource.ru.md index 6ba79c94..facd6619 100644 --- a/content/documentation/admin/actions/kubernetes/deletekubernetesresource.ru.md +++ b/content/documentation/admin/actions/kubernetes/deletekubernetesresource.ru.md @@ -17,6 +17,7 @@ version: v1 resource_type: deployments resource_name: nginx-deployment namespace: example +ignore_not_found: true ``` ### Спецификация запроса @@ -28,3 +29,8 @@ namespace: example | 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 | Да | Неймспейс, в котором находится ресурс | - | +| ignore_not_found | Нет | При значении `true` удаление объекта, которого нет в кластере, завершается успешно. По умолчанию `false`: удаление отсутствующего объекта завершается ошибкой | `true`, `false` | + +### Примечание + +Параметр `ignore_not_found` не подавляет другие ошибки API Kubernetes. Используйте его в процессах удаления, которые могут запускаться повторно. diff --git a/content/documentation/admin/actions/kubernetes/getkubernetesresource.ru.md b/content/documentation/admin/actions/kubernetes/getkubernetesresource.ru.md index 004ef269..c374e9f1 100644 --- a/content/documentation/admin/actions/kubernetes/getkubernetesresource.ru.md +++ b/content/documentation/admin/actions/kubernetes/getkubernetesresource.ru.md @@ -18,6 +18,7 @@ version: v1alpha1 resource_type: postgres resource_name: example-postgres namespace: default +ignore_not_found: true ``` ### Спецификация запроса @@ -29,13 +30,15 @@ namespace: default | resource_type | Да | Тип получаемого ресурса | - | | resource_name | Да | Название конкретного ресурса, который необходимо получить | - | | namespace | Да | Неймспейс, в котором находится ресурс | - | +| ignore_not_found | Нет | При значении `true` отсутствие объекта не считается ошибкой. По умолчанию `false` | `true`, `false` | ### Ответ -При успешном выполнении действие возвращает объект ресурса в поле `resource`. Если ресурс не найден, действие завершается с ошибкой. +При успешном выполнении действие возвращает признак `found` и объект в поле `resource`. Если объект не найден и `ignore_not_found` не включён, действие завершается с ошибкой; при `ignore_not_found: true` действие завершается успешно с `found: false` и без поля `resource`. | Название | Описание | | ------------ | ----------------------------------------------- | +| `found` | `true`, если объект найден | | `resource` | Объект ресурса в формате Kubernetes | ### Определение требуемых Group и Version diff --git a/content/documentation/admin/actions/overview.ru.md b/content/documentation/admin/actions/overview.ru.md index a024ce6f..c5c158f3 100644 --- a/content/documentation/admin/actions/overview.ru.md +++ b/content/documentation/admin/actions/overview.ru.md @@ -64,6 +64,10 @@ weight: 10 При выборе формата «Form URL Encoded» тело запроса должно содержать только плоские пары «ключ — значение». Вложенные структуры и массивы в этом формате не поддерживаются. {{< /alert >}} +Если тело запроса пустое, вебхук отправляет запрос без тела и без заголовка `Content-Type`. Так настраиваются запросы `GET` и `DELETE`. + +Если внешняя система вернула код ответа с ошибкой, тело ответа сохраняется в ответе действия: JSON — как объект, остальное — в поле `raw_body`. Текст ошибки действия имеет вид `unexpected status code: <код>, response: <тело ответа>`, тело ответа обрезается до 8192 байт. + Пример: ```yaml @@ -146,6 +150,7 @@ project_id: {{ .property.project_id }} | `.global` | Глобальные переменные (идентификатор набора, затем ключ) | `{{ .global.myGroup.apiUrl }}` | | `.team` | Переменные команды, выбранной при запуске | `{{ .team.token }}` | | `.store` | Переменные из хранилища процесса | `{{ .store.myKey }}` | +| `.context` | [Контекст запуска процесса](../processes/overview/#контекст-запуска), например данные окружения, выбранного на главной | `{{ .context.environment.slug }}` | #### Обновление параметров сущности @@ -176,6 +181,7 @@ project_id: {{ .property.project_id }} | Поле | Описание | | -------------------------------------- | --------------------------------------------------------------------------------------------- | +| Владелец — инициатор запуска | Владельцем создаваемых сущностей становится пользователь, запустивший действие. Если инициатор неизвестен (запуск автоматизацией или вебхуком), владельцем становится пользователь из поля «Владелец создаваемых сущностей» | | Владелец создаваемых сущностей | Назначается владельцем всем сущностям, которые действие создаёт в каталоге | | Команда-владелец создаваемых сущностей | Назначается командой-владельцем всем сущностям, которые действие создаёт в каталоге | | Ресурс | Ресурс каталога, в котором будет создана сущность | @@ -298,6 +304,14 @@ project_id: {{ .property.project_id }} Подробное описание операций, примеры правил, цикл по коллекции и просмотр хранилища — в разделе [«Хранилище процесса»](../processes/store/). +#### Синхронизация источников данных + +Синхронизация источников данных после действия переносит в каталог объект, который действие создало или удалило во внешней системе, без ожидания синхронизации по расписанию. + +Чтобы включить синхронизацию, включите переключатель в заголовке раздела «Синхронизация источников данных» и выберите источники в поле «Источники данных». Выберите источники, которые загружают в каталог объект, созданный или удалённый действием. Если переключатель включён, выберите хотя бы один источник данных. + +Синхронизация запускается после успешного выполнения действия и применения правил обновления. Синхронизация выполняется в фоне: действие не ожидает её завершения и не завершается ошибкой, если синхронизация не удалась. Удалённые источники данных пропускаются. + ### Безопасность #### Условия выполнения diff --git a/content/documentation/admin/datasets.ru.md b/content/documentation/admin/datasets.ru.md index b433a6ea..dd904314 100644 --- a/content/documentation/admin/datasets.ru.md +++ b/content/documentation/admin/datasets.ru.md @@ -37,6 +37,8 @@ menuTitle: Наборы данных 1. Если параметры не требуются, появится окно подтверждения. 1. После успешного применения все компоненты набора данных будут созданы в системе. +Набор данных, который зависит от другого набора, применяется только после него: иначе применение завершается ошибкой «Ошибка записи набора данных». Если не заполнен обязательный параметр, отображается ошибка «Заполните обязательные параметры набора данных». + ### Удаление набора данных 1. Нажмите кнопку «Удалить» на карточке примененного набора данных. @@ -51,81 +53,51 @@ menuTitle: Наборы данных 1. Заполните необходимые учётные данные (токены, пароли и т.д.). 1. Сохраните изменения. -## Доступные наборы данных - -### GitLab +### Первоначальная настройка -Набор данных предназначен для работы с GitLab-репозиториями и анализа процессов CI/CD. +Кнопка «Первоначальная настройка» открывает мастер, который применяет наборы данных «Каноничной архитектуры» для главной одним запуском: модель каталога, правила маппинга, подключения к Kubernetes, Vault и GitLab, источники данных, процессы и виджеты. +Мастер и наборы данных, которые он применяет, описаны в разделе [«Первоначальная настройка»](home/setup/). -Дашборды: +Переключатель «Показывать баннер первоначальной настройки» возвращает на главную баннер «Платформа готова к настройке», скрытый кнопкой «Скрыть». -- «Статистика репозитория» — для анализа статистики пайплайнов. -- «Управление репозиторием» — для управления репозиториями. +## Доступные наборы данных -Виджеты: +### GitLab -- «Статистика пайплайнов GitLab» — для детальной аналитики пайплайнов. -- «GitLab пайплайны» — для управления пайплайнами. -- «Редактор пайплайнов GitLab» — для редактирования конфигурации пайплайнов. +Набор данных предназначен для подключения к API GitLab. -Настройка: +Создаваемые объекты: -Перед применением создайте [внешний сервис](../external-services/#gitlab) для GitLab и выберите его при настройке набора данных. +- внешний сервис «GitLab»; +- тип учётных данных «GitLab токен» — personal access token для доступа к API GitLab; +- тип учётных данных «GitLab username» — имя пользователя GitLab. Параметры настройки: -- «Внешний сервис» — внешний сервис GitLab, который будет использоваться набором данных. - -Требования: - -- Настроенный внешний сервис GitLab с доступом к API. -- Учётные данные для внешнего сервиса с правами на чтение репозиториев и пайплайнов. - -Применение: +| Название | Описание | Значение по умолчанию | +|--------------|--------------------------------------------------------|-----------------------| +| «URL GitLab» | Базовый URL GitLab, например `https://gitlab.example.com`. Обязательный параметр | — | -1. Создайте внешний сервис для GitLab в разделе «Администрирование» → «Внешние сервисы». -1. Нажмите «Применить» на карточке набора данных GitLab. -1. В форме конфигурации выберите созданный внешний сервис и нажмите «Применить». -1. Перейдите в «Профиль» → «Учётные данные». -1. Заполните учётные данные, указанные во внешнем сервисе. -1. Сохраните изменения. +После применения заполните в профиле пользователя учётные данные «GitLab токен» и «GitLab username». -После этого в разделе «Каталог» появятся ваши репозитории GitLab, а на дашбордах будет отображаться статистика и управление пайплайнами. +Группы, репозитории и виджеты GitLab для главной создают наборы данных «GitLab: группы», «GitLab: активность репозиториев» и «GitLab: виджеты». Они описаны в разделе [«Первоначальная настройка»](home/setup/#наборы-данных-мастера). -### Yandex Cloud +### Kubernetes -Набор данных предназначен для подключения к API Yandex Cloud. +Набор данных предназначен для подключения к API Kubernetes. Создаваемые объекты: -- внешний сервис «Yandex Cloud»; -- тип учётных данных «Yandex Cloud сервисный аккаунт» — JSON-ключ сервисного аккаунта; -- тип учётных данных «Yandex Cloud IAM-токен» — короткоживущий токен для запросов к API; -- действие «Yandex Cloud: получить IAM токен» — получение IAM-токена по JSON-ключу сервисного аккаунта и сохранение его в учётных данных. - -Настройка: - -Набор данных настраивает подключение к API Yandex Cloud через внешний сервис. IAM-токен имеет ограниченный срок действия, поэтому его нужно периодически обновлять с помощью действия «Yandex Cloud: получить IAM токен». - -{{< alert level="info" >}} -После применения укажите в профиле супер-администратора JSON-ключ сервисного аккаунта, затем выполните действие «Yandex Cloud: получить IAM токен» для заполнения IAM-токена. -{{< /alert >}} +- внешний сервис «Kubernetes»; +- тип учётных данных «Kubernetes токен» — токен сервисного аккаунта для доступа к API Kubernetes. Параметры настройки: -| Название | Описание | Значение по умолчанию | -|-----------|-----------------------------------------------|------------------------------------| -| «URL API» | Базовый URL API Yandex Cloud | `https://api.cloud.yandex.net` | - -Применение: - -1. Примените набор данных Yandex Cloud. -1. Перейдите в профиль супер-администратора. -1. Заполните учётные данные «Yandex Cloud сервисный аккаунт» JSON-ключом. -1. Выполните действие «Yandex Cloud: получить IAM токен». -1. Подключите внешний сервис «Yandex Cloud» к действиям, виджетам или источникам данных, которые обращаются к API Yandex Cloud. +| Название | Описание | Значение по умолчанию | +|----------------------|---------------------------------------------------------------------------|-----------------------| +| «URL Kubernetes API» | Базовый URL API-сервера Kubernetes, например `https://api.cluster.example.com`. Обязательный параметр | — | -После этого запросы через внешний сервис будут использовать актуальный IAM-токен из учётных данных пользователя. +После применения заполните в профиле пользователя учётные данные «Kubernetes токен». ### Vault @@ -148,7 +120,7 @@ menuTitle: Наборы данных | Название | Описание | Значение по умолчанию | |-------------|---------------------------------|-------------------------------| -| «URL Vault» | Базовый URL API HashiCorp Vault | `https://vault.example.com` | +| «URL Vault» | Базовый URL API HashiCorp Vault, например `https://vault.example.com`. Обязательный параметр | — | Применение: @@ -178,9 +150,14 @@ menuTitle: Наборы данных | Название | Описание | Значение по умолчанию | |----------|----------|-----------------------| -| «Внешний сервис Kubernetes» | Kubernetes кластер, в котором будет разворачиваться managed PostgreSQL | — | -| «Внешний сервис Vault или Stronghold» | Внешний сервис для записи реквизитов подключения в KV v2 | — | +| «Внешний сервис Kubernetes» | Kubernetes кластер, в котором будет разворачиваться managed PostgreSQL. Обязательный параметр | — | +| «Внешний сервис Vault или Stronghold» | Внешний сервис для записи реквизитов подключения в KV v2. Обязательный параметр | — | | «Префикс пути Vault» | Префикс пути KV v2 для сохранения реквизитов (с `/data/`) | `services/data/` | +| «Создать ресурс каталога» | Создать собственный родительский ресурс набора. Отключите, если процессы привязываются к каноничным общим ресурсам | Включено | +| «Создать действия» | Создать действия создания и удаления managed-сервиса | Включено | +| «Создать процессы» | Создать процессы создания и удаления managed-сервиса | Включено | +| «Создать источник данных» | Собирать инстансы managed-сервиса из кластера в каталог: статус, окружение, класс и выделенные ресурсы. Синхронизируются только объекты с метками DDP | Включено | +| «Ресурс каталога для процессов» | Если задан, процессы привязываются к этому ресурсу вместо собственного родительского. Для каноничной модели главной укажите UUID ресурса «Общие ресурсы» | — | ### Deckhouse managed Valkey @@ -200,9 +177,14 @@ menuTitle: Наборы данных | Название | Описание | Значение по умолчанию | |----------|----------|-----------------------| -| «Внешний сервис Kubernetes» | Kubernetes кластер, в котором будет разворачиваться managed Valkey | — | -| «Внешний сервис Vault или Stronghold» | Внешний сервис для записи реквизитов подключения в KV v2 | — | +| «Внешний сервис Kubernetes» | Kubernetes кластер, в котором будет разворачиваться managed Valkey. Обязательный параметр | — | +| «Внешний сервис Vault или Stronghold» | Внешний сервис для записи реквизитов подключения в KV v2. Обязательный параметр | — | | «Префикс пути Vault» | Префикс пути KV v2 для сохранения реквизитов (с `/data/`) | `services/data/` | +| «Создать ресурс каталога» | Создать собственный родительский ресурс набора. Отключите, если процессы привязываются к каноничным общим ресурсам | Включено | +| «Создать действия» | Создать действия создания и удаления managed-сервиса | Включено | +| «Создать процессы» | Создать процессы создания и удаления managed-сервиса | Включено | +| «Создать источник данных» | Собирать инстансы managed-сервиса из кластера в каталог: статус, окружение, класс и выделенные ресурсы. Синхронизируются только объекты с метками DDP | Включено | +| «Ресурс каталога для процессов» | Если задан, процессы привязываются к этому ресурсу вместо собственного родительского. Для каноничной модели главной укажите UUID ресурса «Общие ресурсы» | — | ### Deckhouse managed Kafka @@ -222,6 +204,11 @@ menuTitle: Наборы данных | Название | Описание | Значение по умолчанию | |----------|----------|-----------------------| -| «Внешний сервис Kubernetes» | Kubernetes кластер, в котором будет разворачиваться managed Kafka | — | -| «Внешний сервис Vault или Stronghold» | Внешний сервис для записи реквизитов подключения в KV v2 | — | +| «Внешний сервис Kubernetes» | Kubernetes кластер, в котором будет разворачиваться managed Kafka. Обязательный параметр | — | +| «Внешний сервис Vault или Stronghold» | Внешний сервис для записи реквизитов подключения в KV v2. Обязательный параметр | — | | «Префикс пути Vault» | Префикс пути KV v2 для сохранения реквизитов (с `/data/`) | `services/data/` | +| «Создать ресурс каталога» | Создать собственный родительский ресурс набора. Отключите, если процессы привязываются к каноничным общим ресурсам | Включено | +| «Создать действия» | Создать действия создания и удаления managed-сервиса | Включено | +| «Создать процессы» | Создать процессы создания и удаления managed-сервиса | Включено | +| «Создать источник данных» | Собирать инстансы managed-сервиса из кластера в каталог: статус, окружение, класс и выделенные ресурсы. Синхронизируются только объекты с метками DDP | Включено | +| «Ресурс каталога для процессов» | Если задан, процессы привязываются к этому ресурсу вместо собственного родительского. Для каноничной модели главной укажите UUID ресурса «Общие ресурсы» | — | diff --git a/content/documentation/admin/datasources/types.ru.md b/content/documentation/admin/datasources/types.ru.md index eb50ba70..17650f56 100644 --- a/content/documentation/admin/datasources/types.ru.md +++ b/content/documentation/admin/datasources/types.ru.md @@ -78,6 +78,51 @@ DDP (портал) выполняет GET-запрос по URL: `/api/v2/produc |tags_sort |Опционально |Направление сортировки тегов. Описание параметра — в [GitLab Tags API](https://docs.gitlab.com/api/tags/#list-project-repository-tags) |`asc`, `desc` |`desc` | |tags_search |Опционально |Строка для поиска тегов по имени. Описание параметра — в [GitLab Tags API](https://docs.gitlab.com/api/tags/#list-project-repository-tags) |Строка |\- | +## GitlabRepositoryActivity + +Источник данных типа `GitlabRepositoryActivity` возвращает активность проектов GitLab: число открытых merge request, последний коммит и последний пайплайн ветки по умолчанию. + +Источник заполняет показатели карточки микросервиса на главной и используется набором данных «GitLab: активность репозиториев». + +### Авторизация + +Конфигурация авторизации описана в разделе [«Внешний сервис GitLab»](../external-services/#gitlab). + +### Спецификация ответа + +Портал выполняет POST-запросы к GraphQL API GitLab по URL `/api/graphql`, по 50 проектов на запрос. Для каждой группы, заданной числовым ID, дополнительно выполняется GET-запрос по URL `/api/v4/groups/:id`. + +Для каждого проекта источник возвращает поля: + +| Поле | Описание | +| ----------------------- | ----------------------------------------------------------------- | +| `path` | Путь проекта без пути группы | +| `gitlab_repository_id` | Числовой ID проекта | +| `default_branch` | Ветка по умолчанию | +| `open_mr_count` | Число открытых merge request | +| `last_commit_sha` | Короткий SHA последнего коммита ветки по умолчанию | +| `last_commit_message` | Заголовок последнего коммита | +| `last_commit_author` | Автор последнего коммита | +| `last_pipeline_id` | Номер (`iid`) последнего пайплайна ветки по умолчанию | +| `last_pipeline_status` | Статус последнего пайплайна в нижнем регистре | +| `last_pipeline_web_url` | Ссылка на последний пайплайн | + +Если у проекта нет коммитов или пайплайнов, поля коммита и пайплайна отсутствуют. + +### Конфигурация + +* `URL` — URL GitLab в формате `https://gitlab.com`, без части `/api/graphql`. + +### Параметры + +| Название | Обязательность | Описание | Возможные значения | По умолчанию | +| ----------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------- | --------------------------- | ------------ | +| all | Опционально | Собирать активность всех проектов, участником которых является пользователь токена. Параметр `group_ids` при этом не используется | true, false | false | +| group_ids | Обязательно, если `all` в значении `false` | ID или полные пути групп через запятую | Пример: `1001,platform/backend` | \- | +| include_subgroups | Опционально | Собирать проекты подгрупп указанных групп | true, false | false | + +Если группа не найдена или недоступна, синхронизация завершается ошибкой `gitlab group "" not found or not accessible`. + ## HarborArtifacts Источник данных типа `HarborArtifacts` собирает информацию о всех артефактах в Harbor. diff --git a/content/documentation/admin/examples/home-custom-catalog.ru.md b/content/documentation/admin/examples/home-custom-catalog.ru.md new file mode 100644 index 00000000..ab5c5cb5 --- /dev/null +++ b/content/documentation/admin/examples/home-custom-catalog.ru.md @@ -0,0 +1,101 @@ +--- +title: Главная для собственной модели каталога +weight: 31 +description: Настройка правил маппинга главной DDP для существующей модели каталога — сопоставление ресурсов, связей и параметров ролям главной без набора данных «Каноничная архитектура». +--- + +Инструкция описывает подключение главной к каталогу, в котором уже есть собственные ресурсы систем, микросервисов и окружений. Набор данных «Каноничная архитектура» в этом сценарии не применяется: главная использует существующие ресурсы через правила маппинга. + +В примере используется каталог со следующими ресурсами: + +- «Продукты» — системы с параметрами «Домен» (`domain`) и «Статус» (`status`); +- «Сервисы» — микросервисы с параметрами «Язык» (`lang`) и «Репозиторий» (`repo_url`); +- «Стенды» — окружения с параметрами «Тип стенда» (`stand_type`) и «Домен» (`base_domain`); +- «Workloads» — развёртывания с параметрами `replicas` и `image`. + +Ресурсы связаны связями «Продукт — сервис», «Сервис — workload» и «Workload — стенд». + +## Перед началом работы + +Для выполнения инструкции требуются разрешения `create:home-mapping-sets`, `update:home-mapping-sets`, а также разрешения на просмотр ресурсов, связей ресурсов, процессов и виджетов, чтобы в форме заполнялись списки выбора. + +## Соответствие ресурсов ролям + +Составьте таблицу соответствия ресурсов, связей и параметров каталога ролям главной. Для примера: + +| Роль | Объект каталога | +| --- | --- | +| `system` | Ресурс «Продукты» | +| `system_domain` | Параметр `domain` ресурса «Продукты» | +| `system_lifecycle` | Параметр `status` ресурса «Продукты» | +| `microservice` | Ресурс «Сервисы» | +| `microservice_language` | Параметр `lang` ресурса «Сервисы» | +| `microservice_repository` | Параметр `repo_url` ресурса «Сервисы» | +| `contains_service` | Связь «Продукт — сервис» | +| `deployment` | Ресурс «Workloads» | +| `deployment_replicas` | Параметр `replicas` ресурса «Workloads» | +| `deployment_image_tag` | Параметр `image` ресурса «Workloads» | +| `has_deployment` | Связь «Сервис — workload» | +| `deployment_in_environment` | Связь «Workload — стенд» | +| `environment` | Ресурс «Стенды» | +| `environment_type` | Параметр `stand_type` ресурса «Стенды» | +| `environment_domain` | Параметр `base_domain` ресурса «Стенды» | + +Роли, которым нет соответствия в каталоге, оставьте пустыми. Разделы, основная роль которых не сопоставлена, покажут сообщение «Настройте правила маппинга или примените набор данных «Каноничная архитектура»». +Перечень всех ролей — в разделе [«Правила маппинга»](../home/mapping/#роли-ресурсов). + +## Создание набора маппинга + +Создайте набор маппинга и сделайте его набором по умолчанию: + +1. Перейдите в раздел «Администрирование» → «Справочники» → «Правила маппинга» и нажмите «Создать». +1. На вкладке «Основная информация» заполните поля: + - «Название» — например `Главная для продуктов`; + - «Идентификатор» — например `home-products`; + - включите «По умолчанию для главной». +1. Перейдите на вкладку «Маппинг каталога». + +## Заполнение областей + +Области заполняются по очереди: связи и параметры роли выбираются из ресурса её родительской роли, поэтому сначала сопоставьте ресурсы. + +Заполните область «Системы»: + +1. В блоке «Ресурс каталога» выберите «Продукты». +1. В блоке «Свойства» выберите `domain` для «Домен системы» и `status` для «Жизненный цикл системы». + +Заполните область «Микросервисы»: + +1. В блоке «Ресурсы каталога» нажмите «Добавить ресурс» и выберите «Сервисы». +1. В карточке ресурса выберите параметры `lang` для «Язык микросервиса» и `repo_url` для «Репозиторий микросервиса». +1. Выберите связь «Продукт — сервис» для «Содержит микросервис» и связь «Сервис — workload» для «Имеет развёртывание». + +Заполните области «Окружения» и «Развёртывания»: + +1. В области «Окружения» выберите ресурс «Стенды» и параметры `stand_type` для «Тип окружения» и `base_domain` для «Домен окружения». +1. В области «Развёртывания» выберите ресурс «Workloads», связь «Workload — стенд» для «Развёртывание в окружении» и параметры `replicas` и `image`. + +Нажмите «Сохранить». + +Если после сохранения изменить ресурс роли, форма очистит зависимые связи и параметры. Проверьте их перед повторным сохранением. + +## Проверка результата + +Откройте главную и проверьте разделы: + +- «Системы» — в дереве «Домены» отображаются продукты, сгруппированные по параметру `domain`. Продукты без значения `domain` в дереве не отображаются; +- «Микросервисы» — в таблице отображаются сервисы, их языки и продукты в колонке «Система»; +- «Окружения» — в таблице отображаются стенды с типами и доменами; +- «Потребление ресурсов» — в таблице отображаются сущности ресурса «Workloads» с числом реплик. + +Если раздел показывает «Настройте правила маппинга или примените набор данных «Каноничная архитектура»», проверьте, что основная роль раздела сопоставлена ресурсу и что у пользователя есть права на просмотр сущностей этого ресурса. + +## Процессы + +Чтобы запускать процессы с главной, добавьте процессы в слоты действий. Например, чтобы создавать стенды кнопкой «Создать окружение»: + +1. Откройте набор маппинга, область «Окружения», блок «Действия». +1. В слоте «Создать окружение» нажмите «Добавить процесс» и выберите процесс создания стенда. +1. Сохраните набор. + +Требования к процессам главной и контекст, который они получают, описаны в разделе [«Процессы главной»](../home/processes/). diff --git a/content/documentation/admin/examples/home-custom-process.ru.md b/content/documentation/admin/examples/home-custom-process.ru.md new file mode 100644 index 00000000..55ad7dc5 --- /dev/null +++ b/content/documentation/admin/examples/home-custom-process.ru.md @@ -0,0 +1,96 @@ +--- +title: Собственный процесс заказа ресурса +weight: 32 +description: Добавление собственного процесса заказа и удаления общего ресурса на главную DDP — параметры из контекста запуска, регистрация ресурса в каталоге, категории слотов order_resource и delete_shared_resource. +--- + +Инструкция описывает добавление на главную заказа собственного типа ресурса — кеша Redis, который выдаёт внутренняя система заказа ресурсов через HTTP API. +В результате Redis отображается в разделе «Заказ ресурсов» как отдельный тип ресурса, заказывается для выбранных системы и окружения и удаляется из списка «Недавние ресурсы». + +## Перед началом работы + +Для выполнения инструкции подготовьте: + +- разрешения на создание действий и процессов и разрешение `update:home-mapping-sets`; +- [внешний сервис](../external-services/) для API системы заказа ресурсов; +- набор маппинга, в котором сопоставлены роли `system`, `environment` и `shared_resource`, например набор, созданный [мастером первоначальной настройки](../home/setup/). + +В примере используются идентификаторы параметров каноничной модели каталога: ресурс «Общие ресурсы» с параметрами `kind`, `provider` и `environment`. Для собственной модели каталога используйте параметры, сопоставленные ролям `shared_kind`, `shared_provider` и `shared_environment`. + +## Действие заказа + +Создайте действие, которое вызывает API системы заказа и регистрирует ресурс в каталоге: + +1. Создайте действие типа HTTP-запроса с внешним сервисом системы заказа. Порядок создания действия описан в разделе [«Действия»](../actions/overview/). +1. Задайте тело запроса с параметрами процесса: + + ```json + { + "name": "{{ .process.instance_name }}", + "namespace": "{{ .process.environment }}", + "owner": "{{ .process.system }}", + "type": "redis" + } + ``` + +1. Настройте [создание сущности](../actions/overview/#создание-сущностей) в ресурсе «Общие ресурсы» после успешного выполнения действия: + - название и идентификатор — `{{ .process.instance_name }}`; + - параметр `kind` — `Redis`; + - параметр `provider` — `Internal`; + - параметр `environment` — `{{ .process.environment }}`. +1. Настройте [создание связи](../actions/overview/#создание-связей-сущности) созданного ресурса с системой запуска — связью, сопоставленной роли `contains_shared`. + +Значения `kind` и `provider` определяют, в какой категории главная ищет процесс удаления ресурса. + +## Процесс заказа + +Процесс получает систему и окружение из контекста запуска: систему, выбранную в заголовке раздела «Заказ ресурсов», и окружение, выбранное в окне «Заказать ресурс». + +Создайте процесс: + +1. Создайте процесс с названием «Заказать Redis» и добавьте в него задачу с действием заказа. Порядок создания процесса описан в разделе [«Процессы»](../processes/overview/). +1. Добавьте параметры процесса: + + | Идентификатор | Значение по умолчанию | Настройки | + | --- | --- | --- | + | `environment` | `{{ .context.environment.slug }}` | Обязательный | + | `system` | `{{ .context.system.slug }}` | Обязательный | + | `instance_name` | `{{ .context.system.slug }}-{{ .context.environment.slug }}` | Обязательный, показывать в упрощённой форме | + +1. Заполните описание процесса: оно отображается на карточке процесса в разделе «Заказ ресурсов». + +Название ресурса по умолчанию `<идентификатор системы>-<идентификатор окружения>` совпадает с названием временной строки, которую главная показывает во время заказа. Если пользователь изменит название, временная строка исчезнет по завершении процесса, а созданный ресурс появится в списке после перезагрузки данных. + +## Процесс удаления + +Процесс удаления запускается для сущности общего ресурса, поэтому данные ресурса процесс получает из корня `.entity`. + +Создайте процесс «Удалить Redis»: + +1. Добавьте задачу с действием, которое вызывает API удаления ресурса и удаляет сущность из каталога после успешного выполнения. Удаление сущности настраивается в разделе действия [«Удаление сущностей»](../actions/overview/#удаление-сущностей). +1. Добавьте обязательный параметр `instance_name` со значением по умолчанию `{{ .entity.slug }}` и используйте его в теле запроса. + +## Добавление процессов на главную + +Добавьте процессы в слоты действий набора маппинга: + +1. Перейдите в раздел «Администрирование» → «Справочники» → «Правила маппинга» и откройте набор по умолчанию. +1. На вкладке «Маппинг каталога» раскройте область «Общие ресурсы» и найдите блок «Действия». +1. В слоте «Заказать ресурс» нажмите «Добавить категорию», укажите категорию `Redis` и добавьте процесс «Заказать Redis». +1. В слоте «Удалить общий ресурс» нажмите «Добавить категорию», укажите категорию `Internal Redis` и добавьте процесс «Удалить Redis». +1. Нажмите «Сохранить». + +Категория `Internal Redis` состоит из значений параметров `provider` и `kind` ресурса. По ней главная выбирает процесс удаления для ресурсов Redis и не предлагает его для ресурсов других типов. + +## Проверка результата + +Проверьте заказ и удаление ресурса: + +1. Откройте главную → «Заказ ресурсов» и выберите систему. +1. Убедитесь, что в показателе «Типы ресурсов» есть `Redis`, а в каталоге процессов — карточка «Заказать Redis». +1. Нажмите «Запустить» на карточке, выберите окружение и нажмите «Далее». +1. В окне «Запустить процесс» проверьте, что параметр `instance_name` заполнен значением `<система>-<окружение>`, и нажмите «Запустить». +1. Дождитесь, пока в списке «Недавние ресурсы» строка с подписью «создаётся» заменится созданным ресурсом. +1. Нажмите «Удалить» в строке ресурса и запустите процесс удаления. + +Если параметр `environment` не заполнился, проверьте, что шаблон значения по умолчанию начинается с `.context`, и что окружение выбрано в окне «Заказать ресурс». Контекст каждого сценария главной описан в разделе [«Процессы главной»](../home/processes/#сущность-и-контекст-по-сценариям). diff --git a/content/documentation/admin/examples/home-quick-start.ru.md b/content/documentation/admin/examples/home-quick-start.ru.md new file mode 100644 index 00000000..569274e8 --- /dev/null +++ b/content/documentation/admin/examples/home-quick-start.ru.md @@ -0,0 +1,127 @@ +--- +title: Быстрая настройка главной +weight: 30 +description: Пошаговая настройка главной DDP на новой установке — мастер первоначальной настройки, включение главной, учётные данные, реестр шаблонов, привязка процессов к шаблонам и проверка результата. +--- + +Инструкция описывает настройку главной на новой установке Deckhouse Development Portal (DDP, портал) с каноничной моделью каталога. В результате на главной отображаются окружения и развёртывания кластера, а разработчики создают микросервисы из шаблонов и разворачивают их на окружения. + +## Перед началом работы + +Для выполнения инструкции подготовьте: + +- пользователя портала с разрешениями `apply:seeds`, `update:home-mapping-sets`, `edit:template-registries` и `read:template-packs`, например с пресетом роли «Admin»; +- URL API-сервера Kubernetes и токен сервисного аккаунта с правами на создание неймспейсов и развёртываний; +- URL Vault или Deckhouse Stronghold и токен доступа; +- URL GitLab, персональный токен GitLab с правами на создание проектов и имя пользователя GitLab; +- хранилище образов контейнеров с опубликованными пакетами шаблонов. Как опубликовать пакет, описано в примере [«Создание и публикация шаблона микросервиса»](template-first-pack/). + +## Применение наборов данных + +Наборы данных создают модель каталога, правила маппинга, подключения к внешним системам, источники данных и процессы главной. + +Чтобы применить наборы данных: + +1. Перейдите в раздел «Администрирование» → «Справочники» → «Наборы данных» и нажмите «Первоначальная настройка». +1. На шаге «Пресет» выберите «Настройка платформы». Чтобы наполнить каталог примерами, выберите «Настройка платформы с демоданными». +1. На шаге «Выбор» оставьте все наборы отмеченными и нажмите «Далее». +1. На шаге «Параметры» заполните обязательные параметры: + - «URL Kubernetes API» в наборе «Kubernetes», например `https://api.cluster.example.com`; + - «URL Vault» в наборе «Vault», например `https://vault.example.com`; + - «URL GitLab» в наборе «GitLab», например `https://gitlab.example.com`. + + Остальные параметры мастер заполняет автоматически. +1. На шаге «Проверка» включите «Подтвердить применение» и нажмите «Применить». +1. Дождитесь сообщения «Все выбранные наборы успешно применены». + +Если применение набора завершилось ошибкой, исправьте причину и нажмите «Повторить с текущего». + +## Включение главной + +Главная выключена после установки портала. Включите её: + +1. Перейдите в раздел «Администрирование» → «Справочники» → «Правила маппинга». +1. Убедитесь, что в таблице есть набор «Главная (по умолчанию)» с включённым переключателем «По умолчанию для главной». +1. Включите переключатель «Показывать главную». + +В верхней панели портала появится вкладка «Главная». + +## Учётные данные + +Процессы главной выполняют действия в Kubernetes, Vault и GitLab с учётными данными пользователя, который их запускает. + +Заполните учётные данные в профиле пользователя: токен Kubernetes, токен Vault, токен и имя пользователя GitLab. Порядок описан в разделе [«Учётные данные»](../../user/credentials/). + +Каждый пользователь, который запускает процессы с главной, заполняет учётные данные в своём профиле. + +## Окружения из кластера + +Источники данных Kubernetes загружают в каталог только неймспейсы, Deployment и Ingress с лейблом `ddp.deckhouse.io/environment`. Неймспейсы, созданные кнопкой «Создать окружение» на главной, получают лейбл автоматически. + +Чтобы существующий неймспейс отображался на главной как окружение, добавьте ему лейбл со значением, равным имени неймспейса: + +```shell +d8 k label namespace ddp.deckhouse.io/environment= +``` + +Где `` — имя неймспейса. + +Неймспейсы `d8-*` и `kube-*` не загружаются. + +Окружение появится в разделе «Окружения» после синхронизации источника данных неймспейсов из набора «Kubernetes: deployments, ingresses и namespaces». Заполните в каталоге параметры окружения, которые не приходят из кластера: тип, домен и связь с кластером. + +## Подключение реестра шаблонов + +Реестр шаблонов подключает хранилище образов с пакетами шаблонов. Подключите хранилище: + +1. Перейдите в раздел «Администрирование» → «Интеграции» → «Шаблоны». +1. На вкладке «Реестры» нажмите «Подключить реестр» и заполните поля: + - «Название» — например `company`; + - «Реестр» — хост хранилища, например `registry.example.com`; + - «Префикс репозиториев» — например `ddp-templates`; + - «Имя пользователя» и «Пароль» — учётные данные хранилища. +1. Сохраните подключение. +1. На вкладке «Настройки» включите «Включить синхронизацию» и сохраните настройки. +1. На вкладке «Запуски синхронизации» нажмите «Синхронизировать» и дождитесь статуса «Успех». +1. На вкладке «Шаблоны» проверьте, что у версий шаблонов статус «доступна». + +Если синхронизация завершилась ошибкой, текст ошибки отображается в колонке «Ошибка». Причины ошибок описаны в разделе [«Реестр шаблонов»](../templates/registry/#ошибки-синхронизации). + +## Привязка процессов к шаблонам + +Действия над микросервисом выполняют процессы, привязанные к шаблону микросервиса. Набор данных «Реестр шаблонов микросервисов» создал процессы, которые подходят для любого шаблона. + +Привяжите процессы к каждому шаблону: + +1. Перейдите в раздел «Администрирование» → «Справочники» → «Правила маппинга» и откройте набор «Главная (по умолчанию)». +1. На вкладке «Маппинг каталога» раскройте область «Микросервисы» и найдите блок «Действия по шаблонам». +1. Нажмите «Добавить шаблон» и выберите шаблон в поле «Шаблон». +1. Выберите процессы действий: + - «Создать микросервис» — «Создать микросервис из шаблона»; + - «Развернуть микросервис на окружение» — «Развернуть микросервис на окружение»; + - «Удалить микросервис с окружения» — «Удалить микросервис с окружения»; + - «Обновить микросервис из шаблона» — «Обновить микросервис из шаблона». +1. Повторите шаги 3–4 для остальных шаблонов и нажмите «Сохранить». + +## Проверка результата + +Проверьте работу главной на создании микросервиса: + +1. Откройте вкладку «Главная» → «Создать микросервис». +1. Выберите шаблон, заполните шаги «Сервис» и «Параметры» и нажмите «Создать микросервис». +1. В окне «Запустить процесс» нажмите «Запустить». +1. Дождитесь завершения процесса в панели «Мои активности». + +Главная настроена, если выполнены условия: + +- в GitLab создан проект микросервиса с файлом `.ddp/template.lock.yaml`; +- микросервис отображается в разделе «Микросервисы», а в его карточке заполнены поля «Шаблон» и «Версия»; +- в разделе «Окружения» отображаются окружения кластера. + +## Следующие шаги + +После базовой настройки выполните при необходимости: + +- настройку автоматического обновления микросервисов — пример [«Выпуск новой версии шаблона и обновление микросервисов»](template-release-update/); +- добавление собственных процессов на главную — пример [«Собственный процесс заказа ресурса»](home-custom-process/); +- выдачу разработчикам доступа к сущностям каталога — раздел [«Права доступа»](../home/overview/#права-доступа). diff --git a/content/documentation/admin/examples/home-widget-slot.ru.md b/content/documentation/admin/examples/home-widget-slot.ru.md new file mode 100644 index 00000000..cd359976 --- /dev/null +++ b/content/documentation/admin/examples/home-widget-slot.ru.md @@ -0,0 +1,61 @@ +--- +title: Виджет на вкладке микросервиса +weight: 33 +description: Вывод виджета GitLab на вкладках «Пайплайны» и «MRs» карточки микросервиса на главной DDP — конфигурация виджета с контекстом микросервиса и заполнение слотов виджетов в правилах маппинга. +--- + +Инструкция описывает вывод виджета «GitLab. Пайплайны» на вкладке «Пайплайны» карточки микросервиса. Виджет показывает пайплайны репозитория того микросервиса, карточка которого открыта. + +Один виджет обслуживает все микросервисы: идентификатор проекта GitLab виджет получает из контекста карточки, а не из собственной конфигурации. + +## Перед началом работы + +Для выполнения инструкции подготовьте: + +- разрешения на создание виджетов и разрешение `update:home-mapping-sets`; +- внешний сервис GitLab; +- у сущностей микросервисов — параметр с числовым ID проекта GitLab, сопоставленный роли `microservice_gitlab_project_id`. В каноничной модели каталога это параметр `gitlab_repository_id`, который заполняет процесс создания микросервиса из шаблона или источник данных «GitLab: активность репозиториев». + +Набор данных «GitLab: виджеты» создаёт готовые виджеты для обеих вкладок. Инструкция показывает, как настроить виджет самостоятельно, например для другой системы контроля версий или с другими параметрами. + +## Создание виджета + +Создайте виджет с идентификатором проекта из контекста: + +1. Создайте виджет типа [«GitLab. Пайплайны»](../widgets/gitlab/pipelines/) с внешним сервисом GitLab. +1. В поле «ID проекта» укажите `{{ .context.repository.id }}`. +1. Сохраните виджет. + +Главная передаёт виджету на вкладке карточки микросервиса следующие значения: + +| Путь | Значение | +| --- | --- | +| `.context.microservice.uuid` | UUID сущности микросервиса | +| `.context.microservice.slug` | Идентификатор микросервиса | +| `.context.microservice.name` | Название микросервиса | +| `.context.repository.id` | Значение роли `microservice_gitlab_project_id` | +| `.context.repository.url` | Значение роли `microservice_repository` | + +Контекст передаётся только на вкладках карточки микросервиса. Для дашбордов создайте отдельный виджет с конкретным ID проекта. + +## Заполнение слота виджета + +Добавьте виджет в слот вкладки «Пайплайны»: + +1. Перейдите в раздел «Администрирование» → «Справочники» → «Правила маппинга» и откройте набор по умолчанию. +1. На вкладке «Маппинг каталога» раскройте область «Микросервисы» и найдите блок «Виджеты». +1. В поле «Виджет вкладки «Пайплайны»» выберите созданный виджет. +1. Нажмите «Сохранить». + +Вкладка «MRs» заполняется полем «Виджет вкладки «MRs»», например виджетом [«GitLab. Запросы слияния»](../widgets/gitlab/merge-requests/) с тем же значением поля «ID проекта». + +## Проверка результата + +Проверьте виджет на главной: + +1. Откройте главную → «Микросервисы» и выберите микросервис в таблице. +1. Откройте вкладку «Пайплайны» в карточке микросервиса. + +На вкладке отображаются пайплайны репозитория выбранного микросервиса. При выборе другого микросервиса виджет показывает пайплайны его репозитория. + +Если на вкладке отображается «Раздел пока недоступен», слот виджета не заполнен. Если виджет не показывает данные, проверьте, что у микросервиса заполнен параметр, сопоставленный роли `microservice_gitlab_project_id`. diff --git a/content/documentation/admin/examples/microservice-lifecycle.ru.md b/content/documentation/admin/examples/microservice-lifecycle.ru.md new file mode 100644 index 00000000..469c7d68 --- /dev/null +++ b/content/documentation/admin/examples/microservice-lifecycle.ru.md @@ -0,0 +1,91 @@ +--- +title: Микросервис от создания до развёртывания +weight: 42 +description: Сквозной сценарий работы разработчика на главной DDP — создание микросервиса из шаблона, создание окружения, развёртывание, заказ и подключение базы данных, обновление из шаблона. +--- + +Инструкция описывает путь нового микросервиса на главной: создание из шаблона, развёртывание на временное окружение, заказ базы данных PostgreSQL и её подключение к микросервису. +Сценарий выполняется разработчиком на главной без обращения к каталогу и администрированию. + +## Перед началом работы + +Для выполнения инструкции требуется: + +- главная, настроенная администратором портала, например по инструкции [«Быстрая настройка главной»](home-quick-start/); +- доступ к сущностям каталога и право на запуск процессов; +- учётные данные Kubernetes, Vault и GitLab в [профиле пользователя](../../user/credentials/). + +## Создание микросервиса + +Создайте микросервис из шаблона: + +1. Откройте главную → «Создать микросервис». +1. На шаге «Шаблон» выберите шаблон, например «Go service», и нажмите «Далее». +1. На шаге «Сервис» заполните поля: + - «Название микросервиса» — `Billing API`; + - «Идентификатор микросервиса» — заполнится как `billing-api`; + - «Система» — система, в которую войдёт микросервис; + - «Пространство в системе контроля версий» — группа GitLab для репозитория. +1. Нажмите «Далее», заполните параметры шаблона и нажмите «Создать микросервис». +1. В окне «Запустить процесс» нажмите «Запустить». + +Ход создания отображается в строке «Выполняются процессы». После завершения процесса микросервис появится в разделе «Микросервисы», а в GitLab — репозиторий `billing-api`. + +## Создание окружения + +Создайте временное окружение для проверки микросервиса: + +1. Откройте главную → «Окружения» и нажмите «Создать окружение». +1. Заполните «Идентификатор», например `billing-review`, и выберите «TTL» — «7 дней». +1. Нажмите «Запустить». + +Пока окружение создаётся, в таблице отображается строка `billing-review` с подписью «создаётся». Окружение появится в таблице после синхронизации каталога с кластером. + +Чтобы у микросервиса был адрес на окружении, задайте домен окружения: откройте карточку окружения, нажмите значок карандаша в строке «Домен» и введите домен, например `review.example.com`. + +## Развёртывание микросервиса + +Разверните микросервис на созданное окружение: + +1. Откройте главную → «Развертывание систем», выберите систему микросервиса и окружение `billing-review`. +1. Нажмите «Развернуть микросервис». +1. Выберите микросервис `Billing API` и окружение `billing-review`, нажмите «Далее». +1. В окне «Запустить процесс» нажмите «Запустить». + +В колонке «Развертывания» появится карточка `Billing API` с подписью «создаётся», а после завершения процесса — карточка развёртывания с параметрами реплик и ресурсов. +При заданном домене окружения процесс из набора данных создаёт Ingress с хостом `billing-api.review.example.com`, который отображается в колонке «Инфраструктура». + +## Заказ базы данных + +Закажите базу данных PostgreSQL для микросервиса: + +1. В разделе «Развертывание систем» нажмите «Заказать ресурс» под колонкой «Ресурсы данных». +1. В окне «Заказать ресурс» выберите «Сервис» — процесс заказа PostgreSQL. Окружение `billing-review` уже выбрано. +1. Нажмите «Далее» и в окне «Запустить процесс» нажмите «Запустить». + +В колонке «Ресурсы данных» появится карточка ресурса. Реквизиты подключения к базе данных записываются в Vault. + +## Подключение базы данных + +Подключите базу данных к развёртыванию микросервиса: + +1. Нажмите на точку слева на карточке базы данных и перетащите линию на карточку развёртывания `Billing API`. +1. В окне «Запустить процесс» нажмите «Запустить». + +После завершения процесса на схеме отображается линия подключения, а секреты базы данных доставлены в приложение. + +## Обновление из шаблона + +Когда автор шаблона выпустит новую версию, в карточке микросервиса появится блок «Доступна версия {version}». + +Обновите микросервис: + +1. Откройте главную → «Микросервисы» и выберите `Billing API`. +1. Нажмите «Обновить» и в окне «Запустить процесс» нажмите «Запустить». +1. Откройте merge request `Upgrade <шаблон> to <версия>` в GitLab, проверьте изменения и примите его. + +## Удаление + +DDP записывает TTL в лейбл `ddp.deckhouse.io/deletion-ttl` неймспейса. Окружение удаляется по истечении TTL, если в кластере настроена очистка неймспейсов по этому лейблу. Чтобы удалить окружение сразу, откройте его карточку в разделе «Окружения» и нажмите «Удалить окружение» в блоке «Опасная зона». + +Удаление окружения удаляет все развёртывания в нём. diff --git a/content/documentation/admin/examples/template-first-pack.ru.md b/content/documentation/admin/examples/template-first-pack.ru.md new file mode 100644 index 00000000..3576e305 --- /dev/null +++ b/content/documentation/admin/examples/template-first-pack.ru.md @@ -0,0 +1,208 @@ +--- +title: Создание и публикация шаблона микросервиса +weight: 40 +description: Пошаговое создание пакета шаблона Go-сервиса для DDP — манифест, параметры, файлы, проверка утилитой ddp-template, публикация в хранилище образов, синхронизация и создание микросервиса из шаблона. +--- + +Инструкция описывает создание шаблона HTTP-сервиса на Go и его публикацию в реестр шаблонов портала. В результате шаблон отображается в галерее раздела главной «Создать микросервис», а созданный из него репозиторий содержит код, CI и Helm-чарт. + +## Перед началом работы + +Для выполнения инструкции подготовьте: + +- хранилище образов контейнеров с OCI Distribution Spec v2, например `registry.example.com`, и токен с правами на запись в репозиторий `ddp-templates/go-service`; +- утилиту `ddp-template`; +- подключение этого хранилища в реестре шаблонов портала с префиксом репозиториев `ddp-templates`. Порядок подключения описан в разделе [«Реестр шаблонов»](../templates/registry/#подключение-хранилища). + +## Структура пакета + +Создайте директорию пакета со следующими файлами: + +```text +go-service/ + template.yaml + values.yaml + .templateignore + .editorconfig + .gitlab-ci.yml + go.mod + cmd/{{ .slug }}/main.go + deploy/helm/Chart.yaml + deploy/helm/values.yaml + deploy/helm/templates/deployment.yaml +``` + +Директория `cmd/{{ .slug }}` получит имя по идентификатору микросервиса. + +### Манифест + +Манифест `template.yaml` задаёт идентификатор шаблона и правила обновления. CI и Helm-чарт принадлежат шаблону и перезаписываются при обновлении, а `.editorconfig` добавляется, только если его нет в репозитории: + +```yaml +id: go-service +name: Go service +description: HTTP service on Go with GitLab CI and Helm chart +language: Go +tags: + - http + - helm +update: + strategy: selective_additive + overwrite: + - .gitlab-ci.yml + - deploy/** + addIfMissing: + - .editorconfig +``` + +Значение `id` совпадает с именем репозитория пакета в хранилище: `ddp-templates/go-service`. + +### Параметры + +Файл `values.yaml` описывает параметры шаблона. Идентификатор, название микросервиса и система заполняются из контекста запуска и не отображаются в форме; порт пользователь вводит на шаге «Параметры»: + +```yaml +type: object +required: + - slug + - name + - system + - port +properties: + slug: + type: string + title: Service identifier + x-ddp-from: context.microservice.slug + name: + type: string + title: Service name + x-ddp-from: context.microservice.name + system: + type: string + title: System + x-ddp-from: context.system.slug + port: + type: integer + title: HTTP port + description: Port the service listens on + default: 8080 +``` + +### Файлы репозитория + +Файлы репозитория используют параметры шаблона. Файл `go.mod`: + +```go-html-template +module {{ .slug }} + +go 1.23 +``` + +Файл `cmd/{{ .slug }}/main.go`: + +```go-html-template +package main + +import ( + "log" + "net/http" +) + +func main() { + // Service {{ .name }} of system {{ .system }}. + log.Fatal(http.ListenAndServe(":{{ .port }}", nil)) +} +``` + +Файл `deploy/helm/values.yaml`: + +```go-html-template +name: {{ .slug }} +system: {{ .system }} +port: {{ .port }} +``` + +Файл `deploy/helm/templates/deployment.yaml` использует синтаксис Helm `{{ .Values }}`. Чтобы портал не обрабатывал его как шаблон, добавьте путь в `.templateignore`: + +```text +# Helm templates are copied as is. +deploy/helm/templates/** +``` + +## Проверка пакета + +Проверьте пакет утилитой `ddp-template`: + +```shell +ddp-template lint ./go-service +``` + +Команда проверяет манифест, схему параметров, `.templateignore`, списки путей обновления и выполняет пробную отрисовку. Код завершения `0` означает, что ошибок нет. + +Чтобы посмотреть результат отрисовки, создайте файл `test-values.yaml` с тестовыми значениями и отрисуйте пакет: + +```yaml +slug: billing-api +name: Billing API +system: billing +port: 8080 +``` + +```shell +ddp-template render ./go-service --values ./test-values.yaml --output ./render-out +``` + +В директории `./render-out` появятся файлы репозитория: `cmd/billing-api/main.go`, `go.mod` с `module billing-api` и неизменённые Helm-шаблоны. + +## Публикация + +Опубликуйте версию `1.0.0` в хранилище образов: + +```shell +export DDP_TEMPLATE_REGISTRY_TOKEN= +ddp-template publish ./go-service --version 1.0.0 \ + --registry registry.example.com \ + --repository-prefix ddp-templates +``` + +Где `` — токен хранилища образов с правами на запись. + +Команда выводит JSON с полями `templateId`, `version`, `ociRef` и `sha256`. Опубликованную версию перезаписать нельзя: для изменений публикуйте новую версию. + +## Синхронизация + +Портал загружает версию при следующей синхронизации реестра шаблонов. Чтобы загрузить версию сразу: + +1. Перейдите в раздел «Администрирование» → «Интеграции» → «Шаблоны» → «Запуски синхронизации». +1. Нажмите «Синхронизировать» и дождитесь статуса «Успех». +1. На вкладке «Шаблоны» найдите `go-service` версии `1.0.0` и убедитесь, что у неё статус «доступна» и тег «последняя». + +Если поле «Идентификаторы репозиториев» подключения заполнено, добавьте в него `go-service` перед синхронизацией. + +Если у версии статус «некорректна», причина указана в колонке «Причина статуса». Исправьте пакет и опубликуйте версию `1.0.1`. + +## Привязка процессов + +Привяжите к шаблону процессы в правилах маппинга главной: + +1. Перейдите в раздел «Администрирование» → «Справочники» → «Правила маппинга» и откройте набор по умолчанию. +1. На вкладке «Маппинг каталога» раскройте «Микросервисы» → «Действия по шаблонам» и нажмите «Добавить шаблон». +1. Выберите шаблон `go-service` и процессы действий «Создать микросервис», «Развернуть микросервис на окружение», «Удалить микросервис с окружения» и «Обновить микросервис из шаблона». +1. Нажмите «Сохранить». + +## Проверка результата + +Создайте микросервис из шаблона: + +1. Откройте главную → «Создать микросервис» и выберите карточку «Go service». +1. На шаге «Сервис» заполните название `Billing API`, выберите систему и пространство GitLab и нажмите «Далее». +1. На шаге «Параметры» проверьте, что отображается только поле «HTTP port», и нажмите «Создать микросервис». +1. В окне «Запустить процесс» нажмите «Запустить» и дождитесь завершения процесса. + +Шаблон работает, если выполнены условия: + +- в GitLab создан проект `billing-api` с файлами `cmd/billing-api/main.go` и `.ddp/template.lock.yaml`; +- в lock-файле указаны `templateId: go-service` и `templateVersion: 1.0.0`; +- в карточке микросервиса на главной поля «Шаблон» и «Версия» содержат `go-service` и `1.0.0`. + +Выпуск следующей версии шаблона и обновление микросервисов описаны в примере [«Выпуск новой версии шаблона и обновление микросервисов»](template-release-update/). diff --git a/content/documentation/admin/examples/template-release-update.ru.md b/content/documentation/admin/examples/template-release-update.ru.md new file mode 100644 index 00000000..0b081529 --- /dev/null +++ b/content/documentation/admin/examples/template-release-update.ru.md @@ -0,0 +1,119 @@ +--- +title: Выпуск новой версии шаблона и обновление микросервисов +weight: 41 +description: Выпуск новой версии шаблона микросервиса DDP и перенос изменений в репозитории микросервисов — локальная проверка обновления, ручное обновление кнопкой, автоматическое обновление и разбор конфликтов. +--- + +Инструкция описывает выпуск версии `1.1.0` шаблона `go-service` и обновление микросервисов, созданных из версии `1.0.0`. В новой версии меняется CI и добавляется файл `.dockerignore`. +В результате в репозиториях микросервисов открываются merge request с изменениями шаблона, а после их принятия версия шаблона микросервисов в каталоге становится `1.1.0`. + +Инструкция продолжает пример [«Создание и публикация шаблона микросервиса»](template-first-pack/). + +## Перед началом работы + +Для выполнения инструкции подготовьте: + +- шаблон `go-service` версии `1.0.0` в реестре шаблонов и микросервисы, созданные из него; +- процесс «Обновить микросервис из шаблона», привязанный к шаблону в блоке «Действия по шаблонам» правил маппинга; +- разрешение `edit:template-registries` для изменения настроек реестра шаблонов. + +## Подготовка новой версии + +Внесите изменения в пакет: + +1. Измените `.gitlab-ci.yml`, например добавьте задачу тестирования. +1. Создайте файл `.dockerignore`. +1. Добавьте `.dockerignore` в список `update.addIfMissing` манифеста: + + ```yaml + update: + strategy: selective_additive + overwrite: + - .gitlab-ci.yml + - deploy/** + addIfMissing: + - .editorconfig + - .dockerignore + ``` + +1. Проверьте пакет командой `ddp-template lint ./go-service`. + +Файлы, которые не входят в `update.overwrite` и `update.addIfMissing`, например `cmd/{{ .slug }}/main.go`, при обновлении не изменяются: изменения разработчиков в этих файлах сохраняются. + +## Проверка обновления на копии микросервиса + +Перед публикацией проверьте, какие файлы изменит обновление в существующем микросервисе. Скопируйте раздел `values` lock-файла `.ddp/template.lock.yaml` микросервиса в файл `service-values.yaml` и отрисуйте новую версию с имитацией стратегии обновления: + +```shell +ddp-template render ./go-service \ + --values ./service-values.yaml \ + --use-overwrite \ + --output ./render-out +``` + +Значения параметров с аннотацией `x-ddp-from` в lock-файле уже записаны, поэтому команда отрисует файлы с данными микросервиса. + +## Публикация и синхронизация + +Опубликуйте версию `1.1.0` и загрузите её в портал: + +1. Выполните публикацию: + + ```shell + ddp-template publish ./go-service --version 1.1.0 \ + --registry registry.example.com \ + --repository-prefix ddp-templates + ``` + +1. Перейдите в раздел «Администрирование» → «Интеграции» → «Шаблоны» → «Запуски синхронизации», нажмите «Синхронизировать» и дождитесь статуса «Успех». +1. На вкладке «Шаблоны» убедитесь, что тег «последняя» отмечает версию `1.1.0`. + +## Ручное обновление + +Обновите один микросервис кнопкой в карточке: + +1. Откройте главную → «Микросервисы» и выберите микросервис, созданный из `go-service`. +1. На вкладке «Справка» в блоке «Доступна версия 1.1.0» нажмите «Обновить». +1. В окне «Запустить процесс» нажмите «Запустить» и дождитесь завершения процесса в панели «Мои активности». +1. Откройте проект микросервиса в GitLab и найдите merge request `Upgrade go-service to 1.1.0` из ветки `ddp/template-upgrade-1.1.0`. + +Merge request содержит изменённый `.gitlab-ci.yml`, новый `.dockerignore` и lock-файл с версией `1.1.0`. Если `.dockerignore` уже был в репозитории, он не изменяется. + +Примите merge request. Через интервал сверки версии поле «Версия» в карточке микросервиса примет значение `1.1.0`, а блок «Доступна версия» исчезнет. +Сверка версии выполняется, если в настройках реестра задан пользователь автоматизации; без него версия в каталоге обновится при следующем запуске процесса обновления. + +## Автоматическое обновление + +Автоматическое обновление открывает merge request во всех микросервисах шаблона без нажатия кнопки. Настройте его до публикации следующей версии. + +Настройте пользователя автоматизации: + +1. Создайте сервисного пользователя, например `template-bot`, и заполните в его профиле токен и имя пользователя GitLab. +1. Перейдите в раздел «Администрирование» → «Интеграции» → «Шаблоны» → «Настройки». +1. Выберите пользователя в поле «Пользователь автоматизации». +1. Задайте «Лимит очереди обновлений» не меньше числа микросервисов шаблона, например `20`, и сохраните настройки. + +Включите автоматическое обновление для микросервисов: откройте сущность микросервиса в каталоге и установите параметр «Политика обновления шаблона» в значение «Ревью автоматически». + +После публикации и синхронизации следующей версии, например `1.2.0`, портал запустит процесс обновления для каждого микросервиса с политикой «Ревью автоматически» от имени пользователя автоматизации. Merge request создаются так же, как при ручном обновлении. + +Автоматическое обновление не запускается для микросервиса, если в его репозитории открыт merge request обновления из предыдущей версии. Примите или закройте такой merge request и обновите микросервис кнопкой «Обновить». + +## Конфликты и ручные изменения + +Стратегия `selective_additive` перезаписывает `.gitlab-ci.yml` и файлы `deploy/**` целиком. Если разработчики изменили эти файлы в репозитории, их изменения будут заменены версией шаблона в merge request; проверьте изменения перед принятием. + +Чтобы сохранить изменения разработчиков в файлах шаблона, задайте для микросервиса стратегию `merge`: + +1. Откройте сущность микросервиса в каталоге. +1. Установите параметр «Стратегия обновления шаблона» в значение `merge`. +1. Запустите обновление кнопкой «Обновить». + +При стратегии `merge` портал сливает изменения шаблона с изменениями в репозитории. Если изменения пересекаются, обновление завершается ошибкой `merge_conflict` со списком файлов, и репозиторий не изменяется. +В этом случае верните стратегию `selective_additive`, запустите обновление и перенесите изменения разработчиков в ветку merge request вручную. + +## Удаление файлов из шаблона + +Обновление не удаляет файлы. Если в новой версии шаблона файл удалён или переименован, старый файл остаётся в репозиториях микросервисов. + +Опишите в описании версии шаблона, какие файлы нужно удалить, и удалите их в ветке merge request обновления до его принятия. diff --git a/content/documentation/admin/home/_index.ru.md b/content/documentation/admin/home/_index.ru.md new file mode 100644 index 00000000..c0d75178 --- /dev/null +++ b/content/documentation/admin/home/_index.ru.md @@ -0,0 +1,4 @@ +--- +title: Главная +weight: 25 +--- diff --git a/content/documentation/admin/home/mapping.ru.md b/content/documentation/admin/home/mapping.ru.md new file mode 100644 index 00000000..522b8187 --- /dev/null +++ b/content/documentation/admin/home/mapping.ru.md @@ -0,0 +1,361 @@ +--- +title: Правила маппинга +weight: 30 +description: Справочник по наборам маппинга главной DDP — форма набора, области, роли ресурсов, связей и свойств, слоты действий, действия по шаблонам, слоты виджетов и ошибки проверки. +--- + +Правила маппинга сопоставляют понятиям главной ресурсы, связи, параметры, процессы и виджеты каталога. +Правила хранятся в наборах маппинга главной; главная использует набор по умолчанию. Как главная выбирает набор, описано в разделе [«Обзор»](overview/#набор-маппинга-по-умолчанию). + +## Страница «Правила маппинга» + +Наборы маппинга находятся в разделе «Администрирование» → «Справочники» → «Правила маппинга». + +На панели над таблицей расположены: + +- переключатель «Показывать главную» — включает и выключает главную для всех пользователей; +- кнопка «Создать» — открывает форму нового набора; +- поле «Поиск» — фильтрует наборы по названию и идентификатору. + +В таблице наборов отображаются следующие колонки: + +| Колонка | Содержимое | +| --- | --- | +| «Название» | Название набора | +| «Идентификатор» | Идентификатор набора | +| «По умолчанию для главной» | Переключатель набора по умолчанию. У текущего набора по умолчанию переключатель недоступен: чтобы сменить набор, включите переключатель у другого набора | +| «Ресурсы» | Число сопоставленных ролей ресурсов | +| «Связи» | Число сопоставленных ролей связей | +| «Свойства» | Число сопоставленных ролей свойств | +| «Слоты действий» | Число заполненных слотов действий | +| «Шаблоны» | Число шаблонов, к которым привязан хотя бы один процесс | +| «Виджеты» | Число заполненных слотов виджетов | + +Для удаления набора введите его идентификатор в окне подтверждения. Набор по умолчанию удалить нельзя. + +Права на работу с наборами: + +- `create:home-mapping-sets` — создание наборов; +- `update:home-mapping-sets` — изменение наборов, выбор набора по умолчанию, переключатель «Показывать главную»; +- `delete:home-mapping-sets` — удаление наборов. + +Для просмотра наборов разрешение не требуется: наборы читает каждая страница главной. +Чтобы в форме набора заполнялись списки выбора, пользователю также нужны разрешения на просмотр ресурсов, связей ресурсов, процессов (`read:processes`), виджетов (`read:widgets`) и шаблонов (`read:template-packs`). + +## Форма набора + +Форма набора открывается кнопкой «Создать» или кнопкой редактирования в строке таблицы. Форма содержит две вкладки. + +На вкладке «Основная информация» заполняются поля: + +- «Название» — от 3 до 64 символов; +- «Идентификатор» — стабильный идентификатор набора: от 3 до 64 символов, строчные латинские буквы, цифры и дефис. После создания не меняется; +- «По умолчанию для главной» — делает набор набором по умолчанию. Первый созданный набор становится набором по умолчанию автоматически. + +На вкладке «Маппинг каталога» правила сгруппированы по областям главной. Каждая область раскрывается отдельно и содержит блоки: + +| Блок | Назначение | +| --- | --- | +| «Ресурс каталога» | Ресурс, на котором строится область | +| «Ресурсы каталога» | Несколько ресурсов области, у каждого свои свойства и связи. Используется в областях «Микросервисы» и «Общие ресурсы» | +| «Связи» | Связи, по которым главная обходит сущности области | +| «Свойства» | Идентификаторы параметров сущностей, которые читает главная | +| «Действия» | Слоты действий области | +| «Действия по шаблонам» | Процессы, привязанные к шаблону микросервиса. Только в области «Микросервисы» | +| «Виджеты» | Слоты виджетов. Только в области «Микросервисы» | + +У каждого поля формы есть подсказка с описанием назначения роли, её действия и места на главной. + +Кнопка «Редактор спецификации» открывает весь набор в виде документа JSON. Кнопка «К форме» возвращает к форме. +Удаление ключа в тексте спецификации не удаляет значение из формы: очистите значение в форме или замените его в тексте. + +### Выбор связей и свойств + +Список связей и свойств роли строится по ресурсу её родительской роли. Например, связь `has_deployment` выбирается из связей ресурса роли `microservice`, а свойство `environment_domain` — из параметров ресурса роли `environment`. + +Пока родительская роль не сопоставлена ресурсу, поле недоступно и отображается подсказка «Сначала настройте маппинг связанной роли ресурса, чтобы выбрать элементы из его каталога». + +При смене ресурса роли форма очищает связи и свойства, которые зависят от этой роли. +Например, при смене ресурса роли `system` очищаются связи `contains_service` и `contains_shared` во всех ресурсах областей «Микросервисы» и «Общие ресурсы». +Очистка выполняется в форме до сохранения; сохраните набор, чтобы изменения применились. + +### Несколько ресурсов области + +В областях «Микросервисы» и «Общие ресурсы» роль можно сопоставить нескольким ресурсам каталога, например микросервисам из разных систем учёта. Для каждого ресурса задаются собственные свойства и связи. + +Чтобы добавить ресурс, нажмите «Добавить ресурс» и заполните карточку ресурса. +Связь, родитель которой находится в другой области, например `contains_service` от системы к микросервису, доступна для выбора после того, как сопоставлен ресурс этой области. +При смене ресурса в карточке её свойства и связи очищаются. + +## Области маппинга + +Каждая область маппинга принадлежит одному разделу главной. В таблице перечислены области, разделы и их роли: + +| Область | Раздел главной | Роль ресурса | Роли связей | Роли свойств | Слоты | +| --- | --- | --- | --- | --- | --- | +| «Системы» | «Системы» | `system` | `has_ingress`, `system_has_deployment`, `system_has_integration` | `system_domain`, `system_lifecycle` | — | +| «Микросервисы» | «Микросервисы» | `microservice` (несколько ресурсов) | `contains_service`, `has_deployment` | `microservice_*` | `deploy_microservice`, `delete_microservice`; действия по шаблонам; слоты виджетов | +| «Окружения» | «Окружения» | `environment` | `environment_hosts_ingress` | `environment_type`, `environment_ttl`, `environment_marked_for_deletion`, `environment_domain` | `create_environment`, `delete_environment` | +| «Общие ресурсы» | «Заказ ресурсов» | `shared_resource` (несколько ресурсов) | `contains_shared`, `shared_has_deployment` | `shared_environment`, `shared_kind`, `shared_provider` | `order_resource`, `connect_shared_resource`, `disconnect_shared_resource`, `delete_shared_resource` | +| «Развёртывания» | «Развертывание систем» | `deployment` | `deployment_in_environment` | `deployment_*` | — | +| «Ingress» | «Развертывание систем» | `ingress` | `ingress_routes_to` | `ingress_host`, `ingress_routes` | — | +| «Кластеры» | «Кластеры и сети» | `cluster` | `cluster_hosts_environment` | `cluster_region`, `cluster_provider` | — | +| «Гайды» | «Как работает платформа» | `guide` | — | `guide_category`, `guide_video_url`, `guide_doc_url` | — | +| «Интеграции» | «Интеграции» | `integration` | `integration_targets_system` | `integration_criticality`, `integration_link_type` | — | +| «Пространства в системе контроля версий» | «Создать микросервис» | `vcs_namespace` | — | `vcs_namespace_id` | — | + +Если в наборе есть ключи, которые не относятся к известным областям, форма показывает их в области «Прочее». + +Разделы «Команды», «Диаграммы» и «Потребление ресурсов» собственных областей не имеют и используют роли других областей. + +## Роли ресурсов + +Роль ресурса указывает, сущности какого ресурса каталога главная показывает как объекты определённого вида. В столбце «Каноничный ресурс» указан ресурс, который создаёт набор данных «Каноничная архитектура (схема)». + +| Роль | Название в форме | Назначение | Каноничный ресурс | +| --- | --- | --- | --- | +| `system` | «Система» | Системы: дерево доменов, зависимости, состав, владельцы | «Системы» (`systems`) | +| `microservice` | «Микросервис» | Микросервисы: список, карточка, развёртывание, обновление из шаблона | «Микросервисы» (`microservices`) | +| `environment` | «Окружение» | Окружения. Окружение — это неймспейс Kubernetes | «Namespaces» (`kubernetes-namespaces`) | +| `shared_resource` | «Общий ресурс» | Общие ресурсы: базы данных, очереди, кеши | «Общие ресурсы» (`shared-resources`) | +| `deployment` | «Развёртывание» | Развёртывания микросервисов и систем на окружениях | «Deployments» (`kubernetes-deployments`) | +| `ingress` | «Ingress» | Точки входа на схеме развёртывания | «Ingresses» (`kubernetes-ingresses`) | +| `cluster` | «Кластер» | Кластеры, в которых размещены окружения | «Кластеры» (`clusters`) | +| `guide` | «Гайд» | Карточки раздела «Как работает платформа» | «Справка» (`guides`) | +| `integration` | «Интеграция» | Интеграции между системами | «Интеграции» (`integrations`) | +| `vcs_namespace` | «Пространство в системе контроля версий» | Группы, в которых создаются репозитории микросервисов | «Groups» (`gitlab-groups`) | + +## Роли связей + +Роль связи указывает, по какой связи каталога главная переходит от одной сущности к другой. + +| Роль | Название в форме | Направление | Каноничная связь | +| --- | --- | --- | --- | +| `contains_service` | «Содержит микросервис» | Система → микросервис | «Система — микросервис» | +| `contains_shared` | «Содержит общий ресурс» | Система → общий ресурс | «Система — общий ресурс» | +| `system_has_integration` | «Система участвует в интеграции» | Система-клиент → интеграция | «Система — интеграция» | +| `integration_targets_system` | «Интеграция ведёт в систему» | Интеграция → система-сервер | «Интеграция — система» | +| `has_ingress` | «Имеет ingress» | Система → Ingress | «Система — ingress» | +| `environment_hosts_ingress` | «Окружение содержит ingress» | Окружение → Ingress | «Namespace — ingress» | +| `ingress_routes_to` | «Ingress маршрутизирует на» | Ingress → микросервис | «Ingress — микросервис» | +| `has_deployment` | «Имеет развёртывание» | Микросервис → развёртывание | «Микросервис — deployment» | +| `system_has_deployment` | «Система содержит развёртывание» | Система → развёртывание | «Система — deployment» | +| `shared_has_deployment` | «Общий ресурс имеет развёртывание» | Общий ресурс → развёртывание | «Общий ресурс — deployment» | +| `deployment_in_environment` | «Развёртывание в окружении» | Развёртывание → окружение | «Deployment — окружение» | +| `cluster_hosts_environment` | «Кластер размещает окружение» | Кластер → окружение | «Кластер — окружение» | + +Системы связаны друг с другом только через интеграции: система-клиент связана с интеграцией ролью `system_has_integration`, а интеграция с системой-сервером — ролью `integration_targets_system`. + +Если роль связи не сопоставлена, главная использует любую связь между сущностями соответствующих ресурсов. Это позволяет работать с частично заполненным набором. + +## Роли свойств + +Роль свойства содержит идентификатор параметра сущности. Параметр выбирается из параметров ресурса родительской роли: для `system_*` — ресурса роли `system`, для `microservice_*` — ресурса роли `microservice` и т. д. + +### Системы, интеграции, кластеры, гайды + +Роли свойств систем, интеграций, кластеров и гайдов: + +| Роль | Название в форме | Где отображается | Каноничный параметр | +| --- | --- | --- | --- | +| `system_domain` | «Домен системы» | Дерево «Домены» в разделе «Системы», колонка «Домен» в разделе «Микросервисы» | `domain` | +| `system_lifecycle` | «Жизненный цикл системы» | «Жизненный цикл» на вкладке «Справка» системы | `lifecycle` | +| `integration_criticality` | «Критичность интеграции» | «Критичность» интеграции, карточка «Критичные связи» | `criticality` | +| `integration_link_type` | «Тип связи интеграции» | «Тип связи» интеграции | `link_type` | +| `cluster_region` | «Регион кластера» | Карточка кластера | `region` | +| `cluster_provider` | «Провайдер кластера» | Карточка кластера | `provider` | +| `guide_category` | «Категория гайда» | Группировка и фильтр гайдов | `category` | +| `guide_video_url` | «URL видео гайда» | Кнопка «Смотреть видео» | `video_url` | +| `guide_doc_url` | «URL документации гайда» | Кнопка «Открыть документацию» | `doc_url` | + +Интеграция считается критичной, если значение параметра `integration_criticality` равно `high` без учёта регистра. + +### Микросервисы + +Роли свойств микросервисов. Значения ролей `microservice_binding_*` записывает процесс создания микросервиса из шаблона; по ним работает [обновление из шаблона](../templates/updates/). + +| Роль | Название в форме | Назначение | Каноничный параметр | +| --- | --- | --- | --- | +| `microservice_language` | «Язык микросервиса» | Колонка «Язык», фильтр «Все языки» | `language` | +| `microservice_repository` | «Репозиторий микросервиса» | Ссылка на репозиторий; `.context.repository.url` виджетов | `repository` | +| `microservice_gitlab_project_id` | «ID проекта GitLab» | `.context.repository.id` виджетов | `gitlab_repository_id` | +| `microservice_binding_template_id` | «Идентификатор шаблона микросервиса» | Шаблон, из которого создан микросервис. По нему выбираются действия по шаблонам | `template_id` | +| `microservice_binding_template_version` | «Версия шаблона микросервиса» | Текущая версия шаблона в репозитории | `template_version` | +| `microservice_binding_template_source` | «Источник шаблона микросервиса» | Название реестра, из которого получен шаблон | `template_source` | +| `microservice_binding_template_update_policy` | «Политика обновления шаблона» | `manual` или `review-auto` | `template_update_policy` | +| `microservice_binding_template_upgrade_strategy` | «Стратегия обновления шаблона» | Стратегия обновления, заданная для микросервиса | `template_upgrade_strategy` | +| `microservice_binding_template_upgrade_overwrite` | «Пути, перезаписываемые при обновлении» | Список путей для перезаписи, заданный для микросервиса | `template_upgrade_overwrite` | +| `microservice_binding_template_upgrade_add_if_missing` | «Пути, добавляемые при обновлении» | Список добавляемых путей, заданный для микросервиса | `template_upgrade_add_if_missing` | +| `microservice_vcs_provider` | «Провайдер системы контроля версий» | Провайдер репозитория микросервиса | `vcs_provider` | +| `microservice_vcs_external_service_uuid` | «Внешний сервис системы контроля версий» | Внешний сервис GitLab, в котором находится репозиторий | `vcs_external_service_uuid` | +| `microservice_default_branch` | «Ветка по умолчанию микросервиса» | Ветка, в которую создаётся merge request обновления | `default_branch` | +| `microservice_open_mr_count` | «Открытые merge request» | Показатель «Открытые MR» | `open_mr_count` | +| `microservice_last_pipeline_status` | «Статус последнего пайплайна» | Показатель «Последний пайплайн» | `last_pipeline_status` | +| `microservice_last_pipeline_id` | «ID последнего пайплайна» | Номер пайплайна в показателе «Последний пайплайн» | `last_pipeline_id` | +| `microservice_last_pipeline_web_url` | «Ссылка на последний пайплайн» | Ссылка на пайплайн | `last_pipeline_web_url` | +| `microservice_last_commit_sha` | «Хэш последнего коммита» | Строка «Последняя поставка» | `last_commit_sha` | +| `microservice_last_commit_message` | «Сообщение последнего коммита» | Строка «Последняя поставка» | `last_commit_message` | +| `microservice_last_commit_author` | «Автор последнего коммита» | Строка «Последняя поставка» | `last_commit_author` | + +Если роли `microservice_binding_*`, `microservice_vcs_*` или `microservice_default_branch` не сопоставлены, механизм обновления из шаблона использует каноничные идентификаторы параметров из таблицы. + +### Окружения + +Роли свойств окружений: + +| Роль | Название в форме | Назначение | Каноничный параметр | +| --- | --- | --- | --- | +| `environment_type` | «Тип окружения» | Колонка «Тип»; цвет окружения на схеме развёртывания | `type` | +| `environment_ttl` | «TTL окружения» | Колонка «TTL». Окружение с TTL считается временным | `deletion_ttl` | +| `environment_marked_for_deletion` | «Окружение помечено на удаление» | Тег «Помечено на удаление» при значении `true`, `1` или `yes` | `marked_for_deletion` | +| `environment_domain` | «Домен окружения» | Колонка «Домен». Значение изменяется из карточки окружения | `domain` | + +Окружение также считается временным, если его тип содержит `temp` или `preview` без учёта регистра. + +В каноничной модели параметр `deletion_ttl` заполняется из лейбла `ddp.deckhouse.io/deletion-ttl` неймспейса при каждой синхронизации. Параметры `type`, `domain` и `marked_for_deletion` из кластера не синхронизируются и задаются в каталоге. + +### Общие ресурсы и развёртывания + +Роли свойств общих ресурсов, развёртываний, Ingress и пространств в системе контроля версий: + +| Роль | Название в форме | Назначение | Каноничный параметр | +| --- | --- | --- | --- | +| `shared_environment` | «Окружение общего ресурса» | Окружение, в котором размещён ресурс | `environment` | +| `shared_kind` | «Тип общего ресурса» | Тип ресурса, например PostgreSQL | `kind` | +| `shared_provider` | «Провайдер общего ресурса» | Провайдер, например Deckhouse | `provider` | +| `deployment_replicas` | «Реплики развёртывания» | Число реплик | `replicas` | +| `deployment_cpu_request` | «Запрос CPU развёртывания» | CPU request | `cpu_request` | +| `deployment_memory_request` | «Запрос памяти развёртывания» | Memory request | `memory_request` | +| `deployment_cpu_limit` | «Лимит CPU развёртывания» | CPU limit | `cpu_limit` | +| `deployment_memory_limit` | «Лимит памяти развёртывания» | Memory limit | `memory_limit` | +| `deployment_image_tag` | «Тег образа развёртывания» | Версия образа | `image_tag` | +| `ingress_host` | «Хост ingress» | Строка «Хост» карточки Ingress | `host` | +| `ingress_routes` | «Маршруты ingress» | Маршруты: список объектов с полями `path` и `microservice` (идентификатор микросервиса) | `routes` | +| `vcs_namespace_id` | «Идентификатор пространства в системе контроля версий» | ID группы, в которой создаётся репозиторий | `id` | + +Значения CPU и памяти указываются в формате Kubernetes, например `200m`, `0.5`, `256Mi`, `1Gi`. + +Общий ресурс отображается на схеме окружения, если параметр `shared_environment` пуст или равен идентификатору окружения. + +## Слоты действий + +Слот действия содержит процессы, которые главная запускает кнопкой или пунктом меню. Слоты заполняются в блоке «Действия» области. + +| Слот | Название в форме | Раздел и кнопка | Категории | +| --- | --- | --- | --- | +| `deploy_microservice` | «Развернуть микросервис на окружение (без шаблона)» | «Развертывание систем» → «Развернуть микросервис» для микросервисов без шаблона | Нет | +| `delete_microservice` | «Удалить микросервис с окружения (без шаблона)» | «Развертывание систем» → удаление развёртывания микросервиса без шаблона | Нет | +| `create_environment` | «Создать окружение» | «Окружения» → «Создать окружение» | Нет | +| `delete_environment` | «Удалить окружение» | «Окружения» → карточка окружения → «Удалить окружение» | Нет | +| `order_resource` | «Заказать ресурс» | «Заказ ресурсов» и «Развертывание систем» → «Заказать ресурс» | Тип ресурса, например `PostgreSQL` | +| `connect_shared_resource` | «Подключить общий ресурс» | «Развертывание систем» → перетаскивание ресурса на развёртывание | Нет | +| `disconnect_shared_resource` | «Отключить общий ресурс» | «Развертывание систем» → перетаскивание ресурса на подключённое развёртывание | Нет | +| `delete_shared_resource` | «Удалить общий ресурс» | «Заказ ресурсов» и «Развертывание систем» → удаление ресурса | Провайдер и тип ресурса, например `Deckhouse PostgreSQL` | + +В слот можно добавить несколько процессов кнопкой «Добавить процесс». Если в слоте один процесс, он выбирается в окне запуска автоматически; если несколько — пользователь выбирает процесс в окне запуска. + +### Категории + +Категории разделяют процессы внутри слота, когда для разных типов ресурсов запускаются разные процессы. Категории используются только в слотах `order_resource` и `delete_shared_resource`; в остальных слотах поле категории не отображается. + +Чтобы добавить категорию, нажмите «Добавить категорию» и укажите значение в поле «Категория ресурса». +Категория `default` содержит процессы без категории: они отображаются первыми и используются, когда точного совпадения нет. + +В слоте `order_resource` категория — это тип заказываемого ресурса. Главная группирует по ней процессы в списке «Сервис» и строит фильтр по типу на карточках процессов. + +В слоте `delete_shared_resource` процесс удаления выбирается по параметрам конкретного ресурса в следующем порядке: + +1. Категория `<провайдер> <тип>`, например `Deckhouse PostgreSQL`, по значениям ролей `shared_provider` и `shared_kind`. +1. Категория `<тип>`, например `PostgreSQL`. +1. Категория `default`. + +Используется первая непустая категория. Если подходящих процессов нет, кнопка удаления ресурса недоступна. + +Категория может содержать латинские буквы, цифры, пробел и символы `_`, `.`, `-`, начинается с буквы или цифры, длина — до 64 символов. + +## Действия по шаблонам + +Действия по шаблонам задают процессы для микросервисов, созданных из конкретного шаблона реестра. Блок находится в области «Микросервисы». + +Каждая строка блока соответствует одному шаблону. Для строки выберите шаблон в поле «Шаблон» и процессы действий: + +| Действие | Слот | Где запускается | +| --- | --- | --- | +| «Создать микросервис» | `create_microservice` | «Создать микросервис» → «Создать микросервис» | +| «Развернуть микросервис на окружение» | `deploy_microservice` | «Развертывание систем» → «Развернуть микросервис» | +| «Удалить микросервис с окружения» | `delete_microservice` | «Развертывание систем» → удаление развёртывания | +| «Обновить микросервис из шаблона» | `upgrade_service_from_template` | «Микросервисы» → карточка микросервиса → «Обновить», а также автоматическое обновление | + +Для каждого действия шаблона выбирается один процесс. Шаблон можно добавить только в одну строку. Кнопка «Добавить шаблон» недоступна, пока шаблоны загружаются, пока у какой-либо строки не выбран шаблон или когда свободных шаблонов не осталось. + +В списке «Шаблон» отображаются шаблоны из [реестра шаблонов](../templates/registry/) в последней доступной версии. +Если шаблон, к которому привязаны процессы, больше не доступен в реестре, строка отмечается «нет в реестре». +Если реестр пуст, отображается подсказка «В реестре шаблонов нет доступных шаблонов — синхронизируйте реестр, чтобы привязать действия». + +Главная определяет шаблон микросервиса по роли свойства `microservice_binding_template_id` в ресурсе этого микросервиса и выбирает процессы следующим образом: + +- у микросервиса есть шаблон — используется процесс, привязанный к этому шаблону. Если процесс для действия не привязан, действие недоступно с подсказкой, например «Для шаблона {template} не задан процесс развёртывания»; +- у микросервиса нет шаблона — для развёртывания и удаления с окружения используются процессы слотов `deploy_microservice` и `delete_microservice` из блока «Действия». + +Процесс, привязанный к другому шаблону, для микросервиса не используется, а процессы из блока «Действия» не заменяют отсутствующую привязку шаблона. + +Процессы `create_microservice` и `upgrade_service_from_template` задаются только в блоке «Действия по шаблонам»; в блоке «Действия» таких слотов нет. + +## Слоты виджетов + +Слот виджета выводит существующий виджет в фиксированном месте экрана главной. Слоты заполняются в блоке «Виджеты» области «Микросервисы». + +| Слот | Название в форме | Где отображается | +| --- | --- | --- | +| `microservice_repository_widget` | «Виджет вкладки «Пайплайны»» | «Микросервисы» → карточка микросервиса → вкладка «Пайплайны» | +| `microservice_merge_requests_widget` | «Виджет вкладки «MRs»» | «Микросервисы» → карточка микросервиса → вкладка «MRs» | + +В каждый слот выбирается ровно один виджет. Если слот не заполнен, на вкладке отображается «Раздел пока недоступен». + +Главная передаёт виджету контекст выбранного микросервиса. В конфигурации виджета контекст доступен через шаблонизацию: + +| Путь | Значение | +| --- | --- | +| `.context.microservice.uuid` | UUID сущности микросервиса | +| `.context.microservice.slug` | Идентификатор микросервиса | +| `.context.microservice.name` | Название микросервиса | +| `.context.repository.id` | Значение роли `microservice_gitlab_project_id`, пустая строка, если значение не задано | +| `.context.repository.url` | Значение роли `microservice_repository` | + +Пример настройки — в разделе [«Виджет на вкладке микросервиса»](../examples/home-widget-slot/). + +## Настройка маппинга с главной + +Правила маппинга раздела можно изменить прямо на главной, не переходя в «Администрирование». Изменения сохраняются в набор маппинга по умолчанию. + +Чтобы изменить правила раздела: + +1. В нижней части бокового меню главной включите переключатель «Настроить маппинг». +1. Нажмите значок настройки рядом с названием раздела. Значок отображается у разделов, у которых есть области маппинга. +1. В окне «Маппинг: {раздел}» измените поля областей раздела и нажмите «Сохранить». + +После сохранения страницы главной загружают данные по новым правилам. + +Переключатель «Настроить маппинг» доступен пользователям с разрешением `update:home-mapping-sets`. +Если набора маппинга нет, в окне отображается сообщение «Нет активного набора маппинга. Создайте его в Администрирование → Справочники → Правила маппинга.». + +## Проверки при сохранении + +Перед сохранением форма проверяет значения полей и наличие выбранных объектов в каталоге. + +| Сообщение | Причина | +| --- | --- | +| «Введите название» | Не заполнено поле «Название» | +| «Некоторые цели маппинга удалены из каталога. Обновите или очистите: {details}» | Ресурс, связь, параметр, процесс или виджет, выбранный в наборе, удалён из каталога. В `{details}` перечислены роли, например `ресурс «system»` | +| «Не удалось загрузить данные каталога для проверки маппинга. Попробуйте позже.» | Не удалось загрузить объекты каталога для проверки | +| «Исправьте ошибки в редакторе спецификации перед сохранением» | В редакторе спецификации есть ошибки | +| «Некорректный документ маппинга: {details}» | Значение не прошло проверку формата при сохранении раздела с главной. В `{details}` указан путь к значению | +| «Некорректный документ маппинга главной» | Документ набора не прошёл проверку портала | +| «Нельзя снять признак набора по умолчанию без назначения другого набора» | Выключен признак «По умолчанию для главной» у набора по умолчанию | +| «Нельзя удалить набор маппинга главной по умолчанию» | Попытка удалить набор по умолчанию | + +Портал проверяет формат значений: + +- идентификатор параметра — строчные латинские буквы, цифры, `_` и `-`, до 64 символов; +- идентификатор шаблона — строчные латинские буквы, цифры и символы `.`, `_`, `/`, `-`, до 128 символов; +- в слоте виджета — ровно один виджет. diff --git a/content/documentation/admin/home/overview.ru.md b/content/documentation/admin/home/overview.ru.md new file mode 100644 index 00000000..d50d900f --- /dev/null +++ b/content/documentation/admin/home/overview.ru.md @@ -0,0 +1,148 @@ +--- +title: Обзор +weight: 10 +description: Как главная страница DDP получает данные из каталога, какой набор правил маппинга она использует, как её включить и какие права нужны для работы с ней. +--- + +Главная — рабочее пространство разработчиков и владельцев систем в Deckhouse Development Portal (DDP, портал). +На ней собраны команды, системы и их интеграции, микросервисы, окружения, развёртывания, общие ресурсы и потребление ресурсов кластера. +С главной пользователи создают микросервисы из шаблонов, разворачивают их на окружения, заказывают ресурсы и обновляют микросервисы до новых версий шаблонов. + +{{< alert level="warning" >}} +Главная — экспериментальная функциональность. Состав разделов, структура правил маппинга и API могут измениться в следующих выпусках без сохранения обратной совместимости. +{{< /alert >}} + +Описание экранов с точки зрения пользователя — в [руководстве пользователя по главной](../../user/home/overview/). + +## Принцип работы + +Главная не хранит собственных данных. Все объекты, которые она показывает, — это сущности каталога, а все действия — это процессы каталога. +Какие ресурсы, связи, параметры, процессы и виджеты использовать, задают правила маппинга. + +Правила маппинга сопоставляют понятиям главной объекты каталога: + +- **роль ресурса** — ресурс каталога, сущности которого главная показывает как системы, микросервисы, окружения и т. п.; +- **роль связи** — связь каталога, по которой главная находит, например, микросервисы системы или окружение развёртывания; +- **роль свойства** — идентификатор параметра сущности, из которого главная читает, например, язык микросервиса или домен окружения; +- **слот действия** — процессы, которые запускаются с главной кнопкой или пунктом меню, например «Создать окружение»; +- **действие по шаблону** — процесс, который выполняет действие над микросервисом, созданным из конкретного шаблона; +- **слот виджета** — виджет, который главная показывает в фиксированном месте экрана. + +Схема ниже показывает, как данные каталога попадают на экраны главной: + +```mermaid +flowchart LR + subgraph Catalog["Каталог"] + R["Ресурсы, связи, параметры"] + P["Процессы"] + W["Виджеты"] + end + M["Набор маппинга главной
(по умолчанию)"] + H["Экраны главной"] + R --> M + P --> M + W --> M + M --> H + H -- "запуск процесса
с контекстом" --> P +``` + +Роли не привязаны к конкретным идентификаторам ресурсов: главную можно подключить к любой модели каталога, в которой есть нужные ресурсы и связи. +Готовую модель каталога и правила маппинга для неё создаёт набор данных «Каноничная архитектура (схема)», который применяется [мастером первоначальной настройки](setup/). + +Полный перечень ролей, слотов и правил их заполнения — в разделе [«Правила маппинга»](mapping/). + +## Набор маппинга по умолчанию + +Правила маппинга хранятся в наборах маппинга главной. В портале может быть несколько наборов, но главная использует только один — набор по умолчанию. + +Главная выбирает набор в следующем порядке: + +1. Набор, у которого включён переключатель «По умолчанию для главной». +1. Набор с идентификатором `home-default`. +1. Первый набор в списке. + +Набором по умолчанию может быть только один набор. Когда другой набор становится набором по умолчанию, признак у предыдущего снимается автоматически. +Набор по умолчанию нельзя удалить. + +Правила маппинга действуют для всех пользователей портала. Выбрать другой набор на главной пользователь не может. + +## Включение главной + +Главная выключена после установки портала: вкладка «Главная» скрыта у всех пользователей, а адреса страниц главной перенаправляют в каталог. + +Чтобы включить главную: + +1. Перейдите в раздел «Администрирование» → «Справочники» → «Правила маппинга». +1. Включите переключатель «Показывать главную». + +Переключатель действует сразу для всех пользователей. Для его изменения требуется разрешение `update:home-mapping-sets`. + +При включении главной у пользователей в верхней панели появляется вкладка «Главная», а при переходе на неё открывается раздел «Команды». + +{{< alert level="info" >}} +Баннер «Платформа готова к настройке», из которого запускается мастер первоначальной настройки, отображается на главной. +Пока главная выключена, мастер доступен только в разделе «Администрирование» → «Справочники» → «Наборы данных». +{{< /alert >}} + +## Разделы главной + +Разделы главной сгруппированы в боковом меню. Для работы каждого раздела нужны свои роли маппинга; если основная роль раздела не сопоставлена ресурсу каталога, в разделе отображается сообщение «Настройте правила маппинга или примените набор данных «Каноничная архитектура»». + +В таблице перечислены разделы, их основные роли ресурсов и слоты действий: + +| Группа | Раздел | Роли ресурсов | Слоты действий и действия по шаблонам | +| --- | --- | --- | --- | +| Организация | «Команды» | Команды портала; `system`, `microservice` | — | +| Архитектура | «Системы» | `system`, `microservice`, `shared_resource`, `deployment`, `environment`, `cluster`, `integration` | — | +| Архитектура | «Интеграции» | `system`, `integration` | — | +| Архитектура | «Диаграммы» | `system`, `microservice`, `shared_resource` | — | +| Архитектура | «Кластеры и сети» | `cluster`, `environment` | — | +| Архитектура | «Как работает платформа» | `guide` | — | +| Разработка | «Создать микросервис» | `system`, `vcs_namespace` | Действие по шаблону «Создать микросервис» | +| Разработка | «Микросервисы» | `microservice`, `system`, `shared_resource`, `deployment`, `environment`, `cluster` | Действие по шаблону «Обновить микросервис из шаблона»; слоты виджетов вкладок «Пайплайны» и «MRs» | +| Разработка | «Развертывание систем» | `system`, `microservice`, `environment`, `shared_resource`, `ingress`, `deployment` | `deploy_microservice`, `delete_microservice`, `order_resource`, `connect_shared_resource`, `disconnect_shared_resource`, `delete_shared_resource`; действия по шаблону «Развернуть микросервис на окружение» и «Удалить микросервис с окружения» | +| Разработка | «Заказ ресурсов» | `shared_resource`, `system` | `order_resource`, `delete_shared_resource` | +| Разработка | «Окружения» | `environment` | `create_environment`, `delete_environment` | +| Разработка | «Потребление ресурсов» | `deployment` | — | + +Разделы «DORA и SDLC метрики», «Затраты на эксплуатацию», «Адаптация платформы», «Требования к системам», «Сборка и Доставка», «Troubleshooting хаб» и все разделы группы «Безопасность» отмечены в меню меткой «TBD». +При открытии такого раздела отображается сообщение «Раздел пока недоступен». + +## Права доступа + +Главная использует общую ролевую модель портала. Отдельной роли для главной нет: что увидит и сможет сделать пользователь, определяют его разрешения на сущности, процессы и настройки главной. + +В таблице перечислены разрешения, которые влияют на работу главной: + +| Разрешение | Где используется | +| --- | --- | +| `read:entities` (глобальное или на ресурс) | Загрузка сущностей для всех разделов. Если сущности ресурса недоступны пользователю, раздел выглядит так же, как при несопоставленной роли | +| `read:processes` | Загрузка процессов слотов действий. Процесс, недоступный пользователю, не отображается в слоте | +| `control:processes` (глобальное, на ресурс или на сущность) | Запуск процессов с главной. Кнопки запуска не блокируются; при отсутствии разрешения портал возвращает ошибку «Запрещено политиками доступа» | +| `update:entities` или разрешение `update:entity` на сущность | Изменение домена окружения в разделе «Окружения» | +| `run:actions` на сущность микросервиса | Кнопка «Обновить» в карточке микросервиса | +| `read:template-packs` | Галерея шаблонов в разделе «Создать микросервис» и уведомление о новой версии шаблона в карточке микросервиса | +| `read:template-registries` | Уведомления о предварительных (prerelease) версиях шаблонов в карточке микросервиса | +| `update:home-mapping-sets` | Переключатели «Показывать главную» и «Настроить маппинг», изменение правил маппинга | +| `create:home-mapping-sets`, `delete:home-mapping-sets` | Создание и удаление наборов маппинга главной | +| `apply:seeds` | Баннер «Платформа готова к настройке» и мастер первоначальной настройки | + +Для просмотра главной отдельное разрешение не требуется: вкладка «Главная» доступна всем пользователям, если главная включена. + +{{< alert level="warning" >}} +Пресет роли «Developer» не содержит разрешения `read:entities`. +Чтобы разработчики видели данные на главной, выдайте им доступ к сущностям нужных ресурсов через роли ресурсов или добавьте разрешение `read:entities` в их роль. +{{< /alert >}} + +Подробнее о разрешениях — в разделе [«Ролевая модель»](../security/rbac/). + +## Порядок настройки + +Чтобы подготовить главную к работе, выполните следующие шаги: + +1. Примените наборы данных [мастером первоначальной настройки](setup/) или настройте [правила маппинга](mapping/) для собственной модели каталога. +1. Включите переключатель «Показывать главную». +1. Подключите [реестр шаблонов](../templates/registry/) и привяжите процессы к шаблонам в блоке «Действия по шаблонам». +1. При необходимости добавьте собственные процессы в слоты действий. Требования к таким процессам описаны в разделе [«Процессы главной»](processes/). + +Пошаговый сценарий — в примере [«Быстрая настройка главной»](../examples/home-quick-start/). diff --git a/content/documentation/admin/home/processes.ru.md b/content/documentation/admin/home/processes.ru.md new file mode 100644 index 00000000..eaceb1e7 --- /dev/null +++ b/content/documentation/admin/home/processes.ru.md @@ -0,0 +1,155 @@ +--- +title: Процессы главной +weight: 40 +description: Требования к процессам, которые запускаются с главной DDP, — сущность запуска, контекст запуска и его ключи для каждого сценария, отображение результата и соглашения об именах. +--- + +С главной запускаются обычные процессы каталога. Главная передаёт процессу сущность, для которой он выполняется, и контекст запуска — данные о выбранных на экране объектах. +Процесс читает контекст в шаблонах параметров, действий и правил обновления сущностей. + +Процессы для главной создаются так же, как любые другие процессы: [в редакторе процессов](../processes/overview/). Затем процесс добавляется в слот действия или действие по шаблону в [правилах маппинга](mapping/#слоты-действий). + +## Запуск процесса с главной + +Все сценарии главной завершаются окном «Запустить процесс». В заголовке окна отображается название сущности, для которой запускается процесс. + +Окно запуска работает так же, как при запуске процесса из каталога: + +- если в слоте несколько процессов, пользователь выбирает процесс в списке; если процесс один, он выбран автоматически; +- по умолчанию отображаются только параметры процесса с признаком показа в упрощённой форме и незаполненные обязательные параметры. Переключатель «Все параметры процесса» открывает все параметры и конфигурацию задач; +- значения по умолчанию параметров отображаются как есть, в том числе шаблоны вида `{{ .context.environment.slug }}`. Шаблоны вычисляются при запуске процесса. + +После нажатия «Запустить» отображается уведомление «Процесс "{name}" запущен». + +Если обязательный параметр после вычисления шаблона остался пустым, например ключа нет в контексте, процесс не запускается и отображается ошибка «Не удалось запустить процесс». +Если у пользователя нет разрешения `control:processes`, отображается ошибка «Запрещено политиками доступа». + +## Контекст запуска + +Контекст запуска доступен в шаблонах процесса через корень `.context`: в значениях по умолчанию параметров процесса, в телах действий, в правилах создания и обновления сущностей, в условиях шлюзов и циклах. + +Сущности в контексте передаются в едином формате: + +```yaml +name: <название сущности> +slug: <идентификатор сущности> +uuid: +properties: + <идентификатор параметра>: <значение> +``` + +Ключи `properties` — идентификаторы параметров сущности в каталоге, а не роли маппинга. Например, домен окружения в каноничной модели читается как `.context.environment.properties.domain`. + +Примеры обращения к контексту: + +```go-html-template +{{ .context.environment.slug }} +{{ .context.microservice.name }} +{{ with .context.environment.properties.domain }}{{ $.context.microservice.slug }}.{{ . }}{{ end }} +``` + +В значениях параметров процесса отсутствующий ключ контекста вычисляется в пустую строку, а в телах действий и условиях завершает шаг ошибкой. Поэтому читайте контекст в значениях по умолчанию параметров процесса, а в действиях используйте параметры процесса. Подробнее — в разделе [«Шаблонизация»](../../user/templating/#контекст-запуска-процесса). + +## Сущность и контекст по сценариям + +В таблице перечислены сценарии главной, сущность запуска (`.entity`) и ключи контекста: + +| Сценарий | Слот | Сущность запуска | Ключи `.context` | +| --- | --- | --- | --- | +| Создание микросервиса | Действие по шаблону `create_microservice` | Выбранная система | `microservice`, `repository`, `system`, `template` | +| Обновление микросервиса из шаблона | Действие по шаблону `upgrade_service_from_template` | Микросервис | `template`, `upgrade`, `review` | +| Развёртывание микросервиса на окружение | `deploy_microservice` или действие по шаблону | Микросервис | `environment`, `microservice`, `system` | +| Удаление микросервиса с окружения | `delete_microservice` или действие по шаблону | Микросервис | `environment`, `microservice`, `system` | +| Заказ ресурса | `order_resource` | Выбранная система | `environment`, `system` | +| Удаление общего ресурса | `delete_shared_resource` | Общий ресурс | `system` | +| Подключение и отключение общего ресурса | `connect_shared_resource`, `disconnect_shared_resource` | Общий ресурс | `deployment`, `environment`, `system`, `microservice` | +| Создание окружения | `create_environment` | Первое по названию окружение, если окружений нет — первая по названию система | Не передаётся | +| Удаление окружения | `delete_environment` | Окружение | Не передаётся | + +Ключ `system` передаётся, если на экране выбрана система. Ключ `microservice` при подключении и отключении общего ресурса передаётся, если у развёртывания найден микросервис. + +При создании окружения сущность запуска не связана с создаваемым окружением: `.entity` в таком процессе указывает на существующее окружение или систему. +Данные нового окружения процесс получает из собственных параметров, которые заполняет пользователь. + +При удалении общего ресурса в разделе «Заказ ресурсов» ключ `system` содержит систему, выбранную в заголовке раздела. + +### Создание микросервиса + +Мастер «Создать микросервис» передаёт процессу контекст следующей структуры: + +| Путь | Значение | +| --- | --- | +| `.context.microservice.name` | Название микросервиса | +| `.context.microservice.slug` | Идентификатор микросервиса | +| `.context.repository.default_branch` | Значение настройки «Ветка по умолчанию» реестра шаблонов, при пустой настройке — `main` | +| `.context.repository.description` | Описание репозитория, может быть пустым | +| `.context.repository.namespace` | Выбранное пространство в системе контроля версий: `id` (значение роли `vcs_namespace_id`), `name`, `slug`, `uuid` | +| `.context.system` | Выбранная система в формате сущности | +| `.context.template.id` | Идентификатор шаблона | +| `.context.template.version` | Выбранная версия шаблона | +| `.context.template.source` | Название реестра, из которого получен шаблон | +| `.context.template.language` | Язык шаблона | +| `.context.template.values` | Значения параметров шаблона с шага «Параметры». Параметры с аннотацией `x-ddp-from` не передаются | + +Параметры шаблона с аннотацией `x-ddp-from` заполняются из этого же контекста при создании репозитория. Подробнее — в разделе [«Пакет шаблона»](../templates/packs/#связь-параметров-с-контекстом-запуска). + +### Обновление микросервиса из шаблона + +Кнопка «Обновить» в карточке микросервиса и автоматическое обновление передают процессу одинаковый контекст: + +| Путь | Значение | +| --- | --- | +| `.context.template.id` | Идентификатор шаблона микросервиса | +| `.context.template.version` | Целевая версия шаблона — последняя доступная | +| `.context.upgrade.strategy` | Стратегия обновления: значение роли `microservice_binding_template_upgrade_strategy` микросервиса, если оно задано, иначе стратегия из пакета шаблона | +| `.context.upgrade.overwrite` | Перезаписываемые пути: значение микросервиса или пакета | +| `.context.upgrade.add_if_missing` | Добавляемые пути: значение микросервиса или пакета | +| `.context.review.title` | Заголовок merge request: `Upgrade to ` | + +Как выполняется обновление, описано в разделе [«Обновление из шаблона»](../templates/updates/). + +## Отображение результата + +Главная отслеживает запущенные процессы и показывает их состояние, пока процесс выполняется. Уведомления о завершении процесса не отображаются; итог выполнения пользователь видит в панели «Мои активности». + +Во время выполнения процесса: + +- в верхней части главной отображается строка «Выполняются процессы: {count}», для процессов на согласовании — «Ожидают согласования: {count}», для процессов других пользователей — «Запустили: {initiators}»; +- строка или карточка объекта, над которым выполняется процесс, отмечается индикатором и подписью «выполняется», а её кнопки действий недоступны; +- для создаваемого объекта отображается временная строка или карточка с подписью «создаётся». + +Главная проверяет состояние запусков с интервалом от 2 до 15 секунд. Отслеживание прекращается по завершении процесса, по истечении тайм-аута процесса или, если тайм-аут не задан, через 30 минут. Приостановленные процессы и процессы, ожидающие согласования, отслеживаются без ограничения по времени. +Состояние запусков загружается с сервера, поэтому индикаторы сохраняются после перезагрузки страницы и видны другим пользователям. + +После завершения процесса разделы «Системы», «Микросервисы», «Развертывание систем», «Заказ ресурсов» и «Окружения» загружают данные заново, и временная строка заменяется созданным объектом. + +### Соглашения для процессов + +Временная строка заменяется созданным объектом, только если объект появился в каталоге и совпал с ожидаемым. Чтобы результат отображался сразу после завершения процесса, выполните следующие условия: + +- добавьте в конец процесса задачу синхронизации источника данных или создания сущности. Иначе объект появится на главной только после следующей синхронизации источника данных; +- в процессе создания окружения назовите параметр с идентификатором окружения `slug`. По значению этого параметра главная строит временную строку и находит созданное окружение; +- в процессе развёртывания микросервиса создавайте развёртывание с названием, совпадающим с названием микросервиса; +- в процессе заказа ресурса предлагайте название ресурса вида `<идентификатор системы>-<идентификатор окружения>`. Если пользователь изменит название, временная строка исчезнет по завершении процесса. + +## Процессы наборов данных + +Набор данных «Каноничная архитектура» и связанные с ним наборы создают готовые процессы для слотов главной. Их можно использовать как образец собственных процессов. + +| Процесс | Набор данных | Слот | Контекст и параметры | +| --- | --- | --- | --- | +| «Создать микросервис из шаблона» | «Реестр шаблонов микросервисов» | Действие по шаблону `create_microservice` | Задачи «Создание проекта GitLab», «Создание репозитория из шаблона», «Регистрация entity microservice». Параметр «Группа GitLab» — `{{ with .context.repository.namespace }}{{ .id }}{{ end }}` | +| «Обновить микросервис из шаблона» | «Реестр шаблонов микросервисов» | Действие по шаблону `upgrade_service_from_template` | Задачи «Обновление репозитория из шаблона» и «Создание код-ревью» | +| «Развернуть микросервис на окружение» | «Реестр шаблонов микросервисов» | Действие по шаблону `deploy_microservice` | Параметр `environment` — `{{ .context.environment.slug }}`. Хост Ingress — `<идентификатор микросервиса>.<домен окружения>` | +| «Удалить микросервис с окружения» | «Реестр шаблонов микросервисов» | Действие по шаблону `delete_microservice` | — | +| «Создать окружение» | «Управление окружениями» | `create_environment` | Параметры «Идентификатор» (`slug`) и «TTL» | +| «Удалить окружение» | «Управление окружениями» | `delete_environment` | Параметр «Идентификатор окружения» — `{{ .entity.slug }}` | +| «Подключить секреты к приложению», «Отключить общий ресурс» | «Привязка общих ресурсов» | `connect_shared_resource`, `disconnect_shared_resource` | — | +| Процессы заказа и удаления managed-сервисов | «Deckhouse managed PostgreSQL», «Deckhouse managed Valkey», «Deckhouse managed Kafka» | `order_resource`, `delete_shared_resource` | — | + +Процесс «Создать окружение» создаёт неймспейс Kubernetes с лейблами DDP. Параметр «TTL» принимает значения «1 день», «3 дня», «7 дней», «14 дней», «1 месяц» и записывается в лейбл `ddp.deckhouse.io/deletion-ttl`; пустое значение создаёт постоянное окружение. +DDP не удаляет окружения по TTL самостоятельно: лейбл предназначен для внешнего механизма очистки кластера. + +Процесс «Удалить окружение» удаляет неймспейс со всеми развёртываниями, ожидает его удаления до 5 минут и обновляет каталог. + +Пример добавления собственного процесса — в разделе [«Собственный процесс заказа ресурса»](../examples/home-custom-process/). diff --git a/content/documentation/admin/home/setup.ru.md b/content/documentation/admin/home/setup.ru.md new file mode 100644 index 00000000..d2e72d64 --- /dev/null +++ b/content/documentation/admin/home/setup.ru.md @@ -0,0 +1,135 @@ +--- +title: Первоначальная настройка +weight: 20 +description: Мастер первоначальной настройки главной DDP — пресеты, наборы данных «Каноничной архитектуры», их параметры и шаги, которые выполняются вручную после мастера. +--- + +Мастер первоначальной настройки применяет подготовленные наборы данных, которые создают модель каталога для главной, правила маппинга, подключения к Kubernetes, Vault и GitLab, источники данных, процессы и виджеты. +После мастера главная показывает данные кластеров и репозиториев и позволяет запускать процессы. + +## Перед началом работы + +Для работы мастера требуется разрешение `apply:seeds`. + +Подготовьте адреса внешних систем, которые будут подключены к порталу: + +- URL API-сервера Kubernetes, например `https://api.cluster.example.com`; +- URL Vault или Deckhouse Stronghold, например `https://vault.example.com`; +- URL GitLab, например `https://gitlab.example.com`. + +Наборы данных не проверяют, применялись ли они раньше. Повторное применение набора, объекты которого уже есть в портале, завершается ошибкой. +Запускайте мастер на портале, где наборы «Каноничной архитектуры» ещё не применялись. + +## Запуск мастера + +Мастер запускается одним из способов: + +- кнопкой «Запустить» в баннере «Платформа готова к настройке» на главной; +- кнопкой «Первоначальная настройка» в разделе «Администрирование» → «Справочники» → «Наборы данных». + +Баннер видят только пользователи с разрешением `apply:seeds`. Баннер скрывается для всех пользователей кнопкой «Скрыть» или автоматически после успешного применения всех выбранных наборов. +Чтобы вернуть баннер, включите переключатель «Показывать баннер первоначальной настройки» в разделе «Наборы данных». + +Главная выключена после установки портала, поэтому на новой установке баннер не отображается, пока не включён переключатель «Показывать главную». + +## Шаги мастера + +Мастер состоит из пяти шагов: «Пресет», «Выбор», «Параметры», «Проверка», «Прогресс». + +### Пресет + +На шаге «Пресет» выберите один из вариантов: + +- «Настройка платформы» — схема каталога, подключения к Kubernetes, Vault и GitLab, процессы и виджеты главной страницы; +- «Настройка платформы с демоданными» — то же самое плюс демоданные: примеры сервисов, ресурсов и запущенных процессов. + +Демоданные можно удалить позже в разделе «Наборы данных». + +### Выбор + +На шаге «Выбор» отображаются наборы данных пресета, сгруппированные по слоям: «Схема», «Демоданные», «Инфраструктура», «Провайдеры и операции», «Привязка процессов». +Снимите отметку с наборов, которые не нужны. + +Мастер не даёт снять отметку с набора, от которого зависят другие выбранные наборы. Такой набор отмечен тегом «Обязательный» и подписью «Нужен для: …». +Наборы «Каноничная архитектура (схема)» и «Каноничная архитектура (привязки главной)» заблокированы, пока выбраны наборы с процессами или виджетами для главной. + +### Параметры + +На шаге «Параметры» для каждого выбранного набора отображается панель с его параметрами. Панели с незаполненными обязательными параметрами отмечены звёздочкой. + +Мастер заполняет часть параметров автоматически: внешние сервисы и источники данных, которые создаются наборами этого же запуска, подставляются в параметры зависимых наборов. +Заполните вручную URL внешних систем. Параметры наборов перечислены в разделе [«Наборы данных мастера»](#наборы-данных-мастера). + +### Проверка + +На шаге «Проверка» отображается таблица наборов в порядке применения с числом объектов каждого набора. +Включите переключатель «Подтвердить применение» и нажмите «Применить». + +### Прогресс + +На шаге «Прогресс» наборы применяются по очереди. Для каждого набора отображается статус: «Ожидает», «Выполняется», «Успех» или «Ошибка». + +Если применение набора завершилось ошибкой, очередь останавливается, а объекты уже применённых наборов остаются в портале. +Исправьте причину ошибки и нажмите «Повторить с текущего», чтобы продолжить с набора, на котором произошла ошибка. Кнопка «К проверке» возвращает к шагу «Проверка». + +Пока очередь выполняется, окно мастера закрыть нельзя. После успешного применения всех наборов отображается сообщение «Все выбранные наборы успешно применены». + +## Наборы данных мастера + +Наборы данных применяются в порядке зависимостей. В таблице перечислены наборы, которые входят в пресеты мастера: + +| Набор данных | Что создаёт | Параметры | +| --- | --- | --- | +| «Каноничная архитектура (схема)» | Ресурсы каталога «Архитектура», «Системы», «Микросервисы», «Общие ресурсы», «Kubernetes», «Ingresses», «Deployments», «Namespaces», «Привязки секретов», «GitLab», «Groups», «Кластеры», «Справка», «Интеграции», связи между ними и набор маппинга «Главная (по умолчанию)» с идентификатором `home-default` | — | +| «Каноничная архитектура (демоданные)» | Демонстрационные сущности системы Billing: системы, микросервисы, окружения, общие ресурсы, развёртывания, кластеры, гайды, интеграции. Входит только в пресет «Настройка платформы с демоданными» | — | +| «Kubernetes» | Внешний сервис «Kubernetes» и тип учётных данных «Kubernetes токен» | «URL Kubernetes API» — обязательный | +| «Vault» | Внешний сервис «Vault» и тип учётных данных «Vault токен» | «URL Vault» — обязательный | +| «GitLab» | Внешний сервис «GitLab» и типы учётных данных «GitLab токен», «GitLab username» | «URL GitLab» — обязательный | +| «Реестр шаблонов микросервисов» | Действия и процессы «Создать микросервис из шаблона», «Обновить микросервис из шаблона», «Развернуть микросервис на окружение», «Удалить микросервис с окружения» | «Провайдер VCS», «Внешний сервис», «Источник данных Deployments», «Источник данных Ingresses» | +| «Kubernetes: deployments, ingresses и namespaces» | Источники данных, которые собирают из кластера Deployment, Ingress и неймспейсы | «Внешний сервис Kubernetes» | +| «Привязка общих ресурсов» | Источник данных «Привязки секретов», процессы «Подключить секреты к приложению» и «Отключить общий ресурс» | «Внешний сервис Kubernetes», «Источник данных Deployments» | +| «Управление окружениями» | Процессы «Создать окружение» и «Удалить окружение» | «Внешний сервис Kubernetes», «Источник данных Namespaces» | +| «GitLab: группы» | Источник данных групп GitLab для выбора пространства при создании микросервиса | «Внешний сервис GitLab» | +| «GitLab: активность репозиториев» | Источник данных, который заполняет в карточке микросервиса открытые merge request, последний пайплайн и последний коммит | «Внешний сервис GitLab», «Все репозитории», «ID групп GitLab», «Включать подгруппы» | +| «GitLab: виджеты» | Виджеты «GitLab: пайплайны репозитория» и «GitLab: merge requests репозитория» для вкладок карточки микросервиса | «Внешний сервис GitLab» | +| «Deckhouse managed PostgreSQL», «Deckhouse managed Valkey», «Deckhouse managed Kafka» | Действия, процессы заказа и удаления managed-сервиса, источник данных | «Внешний сервис Kubernetes», «Внешний сервис Vault или Stronghold», «Префикс пути Vault» и параметры создания объектов | +| «Каноничная архитектура (привязки главной)» | Добавляет процессы и виджеты выбранных наборов в слоты набора маппинга `home-default`. Применяется только мастером | — | + +Если в наборе «GitLab: активность репозиториев» выключен параметр «Все репозитории», заполните «ID групп GitLab». + +Источники данных Kubernetes собирают только объекты с лейблом `ddp.deckhouse.io/environment` и пропускают неймспейсы `d8-*` и `kube-*`. + +Какие слоты заполняет набор «Каноничная архитектура (привязки главной)», показано в таблице: + +| Набор данных | Слот действия | Категория | +| --- | --- | --- | +| «Управление окружениями» | `create_environment`, `delete_environment` | `default` | +| «Привязка общих ресурсов» | `connect_shared_resource`, `disconnect_shared_resource` | `default` | +| «Deckhouse managed PostgreSQL» | `order_resource`, `delete_shared_resource` | `PostgreSQL`, `Deckhouse PostgreSQL` | +| «Deckhouse managed Valkey» | `order_resource`, `delete_shared_resource` | `Valkey`, `Deckhouse Valkey` | +| «Deckhouse managed Kafka» | `order_resource`, `delete_shared_resource` | `Kafka`, `Deckhouse Kafka` | +| «GitLab: виджеты» | Слоты виджетов `microservice_repository_widget`, `microservice_merge_requests_widget` | — | + +Набор «Реестр шаблонов микросервисов» процессы в правила маппинга не добавляет: их привязывают к шаблонам вручную после подключения реестра шаблонов. + +## Действия после мастера + +Мастер не выполняет часть настроек, которые зависят от конкретной установки. Выполните их вручную: + +1. Включите главную: «Администрирование» → «Справочники» → «Правила маппинга» → переключатель «Показывать главную». +1. Заполните учётные данные в профиле пользователя: токен сервисного аккаунта Kubernetes, токен Vault, персональный токен и имя пользователя GitLab. + Процессы главной выполняют действия с учётными данными пользователя, который их запускает, поэтому учётные данные нужны каждому пользователю, запускающему процессы. +1. Подключите реестр шаблонов и выполните синхронизацию. Порядок описан в разделе [«Реестр шаблонов»](../templates/registry/). +1. Привяжите процессы к шаблонам: «Правила маппинга» → набор по умолчанию → «Маппинг каталога» → «Микросервисы» → «Действия по шаблонам». + Для каждого шаблона выберите процессы «Создать микросервис», «Развернуть микросервис на окружение», «Удалить микросервис с окружения» и «Обновить микросервис из шаблона». +1. Если в каталоге есть микросервисы, созданные без шаблона, заполните в разделе «Микросервисы» → «Действия» слоты «Развернуть микросервис на окружение (без шаблона)» и «Удалить микросервис с окружения (без шаблона)». +1. Заполните в каталоге параметры окружений, которые не приходят из кластера: тип, кластер, домен и признак «помечено на удаление». Домен окружения также меняется из раздела «Окружения» на главной. + +## Удаление набора данных + +Набор данных удаляется кнопкой «Удалить» на его карточке в разделе «Наборы данных». + +При удалении набора с процессами для главной из слотов набора маппинга удаляются только процессы и виджеты этого набора. +Набор маппинга по умолчанию при удалении набора данных не удаляется. + +Общие правила работы с наборами данных — в разделе [«Наборы данных»](../datasets/). diff --git a/content/documentation/admin/processes/overview.ru.md b/content/documentation/admin/processes/overview.ru.md index 8cded42e..6fca580a 100644 --- a/content/documentation/admin/processes/overview.ru.md +++ b/content/documentation/admin/processes/overview.ru.md @@ -213,17 +213,35 @@ description: Создание и запуск процессов — элеме 1. Перейдите к сущности, для которой нужно запустить процесс. 1. В меню сущности выберите «Запустить процесс». -1. Выберите нужный процесс из списка. +1. Выберите процесс в списке. Если доступен один процесс, он выбран автоматически и список не отображается. 1. Заполните параметры процесса. 1. Нажмите «Запустить». +После запуска отображается уведомление «Процесс "{name}" запущен». + ### Параметры запуска -При запуске процесса доступны: +Окно «Запустить процесс» открывается в упрощённом режиме. В нём отображаются только параметры процесса с признаком [«Показывать в упрощённой форме»](../../user/properties/#конфигурация) и обязательные параметры, у которых нет значения. Остальные параметры сохраняют значения по умолчанию и передаются при запуске. + +Над параметрами отображается подсказка «Показаны важные параметры: {important} из {total}». Если важных параметров нет, отображается «Важных параметров нет», а если заполнять ничего не нужно — сообщение «Для запуска этого процесса не нужно заполнять параметры — нажмите «Запустить»». + +Кнопка «Все параметры процесса» переключает окно в полный режим, кнопка «Только важные параметры» — обратно. В полном режиме доступны разделы: + +* «Общие параметры процесса» — параметры, определённые в конфигурации процесса; +* «Командные параметры процесса» — команда, переменные которой используются при выполнении; +* «Конфигурация» — схема процесса. Нажмите на задачу, чтобы включить или выключить её действие и заполнить его параметры. + +Описание процесса отображается под заголовком в сокращённом виде; ссылка «подробнее» раскрывает его полностью. -* «Общие параметры процесса» — параметры, определённые в конфигурации процесса. -* «Параметры действий» — параметры для каждого действия в процессе. -* «Переменные окружения» — дополнительные переменные для выполнения. +Если обязательный параметр процесса не заполнен, при нажатии «Запустить» отображается ошибка «Заполните все обязательные параметры процесса». Если не заполнено обязательное поле включённой задачи, окно переключается в полный режим с ошибкой «Заполните все обязательные поля для всех включённых задач». + +### Контекст запуска + +Контекст запуска — значения, которые раздел интерфейса передаёт процессу при запуске: например, окружение и система, выбранные на главной. Пользователь контекст не вводит, и в конфигурации процесса он не хранится. + +В шаблонах процесса контекст доступен через корень `.context`, например `{{ .context.environment.slug }}`. Процесс, запущенный из каталога, получает пустой контекст. + +Состав контекста для каждого сценария главной описан в разделе [«Процессы главной»](../home/processes/#сущность-и-контекст-по-сценариям). ## Управление выполнением @@ -249,6 +267,8 @@ description: Создание и запуск процессов — элеме ### Отслеживание состояния +Пока у пользователя выполняются процессы, значок панели «Мои активности» в верхней панели портала заменяется индикатором. На вкладке «Процессы» панели отображается число выполняющихся процессов и строка «Выполняются процессы: {count}»; список обновляется при запуске и завершении процесса. + В разделе «Запуски процессов» можно просмотреть: * Список всех запусков процессов для сущности. diff --git a/content/documentation/admin/security/encryption-key-rotation.ru.md b/content/documentation/admin/security/encryption-key-rotation.ru.md index 2b00748d..108ce0a0 100644 --- a/content/documentation/admin/security/encryption-key-rotation.ru.md +++ b/content/documentation/admin/security/encryption-key-rotation.ru.md @@ -26,6 +26,7 @@ Deckhouse Development Portal (DDP) позволяет безопасно сме - «Временные ответы действий» — зашифрованные временные ответы в записях выполнения действий. - «Секреты Vault» — значения учётных данных, хранящихся в HashiCorp Vault или Deckhouse Stronghold. - «Конфигурация Vault» — AppRole Role ID и AppRole Secret ID в настройках интеграции с Vault. +- Пароли подключений [реестра шаблонов](../templates/registry/). Отдельной строки в таблице результата для них нет: они учитываются в итоговом числе перешифрованных значений. ## Порядок выполнения diff --git a/content/documentation/admin/security/rbac.ru.md b/content/documentation/admin/security/rbac.ru.md index 6eba8b72..bc052856 100644 --- a/content/documentation/admin/security/rbac.ru.md +++ b/content/documentation/admin/security/rbac.ru.md @@ -119,6 +119,22 @@ MCP: - `update:team-variables` — редактирование переменных команд. - `edit:team-filter-rules` — настройка правил фильтрации групп при синхронизации из Dex. +Наборы данных: +- `read:seeds` — просмотр наборов данных. +- `apply:seeds` — применение наборов данных, мастер первоначальной настройки и баннер первоначальной настройки на главной. +- `delete:seeds` — удаление наборов данных. + +Правила маппинга главной: +- `create:home-mapping-sets` — создание наборов маппинга главной. +- `update:home-mapping-sets` — изменение наборов маппинга главной, выбор набора по умолчанию, включение и выключение главной. Подробнее — [в документации по правилам маппинга](../home/mapping/). +- `delete:home-mapping-sets` — удаление наборов маппинга главной. + +Шаблоны микросервисов: +- `read:template-packs` — просмотр версий шаблонов: галерея создания микросервиса и уведомления о новой версии шаблона. +- `edit:template-packs` — отзыв, возврат и удаление версий шаблонов. +- `read:template-registries` — просмотр подключений, настроек и запусков синхронизации реестра шаблонов. +- `edit:template-registries` — изменение подключений и настроек реестра шаблонов, запуск синхронизации. Подробнее — [в документации по реестру шаблонов](../templates/registry/). + Иконки: - `create:icons` — создание иконок. - `delete:icons` — удаление иконок. @@ -407,7 +423,7 @@ MCP: - `read:actions`, `read:automations`, `read:dashboards`. - `read:datasources`, `read:entities`, `read:external-services`. - `read:processes`, `read:resource-relations`, `read:resources`. - - `read:seeds`, `read:system-alerts`, `read:trusted-certificates`, `read:webhooks`. + - `read:seeds`, `read:system-alerts`, `read:template-packs`, `read:trusted-certificates`, `read:webhooks`. - `read:widgets`, `read:workflows`. - `read:audit-logs`, `view:admin-page`, `view:self-service-page`. - Назначение: пользователи с правами только на просмотр. @@ -417,7 +433,7 @@ MCP: - Тип: `глобальные`. - Разрешения: - `read:actions`, `read:dashboards`, `read:external-services`. - - `read:processes`, `read:widgets`, `read:workflows`. + - `read:processes`, `read:template-packs`, `read:widgets`, `read:workflows`. - `run:actions`, `run:widget-actions`, `control:processes`. - `update:team-variables`. - Назначение: разработчики, которым нужен доступ к просмотру информации и выполнению действий, но не требуется доступ к созданию, изменению или удалению объектов. Разработчики видят только те сущности, к которым им предоставлен доступ через привязки ролей на уровне ресурсов или сущностей. diff --git a/content/documentation/admin/templates/_index.ru.md b/content/documentation/admin/templates/_index.ru.md new file mode 100644 index 00000000..b276134d --- /dev/null +++ b/content/documentation/admin/templates/_index.ru.md @@ -0,0 +1,4 @@ +--- +title: Шаблоны микросервисов +weight: 26 +--- diff --git a/content/documentation/admin/templates/overview.ru.md b/content/documentation/admin/templates/overview.ru.md new file mode 100644 index 00000000..6231a2fc --- /dev/null +++ b/content/documentation/admin/templates/overview.ru.md @@ -0,0 +1,88 @@ +--- +title: Обзор +weight: 10 +description: Шаблоны микросервисов в DDP — пакеты шаблонов в OCI-реестре, реестр шаблонов портала, создание репозиториев из шаблона и их обновление до новых версий через merge request. +--- + +Шаблоны микросервисов задают структуру репозитория нового микросервиса: код-заготовку, CI/CD, манифесты развёртывания и конфигурацию. +Deckhouse Development Portal (DDP, портал) создаёт репозиторий микросервиса из шаблона, а при выходе новой версии шаблона переносит изменения в репозиторий через merge request. + +{{< alert level="warning" >}} +Реестр шаблонов и обновление из шаблона — экспериментальная функциональность. Формат пакета, состав настроек и API могут измениться в следующих выпусках без сохранения обратной совместимости. +{{< /alert >}} + +## Основные понятия + +Механизм шаблонов использует следующие понятия: + +- **пакет шаблона** — директория с манифестом `template.yaml`, схемой параметров `values.yaml` и файлами на Go-шаблонах. Пакет публикуется в хранилище образов контейнеров как OCI-артефакт; версия пакета — тег артефакта в формате semver; +- **реестр шаблонов** — подключения портала к хранилищам образов контейнеров, в которых опубликованы пакеты. Портал синхронизирует реестр по расписанию и ведёт каталог версий шаблонов; +- **последняя версия** — рекомендованная версия шаблона: максимальная стабильная версия среди доступных. Её предлагает мастер создания и на неё обновляются микросервисы; +- **lock-файл** — файл `.ddp/template.lock.yaml` в репозитории микросервиса. Хранит идентификатор шаблона, его версию и значения параметров, с которыми создан репозиторий; +- **привязка микросервиса к шаблону** — параметры сущности микросервиса в каталоге: идентификатор шаблона, версия, реестр и политика обновления; +- **действия по шаблонам** — процессы создания, развёртывания, удаления с окружения и обновления, привязанные к конкретному шаблону в правилах маппинга главной. + +## Жизненный цикл шаблона + +Схема ниже показывает путь от публикации шаблона до обновления репозитория микросервиса: + +```mermaid +sequenceDiagram + participant A as Автор шаблона + participant O as Хранилище образов (OCI) + participant D as DDP + participant G as GitLab + A->>O: ddp-template publish (версия 1.0.0) + D->>O: Синхронизация реестра + Note over D: Версия 1.0.0 — последняя + D->>G: Создание микросервиса: проект, файлы, lock-файл + A->>O: ddp-template publish (версия 1.1.0) + D->>O: Синхронизация реестра + Note over D: Версия 1.1.0 — последняя + D->>G: Обновление: ветка, коммит, merge request + Note over G: Владелец микросервиса принимает merge request + D->>G: Сверка версии по lock-файлу + Note over D: Версия микросервиса в каталоге — 1.1.0 +``` + +Этапы жизненного цикла: + +1. Автор шаблона готовит пакет и публикует версию утилитой `ddp-template`. Формат пакета описан в разделе [«Пакет шаблона»](packs/). +1. Портал синхронизирует [реестр шаблонов](registry/) и добавляет версию в каталог версий. +1. Администратор привязывает к шаблону процессы в блоке «Действия по шаблонам» [правил маппинга](../home/mapping/#действия-по-шаблонам). +1. Разработчик создаёт микросервис в разделе главной «Создать микросервис». Процесс создания создаёт проект GitLab, записывает в него отрисованные файлы шаблона и lock-файл, регистрирует микросервис в каталоге. +1. При выходе новой версии шаблона портал показывает в карточке микросервиса уведомление «Доступна версия {version}». Обновление запускается кнопкой «Обновить» или автоматически. +1. Процесс обновления создаёт ветку с изменениями шаблона и открывает merge request. После принятия merge request портал обновляет версию шаблона микросервиса в каталоге. + +Подробно механизм обновления описан в разделе [«Обновление из шаблона»](updates/). + +## Роли участников + +С шаблонами работают разные участники: + +| Участник | Задачи | Где описано | +| --- | --- | --- | +| Автор шаблона | Готовит пакет, выбирает стратегию обновления, публикует версии | [«Пакет шаблона»](packs/) | +| Администратор портала | Подключает хранилища образов, настраивает синхронизацию и автоматическое обновление, привязывает процессы к шаблонам | [«Реестр шаблонов»](registry/), [«Правила маппинга»](../home/mapping/#действия-по-шаблонам) | +| Разработчик | Создаёт микросервис из шаблона, принимает merge request обновления | [«Микросервисы» в руководстве пользователя](../../user/home/microservices/) | + +## Ограничения + +Механизм шаблонов имеет следующие ограничения: + +| Ограничение | Описание | +| --- | --- | +| Хранилище пакетов | Только хранилища образов контейнеров с OCI Distribution Spec v2, например Harbor, GitLab Container Registry, Docker Registry | +| Система контроля версий | Только GitLab. Репозиторий микросервиса доступен по HTTPS на хосте внешнего сервиса GitLab | +| Версии | Только строгий semver без префикса `v`, например `1.2.0`. Опубликованную версию перезаписать нельзя | +| Удаление файлов | Обновление не удаляет файлы из репозитория. Файлы, удалённые или переименованные в новой версии шаблона, удаляются вручную | +| Промежуточные версии | Обновление переводит репозиторий сразу на последнюю версию шаблона, промежуточные версии не применяются по очереди | +| Слияние | Портал не принимает merge request обновления автоматически | +| Привязка к реестру | Микросервис обновляется только из того реестра, из которого создан. Если последняя версия шаблона пришла из другого реестра, обновление микросервису не предлагается | +| Микросервисы без lock-файла | Репозитории, созданные без lock-файла `.ddp/template.lock.yaml`, обновить из шаблона нельзя | +| Новые шаблоны | Для каждого нового шаблона процессы привязываются вручную в правилах маппинга главной | + +{{< alert level="info" >}} +Пример [«Автоматическое обновление сервисов»](../../examples/service-autoupdates/) описывает настройку обновления на действиях, автоматизациях и Git-тегах шаблона без реестра шаблонов. +Механизм, описанный в этом разделе, работает с пакетами шаблонов из OCI-реестра и настраивается без собственных автоматизаций. +{{< /alert >}} diff --git a/content/documentation/admin/templates/packs.ru.md b/content/documentation/admin/templates/packs.ru.md new file mode 100644 index 00000000..d7d552ef --- /dev/null +++ b/content/documentation/admin/templates/packs.ru.md @@ -0,0 +1,305 @@ +--- +title: Пакет шаблона +weight: 30 +description: Формат пакета шаблона микросервиса DDP — манифест template.yaml, схема параметров values.yaml, аннотация x-ddp-from, шаблонизация файлов, версии и публикация утилитой ddp-template. +--- + +Пакет шаблона — это директория с файлами будущего репозитория микросервиса, манифестом и схемой параметров. Портал отрисовывает файлы пакета Go-шаблонизатором с параметрами, которые пользователь заполняет при создании микросервиса. +Пакет публикуется в хранилище образов контейнеров утилитой `ddp-template`. + +## Структура пакета + +Пакет содержит три служебных файла и файлы репозитория: + +- `template.yaml` — манифест: идентификатор, название, язык и правила обновления; +- `values.yaml` — схема параметров шаблона; +- `.templateignore` — пути, которые копируются в репозиторий без шаблонизации; +- остальные файлы и директории — содержимое репозитория микросервиса. + +Пример структуры пакета Go-сервиса: + +```text +go-service/ + template.yaml + values.yaml + .templateignore + .gitlab-ci.yml + cmd/{{ .slug }}/main.go + go.mod + deploy/helm/Chart.yaml +``` + +Файлы `template.yaml`, `values.yaml` и `.templateignore` в репозиторий микросервиса не копируются. Директория `.git` в пакет не включается. + +Не размещайте в пакете директорию `.ddp/`: портал создаёт в ней lock-файл `.ddp/template.lock.yaml` при создании и обновлении репозитория. + +## Манифест template.yaml + +Манифест описывает шаблон и правила его обновления. Пример манифеста: + +```yaml +id: go-service +name: Go service +description: Go HTTP service with CI and Helm chart +language: Go +tags: + - http + - helm +minDdpVersion: "1.7.0" +update: + strategy: selective_additive + overwrite: + - .gitlab-ci.yml + - deploy/** + - go.mod + addIfMissing: + - .dockerignore + - .editorconfig +``` + +Поля манифеста: + +| Поле | Обязательное | Описание | +| --- | --- | --- | +| `id` | Да | Идентификатор шаблона: строчные латинские буквы, цифры и дефис. Совпадает с именем репозитория в хранилище образов | +| `name` | Да | Название шаблона в галерее | +| `description` | Нет | Описание шаблона в галерее | +| `language` | Да | Язык шаблона: `Go`, `Vue`, `TypeScript`, `Python`, `Java` или `Other` | +| `tags` | Нет | Теги для поиска в галерее | +| `minDdpVersion` | Нет | Минимальная версия DDP в формате semver. На более ранней версии DDP версия шаблона получает статус «недоступна» | +| `update.strategy` | Нет | Стратегия обновления: `selective`, `additive`, `selective_additive`, `full` или `merge`. Если не задана, используется `selective` | +| `update.overwrite` | Зависит от стратегии | Glob-шаблоны путей, которые перезаписываются при обновлении | +| `update.addIfMissing` | Зависит от стратегии | Glob-шаблоны путей, которые добавляются при обновлении, если их нет в репозитории | + +Другие поля в манифесте не допускаются. Стратегии и требования к спискам путей описаны в разделе [«Стратегии обновления»](updates/#стратегии-обновления). + +## Параметры values.yaml + +Файл `values.yaml` — схема параметров шаблона в формате OpenAPI Schema Object. По схеме портал строит форму шага «Параметры» мастера создания микросервиса. + +Пример схемы параметров: + +```yaml +type: object +required: + - slug + - name + - port +properties: + slug: + type: string + title: Service slug + description: Identifier used in paths and module name + x-ddp-from: context.microservice.slug + name: + type: string + title: Display name + x-ddp-from: context.microservice.name + port: + type: integer + title: HTTP port + default: 8080 + database: + type: string + title: Database + enum: + - postgres + - none + default: none + metrics: + type: boolean + title: Expose Prometheus metrics + default: true +``` + +Портал использует свойства верхнего уровня `properties` для построения формы: + +- `title` — подпись поля, при отсутствии — ключ параметра; +- `description` — подсказка поля; +- `required` — обязательность поля в форме; +- `default` — начальное значение. Если значение по умолчанию не задано, используется пустое значение типа: пустая строка, `0`, `false`, пустой список или объект. + +Тип поля формы определяется типом параметра: + +| Тип параметра | Поле формы | +| --- | --- | +| `string` с `enum` | Выпадающий список | +| `string` | Текстовое поле | +| `boolean` | Переключатель | +| `integer` | Числовое поле с шагом 1 | +| `number` | Числовое поле с шагом 0,1 | +| `object`, `array`, схемы с `oneOf`, `anyOf`, `allOf`, `$ref` | Поле для ввода JSON | + +Перед отрисовкой пакета портал проверяет итоговые значения по схеме. При несоответствии создание завершается ошибкой `values_invalid: values do not match values.yaml schema: ...`. + +При отрисовке пакета незаданные параметры получают пустые значения типа, поэтому `required` не гарантирует непустое значение. Чтобы запретить пустую строку, используйте ограничения схемы, например `minLength: 1`. + +Схема задаётся объектом. Список параметров в `values.yaml` не поддерживается. + +### Связь параметров с контекстом запуска + +Аннотация `x-ddp-from` заполняет параметр из контекста запуска процесса создания микросервиса. Такой параметр не отображается в форме мастера: пользователь не вводит повторно данные, которые уже указал на шаге «Сервис». + +Значение аннотации — путь в контексте запуска, начинающийся с `context.`: + +| Путь | Значение | +| --- | --- | +| `context.microservice.slug` | Идентификатор микросервиса | +| `context.microservice.name` | Название микросервиса | +| `context.system.slug` | Идентификатор системы, в которую входит микросервис | +| `context.system.name` | Название системы | +| `context.repository.default_branch` | Ветка по умолчанию | +| `context.repository.description` | Описание репозитория | +| `context.template.version` | Версия шаблона | + +Полный состав контекста создания описан в разделе [«Процессы главной»](../home/processes/#создание-микросервиса). + +Правила применения аннотации: + +- значение из контекста заменяет значение, переданное в параметрах процесса; +- если пути нет в контексте, значение по пути `null` или аннотация пустая, создание завершается ошибкой `values_invalid: values.yaml property "k": x-ddp-from "context.x" : path not found in launch context`; +- аннотация применяется только при создании репозитория. При обновлении используются значения из lock-файла. + +## Шаблонизация файлов + +Файлы пакета отрисовываются шаблонизатором Go `text/template`. Параметры шаблона доступны в корне: `{{ .slug }}`, `{{ .port }}`. + +Пример файла пакета: + +```go-html-template +package main + +// {{ .name }} listens on port {{ .port }}. +const port = {{ .port }} +{{- if .metrics }} + +const metricsPath = "/metrics" +{{- end }} +``` + +Правила шаблонизации: + +- обращение к отсутствующему параметру завершает отрисовку ошибкой; +- в шаблонах доступны [функции шаблонизации портала](../../user/templating/#встроенные-функции) и функции библиотеки Sprig, кроме `env`, `expandenv` и `getHostByName`; +- шаблонизируются имена файлов и директорий, например `cmd/{{ .slug }}/main.go`. Путь, который после отрисовки выходит за пределы репозитория, завершает отрисовку ошибкой; +- файл, который после отрисовки пуст или содержит только пробельные символы, в репозиторий не записывается. Так в пакете задаются необязательные файлы. + +### Файлы без шаблонизации + +Файл `.templateignore` перечисляет пути, которые копируются в репозиторий как есть, без шаблонизации. Используйте его для файлов с собственным синтаксисом `{{ }}`, например шаблонов Helm. + +Пример `.templateignore`: + +```text +# Helm templates use their own {{ .Values }} syntax. +deploy/helm/templates/** +``` + +Каждая строка — glob-шаблон пути относительно корня пакета, поддерживается синтаксис `**`. Строки, начинающиеся с `#`, — комментарии. Шаблоны путей в `.templateignore` сами могут содержать выражения `{{ }}`. + +## Версии + +Версия пакета — тег артефакта в хранилище образов в формате strict semver без префикса `v`, например `1.2.0` или `2.0.0-rc.1`. + +Правила версионирования: + +- опубликованную версию перезаписать нельзя: для исправления опубликуйте новую версию; +- увеличивайте major-версию при несовместимых изменениях структуры репозитория; +- предварительные версии, например `2.0.0-rc.1`, не устанавливаются автоматическим обновлением и видны в карточке микросервиса только пользователям с разрешением `read:template-registries`. + +Перед публикацией версии с несовместимыми изменениями проверьте: + +- файлы, переименованные или перемещённые в новой версии, остаются в старых путях репозиториев микросервисов: обновление не удаляет файлы. Опишите ручную очистку в описании версии; +- новые обязательные файлы добавлены в `update.overwrite` или в `update.addIfMissing`, если у пользователей уже могут быть свои копии этих файлов; +- `update.overwrite` содержит только файлы, которыми владеет платформа, например CI и манифесты развёртывания. Файлы, которые редактируют разработчики, перенесите в `update.addIfMissing` или оставьте вне списков. + +## Утилита ddp-template + +Утилита `ddp-template` проверяет, собирает, публикует и локально отрисовывает пакеты шаблонов. + +Команды утилиты: + +| Команда | Назначение | +| --- | --- | +| `ddp-template lint ` | Проверка `template.yaml`, `values.yaml`, `.templateignore`, списков путей обновления и пробная отрисовка пакета | +| `ddp-template pack ` | Сборка архива пакета без директории `.git` | +| `ddp-template publish --version ` | Проверка, сборка и публикация пакета в хранилище образов. Выводит JSON с полями `templateId`, `version`, `ociRef`, `sha256` | +| `ddp-template pull --version ` | Загрузка и распаковка опубликованного пакета | +| `ddp-template render ` | Локальная отрисовка пакета, в том числе с имитацией стратегии обновления | + +Коды завершения `ddp-template lint`: `0` — ошибок нет, `1` — есть ошибки, `2` — есть предупреждения. Флаг `--strict` превращает предупреждения в ошибки, флаг `--render-smoke` выполняет только отрисовку со значениями по умолчанию. + +### Подключение к хранилищу + +Параметры подключения к хранилищу задаются флагами, переменными окружения или файлом конфигурации. Флаги имеют приоритет над переменными окружения, переменные окружения — над профилем из файла конфигурации. + +| Параметр | Флаг | Переменная окружения | +| --- | --- | --- | +| Файл конфигурации | `--config` | `DDP_TEMPLATE_CONFIG` | +| Профиль | `--profile` | `DDP_TEMPLATE_PROFILE` | +| Хост хранилища | `--registry` | `DDP_TEMPLATE_REGISTRY` | +| Префикс репозиториев | `--repository-prefix` | `DDP_TEMPLATE_REPOSITORY_PREFIX` | +| Имя пользователя | `--registry-user` | `DDP_TEMPLATE_REGISTRY_USER` | +| Пароль или токен | `--registry-token` | `DDP_TEMPLATE_REGISTRY_TOKEN` | + +Если имя пользователя не задано, пароль используется как Bearer-токен. + +Файл конфигурации содержит профили подключений: + +```yaml +default: company +registries: + company: + registry: registry.example.com + repositoryPrefix: ddp-templates + auth: + username: + password: +``` + +Где: + +- `` — имя пользователя хранилища; +- `` — пароль или токен хранилища. + +Если задан параметр `default` или профиль один, он используется, когда профиль не указан. + +### Публикация из CI + +Версии публикуются из CI по Git-тегу. Пример задачи GitLab CI, которая публикует шаблон `go-service` по тегу `go-service/vX.Y.Z`: + +```yaml +publish-go-service: + rules: + - if: $CI_COMMIT_TAG =~ /^go-service\/v\d+\.\d+\.\d+$/ + script: + - VERSION="${CI_COMMIT_TAG#go-service/v}" + - ddp-template publish ./template-packs/go-service + --version "$VERSION" + --registry "$REGISTRY" + --repository-prefix ddp-templates +``` + +После публикации версия появляется в портале при следующей синхронизации реестра шаблонов или после нажатия «Синхронизировать» на вкладке «Запуски синхронизации». +Если в подключении заполнено поле «Идентификаторы репозиториев», добавьте в него идентификатор нового шаблона. + +### Локальная проверка обновления + +Утилита отрисовывает новую версию пакета со значениями существующего микросервиса без обращения к GitLab. Так проверяется, какие файлы изменит обновление. + +Команды загружают опубликованную версию и отрисовывают её с имитацией стратегии обновления: + +```shell +ddp-template pull go-service --version 1.1.0 \ + --registry registry.example.com \ + --repository-prefix ddp-templates \ + --output ./packs/go-service-1.1.0 +ddp-template render ./packs/go-service-1.1.0 \ + --values ./values.yaml \ + --use-overwrite \ + --output ./render-out +``` + +Где `./values.yaml` — файл со значениями параметров из раздела `values` lock-файла микросервиса. + +Команда `ddp-template render` не применяет аннотации `x-ddp-from`: передайте значения таких параметров в файле `--values`. diff --git a/content/documentation/admin/templates/registry.ru.md b/content/documentation/admin/templates/registry.ru.md new file mode 100644 index 00000000..a99cb975 --- /dev/null +++ b/content/documentation/admin/templates/registry.ru.md @@ -0,0 +1,223 @@ +--- +title: Реестр шаблонов +weight: 20 +description: Подключение хранилищ образов с пакетами шаблонов к DDP, настройки синхронизации и автоматического обновления, запуски синхронизации, каталог версий шаблонов и их статусы. +--- + +Реестр шаблонов — это подключения портала к хранилищам образов контейнеров, в которых опубликованы пакеты шаблонов, и настройки их синхронизации. +Портал синхронизирует подключённые хранилища, ведёт каталог версий шаблонов и определяет последнюю версию каждого шаблона. + +Реестр шаблонов находится в разделе «Администрирование» → «Интеграции» → «Шаблоны». Страница содержит вкладки «Реестры», «Настройки», «Запуски синхронизации» и «Шаблоны». + +## Быстрый старт + +Чтобы подключить хранилище и получить шаблоны в галерее главной: + +1. На вкладке «Реестры» нажмите «Подключить реестр», заполните поля «Название», «Реестр», «Префикс репозиториев», «Имя пользователя», «Пароль» и сохраните подключение. +1. На вкладке «Настройки» включите переключатель «Включить синхронизацию» и сохраните настройки. +1. На вкладке «Запуски синхронизации» нажмите «Синхронизировать» и дождитесь статуса «Успех». +1. На вкладке «Шаблоны» проверьте, что у версий шаблонов статус «доступна». +1. Привяжите процессы к шаблонам в правилах маппинга главной: «Микросервисы» → «[Действия по шаблонам](../home/mapping/#действия-по-шаблонам)». + +После этого шаблоны отображаются в разделе главной «Создать микросервис». + +## Права доступа + +Для работы с реестром шаблонов используются следующие разрешения: + +| Разрешение | Что даёт | +| --- | --- | +| `read:template-packs` | Просмотр версий шаблонов: галерея «Создать микросервис», уведомление о новой версии в карточке микросервиса | +| `edit:template-packs` | Отзыв, возврат и удаление версий шаблонов | +| `read:template-registries` | Просмотр подключений, настроек и запусков синхронизации; уведомления о предварительных версиях шаблонов в карточке микросервиса | +| `edit:template-registries` | Изменение подключений и настроек, запуск синхронизации | + +Без разрешения `read:template-registries` на странице отображается сообщение «Недостаточно прав для управления реестром шаблонов.». + +## Подключение хранилища + +Подключения к хранилищам образов добавляются на вкладке «Реестры» кнопкой «Подключить реестр». Портал поддерживает хранилища с OCI Distribution Spec v2, например Harbor, GitLab Container Registry, Docker Registry. + +Поля подключения: + +| Поле | Описание | +| --- | --- | +| «Название» | Уникальное название реестра, до 128 символов. Записывается в микросервисы, созданные из шаблонов этого реестра | +| «Реестр» | Хост хранилища образов, например `registry.vendor.example`. Без схемы используется HTTPS | +| «Префикс репозиториев» | Префикс пути внутри хранилища, например `ddp-templates` | +| «Идентификаторы репозиториев» | Идентификаторы шаблонов, которые портал отслеживает в хранилище | +| «Имя пользователя» | Имя пользователя хранилища | +| «Пароль» | Пароль или токен хранилища. Если имя пользователя не задано, значение используется как Bearer-токен | +| «Пропускать проверку TLS» | Только для лабораторных сред и самоподписанных сертификатов. Разрешает подключение по HTTP | + +Пароль хранится в зашифрованном виде и не возвращается в интерфейс. Чтобы сохранить текущий пароль при изменении подключения, оставьте маску в поле «Пароль» без изменений. + +Портал использует [доверенные сертификаты](../trusted-certificates/), добавленные в портал, при подключении к хранилищу. + +Портал не принимает в поле «Реестр»: + +- схему `http://` без включённого параметра «Пропускать проверку TLS»; +- учётные данные, параметры запроса и фрагменты в адресе; +- `localhost` и имена `*.localhost`; +- IP-адреса loopback, частных, link-local и multicast-сетей. + +### Отслеживаемые шаблоны + +Поле «Идентификаторы репозиториев» определяет, как портал находит шаблоны в хранилище: + +- поле пустое — портал запрашивает каталог репозиториев хранилища с префиксом из поля «Префикс репозиториев». Новые шаблоны появляются автоматически, а шаблон, удалённый из хранилища, отзывается целиком; +- поле заполнено — портал запрашивает только перечисленные репозитории. Режим подходит для больших хранилищ и токенов без прав на просмотр каталога. Новые шаблоны добавляются в список вручную, а шаблон, удалённый из хранилища, остаётся в галерее. + +В обоих режимах версии, удалённые из отслеживаемых репозиториев, отзываются. + +Идентификатор шаблона — это имя репозитория в хранилище без префикса. Пакет публикуется по адресу `<реестр>/<префикс репозиториев>/<идентификатор шаблона>:<версия>`. + +### Удаление и переименование подключения + +При удалении или переименовании подключения доступные версии его шаблонов получают статус «недоступна» с причиной `source removed from settings`. Записи о версиях в каталоге не удаляются. + +Если подключение с тем же названием будет добавлено снова, такие версии становятся доступными при следующей синхронизации. + +Версии удалённых подключений отображаются на вкладке «Шаблоны» с тегом «реестр удалён». Кнопка «Удалить осиротевшие ({count})» удаляет их безвозвратно; для подтверждения введите `УДАЛИТЬ`. + +## Настройки + +Вкладка «Настройки» содержит параметры, общие для всех подключений. Изменения применяются без перезапуска портала. + +Раздел «Синхронизация»: + +| Параметр | По умолчанию | Описание | +| --- | --- | --- | +| «Включить синхронизацию» | Выключено | Включает синхронизацию по расписанию и сверку версии шаблона микросервисов с lock-файлом | +| «Интервал синхронизации» | `*/15 * * * *` | Cron-выражение расписания синхронизации, время UTC | +| «Максимальный размер шаблона (килобайты)» | `51200` | Пакет больше лимита отклоняется при синхронизации | + +Раздел «Значения по умолчанию для создаваемых сервисов»: + +| Параметр | По умолчанию | Описание | +| --- | --- | --- | +| «Ветка по умолчанию» | `main` | Ветка по умолчанию для создаваемых микросервисов | +| «Префикс ветки обновления» | `ddp/template-upgrade-` | Префикс ветки обновления шаблона; к нему добавляется версия, например `ddp/template-upgrade-1.3.0`. Заканчивается на `-` или `/`, без пробелов и `..`, до 128 символов | + +Смена префикса ветки обновления не учитывает merge request, уже открытые с веткой со старым префиксом. + +Раздел «Сверка версии и автоматизация»: + +| Параметр | По умолчанию | Описание | +| --- | --- | --- | +| «Интервал сверки версии шаблона» | `*/5 * * * *` | Cron-выражение расписания сверки версии шаблона микросервисов | +| «Пользователь автоматизации» | Не задан | Пользователь, от имени которого запускаются автоматические обновления и выполняется сверка версии. Если не задан, автоматическое обновление и сверка версии выключены | +| «Лимит очереди обновлений» | `5` | Максимальное число автоматических обновлений, которые запускаются после одной синхронизации. Значение от 1 до 1000 | + +Требования к пользователю автоматизации описаны в разделе [«Обновление из шаблона»](updates/#автоматическое-обновление). + +## Синхронизация + +Синхронизация загружает в каталог версий новые версии шаблонов из подключённых хранилищ. + +Синхронизация запускается: + +- по расписанию из параметра «Интервал синхронизации», если включена синхронизация; +- кнопкой «Синхронизировать» на вкладке «Запуски синхронизации». Кнопка запускает синхронизацию и при выключенном параметре «Включить синхронизацию». + +Одновременно выполняется только одна синхронизация. Повторный запуск во время синхронизации завершается ошибкой «Синхронизация реестра шаблонов уже выполняется». + +Для каждого подключения синхронизация выполняет следующие шаги: + +1. Получает список репозиториев: из поля «Идентификаторы репозиториев» или из каталога хранилища. +1. Для каждого тега в формате semver, которого ещё нет в каталоге версий, загружает пакет, проверяет размер, манифест `template.yaml`, схему `values.yaml` и требование `minDdpVersion`. +1. Записывает версию в каталог со статусом «доступна» или с причиной, по которой версия недоступна. +1. Отзывает версии, теги которых удалены из хранилища. +1. Пересчитывает последнюю версию каждого шаблона. + +Теги не в формате strict semver, например `v1.2.0` или `latest`, пропускаются. Уже загруженные версии повторно не загружаются. + +Если у шаблона изменилась последняя версия, после синхронизации запускается [автоматическое обновление](updates/#автоматическое-обновление) микросервисов. + +Ошибка подключения к одному хранилищу, например ошибка авторизации, прерывает синхронизацию этого хранилища, но не мешает синхронизации остальных. Запуск в этом случае получает статус «Ошибка». + +Синхронизация, которая выполняется дольше 2 часов, при перезапуске портала отмечается как завершённая с ошибкой `interrupted: sync run exceeded stale threshold`. + +### Запуски синхронизации + +На вкладке «Запуски синхронизации» отображаются последние 10 запусков. Над таблицей выводится итог последнего запуска, например «Последняя успешная синхронизация: {time}» или «Последний запуск синхронизации завершился с ошибкой.». + +Колонки таблицы: + +- «Статус» — «Выполняется», «Успех» или «Ошибка»; +- «Время» — время запуска; +- «Изменения» — число добавленных, отозванных, конфликтующих, осиротевших и восстановленных версий или «Без изменений»; +- «Ошибка» — текст ошибки. + +Кнопка «Обновить» перезагружает список запусков. + +## Каталог версий + +На вкладке «Шаблоны» отображаются все версии шаблонов, загруженные из подключённых хранилищ. + +Для версии отображаются шаблон, версия, название, реестр, статус, причина статуса, время синхронизации, ссылка на образ и SHA-256. +Тег «последняя» отмечает рекомендованную версию шаблона. + +### Статусы версий + +Версия шаблона может иметь следующие статусы: + +| Статус | Когда присваивается | Что происходит с версией | +| --- | --- | --- | +| «доступна» | Пакет загружен и прошёл проверки | Отображается в галерее, используется для создания и обновления | +| «некорректна» | Пакет не удалось загрузить, распаковать или проверить | Не используется. Причина указана в колонке «Причина статуса» | +| «недоступна» | Версия требует более новой версии DDP (`minDdpVersion`) или подключение удалено | Не используется | +| «отозвана» | Тег удалён из хранилища или администратор отозвал версию | Скрыта из галереи и автоматического обновления | + +Портал не проверяет повторно версии со статусом «некорректна» и версии, недоступные из-за `minDdpVersion`. +Чтобы портал загрузил такую версию заново, удалите её на вкладке «Шаблоны»: при следующей синхронизации тег будет загружен из хранилища снова. Если пакет нужно исправить, опубликуйте новую версию. + +### Последняя версия + +Последняя версия шаблона — максимальная стабильная версия со статусом «доступна» среди всех подключений. Если стабильных версий нет, последней становится максимальная предварительная (prerelease) версия, например `2.0.0-rc.1`. + +Последняя версия — это не всегда максимальная версия по правилам semver: отозванные версии не учитываются. + +### Конфликт реестров + +Если одна и та же версия шаблона есть в нескольких подключениях, используется версия из подключения, которое загрузило её первым. У версии отображается тег «Конфликт» с перечнем других реестров. + +Если версия первого подключения стала недоступной или отозванной, её заменяет доступная копия из другого подключения. + +### Отзыв, возврат и удаление версии + +Для управления версиями требуется разрешение `edit:template-packs`. + +С версией доступны следующие действия: + +- «Отозвать версию» — версия получает статус «отозвана» и скрывается из галереи и автоматического обновления. В поле «Причина» укажите причину отзыва. Тег в хранилище не удаляется; +- «Вернуть версию» — отозванная версия снова становится доступной. Если тега нет в хранилище, следующая синхронизация может снова отозвать версию; +- «Удалить» — запись о версии удаляется из портала. Тег в хранилище остаётся, и следующая синхронизация загрузит версию заново. + +Статусы «некорректна» и «недоступна» вручную не меняются. +Отзыв, возврат и удаление версии пересчитывают последнюю версию шаблона, но не запускают автоматическое обновление микросервисов. + +## Ошибки синхронизации + +Ошибки синхронизации отображаются в колонке «Ошибка» запуска, а ошибки отдельных версий — в колонке «Причина статуса» каталога версий. + +| Сообщение | Причина | Что сделать | +| --- | --- | --- | +| `registry authorization failed` | Хранилище отклонило учётные данные | Проверьте поля «Имя пользователя» и «Пароль» подключения | +| `registry temporarily unavailable` | Хранилище недоступно или вернуло ошибку 429 или 5xx | Повторите синхронизацию позже | +| `list repositories: ...` | Не удалось получить каталог репозиториев | Проверьте права токена на просмотр каталога или заполните поле «Идентификаторы репозиториев» | +| `pack size N exceeds maxPackSize M` | Пакет больше параметра «Максимальный размер шаблона» | Уменьшите пакет или увеличьте лимит, удалите версию и повторите синхронизацию | +| `invalid template.yaml: ...` | Манифест не прошёл проверку | Исправьте манифест и опубликуйте новую версию | +| `manifest id "a" does not match repository template id "b"` | Поле `id` манифеста не совпадает с именем репозитория в хранилище | Опубликуйте пакет в репозиторий с именем, равным `id` | +| `requires DDP version X or newer (running Y)` | Версия DDP ниже `minDdpVersion` пакета | Обновите DDP и удалите версию, чтобы она загрузилась заново | +| `tag removed from registry` | Тег удалён из хранилища | — | +| `source removed from settings` | Подключение удалено или переименовано | Верните подключение с тем же названием или удалите осиротевшие версии | + +Сообщения API реестра шаблонов: + +| Сообщение | Причина | +| --- | --- | +| «Некорректный реестр шаблонов» | Поля подключения не прошли проверку, например адрес указывает на частную сеть | +| «Некорректные настройки реестра шаблонов» | Неверное cron-выражение, префикс ветки обновления или лимит | +| «Синхронизация реестра шаблонов уже выполняется» | Запущена повторная синхронизация до завершения текущей | +| «Некорректное изменение статуса версии шаблона» | Попытка изменить статус версии, отличный от «доступна» и «отозвана» | diff --git a/content/documentation/admin/templates/updates.ru.md b/content/documentation/admin/templates/updates.ru.md new file mode 100644 index 00000000..03841519 --- /dev/null +++ b/content/documentation/admin/templates/updates.ru.md @@ -0,0 +1,239 @@ +--- +title: Обновление из шаблона +weight: 40 +description: Как DDP обновляет репозитории микросервисов до новой версии шаблона — привязка к шаблону, ручное и автоматическое обновление, стратегии обновления, merge request, сверка версии и устранение ошибок. +--- + +Обновление из шаблона переносит изменения новой версии шаблона в репозиторий микросервиса, созданного из этого шаблона. +Портал отрисовывает новую версию пакета со значениями параметров микросервиса, применяет изменения по стратегии обновления в отдельной ветке и открывает merge request. Изменения попадают в основную ветку после того, как владелец микросервиса примет merge request. + +## Перед началом работы + +Для обновления из шаблона выполните следующие условия: + +- подключён и синхронизирован [реестр шаблонов](registry/); +- в правилах маппинга главной для шаблона привязан процесс действия «Обновить микросервис из шаблона»: «Микросервисы» → «[Действия по шаблонам](../home/mapping/#действия-по-шаблонам)». Набор данных «Реестр шаблонов микросервисов» создаёт процесс «Обновить микросервис из шаблона», который можно привязать к любому шаблону; +- микросервис создан из шаблона: в репозитории есть lock-файл `.ddp/template.lock.yaml`, а у сущности микросервиса заполнены параметры привязки к шаблону. + +## Привязка микросервиса к шаблону + +При создании микросервиса из шаблона портал записывает сведения о шаблоне в репозиторий и в каталог. + +В репозиторий записывается lock-файл `.ddp/template.lock.yaml`: + +```yaml +templateId: go-service +templateVersion: 1.2.0 +schemaVersion: 1 +values: + port: 8080 + database: postgres +``` + +Lock-файл содержит значения параметров, переданные при создании, без значений по умолчанию из схемы. По lock-файлу портал определяет текущую версию шаблона в репозитории и значения параметров для отрисовки новой версии. +Не удаляйте и не изменяйте lock-файл вручную: без него репозиторий обновить нельзя. + +В сущность микросервиса записываются параметры привязки. В таблице указаны параметры каноничной модели каталога и роли маппинга, через которые портал их находит: + +| Параметр | Название | Роль маппинга | Значение | +| --- | --- | --- | --- | +| `template_id` | «Идентификатор шаблона» | `microservice_binding_template_id` | Идентификатор шаблона | +| `template_version` | «Версия шаблона» | `microservice_binding_template_version` | Текущая версия шаблона в репозитории | +| `template_source` | «Источник шаблона» | `microservice_binding_template_source` | Название реестра, из которого получен шаблон | +| `template_update_policy` | «Политика обновления шаблона» | `microservice_binding_template_update_policy` | «Вручную» (`manual`) или «Ревью автоматически» (`review-auto`) | +| `template_upgrade_strategy` | «Стратегия обновления шаблона» | `microservice_binding_template_upgrade_strategy` | Стратегия обновления для этого микросервиса | +| `template_upgrade_overwrite` | «Перезаписываемые пути обновления» | `microservice_binding_template_upgrade_overwrite` | Список перезаписываемых путей для этого микросервиса | +| `template_upgrade_add_if_missing` | «Добавляемые пути обновления» | `microservice_binding_template_upgrade_add_if_missing` | Список добавляемых путей для этого микросервиса | +| `default_branch` | — | `microservice_default_branch` | Ветка, в которую создаётся merge request обновления | +| `vcs_provider` | — | `microservice_vcs_provider` | Провайдер системы контроля версий | +| `vcs_external_service_uuid` | «Внешний сервис VCS» | `microservice_vcs_external_service_uuid` | Внешний сервис GitLab, в котором находится репозиторий | + +Микросервис привязан к паре «шаблон и реестр»: обновления предлагаются только из версий шаблона того же реестра. + +### Политика обновления + +Политика обновления определяет, запускается ли обновление автоматически после выхода новой версии шаблона: + +- «Вручную» (`manual`) — обновление запускается только кнопкой «Обновить» в карточке микросервиса. Эта политика назначается при создании микросервиса; +- «Ревью автоматически» (`review-auto`) — портал сам запускает обновление после синхронизации, на которой появилась новая последняя версия, и открывает merge request. + +Чтобы изменить политику, откройте сущность микросервиса в каталоге и измените параметр «Политика обновления шаблона». + +### Настройки обновления микросервиса + +Стратегия и списки путей обновления задаются в манифесте пакета шаблона. Для отдельного микросервиса их можно переопределить параметрами сущности «Стратегия обновления шаблона», «Перезаписываемые пути обновления» и «Добавляемые пути обновления». + +Портал выбирает настройки обновления в следующем порядке: + +1. Параметры процесса обновления, если они заполнены при запуске. +1. Параметры сущности микросервиса, если они заполнены. +1. Поля `update.strategy`, `update.overwrite` и `update.addIfMissing` манифеста новой версии шаблона. +1. Стратегия `selective`, если стратегия нигде не задана. + +Кнопка «Обновить» и автоматическое обновление передают выбранные настройки в контексте запуска процесса. Если процесс «Обновить микросервис из шаблона» из набора данных запускается без контекста, например из каталога, при пустом параметре «Стратегия обновления» используется `selective`. + +## Обнаружение новой версии + +Новая версия шаблона обнаруживается при синхронизации реестра шаблонов. Если в результате синхронизации изменилась последняя версия шаблона, портал запускает автоматическое обновление подходящих микросервисов. + +В карточке микросервиса на главной уведомление «Доступна версия {version}» отображается, если выполнены условия: + +- у сущности микросервиса задан шаблон; +- у шаблона того же реестра есть последняя версия со статусом «доступна»; +- последняя версия выше версии шаблона микросервиса; +- у пользователя есть разрешение `read:template-packs`. + +Уведомления о предварительных версиях, например `2.0.0-rc.1`, видят только пользователи с разрешением `read:template-registries`. Переход на более раннюю версию не предлагается. + +## Ручное обновление + +Ручное обновление запускает пользователь из карточки микросервиса на главной. Ручное обновление доступно при любой политике обновления. + +Чтобы обновить микросервис: + +1. Откройте раздел главной «Микросервисы» и выберите микросервис в таблице. +1. На вкладке «Справка» в блоке «Доступна версия {version}» нажмите «Обновить». +1. В окне «Запустить процесс» проверьте параметры и нажмите «Запустить». +1. Дождитесь завершения процесса и откройте merge request в GitLab. Ссылка на merge request сохраняется в хранилище процесса. + +Кнопка «Обновить» недоступна в следующих случаях: + +| Подсказка | Причина | +| --- | --- | +| «Недостаточно прав для запуска процессов на этой сущности.» | У пользователя нет права на запуск действий для сущности микросервиса | +| «Процесс обновления шаблона уже выполняется для этого сервиса.» | Для микросервиса уже выполняется процесс обновления | +| «Для шаблона {template} не задан процесс обновления. Задайте его в правилах маппинга главной, в действиях по шаблонам.» | К шаблону не привязан процесс действия «Обновить микросервис из шаблона» | +| «У сервиса не определён шаблон, поэтому обновление из шаблона недоступно.» | У сущности микросервиса не задан шаблон | + +## Автоматическое обновление + +Автоматическое обновление запускает процесс обновления без участия пользователя после синхронизации, на которой у шаблона появилась новая последняя версия. + +Портал запускает автоматическое обновление микросервиса, если выполнены все условия: + +- в настройках реестра шаблонов задан «Пользователь автоматизации»; +- у микросервиса политика обновления «Ревью автоматически» (`review-auto`); +- новая последняя версия — стабильная, не предварительная; +- шаблон и реестр микросервиса совпадают с шаблоном и реестром новой версии; +- версия шаблона микросервиса в формате semver и ниже новой версии; +- репозиторий микросервиса находится в GitLab; +- к шаблону привязан процесс действия «Обновить микросервис из шаблона»; +- для микросервиса не выполняется процесс обновления; +- в репозитории нет открытого merge request из ветки с префиксом из настройки «Префикс ветки обновления». + +После одной синхронизации запускается не больше обновлений, чем задано в настройке «Лимит очереди обновлений». Первыми запускаются обновления с наибольшим разрывом версий: сначала по major-версии, затем по minor и patch. + +{{< alert level="warning" >}} +Микросервисы, которые не попали в лимит или были пропущены из-за открытого merge request, повторно не ставятся на обновление до выхода следующей версии шаблона. +Обновите такие микросервисы кнопкой «Обновить» или увеличьте «Лимит очереди обновлений» до публикации следующей версии. +{{< /alert >}} + +Автоматическое обновление также запускается после синхронизации кнопкой «Синхронизировать», в том числе при выключенном параметре «Включить синхронизацию». +Отзыв, возврат и удаление версии на вкладке «Шаблоны» автоматическое обновление не запускают. + +### Пользователь автоматизации + +Процессы автоматического обновления запускаются от имени пользователя автоматизации, а действия процесса выполняются с его учётными данными. + +Подготовьте пользователя автоматизации: + +1. Создайте пользователя, например [сервисного пользователя](../../user/teams-users/#сервисные-пользователи). + Автоматический запуск процесса не проверяет разрешения пользователя на сущности микросервисов. +1. Заполните в профиле пользователя учётные данные GitLab — персональный токен и имя пользователя — для внешнего сервиса GitLab, в котором находятся репозитории микросервисов. +1. Выберите пользователя в поле «Пользователь автоматизации» на вкладке «Настройки» реестра шаблонов. + +Учётные данные пользователя автоматизации используются также для проверки открытых merge request и для сверки версии шаблона. + +Merge request автоматического обновления создаются от имени пользователя автоматизации. Выдайте его учётной записи GitLab только права, необходимые для создания веток и merge request в репозиториях микросервисов. + +## Выполнение обновления + +Процесс «Обновить микросервис из шаблона» из набора данных «Реестр шаблонов микросервисов» состоит из двух задач: «Обновление репозитория из шаблона» и «Создание код-ревью». + +Задача «Обновление репозитория из шаблона» выполняет следующие шаги: + +1. Определяет целевую версию: версию из параметра «Версия шаблона» или последнюю доступную версию шаблона из реестра микросервиса. +1. Клонирует основную ветку репозитория и читает lock-файл. Если версия в lock-файле отличается от версии в каталоге, портал исправляет версию в каталоге по lock-файлу. +1. Если версия в lock-файле не ниже целевой, завершает задачу без изменений; merge request не создаётся. +1. Отрисовывает новую версию пакета. Значения параметров: значения по умолчанию из схемы новой версии, поверх них — значения из lock-файла, поверх них — значения, переданные в процесс. +1. Создаёт ветку `<префикс ветки обновления><версия>`, например `ddp/template-upgrade-1.3.0`, от основной ветки. +1. Применяет изменения по стратегии обновления. +1. Записывает в lock-файл новую версию и значения параметров. +1. Создаёт коммит `chore(template): upgrade <старая версия> -> <новая версия>` и отправляет ветку в GitLab. + +Задача «Создание код-ревью» открывает merge request из ветки обновления: + +- в ветку из параметра `default_branch` микросервиса, если он не задан — в `main`; +- с заголовком `Upgrade to `. + +Если merge request из этой же ветки уже открыт, задача использует его. Если открыт merge request из другой ветки с тем же префиксом, задача завершается ошибкой `review_already_open`. + +Портал не принимает merge request автоматически, не назначает ревьюеров и не отправляет уведомлений. Результат процесса отображается в панели «Мои активности» и в истории запусков процесса. + +### Стратегии обновления + +Стратегия обновления определяет, какие файлы репозитория меняет обновление. Стратегии и требования к спискам путей: + +| Стратегия | `overwrite` | `addIfMissing` | Поведение | +| --- | --- | --- | --- | +| `selective` | Обязателен | Не используется | Перезаписывает файлы, пути которых совпадают с `overwrite` | +| `additive` | Не используется | Обязателен | Добавляет файлы из `addIfMissing`, если их нет в репозитории | +| `selective_additive` | Обязателен | Обязателен | Сначала перезаписывает файлы из `overwrite`, затем добавляет файлы из `addIfMissing` | +| `full` | Не обязателен | Не обязателен | Записывает весь отрисованный пакет поверх репозитория и перезаписывает каждый совпавший файл | +| `merge` | Обязателен | Не обязателен | Выполняет трёхстороннее слияние файлов из `overwrite`, затем добавляет файлы из `addIfMissing` | + +Правила для всех стратегий: + +- файлы вне области стратегии не изменяются; +- файлы не удаляются: файлы, удалённые или переименованные в новой версии шаблона, остаются в репозитории; +- в репозиторий не копируются `template.yaml`, `values.yaml` и `.templateignore`. + +Списки путей — glob-шаблоны относительно корня репозитория, поддерживается синтаксис `**`, например `deploy/**`. + +Если обязательный для стратегии список пуст, обновление завершается ошибкой `invalid_upgrade_config`. + +### Слияние + +Стратегия `merge` сохраняет изменения, которые разработчики внесли в файлы из `overwrite`. Для каждого файла портал сравнивает три версии: + +- базовую — файл, отрисованный из версии шаблона, указанной в lock-файле; +- текущую — файл в репозитории микросервиса; +- новую — файл, отрисованный из новой версии шаблона. + +Если файла нет в репозитории, записывается новая версия файла. Переводы строк CRLF и перевод строки в конце файла сохраняются. + +Любой конфликт слияния, в том числе различие бинарных файлов, прерывает обновление целиком: в репозиторий ничего не записывается, а процесс завершается ошибкой `merge_conflict: merge conflict in files: <файлы>`. +Чтобы обновить микросервис с конфликтами, задайте для него другую стратегию, например `selective`, и перенесите изменения вручную в merge request. + +## Сверка версии после слияния + +После принятия merge request портал обновляет версию шаблона микросервиса в каталоге. Сверка выполняется по расписанию из настройки «Интервал сверки версии шаблона». + +Сверка выполняется, если в настройках реестра включён параметр «Включить синхронизацию» и задан «Пользователь автоматизации». +Портал проверяет микросервисы, у которых версия шаблона в каталоге ниже последней доступной версии, читает lock-файл из ветки `default_branch` (или `main`) через API GitLab и повышает параметр «Версия шаблона», если версия в lock-файле выше. + +Версия в каталоге только повышается. После сверки уведомление «Доступна версия {version}» в карточке микросервиса исчезает. + +Если пользователь автоматизации не задан, версия в каталоге после принятия merge request не меняется до следующего запуска обновления: процесс обновления исправляет версию по lock-файлу. + +## Устранение ошибок + +Ошибки обновления отображаются в журнале задачи процесса. Сообщение начинается с кода ошибки. + +| Код ошибки | Причина | Что сделать | +| --- | --- | --- | +| `lock_not_found` | В репозитории нет файла `.ddp/template.lock.yaml` | Восстановите lock-файл. Репозитории, созданные без lock-файла, из шаблона не обновляются | +| `lock_mismatch` | Lock-файл создан для другого шаблона | Проверьте параметр «Идентификатор шаблона» микросервиса и lock-файл | +| `lock_invalid`, `unsupported_lock_schema` | Lock-файл повреждён или имеет неподдерживаемую версию схемы | Восстановите lock-файл из истории репозитория | +| `merge_conflict` | Конфликт слияния при стратегии `merge` | Смените стратегию микросервиса или выполните обновление вручную | +| `invalid_upgrade_config` | Для стратегии не задан обязательный список путей | Задайте списки путей в манифесте пакета или в параметрах микросервиса | +| `review_already_open` | Открыт merge request из другой ветки обновления | Примите или закройте открытый merge request и повторите обновление | +| `push_failed` | Не удалось отправить ветку в GitLab, например ветка с таким именем уже существует | Удалите ветку обновления в GitLab и повторите обновление | +| `pack_not_found` | В реестре микросервиса нет подходящей версии шаблона | Проверьте реестр шаблона микросервиса и статус версии | +| `pack_deprecated`, `pack_unavailable`, `pack_invalid` | Целевая версия отозвана, недоступна или некорректна | Выберите другую версию или верните версию на вкладке «Шаблоны» | +| `values_invalid` | Значения параметров не соответствуют схеме новой версии | Передайте недостающие значения в процесс обновления или исправьте схему в новой версии шаблона | +| `render_failed` | Ошибка шаблонизации файлов пакета | Исправьте шаблоны и опубликуйте новую версию | +| `clone_failed` | Не удалось клонировать репозиторий | Проверьте учётные данные GitLab пользователя, запустившего процесс | +| `unsupported_vcs_provider` | Провайдер системы контроля версий микросервиса не GitLab | — | + +Чтобы повторить обновление, запустите процесс снова кнопкой «Обновить». diff --git a/content/documentation/admin/widgets/gitlab/merge-requests.ru.md b/content/documentation/admin/widgets/gitlab/merge-requests.ru.md index 56d7688c..c883a810 100644 --- a/content/documentation/admin/widgets/gitlab/merge-requests.ru.md +++ b/content/documentation/admin/widgets/gitlab/merge-requests.ru.md @@ -1,10 +1,10 @@ --- -title: GitLab. Запросы на слияние -description: Фильтрация по статусу и действия с запросами на слияние в GitLab. +title: GitLab. Запросы слияния +description: Просмотр, фильтрация, создание и слияние merge request проекта GitLab. weight: 20 --- -Виджет позволяет отображать данные о запросах на слияние (MR) в GitLab и выполнять действия с ними. +Виджет показывает merge request (MR) проекта GitLab и позволяет создавать, сливать и закрывать их. ## Конфигурация @@ -13,31 +13,60 @@ weight: 20 | URL | Да | URL GitLab API. Используется для получения данных из GitLab | — | | ID проекта | Да | ID проекта, из которого будут загружаться данные в виджет. Пример: `12345` | — | -## Фильтрация по статусу +## Фильтрация -Виджет позволяет фильтровать отображаемые запросы на слияние по статусу. -В настройках запроса виджета можно выбрать один из следующих статусов: +Над таблицей расположены фильтры по состоянию MR с числом MR в каждом состоянии: «Все», «Открытые», «Черновики», «Слитые», «Закрытые». -- «Открытые» — показывает только открытые MR. -- «Закрытые» — показывает только закрытые MR. -- «Слитые» — показывает только слитые MR. -- «Заблокированные» — показывает только заблокированные MR. +По умолчанию выбран фильтр «Открытые»: он показывает открытые MR без черновиков. Открытые черновики отображаются в фильтре «Черновики». -По умолчанию отображаются только открытые MR. +Список «в» с вариантом «Все ветки» фильтрует MR по целевой ветке. Справа отображается число найденных MR из общего числа. -## Дополнительные возможности виджета +## Таблица -При активированной функции действий в настройках виджет позволяет выполнять следующие действия с запросами на слияние: +В таблице отображаются колонки: -- «Слить» — слияние открытого запроса на слияние (доступно только для открытых MR). -- «Закрыть» — закрытие запроса на слияние. -- «Отметить как черновик/готово» — изменение статуса черновика запроса на слияние. -- «Просмотр изменений» — сравнение изменений в запросе на слияние. +- ID — номер MR со ссылкой на GitLab; +- «Статус» — состояние MR; +- «Название» — название MR, тег «Черновик» и значок конфликта с подсказкой «Конфликты с целевой веткой»; +- «Автор» и «Ревьюеры»; +- «Ветка» — ветка-источник, в подсказке — ветка-источник и целевая ветка; +- «Обновлён» — время последнего изменения; +- меню «Действия». + +Нажмите на строку, чтобы раскрыть сведения о MR: даты создания и изменения, ревьюеры, число изменённых файлов с числом добавленных и удалённых строк, статус пайплайна и ссылка «Открыть в GitLab». + +## Действия с MR + +Действия с MR доступны в раскрытой строке и в меню «Действия»: + +- «Слить» — слияние MR после подтверждения; +- «Закрыть» — закрытие MR; +- «Отметить как черновик» и «Отметить как готово» — изменение признака черновика; +- «Изменения» — список изменённых файлов в раскрытой строке или построчное сравнение файлов в отдельном окне из меню «Действия»; +- «Открыть в GitLab» — переход к MR в GitLab. + +Если MR нельзя слить, рядом с кнопками отображается причина: + +- «Слить можно только открытый MR»; +- «Черновик нельзя слить»; +- «Конфликты с целевой веткой»; +- «Пайплайн не зелёный» — последний пайплайн MR завершился не успешно. {{< alert level="info" >}} Для выполнения действий с MR требуются соответствующие права доступа в репозитории GitLab. {{< /alert >}} +### Создание MR + +Кнопка «Создать MR» в заголовке виджета открывает окно создания MR. Заполните поля «Ветка-источник», «Целевая ветка», «Название» и, при необходимости, «Описание» и нажмите «Создать». + +Ветка-источник и целевая ветка должны различаться. Поле «Название» обязательное. + +## Размещение на главной + +Виджет выводится на вкладке «MRs» карточки микросервиса на главной, если он выбран в слоте `microservice_merge_requests_widget` [правил маппинга](../../home/mapping/#слоты-виджетов). +В этом случае в поле «ID проекта» укажите `{{ .context.repository.id }}`: карточка микросервиса передаёт виджету ID проекта своего репозитория. + ## Авторизация Конфигурация авторизации описана в разделе [«Внешние сервисы»](../../external-services/#gitlab). diff --git a/content/documentation/admin/widgets/gitlab/pipelines.ru.md b/content/documentation/admin/widgets/gitlab/pipelines.ru.md index 3cac7ab6..4d0f30f1 100644 --- a/content/documentation/admin/widgets/gitlab/pipelines.ru.md +++ b/content/documentation/admin/widgets/gitlab/pipelines.ru.md @@ -1,10 +1,10 @@ --- title: GitLab. Пайплайны -description: Настройка просмотра и ручного запуска пайплайнов GitLab. +description: Просмотр пайплайнов проекта GitLab, их этапов, задач и журналов, запуск, перезапуск и остановка пайплайнов и задач. weight: 50 --- -Виджет позволяет отображать данные о пайплайнах в GitLab. +Виджет показывает пайплайны проекта GitLab, их этапы и задачи и позволяет запускать, перезапускать и останавливать пайплайны и задачи из Deckhouse Development Portal (DDP). ## Конфигурация @@ -13,19 +13,56 @@ weight: 50 | URL | Да | URL GitLab API. Используется для получения данных из GitLab | — | | ID проекта | Да | ID проекта, из которого будут загружаться данные в виджет. Пример: `12345` | — | -## Дополнительные возможности виджета +## Таблица пайплайнов -### Запуск пайплайнов +В таблице отображаются колонки: -Виджет позволяет запускать пайплайны в GitLab напрямую из Deckhouse Development Portal (DDP). +- ID — номер пайплайна со ссылкой на GitLab; +- «Статус» — состояние пайплайна; +- Ref — ветка или тег; +- «Источник» — событие, которое запустило пайплайн; +- «Инициатор» — пользователь, запустивший пайплайн; +- «Длительность» и «Завершено»; +- меню «Действия». -#### Конфигурация +В меню «Действия» доступны: + +- «Перезапустить пайплайн»; +- «Остановить пайплайн» — для ожидающих и выполняющихся пайплайнов; +- «Открыть в GitLab». + +## Этапы и задачи + +Нажмите на строку пайплайна, чтобы раскрыть время создания, запуска и завершения и этапы пайплайна. Для каждого этапа отображаются статус, число задач с ошибкой и задачи этапа. Если задач больше восьми, остальные скрыты под кнопкой «Показать ещё {count}». + +Нажмите на задачу, чтобы открыть панель задачи. В панели отображаются название, номер задачи со ссылкой на GitLab, этап, длительность и кнопки: + +- «Запустить задачу» — для задач с ручным запуском; +- «Перезапустить задачу» — недоступна для задач с ручным запуском и ожидающих задач; +- «Остановить задачу» — для ожидающих, запланированных и выполняющихся задач. + +### Журнал задачи + +В панели задачи отображается журнал выполнения: по умолчанию последние 50 строк. Кнопка «Полный лог» показывает журнал целиком, кнопка «Последние строки» возвращает сокращённый вид. Цвета вывода задачи сохраняются. + +Если задача ещё не запускалась, отображается сообщение «Задача ещё не запускалась — лога нет». + +## Запуск пайплайна + +Кнопка «Запустить пайплайн» в заголовке виджета запускает пайплайн в GitLab. + +Параметры запуска: | Название | Обязательность | Описание | Значение по умолчанию | | ---------- | -------------- | --------------------------------------------------------------------------------- | --------------------- | | Ref | Да | Целевая ветка или тег для запуска пайплайна | — | | Переменные | Нет | Переменные в формате ключ-значение, которые будут переданы в запускаемый пайплайн | — | +## Размещение на главной + +Виджет выводится на вкладке «Пайплайны» карточки микросервиса на главной, если он выбран в слоте `microservice_repository_widget` [правил маппинга](../../home/mapping/#слоты-виджетов). +В этом случае в поле «ID проекта» укажите `{{ .context.repository.id }}`: карточка микросервиса передаёт виджету ID проекта своего репозитория. + ## Авторизация Конфигурация авторизации описана в разделе [«Внешние сервисы»](../../external-services/#gitlab). diff --git a/content/documentation/admin/widgets/overview.ru.md b/content/documentation/admin/widgets/overview.ru.md index 26911f36..15424fef 100644 --- a/content/documentation/admin/widgets/overview.ru.md +++ b/content/documentation/admin/widgets/overview.ru.md @@ -8,9 +8,11 @@ weight: 10 Виджеты могут быть добавлены на дашборды. Дашборды, в свою очередь, могут быть привязаны: -- к статическим страницам («Каталог», «Самообслуживание», «Главная страница», «Администрирование»); +- к статическим страницам («Каталог», «Самообслуживание», «AI», «Администрирование», «РБПО»); - к карточкам сущностей. +Виджет также выводится на главной в [слоте виджета](../home/mapping/#слоты-виджетов) карточки микросервиса. + ## Конфигурация Конфигурация виджета включает общие параметры и набор полей, специфичных для конкретного типа виджета. @@ -19,6 +21,7 @@ weight: 10 * `{{ .entity.name }}` — подстановка значения параметра сущности `name`. * `{{ .credentials.token }}` — подстановка учётных данных с названием `token`. +* `{{ .context.repository.id }}` — подстановка значения из контекста главной. Контекст передаётся только виджетам в слотах главной; состав контекста описан в разделе [«Слоты виджетов»](../home/mapping/#слоты-виджетов). Для каждого виджета доступно задание области видимости: diff --git a/content/documentation/release-notes/v1.7.0.ru.md b/content/documentation/release-notes/v1.7.0.ru.md index 4d58683b..6a8b3786 100644 --- a/content/documentation/release-notes/v1.7.0.ru.md +++ b/content/documentation/release-notes/v1.7.0.ru.md @@ -1,20 +1,77 @@ --- title: v1.7.0 weight: 890 -description: Заметки о выпуске v1.7.0 — автоматическое удаление сущностей и связей сущностей после успешного выполнения действия, виджет «История параметров». +description: Заметки о выпуске v1.7.0 — новая главная страница, реестр шаблонов микросервисов и обновление микросервисов из шаблона, контекст запуска и упрощённая форма запуска процесса, новые действия GitLab, синхронизация источников данных после действия, обновлённые виджеты GitLab. --- {{< alert level="info" >}} -Выпуск релиза планируется 30.08.2026 +Выпуск релиза планируется 09.10.2026 {{< /alert >}} +{{< alert level="warning" >}} +Главная и реестр шаблонов — экспериментальная функциональность. Состав разделов, формат пакета шаблона, структура правил маппинга и API могут измениться в следующих выпусках без сохранения обратной совместимости. +{{< /alert >}} + +## Несовместимые изменения + +### Главная + +Страница «Главная» с прикреплёнными дашбордами заменена [новой главной](../../user/home/overview/). Дашборды, прикреплённые к главной, больше не отображаются; сами дашборды и их виджеты сохраняются. +Новая главная выключена после обновления, и до её включения вкладка «Главная» скрыта у всех пользователей. + ## Новые возможности +### Главная + +- Добавлена новая [главная страница](../../user/home/overview/) — рабочее пространство разработчиков: команды, системы и интеграции, микросервисы, окружения, схема развёртывания систем, заказ ресурсов и потребление ресурсов кластера. +- Добавлены [правила маппинга главной](../../admin/home/mapping/), которые связывают разделы главной с ресурсами, связями, параметрами, процессами и виджетами каталога. +- Добавлен [мастер первоначальной настройки](../../admin/home/setup/), который применяет наборы данных «Каноничная архитектура»: модель каталога, правила маппинга, подключения к Kubernetes, Vault и GitLab, процессы и виджеты главной. + +### Шаблоны микросервисов + +- Добавлен [реестр шаблонов](../../admin/templates/registry/): портал синхронизирует пакеты шаблонов из хранилищ образов контейнеров и показывает их в галерее создания микросервиса. +- Добавлено [обновление микросервисов из шаблона](../../admin/templates/updates/): при выходе новой версии шаблона портал открывает merge request с изменениями в репозитории микросервиса — по кнопке или автоматически. +- Добавлена утилита `ddp-template` для проверки, локальной отрисовки и публикации [пакетов шаблонов](../../admin/templates/packs/#утилита-ddp-template). + +### Процессы + +- Добавлен [контекст запуска процесса](../../admin/processes/overview/#контекст-запуска) — корень шаблонизации `.context` с данными объектов, выбранных при запуске процесса с главной. +- Окно запуска процесса открывается в [упрощённом режиме](../../admin/processes/overview/#параметры-запуска): отображаются только важные параметры, остальные передаются со значениями по умолчанию. Полный режим открывается кнопкой «Все параметры процесса». +- Добавлен признак параметра процесса [«Показывать в упрощённой форме»](../../user/properties/#конфигурация). +- Пока выполняются процессы пользователя, значок панели «Мои активности» заменяется индикатором, а на вкладке «Процессы» отображается число выполняющихся процессов. + ### Действия - Добавлен механизм автоматического [удаления сущностей](../../admin/actions/overview/#удаление-сущностей) после успешного выполнения действия. - Добавлен механизм автоматического [удаления связей сущности](../../admin/actions/overview/#удаление-связей-сущности) после успешного выполнения действия. +- Добавлена [синхронизация источников данных](../../admin/actions/overview/#синхронизация-источников-данных) после успешного выполнения действия: объект, созданный или удалённый действием, появляется в каталоге без ожидания синхронизации по расписанию. +- Добавлен параметр [«Владелец — инициатор запуска»](../../admin/actions/overview/#создание-сущностей): владельцем сущностей, созданных действием, становится пользователь, запустивший действие. +- Добавлены действия [GetGitlabPipeline](../../admin/actions/gitlab/getgitlabpipeline/) и [CreateGitlabMergeRequestReview](../../admin/actions/gitlab/creategitlabmergerequestreview/) — получение состояния пайплайна и создание merge request из существующей ветки. +- Добавлены действия [CreateRepositoryFromTemplatePack](../../admin/actions/gitlab/createrepositoryfromtemplatepack/) и [UpgradeRepositoryFromTemplatePack](../../admin/actions/gitlab/upgraderepositoryfromtemplatepack/) — создание и обновление репозитория из пакета шаблона. + +### Источники данных + +Добавлен источник данных [GitlabRepositoryActivity](../../admin/datasources/types/#gitlabrepositoryactivity): число открытых merge request, последний коммит и последний пайплайн проектов GitLab. ### Виджеты -Добавлен виджет [«История параметров»](../../admin/widgets/entities/property-history/), который строит график изменений параметров сущности за выбранный период. +- Добавлен виджет [«История параметров»](../../admin/widgets/entities/property-history/), который строит график изменений параметров сущности за выбранный период. +- В виджет [«GitLab. Запросы слияния»](../../admin/widgets/gitlab/merge-requests/) добавлены фильтры по состоянию с числом MR, фильтр по целевой ветке, создание MR, сведения о MR в раскрытой строке и причины, по которым MR нельзя слить. +- В виджете [«GitLab. Пайплайны»](../../admin/widgets/gitlab/pipelines/) этапы и задачи пайплайна отображаются в раскрытой строке, а журнал задачи — в панели задачи с последними строками и полным журналом. + +## Улучшения + +- В действиях [DeleteKubernetesResource](../../admin/actions/kubernetes/deletekubernetesresource/) и [GetKubernetesResource](../../admin/actions/kubernetes/getkubernetesresource/) добавлен параметр `ignore_not_found`: отсутствие объекта в кластере не считается ошибкой. +- Действие [StartGitlabPipeline](../../admin/actions/gitlab/startgitlabpipeline/) возвращает объект созданного пайплайна. +- Действие [Debug](../../admin/actions/debug/debug/) принимает нулевые `sleep_time` и `sleep_count`. +- Вебхук-действие с пустым телом отправляет запрос без тела, а при ответе с кодом ошибки [сохраняет тело ответа](../../admin/actions/overview/#формат-тела-запроса) в ответе действия и в тексте ошибки. +- [AI-ассистент](../../user/ai-assistant/#работа-с-ai-ассистентом) открывается кнопкой в верхней панели в перемещаемом окне с изменяемым размером; диалог сохраняется при закрытии окна. +- Наборы данных [«Kubernetes»](../../admin/datasets/#kubernetes), «Vault» и «GitLab» требуют URL внешней системы. В наборы данных [Deckhouse managed](../../admin/datasets/#deckhouse-managed-postgresql) добавлены параметры создания ресурса, действий, процессов и источника данных. +- [Ротация ключа шифрования](../../admin/security/encryption-key-rotation/) перешифровывает пароли подключений реестра шаблонов. +- Уведомления об ошибках показывают описание ошибки, полученное от портала. + +## Рекомендации по обновлению + +- Перед обновлением прикрепите дашборды, которые отображались на главной, к другой странице портала кнопкой «Прикрепить дашборд», например к странице «Каталог». +- Проверьте шаблоны действий, условий и виджетов на использование функций `env`, `expandenv` и `getHostByName` и на передачу `{{ .credentials.* }}` через переменные и параметры. +- После обновления настройте новую главную по [инструкции](../../admin/examples/home-quick-start/) и включите переключатель «Показывать главную» в разделе «Администрирование» → «Справочники» → «Правила маппинга». diff --git a/content/documentation/user/ai-assistant.ru.md b/content/documentation/user/ai-assistant.ru.md index 0cdc0782..350bc31b 100644 --- a/content/documentation/user/ai-assistant.ru.md +++ b/content/documentation/user/ai-assistant.ru.md @@ -156,11 +156,13 @@ OpenAI-совместимый чат: ## Работа с AI-ассистентом -Панель ассистента открывается справа; кнопка запуска — в правом нижнем углу экрана. +Окно «AI-ассистент» открывается кнопкой с подсказкой «AI-ассистент» в правой части верхней панели портала. Окно перемещается за заголовок и меняет размер за края и углы; положение и размер окна сохраняются в браузере. + +При закрытии окна диалог сохраняется: повторное открытие продолжает тот же чат. ### Выбор провайдера -Вверху панели чата — список провайдеров. Если доступен один провайдер, он выбирается автоматически. +Вверху окна — список провайдеров. Если доступен один провайдер, он выбирается автоматически. ### Чаты @@ -189,7 +191,7 @@ OpenAI-совместимый чат: AI-ассистент использует встроенные инструменты портала и инструменты из [MCP-коллекций](../mcp-management/#mcp-коллекции), к которым у пользователя есть доступ. -В панели чата раскройте «Доступные инструменты», чтобы посмотреть название, тип (`internal`, `external`, `custom`), аргументы и пример. Клик по примеру вставляет текст в поле ввода. В одном запросе модель может вызвать несколько инструментов. +В окне ассистента раскройте «Доступные инструменты», чтобы посмотреть название, тип (`internal`, `external`, `custom`), аргументы и пример. Клик по примеру вставляет текст в поле ввода. В одном запросе модель может вызвать несколько инструментов. - Встроенные инструменты (`internal`) и их параметры описаны в [документации MCP-сервера](../mcp-server/). - Подключение MCP-серверов, пользовательских MCP-инструментов и настройка коллекций — в разделе [«Управление MCP»](../mcp-management/). diff --git a/content/documentation/user/home/_index.ru.md b/content/documentation/user/home/_index.ru.md new file mode 100644 index 00000000..c0d75178 --- /dev/null +++ b/content/documentation/user/home/_index.ru.md @@ -0,0 +1,4 @@ +--- +title: Главная +weight: 25 +--- diff --git a/content/documentation/user/home/architecture.ru.md b/content/documentation/user/home/architecture.ru.md new file mode 100644 index 00000000..360a340d --- /dev/null +++ b/content/documentation/user/home/architecture.ru.md @@ -0,0 +1,82 @@ +--- +title: Архитектура +weight: 30 +description: Разделы главной DDP группы «Архитектура» — системы и их зависимости, интеграции, диаграммы, кластеры и сети, гайды «Как работает платформа». +--- + +Разделы группы «Архитектура» показывают системы, связи между ними и инфраструктуру, на которой они размещены. Разделы группы предназначены для просмотра и не запускают процессы. + +## Системы + +Раздел «Системы» показывает системы, сгруппированные по доменам, и сведения о выбранной системе. + +### Дерево доменов + +В левой панели «Домены» системы сгруппированы по доменам. Домены и системы отсортированы по названию. +Поле «Поиск по системе или домену» фильтрует дерево по названию домена или системы. + +Системы без домена в дереве не отображаются. + +При открытии раздела выбрана первая по названию система. Чтобы выбрать другую систему, нажмите на неё в дереве. + +### Вкладки системы + +Сведения о выбранной системе распределены по вкладкам. При выборе системы открывается вкладка «Зависимости». + +| Вкладка | Содержимое | +| --- | --- | +| «Справка» | «Домен», «Владелец», «Команда владелец», «Жизненный цикл», «Состояние» | +| «Зависимости» | Граф зависимостей системы и таблица интеграций с колонками «Клиент», «Сервер», «Интеграция» | +| «Микросервисы» | Микросервисы системы: «Микросервис», «Язык», «Состояние» | +| «Общесистемные ресурсы» | Общие ресурсы системы: «Ресурс», «Тип» | +| «Окружения» | Окружения, на которых развёрнуты микросервисы системы: «Название», «Тип», «Кластер» | + +Поле «Состояние» показывает результат проверок статуса сущности: «В норме», «С проблемами», «Ошибка» или «Неизвестно». + +### Граф зависимостей + +Граф зависимостей показывает выбранную систему и системы, с которыми она связана интеграциями. Системы связаны друг с другом только через интеграции: система-клиент обращается к системе-серверу через интеграцию. + +На линии между двумя системами отображаются названия интеграций. Если интеграций больше одной, остальные скрыты под тегом «+N»; наведите на тег, чтобы увидеть их список. Если системы обращаются друг к другу в обе стороны, линия отмечена стрелками с обоих концов. + +Нажмите на линию или название интеграции, чтобы открыть панель интеграции. В панели отображаются описание интеграции, системы «Клиент» и «Сервер», «Тип связи» и «Критичность». + +Если у системы нет интеграций, отображается сообщение «У выбранной системы нет зависимостей.». + +## Интеграции + +Раздел «Интеграции» показывает все интеграции между системами. + +В верхней части раздела отображаются показатели: + +- «Интеграции» — число интеграций; +- «Зависимости» — число пар систем «клиент — сервер», связанных интеграциями; +- «Критичные связи» — число интеграций с высокой критичностью. + +На вкладке «Таблица» интеграции перечислены с колонками «Интеграция», «Клиент», «Сервер», «Тип связи», «Критичность». Нажмите на строку, чтобы открыть панель интеграции. + +На вкладке «Граф» отображается граф зависимостей первой системы каталога. + +## Диаграммы + +Раздел «Диаграммы» показывает схемы системы в трёх видах. Вид выбирается переключателем: + +- «Зависимости» — граф зависимостей системы через интеграции; +- «Состав» — дерево системы с её микросервисами и общими ресурсами; +- «Развёртывание» — сводка по системе, её микросервисам и общим ресурсам. Систему выберите в списке «Система». + +Кнопка «Скачать диаграмму» сохраняет выбранную схему в текстовый файл. + +## Кластеры и сети + +Раздел «Кластеры и сети» показывает кластеры и окружения, размещённые в них. + +В верхней части раздела отображаются показатели «Кластеры» и «Окружения». Для каждого кластера отображается карточка с провайдером, названием, регионом и окружениями кластера. + +## Как работает платформа + +Раздел «Как работает платформа» содержит гайды по основным сценариям работы с порталом. Гайды сгруппированы по категориям; гайды без категории отображаются в группе «Без категории». + +Гайды фильтруются полем «Поиск по гайдам» и переключателем категорий. Переключатель категорий отображается, если категорий больше одной. + +В карточке гайда отображаются категория, дата обновления, название и описание. Кнопка «Открыть документацию» открывает документацию гайда, кнопка «Смотреть видео» — видео. diff --git a/content/documentation/user/home/deployment.ru.md b/content/documentation/user/home/deployment.ru.md new file mode 100644 index 00000000..7eecc998 --- /dev/null +++ b/content/documentation/user/home/deployment.ru.md @@ -0,0 +1,203 @@ +--- +title: Развёртывание и окружения +weight: 50 +description: Разделы главной DDP «Развертывание систем», «Заказ ресурсов», «Окружения» и «Потребление ресурсов» — схема развёртывания, развёртывание микросервисов, заказ и подключение общих ресурсов, создание окружений. +--- + +Разделы «Развертывание систем», «Заказ ресурсов», «Окружения» и «Потребление ресурсов» группы «Разработка» показывают, что и где развёрнуто, и запускают процессы развёртывания, заказа ресурсов и управления окружениями. + +Окружение на главной — это неймспейс Kubernetes. Окружения появляются на главной после синхронизации источника данных кластера. + +## Развертывание систем + +Раздел «Развертывание систем» показывает схему развёртывания системы на выбранном окружении: точки входа, развёртывания микросервисов и общие ресурсы, подключённые к ним. + +### Выбор системы и окружения + +Система выбирается в списке в заголовке раздела, окружение — в теге окружения рядом с ним. При открытии раздела выбраны первая по названию система и первое по названию окружение. + +Цвет тега окружения зависит от его типа или идентификатора: окружения `prod` — зелёные, `pre-prod` и `stag` — оранжевые, `dev`, `test`, `qa`, `sandbox` и `non-prod` — синие, остальные — серые. + +Выбранные система и окружение записываются в адрес страницы параметрами `system` и `env`. Ссылку с этими параметрами можно передать другому пользователю. + +### Схема развёртывания + +На вкладке «Схема развёртывания» объекты распределены по трём колонкам: + +| Колонка | Содержимое карточки | +| --- | --- | +| «Инфраструктура» | Ingress: название, микросервисы, «Хост», «Маршруты» | +| «Развертывания» | Развёртывание: название, тег образа, микросервис, «Реплики», «CPU request», «Memory request», «CPU limit», «Memory limit» | +| «Ресурсы данных» | Общий ресурс: название и тип | + +Линии на схеме показывают маршруты от Ingress к развёртываниям и подключения общих ресурсов к развёртываниям. + +На вкладке «Параметры» те же параметры развёртываний отображаются таблицей. + +Если для выбранных системы и окружения нет развёртываний, отображается сообщение «Схема развёртывания для выбранной пары система/окружение не найдена.». + +### Развёртывание микросервиса + +Кнопка «Развернуть микросервис» под колонкой «Развертывания» разворачивает микросервис выбранной системы на окружение. + +Чтобы развернуть микросервис: + +1. Нажмите «Развернуть микросервис». +1. В окне «Развернуть микросервис» выберите «Микросервис» и «Окружение». По умолчанию выбрано окружение, открытое на схеме. +1. Нажмите «Далее». +1. В окне «Запустить процесс» проверьте параметры и нажмите «Запустить». + +Для микросервиса, созданного из шаблона, запускается процесс развёртывания этого шаблона. Если процесс не настроен, в окне отображается сообщение «Для шаблона {template} не задан процесс развёртывания». + +Если развёртывание выполняется на другое окружение, схема переключается на него. Пока процесс выполняется, в колонке «Развертывания» отображается карточка микросервиса с подписью «создаётся». + +Кнопка «Развернуть микросервис» недоступна, если процессы развёртывания не настроены («Процессы развёртывания микросервиса не настроены») или у выбранной системы нет микросервисов («У выбранной системы нет микросервисов»). + +### Удаление микросервиса с окружения + +Значок корзины на карточке развёртывания удаляет микросервис с окружения. + +Нажмите значок корзины, проверьте параметры в окне «Запустить процесс» и нажмите «Запустить». Карточка отмечается индикатором, пока развёртывание не будет удалено. + +Удаление недоступно, если развёртывание не связано с микросервисом («Удаление недоступно: развёртывание не связано с микросервисом») или процесс удаления не настроен. + +### Подключение и отключение общего ресурса + +Общий ресурс подключается к развёртыванию перетаскиванием: секреты подключения ресурса доставляются в приложение. + +Чтобы подключить общий ресурс: + +1. Нажмите на точку слева на карточке общего ресурса и, удерживая кнопку мыши, перетащите линию на карточку развёртывания. Карточка развёртывания подсвечивается синим. +1. Отпустите кнопку мыши. +1. В окне «Запустить процесс» нажмите «Запустить». + +Чтобы отключить ресурс, перетащите линию от ресурса на развёртывание, к которому он уже подключён. Карточка развёртывания подсвечивается красным. + +Пока процесс выполняется, линия подключения отображается сразу, а после завершения процесса схема показывает фактическое состояние каталога. + +### Заказ и удаление ресурса + +Кнопка «Заказать ресурс» под колонкой «Ресурсы данных» открывает мастер заказа ресурса с окружением, выбранным на схеме. Мастер описан в разделе [«Заказ ресурса»](#заказ-ресурса). + +Значок корзины на карточке общего ресурса запускает процесс удаления ресурса. + +## Заказ ресурсов + +Раздел «Заказ ресурсов» предназначен для заказа managed-сервисов — баз данных, кешей, очередей — и получения реквизитов подключения в Vault. + +В заголовке раздела выберите систему, для которой заказывается ресурс. Кнопка «История заказов» переходит к списку недавних ресурсов. + +В верхней части раздела отображаются показатели: + +- «Процессы заказа» — число процессов заказа, доступных для запуска; +- «Выданные ресурсы» — число общих ресурсов в каталоге; +- «Типы ресурсов» — типы ресурсов, которые можно заказать. + +Карточки процессов заказа фильтруются полем «Поиск процесса» и переключателем типа ресурса. Карточки недоступны, пока не выбрана система. + +### Заказ ресурса + +Заказ ресурса выполняется в два шага: выбор сервиса и окружения, затем запуск процесса. + +Чтобы заказать ресурс: + +1. Выберите систему в заголовке раздела. +1. Нажмите «Заказать ресурс» или «Запустить» на карточке процесса. +1. В окне «Заказать ресурс» выберите «Сервис» — managed-сервис, который будет заказан, — и «Окружение», в котором будет размещён ресурс. +1. Нажмите «Далее». +1. В окне «Запустить процесс» проверьте параметры, например название ресурса, и нажмите «Запустить». + +Облачные ресурсы размещение в окружении игнорируют. + +Пока процесс выполняется, в списке «Недавние ресурсы» отображается строка заказываемого ресурса с подписью «создаётся». + +Реквизиты подключения к ресурсу записываются в Vault. Путь к реквизитам задаёт процесс заказа. + +### Недавние ресурсы + +В списке «Недавние ресурсы» отображаются общие ресурсы каталога, отсортированные по дате изменения: «Ресурс», «Тип», «Окружение», «Состояние». Ссылка «Все ресурсы» открывает ресурс общих ресурсов в каталоге. + +Кнопка «Удалить» в строке ресурса запускает процесс удаления. Кнопка недоступна, если для ресурса нет подходящего процесса удаления. + +## Окружения + +Раздел «Окружения» показывает окружения — неймспейсы Kubernetes — и позволяет создавать и удалять их. + +Под заголовком отображается число окружений: всего, постоянных и временных. Временным считается окружение с заданным TTL или с типом, содержащим `temp` или `preview`. + +Вкладки «Все», «Постоянные» и «Временные» фильтруют окружения по классу. Поле «Поиск по названию или кластеру» ищет по названию, кластеру, типу и домену. + +Колонки таблицы: + +| Колонка | Содержимое | +| --- | --- | +| «Название» | Название окружения, число развёрнутых микросервисов и систем | +| «Тип» | Тип окружения и тег «Помечено на удаление», если окружение помечено на удаление | +| «Кластер» | Кластер, в котором размещено окружение | +| «Домен» | Базовый домен окружения | +| «TTL» | Время жизни окружения, например `7d` | +| «Состояние» | Результат проверок статуса | + +Нажмите на строку, чтобы открыть карточку окружения. + +### Создание окружения + +Кнопка «Создать окружение» запускает процесс создания окружения. + +Чтобы создать окружение: + +1. Нажмите «Создать окружение». +1. В окне «Запустить процесс» заполните параметры процесса. Процесс из набора данных «Управление окружениями» запрашивает: + - «Идентификатор» — идентификатор окружения и имя неймспейса Kubernetes: строчные латинские буквы, цифры и дефис, до 63 символов; + - «TTL» — через какое время окружение будет удалено: «1 день», «3 дня», «7 дней», «14 дней» или «1 месяц». Оставьте пустым для постоянного окружения. +1. Нажмите «Запустить». + +Пока процесс выполняется, в начале таблицы отображается строка нового окружения с подписью «создаётся». Окружение появляется в таблице после синхронизации каталога. + +Кнопка «Создать окружение» недоступна, если процесс создания окружения не настроен («В наборе маппинга главной не задан процесс создания окружения.»). + +### Изменение домена окружения + +Домен окружения используется при развёртывании: например, адрес микросервиса строится как `<идентификатор микросервиса>.<домен окружения>`. + +Чтобы изменить домен: + +1. Откройте карточку окружения. +1. Нажмите значок карандаша в строке «Домен». +1. Введите домен, например `stage.example.com`, и нажмите значок сохранения или клавишу Enter. Чтобы отменить изменение, нажмите значок отмены или клавишу Esc. + +Пустое значение удаляет домен. После сохранения отображается уведомление «Домен окружения обновлён». + +Для изменения домена требуется право на изменение сущности окружения. Без него отображается ошибка «Запрещено политиками доступа». + +### Удаление окружения + +Кнопка «Удалить окружение» находится в блоке «Опасная зона» карточки окружения. + +{{< alert level="danger" >}} +Удаление окружения удаляет все развёртывания в нём. Действие необратимо. +{{< /alert >}} + +Нажмите «Удалить окружение», проверьте параметры в окне «Запустить процесс» и нажмите «Запустить». Строка окружения отмечается индикатором, пока окружение не будет удалено из каталога. + +## Потребление ресурсов + +Раздел «Потребление ресурсов» показывает запросы и лимиты CPU и памяти по развёртываниям. Раздел предназначен для просмотра и не запускает процессы. + +В верхней части раздела отображаются показатели для выбранного окружения: + +| Показатель | Значение | +| --- | --- | +| «CPU requests» | Сумма запросов CPU с учётом реплик и доля от лимитов | +| «Memory requests» | Сумма запросов памяти с учётом реплик и доля от лимитов | +| «Развёртывания и реплики» | Число развёртываний и реплик, средние запросы на реплику | +| «Без лимитов» | Число развёртываний, у которых не заданы лимиты CPU или памяти | + +Доля запросов от лимитов выделяется оранжевым от 65% и красным от 85%. Кнопка «Показать в таблице» на показателе «Без лимитов» фильтрует таблицу по развёртываниям без лимитов. + +Блок «Распределение по системам» показывает потребление CPU или памяти по системам. Нажмите на систему, чтобы отфильтровать по ней таблицу. + +Таблица развёртываний фильтруется полем «Поиск по развёртыванию», переключателем окружений, списком «Все системы» и переключателем «Только без лимитов». Колонки таблицы: «Развёртывание», «Система», «Окружение», «Реплики», «CPU итого», «Память итого», «Доля CPU». +Раскройте строку, чтобы увидеть запросы и лимиты на реплику, суммарные лимиты, кластер и версию образа. + +Если у развёртывания не задано число реплик, оно считается равным 1. diff --git a/content/documentation/user/home/microservices.ru.md b/content/documentation/user/home/microservices.ru.md new file mode 100644 index 00000000..7da948a3 --- /dev/null +++ b/content/documentation/user/home/microservices.ru.md @@ -0,0 +1,147 @@ +--- +title: Микросервисы +weight: 40 +description: Создание микросервиса из шаблона на главной DDP, список микросервисов, карточка микросервиса и обновление микросервиса до новой версии шаблона. +--- + +Разделы «Создать микросервис» и «Микросервисы» группы «Разработка» предназначены для создания микросервисов из шаблонов и работы с ними. +Микросервис создаётся из шаблона: портал создаёт репозиторий в GitLab, записывает в него файлы шаблона и регистрирует микросервис в каталоге. + +## Создание микросервиса + +Мастер создания микросервиса открывается в разделе «Создать микросервис» или кнопкой «Создать микросервис» в разделе «Микросервисы». Мастер состоит из трёх шагов: «Шаблон», «Сервис» и «Параметры». + +Для создания микросервиса требуется разрешение `read:template-packs`. Без него отображается сообщение «Недостаточно прав для просмотра галереи шаблонов.». + +### Шаг «Шаблон» + +На шаге «Шаблон» выберите шаблон в галерее. Для каждого шаблона отображаются язык, последняя версия, теги и описание; если шаблоны получены из нескольких реестров, отображается и реестр шаблона. + +Галерея фильтруется полем «Поиск по названию, языку или тегам», переключателем языков и списком «Источник». Переключатель языков отображается, если в галерее шаблоны на разных языках, а список «Источник» — если шаблоны получены из нескольких реестров. + +Выбранный шаблон и его версия отображаются в нижней части шага. Нажмите «Далее». + +Если галерея пуста, отображается сообщение «Шаблонов пока нет. Попросите администратора настроить реестр шаблонов.». + +### Шаг «Сервис» + +На шаге «Сервис» заполните сведения о микросервисе: + +| Поле | Описание | +| --- | --- | +| «Название микросервиса» | Отображаемое название микросервиса. От 3 до 64 символов | +| «Идентификатор микросервиса» | Идентификатор в каталоге и название репозитория. От 3 до 64 символов: строчные латинские буквы, цифры и дефис, не в начале и не в конце. Заполняется по названию, пока вы не измените его вручную | +| «Версия шаблона» | По умолчанию выбрана последняя доступная версия, отмеченная как «(рекомендуемая)» | +| «Система» | Система, в состав которой войдёт микросервис | +| «Пространство в системе контроля версий» | Группа GitLab, в которой будет создан репозиторий микросервиса | +| «Описание репозитория» | Описание проекта в GitLab. Необязательное поле | + +В панели «Что будет создано» отображаются выбранные шаблон, версия, система, название, пространство и идентификатор. Нажмите «Далее». + +Кнопка «Далее» недоступна, пока не заполнены обязательные поля. Если у выбранного пространства не задан идентификатор группы GitLab, кнопка также недоступна: обратитесь к администратору портала. + +Если в каталоге нет систем, отображается сообщение «Нет доступных систем. Сначала создайте систему.». + +### Шаг «Параметры» + +На шаге «Параметры» заполните параметры шаблона. Состав параметров задаёт автор шаблона: например, порт приложения, тип базы данных, включение метрик. +Параметры, которые совпадают с данными шага «Сервис», например идентификатор микросервиса, в форме не отображаются и заполняются автоматически. + +Параметры сложной структуры вводятся в формате JSON. При ошибке в JSON отображается сообщение «Некорректный JSON: {details}». + +Если у шаблона нет параметров, отображается сообщение «У выбранного шаблона нет параметров.». + +Нажмите «Создать микросервис». Откроется окно «Запустить процесс» с процессом создания; нажмите «Запустить». + +Если для шаблона не настроен процесс создания, отображается сообщение «Для шаблона {template} не задан процесс создания микросервиса», и кнопка «Создать микросервис» недоступна. Обратитесь к администратору портала. + +### Результат создания + +После запуска процесса мастер возвращается к первому шагу. Ход выполнения отображается в строке «Выполняются процессы» и в панели «Мои активности». + +Процесс создания из набора данных «Реестр шаблонов микросервисов» выполняет следующие задачи: + +1. Создаёт проект в выбранной группе GitLab. +1. Записывает в репозиторий файлы шаблона и файл `.ddp/template.lock.yaml` с версией шаблона и значениями параметров. +1. Регистрирует микросервис в каталоге и связывает его с системой. + +Микросервис появляется в разделе «Микросервисы» после завершения процесса. + +Не удаляйте файл `.ddp/template.lock.yaml` из репозитория: по нему портал обновляет микросервис до новых версий шаблона. + +## Список микросервисов + +Раздел «Микросервисы» показывает все микросервисы каталога. + +В верхней части раздела отображаются показатели: + +- «Всего микросервисов» — число микросервисов в каталоге; +- «Связанные системы» — число систем, в которые входят микросервисы; +- «Проблемные» — число микросервисов, у которых проверка статуса вернула «С проблемами» или «Ошибка». + +Таблица фильтруется полем «Поиск по имени или системе» и списками «Все домены» и «Все языки». Кнопка «Сбросить» очищает фильтры. + +Колонки таблицы: + +| Колонка | Содержимое | +| --- | --- | +| «Микросервис» | Название микросервиса и ссылка на репозиторий | +| «Владелец» | Владелец сущности микросервиса | +| «Домен» | Домен системы, в которую входит микросервис | +| «Система» | Системы, в которые входит микросервис | +| «Язык» | Язык микросервиса | +| «Окружения» | Окружения, на которых развёрнут микросервис | +| «Состояние» | Результат проверок статуса | + +В таблице отображается 10 микросервисов на странице. Нажмите на строку, чтобы открыть карточку микросервиса. + +## Карточка микросервиса + +Карточка микросервиса открывается в правой панели. В заголовке отображаются название, состояние, домен и язык микросервиса. + +### Вкладка «Справка» + +На вкладке «Справка» отображаются сведения о микросервисе: + +| Поле | Содержимое | +| --- | --- | +| «Репозиторий» | Ссылка на репозиторий | +| «Последняя поставка» | Ветка, коммит, сообщение и автор последнего коммита. Если данные ещё не получены, — «Ещё не синхронизировано» | +| «Шаблон» | Идентификатор шаблона, из которого создан микросервис, или «Нет» | +| «Версия» | Текущая версия шаблона | +| «Владелец», «Команда владелец» | Владелец и команда-владелец сущности | +| «Системы» | Системы микросервиса | +| «Окружения» | Окружения, кластеры и версии образа на каждом окружении | +| «Общие ресурсы» | Общие ресурсы, подключённые к развёртываниям микросервиса | + +Ниже отображаются показатели «Открытые MR» и «Последний пайплайн» со статусом и ссылкой на пайплайн. + +### Вкладки «Пайплайны» и «MRs» + +На вкладках «Пайплайны» и «MRs» отображаются виджеты, которые администратор настроил для карточки микросервиса, например пайплайны и merge request репозитория GitLab. +Если виджет не настроен, на вкладке отображается сообщение «Раздел пока недоступен». + +Вкладки «Изменения», «Окружения» и «Квоты» находятся в разработке. + +## Обновление из шаблона + +Когда выходит новая версия шаблона, из которого создан микросервис, на вкладке «Справка» карточки микросервиса отображается блок «Доступна версия {version}» с кнопкой «Обновить». + +Чтобы обновить микросервис до новой версии шаблона: + +1. Откройте карточку микросервиса и нажмите «Обновить». +1. В окне «Запустить процесс» нажмите «Запустить». +1. Дождитесь завершения процесса. Процесс создаёт в репозитории ветку `ddp/template-upgrade-<версия>` с изменениями шаблона и открывает merge request. +1. Проверьте изменения в merge request и примите его в GitLab. + +После принятия merge request версия в поле «Версия» обновляется в течение нескольких минут, и блок «Доступна версия» исчезает. + +Обновление изменяет только файлы, которые автор шаблона отметил как управляемые шаблоном, и не удаляет файлы из репозитория. Какие файлы изменяются, зависит от стратегии обновления шаблона. + +Кнопка «Обновить» недоступна, если: + +- у вас нет прав на запуск процессов для микросервиса — «Недостаточно прав для запуска процессов на этой сущности.»; +- обновление уже выполняется — «Процесс обновления шаблона уже выполняется для этого сервиса.»; +- для шаблона не настроен процесс обновления — «Для шаблона {template} не задан процесс обновления. Задайте его в правилах маппинга главной, в действиях по шаблонам.». + +Если для микросервиса включено автоматическое обновление, портал сам открывает merge request после выхода новой версии шаблона. Настройка автоматического обновления описана в разделе [«Обновление из шаблона»](../../admin/templates/updates/#автоматическое-обновление) руководства администратора. diff --git a/content/documentation/user/home/overview.ru.md b/content/documentation/user/home/overview.ru.md new file mode 100644 index 00000000..c36ef972 --- /dev/null +++ b/content/documentation/user/home/overview.ru.md @@ -0,0 +1,99 @@ +--- +title: Обзор +weight: 10 +description: Главная страница DDP — разделы и навигация, сообщения при отсутствии данных, запуск процессов и отслеживание их выполнения. +--- + +Главная — рабочее пространство разработчиков и владельцев систем. На главной собраны команды, системы и их интеграции, микросервисы, окружения, развёртывания и общие ресурсы. +С главной создаются микросервисы из шаблонов, микросервисы разворачиваются на окружения, заказываются ресурсы и создаются окружения. + +{{< alert level="warning" >}} +Главная — экспериментальная функциональность. Состав разделов и их поведение могут измениться в следующих выпусках. +{{< /alert >}} + +Главная открывается вкладкой «Главная» в верхней панели портала. Если вкладки нет, главная выключена администратором портала; при переходе по адресу страницы главной открывается каталог. + +Главная показывает данные каталога. Какие ресурсы каталога отображаются на главной и какие процессы запускаются её кнопками, задаёт администратор портала в [правилах маппинга](../../admin/home/mapping/). + +## Разделы + +Разделы главной сгруппированы в боковом меню. Группа раскрывается нажатием на стрелку, нажатие на название группы открывает её первый раздел. При открытии главной открывается раздел «Команды». + +| Группа | Раздел | Назначение | +| --- | --- | --- | +| «Организация» | [«Команды»](teams/) | Команды портала, их участники, системы и микросервисы | +| «Архитектура» | [«Системы»](architecture/#системы) | Системы по доменам, их зависимости, микросервисы, общие ресурсы и окружения | +| «Архитектура» | [«Интеграции»](architecture/#интеграции) | Интеграции между системами | +| «Архитектура» | [«Диаграммы»](architecture/#диаграммы) | Схемы зависимостей, состава и развёртывания системы | +| «Архитектура» | [«Кластеры и сети»](architecture/#кластеры-и-сети) | Кластеры и размещённые в них окружения | +| «Архитектура» | [«Как работает платформа»](architecture/#как-работает-платформа) | Гайды по сценариям работы с порталом | +| «Разработка» | [«Создать микросервис»](microservices/#создание-микросервиса) | Создание микросервиса из шаблона | +| «Разработка» | [«Микросервисы»](microservices/#список-микросервисов) | Список микросервисов, карточка микросервиса, обновление из шаблона | +| «Разработка» | [«Развертывание систем»](deployment/#развертывание-систем) | Схема развёртывания системы на окружении, развёртывание микросервисов, подключение ресурсов | +| «Разработка» | [«Заказ ресурсов»](deployment/#заказ-ресурсов) | Заказ и удаление общих ресурсов | +| «Разработка» | [«Окружения»](deployment/#окружения) | Создание и удаление окружений, домен окружения | +| «Разработка» | [«Потребление ресурсов»](deployment/#потребление-ресурсов) | Запросы и лимиты CPU и памяти по развёртываниям | + +Разделы с меткой «TBD» в меню находятся в разработке. При открытии такого раздела отображается сообщение «Раздел пока недоступен». + +## Если данных нет + +Если в разделе нет данных, вместо содержимого отображается одно из сообщений: + +| Сообщение | Причина | +| --- | --- | +| «Настройте правила маппинга или примените набор данных «Каноничная архитектура»» | Ресурс для раздела не настроен в правилах маппинга, не удалось загрузить сущности или у вас нет прав на просмотр сущностей этого ресурса | +| «Сущностей пока нет. Создайте их в каталоге или синхронизируйте через datasource.» | Ресурс настроен, но в нём нет сущностей | +| «Раздел пока недоступен» | Раздел находится в разработке, или для вкладки не настроен виджет | + +Если сообщение о правилах маппинга отображается только у вас, запросите у администратора портала доступ к сущностям ресурса. + +## Запуск процессов + +Кнопки главной — «Создать окружение», «Развернуть микросервис», «Заказать ресурс» и другие — запускают процессы каталога. Перед запуском открывается окно «Запустить процесс». + +Чтобы запустить процесс: + +1. Если в окне есть список процессов, выберите процесс. Если процесс один, он выбран автоматически. +1. Заполните параметры процесса. По умолчанию отображаются только важные параметры; чтобы увидеть все параметры и задачи процесса, нажмите «Все параметры процесса». +1. Нажмите «Запустить». + +Если параметры заполнять не нужно, в окне отображается сообщение «Для запуска этого процесса не нужно заполнять параметры — нажмите «Запустить»». + +После запуска отображается уведомление «Процесс "{name}" запущен». + +Процесс выполняет действия с вашими учётными данными. Если процесс завершается ошибкой доступа к внешней системе, проверьте учётные данные в [профиле пользователя](../credentials/). + +Если процесс не запускается, отображается одна из ошибок: + +- «Запрещено политиками доступа» — у вас нет прав на запуск процесса; +- «Заполните все обязательные параметры процесса» — не заполнены обязательные параметры; +- «Не удалось запустить процесс» — обязательный параметр процесса оказался пустым после подстановки значений. + +## Отслеживание выполнения + +Главная показывает состояние процессов, пока они выполняются. Уведомление о завершении процесса не отображается. + +Во время выполнения процесса: + +- в верхней части главной отображается строка «Выполняются процессы: {count}». Строка «Ожидают согласования: {count}» показывает процессы, которые ждут согласования, а строка «Запустили: {initiators}» — процессы, запущенные другими пользователями; +- строка или карточка объекта, над которым выполняется процесс, отмечается индикатором и подписью «выполняется». Кнопки действий объекта недоступны до завершения процесса; +- для создаваемого объекта отображается временная строка или карточка с подписью «создаётся». + +Состояние процессов сохраняется после перезагрузки страницы и видно другим пользователям. + +Итог выполнения процесса — успех или ошибка — отображается в панели «Мои активности» на вкладке «Процессы». Панель открывается значком часов в верхней панели портала; пока у вас выполняются процессы, значок заменяется индикатором. + +После завершения процесса раздел загружает данные заново. Если объект создаётся синхронизацией источника данных, он появляется на главной после следующей синхронизации. + +## Первоначальная настройка + +Пользователи с разрешением `apply:seeds` видят в верхней части главной баннер «Платформа готова к настройке». Кнопка «Запустить» открывает мастер первоначальной настройки, кнопка «Скрыть» скрывает баннер для всех пользователей. + +Мастер описан в разделе [«Первоначальная настройка»](../../admin/home/setup/) руководства администратора. + +## Настройка маппинга с главной + +Пользователи с разрешением `update:home-mapping-sets` видят в нижней части бокового меню переключатель «Настроить маппинг». Когда переключатель включён, рядом с разделами появляется значок настройки правил маппинга раздела. + +Порядок настройки описан в разделе [«Правила маппинга»](../../admin/home/mapping/#настройка-маппинга-с-главной). diff --git a/content/documentation/user/home/teams.ru.md b/content/documentation/user/home/teams.ru.md new file mode 100644 index 00000000..34b4296e --- /dev/null +++ b/content/documentation/user/home/teams.ru.md @@ -0,0 +1,41 @@ +--- +title: Команды +weight: 20 +description: Раздел главной DDP «Команды» — показатели команд, карта команд и профиль команды с её системами и микросервисами. +--- + +Раздел «Команды» показывает команды портала, их участников и системы и микросервисы, которыми владеют команды. Раздел открывается при переходе на главную. + +Команды и их участники задаются в разделе «Администрирование». Подробнее — в разделе [«Команды и пользователи»](../teams-users/). Системы и микросервисы команды определяются по полю «Команда владелец» их сущностей в каталоге. + +## Показатели + +В верхней части раздела отображаются показатели: + +| Показатель | Значение | +| --- | --- | +| «Команды» | Число команд портала | +| «Участники команд» | Число уникальных пользователей во всех командах | +| «Средний размер» | Среднее число участников в команде | +| «Пустые команды» | Число команд без участников | + +## Карта команд + +Карта команд показывает все команды портала. Для каждой команды отображаются аватар, название, идентификатор и число участников. + +Карта масштабируется колесом мыши и кнопками «Уменьшить», «Увеличить» и «Показать весь граф в окне». Чтобы сдвинуть карту, перетащите её фон. + +Если команд нет, отображается сообщение «Команд пока нет. Создайте команды в разделе «Администрирование», чтобы увидеть их здесь.». + +## Профиль команды + +Профиль открывается в правой панели при нажатии на команду на карте. При открытии раздела выбрана первая по названию команда. + +В профиле отображаются: + +- описание команды и участники; +- «Идентификатор», «Участники», «Дата создания», «Дата обновления»; +- «Системы» — системы, у которых команда указана в поле «Команда владелец»; +- «Микросервисы» — микросервисы, у которых команда указана в поле «Команда владелец», и микросервисы систем команды. + +Чтобы закрыть профиль, нажмите на выбранную команду ещё раз, на пустую область карты или на кнопку закрытия панели. diff --git a/content/documentation/user/interface.ru.md b/content/documentation/user/interface.ru.md index 32df2b5a..6be3c4cc 100644 --- a/content/documentation/user/interface.ru.md +++ b/content/documentation/user/interface.ru.md @@ -5,12 +5,19 @@ weight: 20 Интерфейс Deckhouse Development Portal (DDP, портал) состоит из следующих разделов: -- «Главная» — стартовая страница портала. Здесь можно размещать один или несколько дашбордов с виджетами. +- «Главная» — рабочее пространство разработчиков: команды, системы, микросервисы, окружения, развёртывание и заказ ресурсов. Вкладка отображается, если главная включена администратором. Подробнее — в разделе [«Главная»](home/overview/). - «Каталог» — сервисный каталог для просмотра ресурсов, сущностей и связей, а также для запуска действий и сценариев. - «Самообслуживание» — раздел для настройки источников данных, действий, вебхуков, автоматизаций, сценариев, дашбордов и виджетов. Доступ к разделу может быть ограничен ролевой моделью. - «AI» — раздел для настройки MCP-серверов, пользовательских инструментов и коллекций инструментов. Подробнее — в разделе [«Управление MCP»](mcp-management/). Доступ к разделу может быть ограничен ролевой моделью. - «Администрирование» — раздел для управления командами, пользователями, политиками доступа и учётными данными. Доступ к разделу может быть ограничен ролевой моделью. +## Верхняя панель + +В правой части верхней панели портала расположены кнопки: + +- «AI-ассистент» — открывает окно [AI-ассистента](ai-assistant/#работа-с-ai-ассистентом); +- «Мои активности» — открывает панель с запусками ваших действий и процессов. Пока у вас выполняются процессы, значок кнопки заменяется индикатором, а на вкладке «Процессы» отображается число выполняющихся процессов. + ## Глобальный поиск В верхней части боковой панели раздела «Каталог» доступно поле «Поиск». Оно позволяет быстро находить сущности по всему порталу. diff --git a/content/documentation/user/properties.ru.md b/content/documentation/user/properties.ru.md index 84bf50c7..0a0b8f6c 100644 --- a/content/documentation/user/properties.ru.md +++ b/content/documentation/user/properties.ru.md @@ -53,6 +53,7 @@ title: Параметры * «Редактируемый параметр» — для каждого параметра можно настроить разрешение либо запрет редактирования пользователем. В случае запрета редактирования пользователь при запуске действий или сценариев не сможет изменить значение параметра, то есть всегда будет использоваться значение по умолчанию. * «Обязательный параметр» — каждый параметр может быть обязательным либо опциональным. Значение обязательного параметра не может быть пустым при запуске действий или сценариев. При этом значение опционального параметра может оставаться пустым без влияния на работоспособность действия. * «Скрытый параметр» — скрытый параметр не отображается в таблицах и карточках сущностей, а также при запуске действий и сценариев. +* «Показывать в упрощённой форме» — параметр отображается в упрощённой форме окна запуска процесса. Остальные параметры сохраняют значения по умолчанию и передаются при запуске. Обязательные параметры без значения отображаются в упрощённой форме независимо от этого признака. Признак доступен только для параметров процесса. ## Типы параметров diff --git a/content/documentation/user/templating.ru.md b/content/documentation/user/templating.ru.md index 57a351aa..77af6ccb 100644 --- a/content/documentation/user/templating.ru.md +++ b/content/documentation/user/templating.ru.md @@ -11,7 +11,7 @@ Deckhouse Development Portal (портал) поддерживает шабло * Функции библиотеки [sprig](https://masterminds.github.io/sprig/). {{< alert level="info" >}} -Функции библиотеки [sprig](https://masterminds.github.io/sprig/) не поддерживаются в источниках данных. +Функции библиотеки [sprig](https://masterminds.github.io/sprig/) не поддерживаются в источниках данных. Функции `env`, `expandenv` и `getHostByName` недоступны во всех шаблонах портала. {{< /alert >}} ## Встроенные функции @@ -490,6 +490,8 @@ Deckhouse Development Portal (портал) поддерживает шабло {{ .credentials.bearerToken }} // Bearer-токен ``` +Обращение к `.credentials` работает, только если оно записано непосредственно в теле или конфигурации объекта. Если выражение `{{ .credentials.* }}` приходит в подставляемом значении — глобальной или командной переменной, параметре, контексте запуска, ответе действия, — портал удаляет его из значения. + ## Сущность Сущность доступна в виджетах с областью видимости `Resource`, действиях, процессах и сценариях через контекст `{{ .entity.* }}`. @@ -565,6 +567,38 @@ Deckhouse Development Portal (портал) поддерживает шабло {{ .process.environment }} // Окружение из параметров процесса ``` +## Контекст запуска процесса + +Контекст запуска содержит данные объектов, выбранных при запуске процесса с главной: систему, микросервис, окружение, развёртывание, шаблон. Контекст доступен в значениях по умолчанию параметров процесса, в телах действий, в правилах создания и обновления сущностей, в условиях шлюзов и циклах. + +Чтобы получить значение из контекста, используйте конструкцию: + +```go +{{ .context. }} +``` + +где `key` — путь к значению в контексте, например `environment.slug`. + +Сущности передаются в контексте в формате с полями `name`, `slug`, `uuid` и `properties`. Ключи `properties` — идентификаторы параметров сущности в каталоге. + +Примеры использования: + +```go +{{ .context.environment.slug }} // Идентификатор окружения, выбранного при запуске +{{ .context.microservice.name }} // Название микросервиса +{{ .context.environment.properties.domain }} // Параметр domain окружения +``` + +Поведение при отсутствии ключа зависит от места шаблона: + +- в значениях параметров процесса отсутствующий ключ подставляется как пустая строка. Если обязательный параметр после подстановки пуст, процесс не запускается; +- в телах действий, условиях шлюзов и циклах отсутствующий ключ завершает шаг ошибкой; +- если контекст пуст, например процесс запущен из каталога, выражение `{{ .context.* }}` в теле действия не подставляется и остаётся в тексте как есть. + +Чтобы процесс работал и при запуске из каталога, задавайте значения из контекста в параметрах процесса и используйте в действиях параметры процесса: `{{ .process. }}`. + +Состав контекста для каждого сценария главной описан в разделе [«Процессы главной»](../admin/home/processes/#сущность-и-контекст-по-сценариям). + ## Параметры сценария Для каждого сценария доступно задание общих параметров, значения которых могут быть использованы во всех действиях, входящих в сценарий. From f99c86d3dbe38ebd30fda6c560dd868d62a5d0f7 Mon Sep 17 00:00:00 2001 From: Nikita Velgin Date: Thu, 1 Oct 2026 10:18:25 +0300 Subject: [PATCH 2/2] fixes --- content/documentation/release-notes/v1.6.0.ru.md | 1 - 1 file changed, 1 deletion(-) diff --git a/content/documentation/release-notes/v1.6.0.ru.md b/content/documentation/release-notes/v1.6.0.ru.md index 7a4ff839..b6f572eb 100644 --- a/content/documentation/release-notes/v1.6.0.ru.md +++ b/content/documentation/release-notes/v1.6.0.ru.md @@ -59,7 +59,6 @@ description: Заметки о выпуске v1.6.0 — управление MC ### Наборы данных -- Добавлен [набор данных Yandex Cloud](../../admin/datasets/#yandex-cloud) для подключения к API Yandex Cloud. - Добавлен [набор данных Vault](../../admin/datasets/#vault) для подключения к API HashiCorp Vault. - Добавлен [набор данных Deckhouse managed PostgreSQL](../../admin/datasets/#deckhouse-managed-postgresql) для развёртывания managed PostgreSQL в Deckhouse Platform. - Добавлен [набор данных Deckhouse managed Valkey](../../admin/datasets/#deckhouse-managed-valkey) для развёртывания managed Valkey в Deckhouse Platform.