Доступно в редакциях:  Open/CE, BE, SE, SE+, Ultimate/EE, Core, Certified Core/CSE Lite (1.73), Certified Pro/CSE Pro (1.73)

Входит в расширения: Мультиарендность

Модуль позволяет создавать проекты в кластере Kubernetes. Проект — это изолированное окружение, в котором можно развернуть приложения.

Основные возможности

  • Создание проектов по шаблонам проектов. Шаблон задаёт профиль безопасности подов, сетевую изоляцию, сбор логов, размещение на узлах и другие политики неймспейсов проекта.
  • Несколько неймспейсов в одном проекте. Настройки шаблона и выданный проекту доступ распространяются на все из них.
  • Доступ ко всему проекту через .spec.administrators, ProjectRoleBinding и ClusterProjectRoleBinding.
  • Квота ресурсов для каждого проекта.
  • Проект для каждого неймспейса: неймспейс, созданный напрямую, автоматически становится проектом.
  • Управление тем, какие cluster-wide-ресурсы, например StorageClass или ClusterIssuer, могут использовать проекты.

Модуль secret-copier нельзя использовать вместе с модулем multitenancy-manager: он копирует секреты во все неймспейсы, в том числе в неймспейсы проектов.

Состав проекта

В проект входят:

  • Основной неймспейс — создаётся автоматически, его имя совпадает с именем проекта.
  • Дополнительные неймспейсы (опционально) — создаются ресурсом ProjectNamespace и получают имена вида <имя проекта>-<имя>. Настройки проекта (политики безопасности, сетевые политики, сбор логов и т. п.) и выданный на проект доступ автоматически распространяются на все его неймспейсы.
  • Стандартные поля — список администраторов (.spec.administrators) и квоты ресурсов (.spec.quota), управляемые самим ресурсом Project независимо от шаблона.
  • Ресурсы из шаблона (опционально) — политики и настройки, описанные в ProjectTemplate и создаваемые контроллером в неймспейсах проекта, а также объекты из его manifests, которые применяются с правами администратора проекта.

Как работает модуль

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

Создание проекта

Для создания проекта используются ресурсы:

  • ProjectTemplate — ресурс, который описывает шаблон проекта: какие настройки и политики получат его неймспейсы и какие параметры можно передать при создании проекта;
  • Project — ресурс, который описывает конкретный проект.

При создании ресурса Project из определённого ProjectTemplate происходит следующее:

  1. Переданные параметры валидируются по OpenAPI-спецификации (параметр parametersSchema.openAPIV3Schema ресурса ProjectTemplate);
  2. Создаётся неймспейс с тем же именем, что у Project;
  3. Из шаблона создаются ресурсы проекта:
    • для современных шаблонов (deckhouse.io/v1alpha2) настройки, например профиль безопасности подов, сетевая изоляция, сбор логов и размещение на узлах, описываются структурированными полями. Контроллер сам создаёт из них нужные объекты в каждом неймспейсе проекта. Другие объекты описываются в manifests и применяются с правами администратора проекта;
    • шаблон с Helm-полем resourcesTemplate рендерится через Helm. Эта форма устарела, как и версия deckhouse.io/v1alpha1 ресурса ProjectTemplate, в которой другой формы нет (подробнее). Ни один шаблон не может получить новое resourcesTemplate, шаблон создаётся только через deckhouse.io/v1alpha2, а в одном из следующих релизов поле будет удалено, поэтому переведите такой шаблон на структурированные поля и manifests;
  4. Стандартные поля проекта применяются независимо от шаблона: .spec.quota преобразуется в ProjectQuotaStatus проекта, который создаёт ResourceQuota d8-project-quota в каждом неймспейсе проекта, а .spec.administrators — в автоматически управляемый ProjectRoleBinding.

API ресурса Project обслуживается как deckhouse.io/v1alpha3. Манифесты v1alpha2 продолжают работать благодаря вебхуку конвертации, а версия v1alpha1 больше не обслуживается (подробнее — в разделе «Версии API ресурса Project»). Поле projectTemplateName необязательно: если его не указать, используется шаблон simple, создающий только неймспейс проекта.

При создании проекта проверяется его имя. Недопустимы имена длиннее 61 символа, имена с системными префиксами d8- и kube-, имена существующих неймспейсов и неймспейсов, которые уже занял ресурс ProjectNamespace, а также имена неймспейсов, чьи ServiceAccount всё ещё указаны в кластерной привязке или в привязке другого проекта. Проект foo-bar рядом с проектом foo создать можно, но это отдельный проект, а не дополнительный неймспейс проекта foo. Вебхук предупреждает об этом, а такие пары показывает алерт (подробнее).

Изменение шаблона проекта применяется ко всем проектам, созданным по нему.

Несколько неймспейсов в проекте

Проект может включать несколько неймспейсов. Дополнительные неймспейсы создаются ресурсом ProjectNamespace в основном неймспейсе проекта и получают имена вида <имя проекта>-<имя> (например, backend-cache для проекта backend).

На дополнительные неймспейсы автоматически распространяются:

  • настройки шаблона проекта — профиль безопасности подов, сетевые политики, сбор логов и другие политики создаются в каждом неймспейсе проекта;
  • доступ, выданный через ProjectRoleBinding и ClusterProjectRoleBinding, включая автоматический доступ администраторов проекта.

Квота проекта (.spec.quota) применяется во всех неймспейсах проекта как единый лимит на сумму их потребления.

При удалении проекта удаляются все его неймспейсы — и основной, и дополнительные. Подробнее — в примерах использования.

Доступ к проекту

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

  • Субъекты из .spec.administrators автоматически получают роль администратора проекта (d8:project:admin).
  • Ресурс ProjectRoleBinding выдаёт роль во всех неймспейсах одного проекта.
  • ClusterProjectRoleBinding выдаёт роль сразу во всех проектах кластера, кроме виртуальных.

ProjectRoleBinding и ClusterProjectRoleBinding могут выдавать только ClusterRole с именами d8:project:*, d8:namespace:*, d8:project-capability:*, d8:namespace-capability:* или d8:custom:*. Подробнее о ролях — в документации модуля user-authz. Подробнее о привязках — в примерах использования.

Автоматическое создание проектов для неймспейсов

Пользователи по-прежнему могут создавать неймспейсы напрямую (d8 k create namespace), если параметр allowNamespacesWithoutProjects не равен false. При false пользователи создают окружения как объекты Project, а напрямую неймспейсы создают только администраторы кластера (system:masters, system:sudouser), Deckhouse, контроллер модуля и системные компоненты. Каждый неймспейс, не входящий ни в один проект, становится отдельным полноценным проектом с тем же именем:

  • шаблон подбирается по тому, что на неймспейсе уже есть: secure — если включено сканирование уязвимостей, default — если задан Pod Security Standard или расширенный мониторинг, иначе simple (только неймспейс);
  • параметры проекта заполняются из текущего состояния неймспейса, поэтому при переходе внутри него ничего не меняется;
  • дальше источником истины становится проект, и он редактируется как любой другой. Удалить неймспейс напрямую нельзя: чтобы убрать окружение, удалите Project, и его неймспейс удалится вместе с ним.

Системные неймспейсы (d8-*, kube-*, upmeter-*, default и всё с лейблом heritage: deckhouse или heritage: upmeter) в проекты не превращаются: их учитывает виртуальный проект deckhouse (кроме default). Лейбла, который оставляет новый пользовательский неймспейс без проекта, нет: пользователи не могут ставить на неймспейс лейбл heritage: upmeter, а лейбл projects.deckhouse.io/project ставит только модуль. Неймспейс с именем длиннее 61 символа (предел для имени Project) тоже пропускается, как и неймспейс с именем deckhouse: Project с таким именем — виртуальный проект.

Создать неймспейс, который не может стать проектом, пользователи не могут (подробнее).

Изоляция проекта

Неймспейс сам по себе не изолирует проект. Проект добавляет следующее:

  • доступ ко всему проекту через .spec.administrators, ProjectRoleBinding и ClusterProjectRoleBinding; обычный RoleBinding в одном неймспейсе допускается для делегируемых ролей;
  • ограничение ресурсов на весь проект через .spec.quota, которое применяется как ResourceQuota d8-project-quota в каждом неймспейсе проекта и как лимит на сумму их потребления;
  • сетевую изоляцию через поле networkPolicy.mode: Isolated шаблона;
  • профиль безопасности подов через поле podSecurityStandard шаблона.

Управление доступом к cluster-wide-ресурсам

Объекты в неймспейсах проектов могут ссылаться на cluster-wide-ресурсы. Например, PersistentVolumeClaim может использовать StorageClass, Certificate — ClusterIssuer, RoleBinding — ClusterRole. Модуль позволяет администраторам кластера определять, какие cluster-wide-ресурсы можно использовать из неймспейсов проектов, и какое значение используется по умолчанию.

Механизм работает независимо от RBAC. RBAC определяет, кто может создавать и изменять объекты, а механизм управления доступом к cluster-wide-ресурсам — какие ресурсы могут использовать эти объекты.

Принцип работы управления доступом

Для управления доступом к cluster-wide-ресурсам используются следующие ресурсы:

  • GrantableClusterResourceDefinition регистрирует тип cluster-wide-ресурсов, доступом к которому можно управлять. Такие ресурсы поставляются Deckhouse Platform или разработчиками модулей.
  • GrantableClusterResourceReference определяет, где используется зарегистрированный cluster-wide-ресурс. Например, какое поле ресурса содержит ссылку на него. Такие ресурсы поставляются модулями.
  • ClusterResourceGrantPolicy задаёт правила доступа. Администратор кластера с помощью лейблов выбирает проекты, на которые распространяется политика, определяет разрешённые и запрещённые ресурсы, а также ресурс, используемый по умолчанию.
  • В каждом неймспейсе каждого проекта контроллер поддерживает AvailableClusterResource для каждого GrantableClusterResourceDefinition. Он содержит список cluster-wide-ресурсов, доступных проекту по применимым политикам, и предназначен только для чтения.
  • При создании или изменении объекта вебхуки проверяют, разрешено ли ему использовать указанный cluster-wide-ресурс. При создании объекта также может автоматически подставляться ресурс, заданный для проекта по умолчанию.

Пока контроллер модуля недоступен, вебхуки отклоняют запросы. До его восстановления объекты зарегистрированных типов (например, PersistentVolumeClaim, Service или RoleBinding) в неймспейсах проектов могут создавать и изменять только компоненты платформы и участники группы system:masters. Чтобы контроллер оставался доступным, включите highAvailability.

flowchart LR
    A["Разработчик модуля или Deckhouse Platform
поставляет
GrantableClusterResourceDefinition
и GrantableClusterResourceReference"] --> C B["Администратор кластера
создаёт
ClusterResourceGrantPolicy"] --> C["Контроллер"] C --> D["Создаёт
AvailableClusterResource
в неймспейсе каждого проекта"] E["Пользователь создаёт объект
(например,
PersistentVolumeClaim)"] --> F["Mutating-вебхук
/defaults"] F --> G["Validating-вебхук
/is-granted"] D -. Доступные имена .-> G G --> H["Объект создан
или отклонён"]

Пока администратор не создал ClusterResourceGrantPolicy, доступность ресурсов определяется их регистрацией: ресурсы доступны всем проектам, если в GrantableClusterResourceDefinition задано defaultAvailability: All (значение по умолчанию) и ресурс не попадает под фильтры excluded или reserved.

Квотирование ресурсов не является частью данного механизма — оно делегировано стандартному ресурсу Kubernetes ResourceQuota.

Проверка доступа выполняется только для объектов в неймспейсах проектов. Если политика доступа изменяется, уже используемые существующими объектами cluster-wide-ресурсы остаются доступными для этих объектов.

Порядок проверки доступа и подстановки значений по умолчанию

Механизм определяет доступность cluster-wide-ресурсов и значения по умолчанию на основе зарегистрированных ресурсов и применяемых к проекту политик.

Определение доступности cluster-wide-ресурса

Если на cluster-wide-ресурс распространяется несколько правил, его доступность определяется в следующем порядке:

  1. Значение excluded в GrantableClusterResourceDefinition — ресурс недоступен независимо от настроек политик.
  2. Значение denied и deniedSelector в соответствующей записи ClusterResourceGrantPolicy.
  3. Значение allowed и allowedSelector в соответствующей записи ClusterResourceGrantPolicy.
  4. Значение reserved в GrantableClusterResourceDefinition — зарезервированный ресурс, который не стал доступен на предыдущих шагах, недоступен. Следующие шаги к нему не применяются, поэтому availabilityDefault: All не делает его доступным.
  5. Значение availabilityDefault в записях ClusterResourceGrantPolicy, которые применяются к проекту. Если в записи задан allowed или allowedSelector без availabilityDefault, все ресурсы вне её списков недоступны. Если хотя бы одна применимая запись задаёт All, это значение имеет приоритет над None в других записях.
  6. Значение defaultAvailability в GrantableClusterResourceDefinition.

Решает первый подходящий шаг. Шаги 2, 3 и 5 объединяют записи всех ClusterResourceGrantPolicy, которые применяются к проекту, включая служебные политики его шаблона и самого проекта.

Подстановка значений по умолчанию

Поведение при создании объекта зависит от режима, заданного в GrantableClusterResourceReference:

  • None — значение проверяется на доступность, но не подставляется автоматически;
  • FillEmpty — если значение не указано, подставляется значение по умолчанию для проекта;
  • Coerce — если значение не указано или указанный cluster-wide-ресурс недоступен проекту, подставляется значение по умолчанию для проекта. О замене указанного значения сообщается предупреждением (admission warning) в ответе на запрос.

Значение по умолчанию для проекта определяется в следующем порядке:

  1. Значение default из соответствующей записи ClusterResourceGrantPolicy.
  2. Значение, определённое с помощью defaultFrom в GrantableClusterResourceDefinition.
  3. Если значение не найдено, оно не подставляется.

Проверка существующих объектов

При изменении политики доступа значения, уже используемые существующими объектами, сохраняются. При обновлении объекта проверяются только новые значения: если значение в поле не изменилось, оно остаётся допустимым даже после ограничения доступа.

Это позволяет существующим объектам продолжать работу после ограничения доступа к cluster-wide-ресурсам.

Системные запросы

Запросы компонентов платформы и участников группы system:masters не проверяются. Компоненты платформы — это API-сервер, ServiceAccount Deckhouse, этого модуля и модуля user-authz, все ServiceAccount неймспейсов d8-system, kube-system и d8-user-authz, а также kubelet. Чтобы проверить политику, выполните запрос от имени пользователя проекта, например d8 k --as <USER_NAME>.

Мониторинг нарушений политик доступа

Если существующий объект использует cluster-wide-ресурс, который стал недоступен проекту после изменения политики, объект продолжает работать, но такое расхождение отслеживается средствами мониторинга.

При обнаружении таких объектов срабатывает алерт ClusterResourceGrantPolicyViolation. Информацию о нарушениях можно просмотреть на дашборде Grafana в разделе «Security» → «Cluster Resource Grant Violations».

Для мониторинга используется метрика d8_cluster_objects_grant_violated. Её отдаёт контроллер модуля: он пересчитывает нарушения при каждой обработке неймспейса проекта и не реже чем раз в две минуты по тем же правилам доступности, что и вебхук /is-granted.

Ресурсы, регистрируемые Deckhouse Platform

Deckhouse Platform регистрирует следующие cluster-wide-ресурсы:

Имя определения Cluster-wide-ресурс Где используется Режим подстановки значения по умолчанию
storageclasses StorageClass (storage.k8s.io) PersistentVolumeClaim .spec.storageClassName Coerce; None для PersistentVolumeClaim с .spec.dataSource или .spec.dataSourceRef
loadbalancerclasses Значение loadbalancerclass Service .spec.loadBalancerClass (для сервисов типа LoadBalancer) FillEmpty
clusterissuers ClusterIssuer (cert-manager.io) Certificate .spec.issuerRef.name; Ingress: аннотация cert-manager.io/cluster-issuer FillEmpty или None
clusterroles ClusterRole (rbac.authorization.k8s.io) RoleBinding .roleRef.name None
applicationpackages ApplicationPackage (deckhouse.io) Application .spec.packageName None

Регистрация clusterroles исключает все ClusterRole без лейбла rbac.deckhouse.io/delegatable: "true". По умолчанию RoleBinding в проекте может ссылаться на роли d8:namespace:* и d8:project:*, устаревшие псевдонимы d8:use:role:* и роли user-authz:user, user-authz:privileged-user, user-authz:editor и user-authz:admin упрощённой модели.

Определение clusterissuers поставляется модулем cert-manager, поэтому оно регистрируется только при включённом модуле cert-manager.

Определение storageclasses и GrantableClusterResourceReference storageclasses-pvc регистрирует этот модуль, если не включён модуль storage-foundation версии 1.0.3 или новее. Если такая версия storage-foundation включена, их регистрирует он под теми же именами и может расширять. При включении, выключении и обновлении storage-foundation до такой версии объекты переходят от одного модуля к другому, поэтому ClusterResourceGrantPolicy продолжают ограничивать StorageClass.

Ресурсы механизма управления доступом

Ресурс Область Кто создаёт Ручное создание Назначение
GrantableClusterResourceDefinition Кластер Разработчик модуля или Deckhouse Platform Разрешено для кастомных ресурсов Регистрирует тип cluster-wide-ресурса, доступом к которому можно управлять
GrantableClusterResourceReference Кластер Разработчик модуля Разрешено для полей кастомных ресурсов Определяет, где используется зарегистрированный cluster-wide-ресурс
ClusterResourceGrantPolicy Кластер Администратор кластера Обязательно Определяет доступные и запрещённые ресурсы, а также ресурс, используемый проектом по умолчанию
AvailableClusterResource Неймспейс Контроллер (автоматически) Запрещено (защищено вебхуком) Каталог доступных проекту ресурсов, только для чтения

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