Правила маппинга сопоставляют понятиям главной ресурсы, связи, параметры, процессы и виджеты каталога. Правила хранятся в наборах маппинга главной; главная использует набор по умолчанию. Как главная выбирает набор, описано в разделе «Обзор».
Страница «Правила маппинга»
Наборы маппинга находятся в разделе «Администрирование» → «Справочники» → «Правила маппинга».
На панели над таблицей расположены:
- переключатель «Показывать главную» — включает и выключает главную для всех пользователей;
- кнопка «Создать» — открывает форму нового набора;
- поле «Поиск» — фильтрует наборы по названию и идентификатору.
В таблице наборов отображаются следующие колонки:
| Колонка | Содержимое |
|---|---|
| «Название» | Название набора |
| «Идентификатор» | Идентификатор набора |
| «По умолчанию для главной» | Переключатель набора по умолчанию. У текущего набора по умолчанию переключатель недоступен: чтобы сменить набор, включите переключатель у другого набора |
| «Ресурсы» | Число сопоставленных ролей ресурсов |
| «Связи» | Число сопоставленных ролей связей |
| «Свойства» | Число сопоставленных ролей свойств |
| «Слоты действий» | Число заполненных слотов действий |
| «Шаблоны» | Число шаблонов, к которым привязан хотя бы один процесс |
| «Виджеты» | Число заполненных слотов виджетов |
Для удаления набора введите его идентификатор в окне подтверждения. Набор по умолчанию удалить нельзя.
Права на работу с наборами:
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_* записывает процесс создания микросервиса из шаблона; по ним работает обновление из шаблона.
| Роль | Название в форме | Назначение | Каноничный параметр |
|---|---|---|---|
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 | «Ветка по умолчанию микросервиса» | Ветка, в которую создаётся запрос на слияние с обновлением | 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 процесс удаления выбирается по параметрам конкретного ресурса в следующем порядке:
- Категория
<провайдер> <тип>, напримерDeckhouse PostgreSQL, по значениям ролейshared_providerиshared_kind. - Категория
<тип>, напримерPostgreSQL. - Категория
default.
Используется первая непустая категория. Если подходящих процессов нет, кнопка удаления ресурса недоступна.
Категория может содержать латинские буквы, цифры, пробел и символы _, ., -, начинается с буквы или цифры, длина — до 64 символов.
Действия по шаблонам
Действия по шаблонам задают процессы для микросервисов, созданных из конкретного шаблона реестра. Блок находится в области «Микросервисы».
Каждая строка блока соответствует одному шаблону. Для строки выберите шаблон в поле «Шаблон» и процессы действий:
| Действие | Слот | Где запускается |
|---|---|---|
| «Создать микросервис» | create_microservice | «Создать микросервис» → «Создать микросервис» |
| «Развернуть микросервис на окружение» | deploy_microservice | «Развертывание систем» → «Развернуть микросервис» |
| «Удалить микросервис с окружения» | delete_microservice | «Развертывание систем» → удаление развёртывания |
| «Обновить микросервис из шаблона» | upgrade_service_from_template | «Микросервисы» → карточка микросервиса → «Обновить», а также автоматическое обновление |
Для каждого действия шаблона выбирается один процесс. Шаблон можно добавить только в одну строку. Кнопка «Добавить шаблон» недоступна, пока шаблоны загружаются, пока у какой-либо строки не выбран шаблон или когда свободных шаблонов не осталось.
В списке «Шаблон» отображаются шаблоны из реестра шаблонов в последней доступной версии. Если шаблон, к которому привязаны процессы, больше не доступен в реестре, строка отмечается «нет в реестре». Если реестр пуст, отображается подсказка «В реестре шаблонов нет доступных шаблонов — синхронизируйте реестр, чтобы привязать действия».
Главная определяет шаблон микросервиса по роли свойства 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 |
Пример настройки — в разделе «Виджет на вкладке микросервиса».
Настройка маппинга с главной
Правила маппинга раздела можно изменить прямо на главной, не переходя в «Администрирование». Изменения сохраняются в набор маппинга по умолчанию.
Чтобы изменить правила раздела:
- В нижней части бокового меню главной включите переключатель «Настроить маппинг».
- Нажмите значок настройки рядом с названием раздела. Значок отображается у разделов, у которых есть области маппинга.
- В окне «Маппинг: {раздел}» измените поля областей раздела и нажмите «Сохранить».
После сохранения страницы главной загружают данные по новым правилам.
Переключатель «Настроить маппинг» доступен пользователям с разрешением update:home-mapping-sets.
Если набора маппинга нет, в окне отображается сообщение «Нет активного набора маппинга. Создайте его в Администрирование → Справочники → Правила маппинга.».
Проверки при сохранении
Перед сохранением форма проверяет значения полей и наличие выбранных объектов в каталоге.
| Сообщение | Причина |
|---|---|
| «Введите название» | Не заполнено поле «Название» |
| «Некоторые цели маппинга удалены из каталога. Обновите или очистите: {details}» | Ресурс, связь, параметр, процесс или виджет, выбранный в наборе, удалён из каталога. В {details} перечислены роли, например ресурс «system» |
| «Не удалось загрузить данные каталога для проверки маппинга. Попробуйте позже.» | Не удалось загрузить объекты каталога для проверки |
| «Исправьте ошибки в редакторе спецификации перед сохранением» | В редакторе спецификации есть ошибки |
| «Некорректный документ маппинга: {details}» | Значение не прошло проверку формата при сохранении раздела с главной. В {details} указан путь к значению |
| «Некорректный документ маппинга главной» | Документ набора не прошёл проверку портала |
| «Нельзя снять признак набора по умолчанию без назначения другого набора» | Выключен признак «По умолчанию для главной» у набора по умолчанию |
| «Нельзя удалить набор маппинга главной по умолчанию» | Попытка удалить набор по умолчанию |
Портал проверяет формат значений:
- идентификатор параметра — строчные латинские буквы, цифры,
_и-, до 64 символов; - идентификатор шаблона — строчные латинские буквы, цифры и символы
.,_,/,-, до 128 символов; - в слоте виджета — ровно один виджет.