Кастомные ресурсы в платформе
Что такое кастомные ресурсы
В Kubernetes кастомные ресурсы (Custom Resources, CRD) позволяют расширять модель объектов за счёт своих типов: поверх базовых Pod, Service, Deployment и др. платформа может добавлять собственные сущности с нужными полями и контроллерами.
Платформа «Штурвал» целиком построена на операторах и кастомных ресурсах: почти все операции в GUI (создание кластера, изменение конфигурации узлов, установка сервисов, назначение прав) в итоге сводятся к созданию или изменению CRD, а операторы приводят фактическое состояние кластера к описанному в них.
Специфические кастомные ресурсы платформы
Ниже приведены основные кастомные ресурсы в API‑группах *.shturval.tech, которые используются в платформе.
API‑группа auth.shturval.tech
В кластере управления.
| Ресурс | Назначение | Где используется в GUI | Документация |
|---|---|---|---|
AuthOidcClient (authoidcclient) | Клиенты внутреннего сервиса аутентификации платформы (backend, frontend, ArgoCD, Grafana и др.), использующие OIDC | При переходе по SSO во внешний сервис | Кастомные ресурсы IAM |
User (user) | Локальные пользователи, хранящиеся в платформе | Управление доступом → пользователи | Управление паролем локального администратора |
Пример kubectl для auth.shturval.tech
kubectl get authoidcclient -A
API‑группа node.shturval.tech
В кластере управления и клиентском кластере.
| Ресурс | Назначение | Где используется в GUI | Документация |
|---|---|---|---|
NodeConfigItem (nodeconfigitem) | Шаблон конфигурации узлов: NTP, sysctl, пакеты, реестры, systemd‑юниты и др.; применяется по селектору узлов | Администрирование → Конфигурация узлов (список и карточки NCI) | Конфигурация узлов (NCI), Объект NCI (NodeConfigItem), Модуль shturval-node-config |
NodeConfig (nodeconfig) | Сводная фактическая конфигурация конкретного узла, собранная из всех применимых NCI, со статусом применения | Вкладки и статусные блоки на странице узла | NodeConfig (NC), Модуль shturval-node-config |
Пример kubectl для node.shturval.tech
kubectl get nodeconfigitem
API‑группа cluster.shturval.tech
В кластере управления.
| Ресурс | Назначение | Где используется в GUI | Документация |
|---|---|---|---|
ClusterConfig (clusterconfig) | Фактическая конфигурация кластера: параметры API, сети, набор сервисов, ссылки на профили. Целевая версия обновления — spec.releaseVersion, стратегия обновления узлов — spec.update.updateStrategy | Дашборд кластера, разделы редактирования конфигурации и обновления | API для управления кластерами, Обновление Kubernetes |
ClusterInfo (clusterinfo) | Сводная информация о кластере для дашбордов: статус, версии, количество узлов, ссылки на разделы мониторинга/логов. Доступные версии обновления — status.update.availableUpdates | Дашборд кластера и связанные страницы мониторинга | Графики и дашборды кластера |
ClusterProfile (clusterprofile) | Профиль, с которым будет развёрнут кластер: версия Kubernetes, сети, endpoints логирования/мониторинга, набор сервисов по умолчанию | Диалоги создания кластера, настройки профилей по умолчанию | Профили кластеров |
ClusterUpdateSchedule (clusterupdateschedule) | Расписание отложенного обновления. В окне обновления записывает целевую версию в ClusterConfig этого кластера | Дашборд кластера → блок Обновление → настройка отложенного обновления | Обновление Kubernetes |
InfrastructureProvider (infrastructureprovider) | Метаданные экземпляра провайдера: шаблоны виртуальных машин и версии Kubernetes (spec.templates), подтип провайдера (spec.subtype). Учётные данные хранятся в ресурсе провайдера | Страница экземпляра провайдера | Подготовка шаблона провайдера |
Пример kubectl для cluster.shturval.tech
kubectl get clusterprofile -A
kubectl get infrastructureprovider -A
API‑группа ops.shturval.tech
В кластере управления и клиентском кластере.
| Ресурс | Назначение | Где используется в GUI | Документация |
|---|---|---|---|
ShturvalRepoConfig (shturvalrepoconfig) | Конфигурация Helm‑репозиториев: URL, протокол, учётные данные, TLS | Сервисы и репозитории → вкладка Репозитории | Как подключить свой репозиторий |
ShturvalServiceConfig (shturvalserviceconfig) | Конфигурация Helm‑чартов (системных сервисов): версия, режим управления, базовые customvalues | Сервисы и репозитории → Установленные сервисы, вкладка Сервис; а также раздел Кастомные ресурсы | Обзор работы с сервисами, Системные сервисы репозитория Shturval |
ShturvalServicePatch (shturvalservicepatch) | Патч для customvalues системного сервиса (Helm‑релиза), накладываемый поверх базового SSC; позволяет безопасно кастомизировать сервисы | Вкладка Примененные ShturvalServicePatch на странице сервиса и через Администрирование → Кастомные ресурсы | Как управлять CustomValues сервисов |
Пример kubectl для ops.shturval.tech
kubectl get shturvalserviceconfig -A
API‑группа update.shturval.tech
В кластере управления и клиентском кластере.
| Ресурс | Назначение | Где используется в GUI | Документация |
|---|---|---|---|
ShturvalUpdate (shturvalupdate) | Ресурс для ручного запуска обновления кластера и отслеживания статуса обновления | Блок «Обновление» на дашборде кластера, раздел Администрирование → Кастомные ресурсы → update.shturval.tech | Запуск и этапы обновления |
ShturvalUpdateChannel (shturvalupdatechannel) | Указание канала обновления (в платформе доступен только стабильный канал stable) | Настройки обновления на дашборде кластера; раздел Кастомные ресурсы | Запуск и этапы обновления, Обновление зеркала в закрытом контуре |
ShturvalUpdateSchedule (shturvalupdateschedule) | Расписание для автоматического (отложенного) обновления кластера | Настройка расписания обновления на дашборде кластера | Режимы обновления |
Пример kubectl для update.shturval.tech (ShturvalUpdateSchedule)
kubectl get shturvalupdateschedule -n shturval-update-system
После обновления кластера на 2.15 объекты ShturvalUpdate, ShturvalUpdateChannel и ShturvalUpdateSchedule удаляются.
Обновление с версии 2.15 на следующую запускают ресурсы группы cluster.shturval.tech: целевая версия и стратегия — в ClusterConfig, расписание — в ClusterUpdateSchedule, доступные версии — в ClusterInfo.
API‑группа permissions.shturval.tech
В кластере управления.
| Ресурс | Назначение | Где используется в GUI | Документация |
|---|---|---|---|
GroupRole (grouprole) | Объект связывания набора разрешений с группой пользователей; определяет, какие Permissions применяются к группе и на каком уровне (платформа, тенант, кластер, неймспейс) | Управление доступом → вкладка Группы и назначение прав группам | Кастомные ресурсы для управления правами доступа, Как происходит назначение прав доступа |
UserRole (userrole) | Объект связывания набора разрешений с конкретным пользователем | Управление доступом → вкладка Пользователи и назначение прав пользователям | Кастомные ресурсы для управления правами доступа, Как происходит назначение прав доступа |
Scope (scope) | Набор объектов применения разрешений (например, платформа, конкретный тенант, кластер или неймспейс) | Внутренняя сущность системы управления доступом; отображается через дерево доступов и страницы назначения прав | Настройка разрешений |
Permission (permission) | Набор разрешений (permissions) — платформа, кластеры, неймспейсы, роли ArgoCD; лежит в основе наборов доступов | Управление доступом → Менеджер доступов → наборы доступов | Настройка разрешений, Кастомные ресурсы для управления правами доступа |
| Tenant | Логическое объединение кластеров целиком либо неймспейсов одного или нескольких кластеров для разграничения доступа | Раздел Тенанты и соответствующие вкладки в Управлении доступом | Концепция тенантов |
Пример kubectl для permissions.shturval.tech
kubectl get userrole -n shturval-backend
Когда использовать GUI, а когда — манифесты
- GUI удобен для типовых операций: создание кластеров, настройка сервисов, назначение прав, изменение конфигурации узлов.
- Манифесты CRD (
kubectl, импорт YAML) удобны, когда:- вы хотите версионировать изменения и применять их через GitOps;
- требуется доступ к полному набору полей ресурса, не всех из которых есть в форме GUI.
Инструкция по импорту YAML‑манифестов через интерфейс: Импорт манифестов.
Для всех перечисленных CRD рекомендуется ориентироваться на профильные разделы документации (ссылки в таблицах выше) — они содержат примеры YAML, ограничения и типовые сценарии использования.