Каталог

Каталог — это раздел DDP (портала), который содержит список всех ресурсов, их параметров и связей, а также предоставляет пользователям возможность запускать сценарии для сущностей ресурсов.

Наполнение каталога возможно в ручном режиме, либо автоматически с использованием источников данных или вебхуков.

Ресурсы

Ресурс — это шаблон или тип сущности в каталоге портала. Ресурс определяет структуру данных, параметры и свойства, которые будут наследовать все сущности данного типа. Например, ресурс «Репозитории GitLab» описывает структуру данных для репозиториев GitLab, а каждая конкретная сущность этого ресурса представляет отдельный репозиторий.

Основной принцип, заложенный в портал, заключается в том, что модель данных настраивается администратором портала. Администратор может самостоятельно создавать те ресурсы, которые ему необходимы.

Именование ресурсов

При именовании ресурсов следуйте правилам:

• «Название ресурса» может быть любым и не требует специальных префиксов или разделителей.
• «Идентификатор ресурса» должен быть уникальным в пределах всего портала.

Группировка ресурсов

Ресурсы в каталоге могут быть организованы в иерархическую структуру. Это позволяет логически группировать связанные ресурсы и улучшает навигацию в каталоге.

Для создания группы ресурсов необходимо:

• «Создать ресурсы» — создать все необходимые ресурсы, которые будут входить в группу. Например, ресурс «GitLab» может быть родительским для ресурсов «Репозитории», «Группы» и т. д.
• «Связать дочерние ресурсы с родительскими» — в нижней части сайдбара каталога включите переключатель «Изменить порядок ресурсов», затем перетащите дочерний ресурс на родительский. Дочерние ресурсы будут автоматически привязаны к родительскому и отобразятся в интерфейсе как вложенные элементы.
• «Настроить отображение» — в сайдбаре каталога родительские ресурсы отображаются с иконкой раскрытия/сворачивания, позволяющей показывать или скрывать дочерние элементы.

Отображение полного пути

В интерфейсе портала (селекторы ресурсов, теги, графы связей) отображается полный путь ресурса с цепочкой родительских ресурсов, разделённых символом /. Например, если ресурс «Репозитории» является дочерним для ресурса «GitLab», то в интерфейсе будет отображаться «GitLab / Репозитории».

Страница ресурса

По умолчанию после создания ресурса на его странице будет отображаться таблица с сущностями ресурса. При клике на сущность в таблице можно перейти на её страницу.

Под заголовком страницы выводится первый абзац описания ресурса. Кнопка «Создать» в заголовке открывает форму новой сущности.

Дашборды

В форме редактирования ресурса задаются три независимых варианта использования дашбордов:

• «Использовать дашборд на странице ресурса» — выбранный дашборд выводится на странице ресурса вместо таблицы или карточек сущностей.
• «Использовать дашборд на странице сущности» — выбранный дашборд выводится на странице сущности вместо встроенного содержимого вкладки «Обзор».
• «Дополнительные вкладки с дашбордами» — дополнительные дашборды в виде вкладок на странице каждой сущности ресурса. Порядок отображения дашбордов зависит от порядка в конфигурации ресурса, доступно изменение порядка перетаскиванием. Один и тот же дашборд нельзя добавить несколько раз для одного и того же ресурса.

Список сущностей

Когда на странице ресурса отображается список сущностей, над списком расположена панель с переключателем вида, поиском и фильтрами:

• переключатель «Вид» — отображение сущностей таблицей или карточками;
• поле поиска — поиск по названию, идентификатору, описанию, значениям параметров, владельцу и команде-владельцу сущностей;
• фильтр по статусу — «Все», «В норме», «С проблемами», «Ошибка» или «Неизвестно»;
• фильтр «Команда-владелец» — сущности выбранной команды; без выбора отображаются сущности любой команды.

Поиск и фильтры действуют в обоих видах. После перехода на страницу сущности и возврата к ресурсу они сохраняются до перезагрузки страницы. Выбранный вид сохраняется в браузере отдельно для каждого ресурса.

Если сущностей нет, отображается сообщение «Сущностей пока нет». Если сущности есть, но не подходят под поиск и фильтры, отображается сообщение «Ничего не найдено. Измените поиск или фильтры».

Таблица

В таблице отображаются столбцы:

• «Название» — название сущности со ссылкой на её страницу, идентификатор и начало описания;
• «Статус» — статус сущности и число пройденных проверок, например «Проверки: 2 из 3»;
• столбцы параметров — значения параметров ресурса, кроме скрытых;
• «Владелец» — пользователь и команда, владеющие сущностью;
• «Обновлено» — дата изменения сущности и дата её создания;
• «Действия» — кнопка «Открыть» и меню сущности.

Таблицу можно отсортировать по столбцам «Название» и «Обновлено». При выборе строк внизу страницы появляется панель с числом выбранных сущностей и кнопкой «Удалить» для массового удаления.

Карточки

Каждая карточка содержит статус сущности с результатом проверок, название, идентификатор, описание, значения параметров, владельца и дату изменения. На карточке отображаются первые шесть параметров ресурса, кроме скрытых. Остальные открываются по ссылке «Ещё N параметров», которая ведёт на страницу сущности.

Нажатие на карточку открывает страницу сущности; с зажатой клавишей Ctrl (⌘ в macOS) страница открывается в новой вкладке браузера. Следующие карточки подгружаются при прокрутке страницы.

Связи между ресурсами

Каждый ресурс может быть связан с другим ресурсом или сам с собой двусторонней связью. Связи настраиваются администратором портала. После настройки связей для ресурса каждая сущность данного ресурса может быть связана с одной либо несколькими сущностями другого ресурса.

Допускается создание как вертикальных связей (сущность из одного ресурса связывается с сущностью из другого ресурса), так и горизонтальных (связываются сущности в рамках одного ресурса).

У каждой связи можно указать параметры родительского и дочернего ресурса, через которые будут связаны сущности. Данные параметры будут отображаться на графе связей при нажатии на соединительную линию между карточками ресурсов или сущностей.

Сущности

Сущность — это конкретная единица каждого ресурса. Например, если ресурс называется «Группы» и является дочерним для ресурса «GitLab», то каждая группа в GitLab, зарегистрированная в портале, является сущностью этого ресурса.

Сущности наследуют параметры ресурсов, при этом возможно задание параметров отдельно для каждой сущности.

Именование сущностей

При именовании сущностей следуйте правилам:

• «Название сущности» может быть любым и не требует специальных префиксов или разделителей.
• «Идентификатор сущности» должен быть уникальным в пределах ресурса.

Создание и редактирование сущности

Чтобы создать сущность, на странице ресурса нажмите «Создать». Чтобы изменить сущность, выберите «Редактировать» в её меню.

Форма сущности состоит из вкладок «Основная информация», «Параметры» и «Связи». Форма не сохраняется в следующих случаях:

• не заполнено название, идентификатор или обязательный параметр — под пустым параметром отображается «Поле не может быть пустым»;
• значение параметра типа «Number» или «Percentage» не является числом — под полем отображается «Значение должно быть числом»;
• название, идентификатор или описание не соответствуют регулярному выражению из настроек ресурса.

При ошибке форма открывает вкладку с первым полем, которое нужно исправить.

Создание сущности требует разрешения create:entities — глобального или для ресурса. Изменение сущности требует разрешения update:entities — глобального или для ресурса — либо разрешения update:entity для сущности. Без разрешения кнопка «Создать» на странице ресурса недоступна, а поля формы и кнопка «Сохранить» недоступны для изменения.

При изменении сущности кнопка «Сохранить» становится доступной после правки полей. При закрытии формы с несохранёнными изменениями портал запрашивает подтверждение.

Страница сущности

В заголовке страницы сущности отображаются её название, статус и способ создания, а также кнопки «Показать связи», «Добавить в избранное» и меню сущности.

Под заголовком выводятся описание сущности, команда и владелец. Длинное описание свёрнуто до трёх строк, полностью оно раскрывается по кнопке «Показать полностью».

Ниже расположены встроенные вкладки и вкладки с дашбордами. Встроенные вкладки:

• «Обзор» — блоки «Параметры», «Запуск» и «Связи».
• «Процессы» — блок «Что можно запустить» с процессами, доступными для сущности, и таблица «История запусков» с запусками процессов.
• «Действия» — блок «Что можно запустить» с действиями, доступными для сущности, и таблица «История выполнения» с запусками действий.
• «События» — события, сгенерированные для сущности.
• «История параметров» — изменения параметров сущности.

Вкладки с дашбордами из поля «Дополнительные вкладки с дашбордами» в настройках ресурса отображаются между вкладками «Обзор» и «Процессы»; порядок вкладок соответствует порядку в настройках ресурса. Если в настройках ресурса выбран дашборд для страницы сущности, на вкладке «Обзор» вместо блоков выводится этот дашборд.

Блок «Параметры»

Блок «Параметры» показывает значения параметров ресурса, кроме скрытых. В заголовке блока отображается заполненность параметров; подсказка к ней перечисляет пустые параметры.

Короткие значения выводятся сеткой. Нажатие на значение открывает его полностью: текст можно выделить или скопировать кнопкой «Копировать». У параметров типов «URL» и «Users» значение открывается значком, который появляется при наведении на параметр.

Параметры типов «JSON», «YAML», «Markdown» и «Object» выводятся отдельной строкой «Документы». Значение такого параметра открывается в окне просмотра; в нём также доступна кнопка «Копировать».

При наведении на параметр рядом с его названием появляется значок часов — он открывает историю изменений параметра. Кнопка «На момент времени» в заголовке блока показывает значения всех параметров на выбранный момент. Подробнее — в разделе «История параметров».

Блок «Запуск»

Блок «Запуск» показывает процессы или действия, доступные для сущности. Переключатель в заголовке блока выбирает список «Процессы» или «Действия» и показывает число элементов в каждом.

В блоке отображается до пяти элементов: сначала недавно запускавшиеся для этой сущности, затем остальные по названию. Для каждого элемента отображаются цвет статуса последнего запуска и время, прошедшее с него, или подпись «не запускался».

Кнопка «Запустить» открывает окно запуска выбранного процесса или действия. Если последний запуск ещё выполняется, вместо неё отображается кнопка «Открыть», которая переводит на вкладку с историей запусков. Ссылки «Все процессы и история запусков» и «Все действия и история запусков» открывают вкладки «Процессы» и «Действия».

Блок «Связи»

Блок «Связи» показывает связанные сущности, сгруппированные по связям ресурса. Для каждой группы отображаются название связи, число связанных сущностей и первые пять из них со статусом. Название сущности ведёт на её страницу.

Ссылка «Открыть таблицей» или «Показать все N» в заголовке группы открывает окно с таблицей всех сущностей группы; в таблице доступно меню каждой сущности. Кнопка «Граф» открывает граф связей сущности.

Если у сущности нет связей, в блоке отображается сообщение «Связанных сущностей нет».

Связи между сущностями

Связи сущности отображаются на её странице в блоке «Связи» и на графе связей. Каждая сущность может быть связана с одной или несколькими сущностями того же или другого ресурса, в зависимости от настроенных связей между ресурсами.

Связи между сущностями могут создаваться в ручном режиме либо автоматически при помощи источников данных или вебхуков.

События

При создании, удалении либо изменении спецификации любой сущности генерируется событие соответствующего типа: ENTITY_CREATED, ENTITY_DELETED, ENTITY_UPDATED. Эти события нужны для следующих целей:

• «Аудит» — фиксация изменений, происходящих с сущностью в течение её жизненного цикла.
• «Настройка автоматизированных реакций» — настройка реакций на изменения спецификации сущности.

Время хранения событий ограничено и может быть настроено через файл конфигурации портала.

События сущности отображаются на вкладке «События» её страницы. В таблице событий отображаются столбцы «Тип события», «Изменённые поля», «Кем» и «Дата создания», записи отсортированы от новых к старым. Для событий изменения в столбце «Изменённые поля» перечислены изменённые название, описание, владелец, команда, статус и названия изменённых параметров.

Над таблицей доступны фильтры:

• поле поиска — поиск по событиям, включая содержимое спецификации сущности;
• фильтр по типу — «Все», «Создание», «Изменение» или «Удаление»;
• период — «Начало периода» и «Конец периода».

Кнопка «Сравнить» у события изменения открывает сравнение прежней и новой спецификации сущности в формате JSON. У событий создания и удаления эта кнопка называется «Открыть».

История параметров

Портал сохраняет историю изменений параметров каждой сущности. Для каждого изменения фиксируются прежнее и новое значение, источник изменения, дата и пользователь, выполнивший изменение. В отличие от событий, история фиксирует каждое изменение отдельного параметра, а не факт изменения спецификации сущности в целом.

Просмотр истории доступен на странице сущности:

• Вкладка «История параметров» — полный список изменений всех параметров сущности.
• Значок часов рядом с названием параметра в блоке «Параметры» — история изменений выбранного параметра в отдельном диалоговом окне. Значок появляется при наведении на параметр.
• Кнопка «На момент времени» в заголовке блока «Параметры» — значения всех параметров сущности на выбранную дату и время.

Таблица истории

В таблице истории отображаются столбцы «Параметр», «Изменение», «Источник», «Кем изменено» и «Дата изменения», записи отсортированы от новых к старым. В столбце «Изменение» прежнее и новое значение показаны кратко: список — числом элементов, например «Список · 3», объект — надписью «JSON». Кнопка «Сравнить» открывает сравнение полных значений в формате JSON.

Столбец «Кем изменено» заполняется, если изменение выполнил пользователь. Для изменений, выполненных без участия пользователя (например, при синхронизации источника данных или обработке вебхука), в столбце отображается «—».

В столбце «Источник» возможны значения:

• «Вручную» — изменение пользователем в интерфейсе.
• «Действие» — изменение при выполнении действия.
• «Источник данных» — изменение при синхронизации источника данных.
• «Вебхук» — изменение при обработке вебхука.
• «Система» — автоматическое изменение порталом.

На вкладке «История параметров» записи можно отфильтровать:

• по параметру — выберите параметр в списке «Все параметры»;
• по времени изменения — задайте «Начало периода» и «Конец периода».

В диалоговом окне с историей одного параметра доступен только фильтр по времени изменения: записи в нём всегда относятся к выбранному параметру.

Параметры на момент времени

В диалоге «Параметры на момент времени» выберите «Дату и время» и нажмите «Показать». Таблица покажет значения всех параметров сущности на выбранный момент.

Параметр не попадёт в таблицу, если на выбранный момент он ещё не существовал или его значение было удалено.

Выбрать момент в будущем нельзя. Если на выбранный момент данных нет, отображается сообщение «Нет данных на выбранный момент».

Если выбранный момент раньше срока хранения истории, таблица покажет состояние на начало сохранившейся истории, а над ней появится сообщение «Показано состояние на <дата>: за более ранний период история не хранится».

Хранение истории

По умолчанию история параметров хранится 180 дней. Срок задаётся параметром clickhouse.propertyHistory.retentionDays в ModuleConfig development-platform или в веб-интерфейсе Deckhouse Platform; значение 0 отключает удаление по сроку, и тогда история хранится бессрочно. Записи удаляются целыми календарными месяцами, поэтому фактически история хранится на срок до месяца дольше заданного.

Если на вкладке «История параметров» в фильтре указано «Начало периода» раньше срока хранения, над таблицей появляется сообщение «История за период до <дата> не хранится»: пустой список в этом случае не означает, что параметры не менялись.

Кроме срока хранения, история не переживает удаление объекта, к которому относится:

• при удалении сущности удаляется вся история её параметров;
• при удалении параметра из настроек ресурса удаляется история этого параметра у всех сущностей ресурса.

В обоих случаях историю удаляет фоновая очистка, а не само удаление объекта.

Избранное

Пользователь может добавить любую сущность в избранное. Для этого на странице сущности нажмите на круглую кнопку со всплывающей подсказкой «Добавить в избранное» рядом с названием сущности. Посмотреть добавленные в избранное сущности можно в разделе каталога «Избранное». Сущности в нём отображаются карточками с названием ресурса; над списком доступен поиск.

Выгрузка сущностей в CSV

Портал предоставляет возможность выгрузки сущностей в CSV-файл для последующего анализа и обработки данных.

Выгрузка сущностей одного ресурса

Для выгрузки сущностей конкретного ресурса:

1. Откройте страницу ресурса в каталоге.

2. Рядом с названием ресурса нажмите на круглую кнопку со всплывающей подсказкой «Выгрузить сущности ресурса в CSV».

3. В выгруженный файл будут включены все сущности ресурса с учётом применённых фильтров, сортировки и пагинации.

Выгрузка сущностей нескольких ресурсов

Для выгрузки сущностей из нескольких ресурсов одновременно:

1. В нижней части сайдбара каталога нажмите кнопку «Выгрузить сущности».

2. В открывшемся диалоге выберите один или несколько ресурсов.

3. Нажмите кнопку «Скачать .csv».

4. Все сущности выбранных ресурсов будут объединены в один CSV-файл.