Шаблоны проектов, доступные по умолчанию

В Deckhouse Platform есть следующие шаблоны проектов. Они идут по нарастающей: каждый следующий включает возможности предыдущего и добавляет свои. Значения параметров задаются в поле .spec.parameters ресурса Project:

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

    Параметры:

    • namespace.labels и namespace.annotations — дополнительные лейблы и аннотации неймспейса проекта.
    • requiredRequests (по умолчанию false) — если true, поды проекта должны задавать запросы CPU и памяти (OperationPolicy в режиме Deny).
  • default — шаблон для базовых сценариев использования проектов. В дополнение к неймспейсу он настраивает сетевую изоляцию, профиль безопасности подов, расширенный мониторинг и доставку логов.

    Параметры (кроме перечисленных для simple):

    • networkPolicy — Isolated (по умолчанию) разрешает входящий трафик только из неймспейсов проекта, от Prometheus, контроллера ingress-nginx и агента service-with-healthchecks, а исходящий — только в неймспейсы проекта и к DNS в kube-system. NotRestricted разрешает весь трафик.
    • podSecurityProfile — профиль Pod Security Standards для неймспейсов проекта: Baseline (по умолчанию) запрещает известные способы повышения привилегий, Restricted применяет максимально строгие практики, Privileged не ограничивает ничего. Пустая строка не задаёт профиль. Проект не ставит на свои неймспейсы лейбл security.deckhouse.io/pod-policy, и к ним применяется политика по умолчанию модуля admission-policy-engine.
    • extendedMonitoringEnabled (по умолчанию true) — алерты о недоступности и перезапусках контроллеров, ошибках 5xx в ingress-nginx и нехватке свободного места в томах PersistentVolume проекта.
    • clusterLogDestinationName — имя ресурса ClusterLogDestination, в который отправлять логи проекта. Если не задан, логи проекта никуда не отправляются.
    • requiredRequests (в этом шаблоне по умолчанию true) — если true, поды проекта должны задавать запросы CPU и памяти (OperationPolicy в режиме Deny). Когда существующий неймспейс становится проектом, параметр получает значение false, чтобы не блокировать уже работающие нагрузки.
  • secure — включает все возможности шаблона default, а также ограничение пользователей и групп внутри контейнеров, аудит их обращений к ядру и сканирование образов на уязвимости.

    Параметры (кроме перечисленных для default):

    • allowedUIDs и allowedGIDs — диапазоны (min, max) идентификаторов, допустимых для пользователей и групп внутри контейнеров проекта. См. Security Context.
    • runtimeAuditEnabled (по умолчанию false) — правила аудита обращений к ядру, выявляющие вредоносную активность. Работают, только если задан диапазон UID/GID.
    • securityScanningEnabled (по умолчанию true) — периодическое сканирование запускаемых образов на известные уязвимости (CVE) средствами Trivy, раз в 24 часа.
  • secure-with-dedicated-nodes — включает все возможности шаблона secure, а также размещение подов основного неймспейса проекта на выделенных узлах.

    Параметры (кроме перечисленных для secure). Если задан dedicatedNodes, в нём должно быть хотя бы одно из двух полей. Без dedicatedNodes поды не размещаются на выделенных узлах:

    • dedicatedNodes.nodeSelector — селектор узлов основного неймспейса. Он объединяется с селектором узлов каждого пода в этом неймспейсе, а под с конфликтующим селектором отклоняется.
    • dedicatedNodes.defaultTolerations — tolerations в формате spec.tolerations пода. Добавляются к подам, создаваемым в основном неймспейсе.

Шаблоны default, secure и secure-with-dedicated-nodes описаны в структурированном виде (deckhouse.io/v1alpha2). Шаблон simple — минимальный структурированный шаблон, который создаёт неймспейс, задаёт его лейблы и аннотации из параметров проекта, а при requiredRequests: true создаёт и OperationPolicy.

Точный набор параметров — в шаблоне, установленном в кластере. Чтобы посмотреть схему параметров шаблона, используйте команду:

d8 k get projecttemplates <PROJECT_TEMPLATE_NAME> -o jsonpath='{.spec.parametersSchema.openAPIV3Schema}' | jq

Для просмотра шаблона целиком используйте команду:

d8 k get projecttemplates <PROJECT_TEMPLATE_NAME> -o yaml

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

Чтобы создать проект, выполните следующие шаги:

  1. Создайте Project с указанием имени шаблона проекта в поле .spec.projectTemplateName.
  2. Задайте стандартные поля .spec.administrators и .spec.quota. Они работают с любым шаблоном.
  3. В параметре .spec.parameters ресурса Project укажите значения параметров для секции .spec.parametersSchema.openAPIV3Schema ресурса ProjectTemplate.

    Пример Project, созданного из шаблона default ProjectTemplate:

    apiVersion: deckhouse.io/v1alpha3
    kind: Project
    metadata:
      name: my-project
    spec:
      description: This is an example from the Deckhouse documentation.
      projectTemplateName: default
      # Стандартные поля, управляемые самим ресурсом Project.
      administrators:
        - kind: Group
          name: k8s-admins
      quota:
        requests.cpu: "5"
        requests.memory: 5Gi
        requests.storage: 1Gi
        limits.cpu: "5"
        limits.memory: 5Gi
      # Параметры конкретного шаблона.
      parameters:
        networkPolicy: Isolated
        podSecurityProfile: Restricted
        extendedMonitoringEnabled: true
    

    Версии API ресурса Project описаны в разделе «Версии API ресурса Project».

  4. Для проверки статуса проекта выполните команду:

    d8 k get projects my-project
    

    Успешно созданный проект должен отображаться в статусе Deployed (синхронизирован). Если отображается статус Error (ошибка), добавьте аргумент -o yaml к команде (например, d8 k get projects my-project -o yaml) для получения более подробной информации о причине ошибки.

Версии API ресурса Project

API ресурса Project обслуживается как deckhouse.io/v1alpha3. Манифесты v1alpha2 продолжают работать: вебхук конвертации автоматически переносит parameters.administrators и parameters.resourceQuota в стандартные поля .spec.administrators и .spec.quota. Если хотя бы один администратор не помещается в .spec.administrators (например, у него задан accessLevel), весь список остаётся в parameters, и .spec.administrators не заполняется. То же относится к квоте, в которой есть что-то, кроме значений ресурсов (например, scopes), к квоте, в которой где-либо есть число 0, а также к пустому списку или пустой квоте. Шаблон, который проверяет значение через with, пропускает число 0 и не задаёт лимит, а в .spec.quota это был бы жёсткий лимит, равный нулю. Строка "0" переносится в .spec.quota как такой лимит. Клиент v1alpha2 читает 0 из .spec.quota как строку "0". Проект не может задавать .spec.administrators вместе с parameters.administrators или .spec.quota вместе с parameters.resourceQuota. Поле spec.grants есть только в deckhouse.io/v1alpha3: изменение проекта, у которого оно задано, через deckhouse.io/v1alpha2 отклоняется, подробнее — в разделе «Выдача cluster-wide-ресурсов одному проекту».

Версия deckhouse.io/v1alpha1 больше не обслуживается, и API-сервер отклоняет манифест с apiVersion: deckhouse.io/v1alpha1. Перед применением такого манифеста замените apiVersion на deckhouse.io/v1alpha3, переименуйте spec.projectTypeName в spec.projectTemplateName (ProjectTemplate с таким именем должен существовать) и spec.template в spec.parameters, а administrators и resourceQuota перенесите из параметров в .spec.administrators и .spec.quota.

Создание проекта без указания шаблона

Поле projectTemplateName необязательно: если его не указать, используется шаблон simple. Такой проект состоит только из неймспейса и стандартных полей (администраторы, квота) — никакие политики из шаблонов в нём не создаются. Используйте его, когда неймспейсу не нужны настройки шаблона или они задаются другими средствами:

apiVersion: deckhouse.io/v1alpha3
kind: Project
metadata:
  name: my-plain-project
spec:
  administrators:
    - kind: Group
      name: k8s-admins
  quota:
    requests.cpu: "2"

Шаблон можно назначить позже, указав его в .spec.projectTemplateName.

Правила именования проектов

Имя проекта одновременно является именем его основного неймспейса, поэтому при создании проекта проверяются следующие правила:

  • имя не может начинаться с d8- и kube- — эти префиксы зарезервированы за системными неймспейсами;
  • имя не может быть default или deckhouse: эти имена заняты виртуальными проектами;
  • имя не может быть длиннее 61 символа;
  • имя не может совпадать с именем существующего неймспейса или неймспейса, который занял ресурс ProjectNamespace. Итоговое имя <проект>-<spec.name> занято с момента создания ресурса ProjectNamespace, даже если контроллер ещё не создал неймспейс. Неймспейс, который не относится ни к одному проекту, становится проектом автоматически.
  • имя не может совпадать с именем неймспейса, чьи ServiceAccount всё ещё указаны среди субъектов ClusterProjectRoleBinding или ProjectRoleBinding проекта, к имени которого новое имя добавляет дефис и суффикс (foo для foo-extra). Такие субъекты часто остаются от удалённого дополнительного неймспейса, и без этого правила ServiceAccount нового проекта получили бы права этой привязки. Сначала удалите эти субъекты из привязки. Привязка в отказе не называется.

Проект может называться как другой проект с дефисом и суффиксом (foo-bar рядом с foo). Это отдельный проект со своим неймспейсом, а не дополнительный неймспейс проекта foo, поэтому шаблон, администраторы, квота и привязки проекта foo на него не распространяются. Вебхук пропускает такой проект с предупреждением, а контроллер отправляет Warning-событие NamedLikeAdditionalNamespace на новый проект. Все такие пары проектов, в том числе появившиеся из уже существовавших неймспейсов, показывает алерт MultitenancyManagerProjectNamedLikeAdditionalNamespace. Чтобы добавить неймспейс в проект, создайте ресурс ProjectNamespace.

Статус и диагностика проекта

Поле .status.state проекта принимает значение Deployed (все ресурсы проекта синхронизированы или объекты из manifests ждут своей привязки) либо Error. Причина ошибки описывается в условиях (.status.conditions):

d8 k get project my-project -o jsonpath='{range .status.conditions[*]}{.type}={.status}: {.message}{"\n"}{end}'
Условие Значение False означает
ProjectTemplateFound Шаблон, указанный в .spec.projectTemplateName, не найден.
Validated Параметры проекта не прошли валидацию по схеме шаблона (parametersSchema).
ResourcesUpgraded Не удалось создать или обновить ресурсы проекта из шаблона (детали — в message).
StandardFieldsApplied Не удалось применить стандартные поля (квоту или администраторов).
TemplateRolesAllowed Шаблон создаёт привязку к роли, запрещённой для выдачи в проектах, — проект переводится в Error, в message указана роль.
QuotaWithinLimits Потребление проекта выше его квоты; в message названы лимиты. У проекта без квоты этого условия нет.
ManifestsApplied Объекты из manifests шаблона не применены. В message указано, чего они ждут, почему не применён ни один из них, какие уже существующие объекты они не трогают или какие объекты отклонил API-сервер, с кодом каждого отказа (например, 403 Forbidden).
HelmOwnership Неймспейс проекта принадлежит другому Helm-релизу. В message указан этот релиз (подробнее — в разделе «Автоматическое создание проекта для неймспейса»).
NamespaceDeleted Проект удаляется, а его неймспейс ещё не удалён. В message указано, с какого момента идёт удаление и что осталось в неймспейсе.

Условие HandoverPending читается наоборот. Оно равно True, пока объекты AuthorizationRule и ResourceQuota, сохранённые от Helm-текста, ждут стандартных полей, которые их заменяют, и удаляется, когда эти объекты удалены (см. «Переход проекта с Helm-текста»).

Прочие полезные поля статуса:

  • .status.namespaces — все неймспейсы проекта с указанием их типа (Main/Additional);
  • .status.usage — потребление проекта, просуммированное по всем его неймспейсам, из его ProjectQuotaStatus;
  • .status.resources — состояние отдельных ресурсов, созданных из шаблона;
  • .status.keptObjects — объекты Helm-текста и релиза структурированных полей, которые релиз оставил на месте вместо удаления, пока их не заберут manifests;
  • .status.manifestObjects — объекты, применённые из manifests шаблона.

Служебные объекты проекта

Контроллер создаёт в неймспейсах проекта служебные объекты. Они управляются автоматически — редактировать их вручную нельзя (попытка будет отклонена):

Объект Где Откуда берётся
ProjectQuotaStatus/<PROJECT_NAME> Кластерный объект Поле .spec.quota проекта (подробнее — в разделе «Квота проекта»).
ResourceQuota/d8-project-quota Каждый неймспейс проекта Поле .spec.quota проекта.
ProjectRoleBinding/d8-administrators Основной неймспейс Поле .spec.administrators проекта.
ProjectRoleBinding/d8-manifests Основной неймспейс Поле manifests шаблона проекта. Выдаёт роль d8:project:admin пользователю, от имени которого применяются эти объекты.
RoleBinding/d8:prb:<имя> Каждый неймспейс проекта Разворачивание ProjectRoleBinding с именем <имя>.
RoleBinding/d8:cprb:<имя> Каждый неймспейс каждого проекта Разворачивание ClusterProjectRoleBinding с именем <имя>

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

Виртуальные проекты

Помимо созданных пользователями проектов, в списке d8 k get projects всегда присутствуют два виртуальных проекта (лейбл projects.deckhouse.io/virtual-project: "true"):

  • deckhouse — системные неймспейсы (d8-*, kube-*, upmeter-*, heritage: deckhouse / heritage: upmeter);
  • default — остальные неймспейсы без своего проекта (сам неймспейс default).

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

Виртуальные проекты нужны для полноты картины: с ними каждый неймспейс кластера относится к какому-то проекту. Управлять ими нельзя: они не редактируются, в них нельзя создавать ProjectNamespace и ProjectRoleBinding, и на них не распространяются ClusterProjectRoleBinding. Их шаблон virtual зарезервирован за ними: пользовательский проект с projectTemplateName: virtual вебхук отклонит — у такого проекта не было бы своего неймспейса. Лейбл projects.deckhouse.io/virtual-project: "true" тоже зарезервирован: вебхук отклонит проект, который создают с ним или которому его добавляют. Виртуальным проект делает шаблон, а не лейбл, поэтому пользовательский проект, на котором лейбл уже есть, работает как обычный; лейбл на нём остаётся с предупреждением, пока его не уберут. Политики ClusterResourceGrantPolicy к их неймспейсам тоже не применяются, даже если селекторы политики выбирают виртуальный Project, потому что правила доступности cluster-wide-ресурсов действуют только в неймспейсах с лейблом projects.deckhouse.io/project, а на неймспейсах виртуальных проектов его нет.

Объекта ProjectTemplate с именем virtual нет, и вебхук не даст его создать. Если такой шаблон уже есть в кластере, он не используется ни одним проектом, и его можно удалить.

Дополнительные неймспейсы проекта

В Deckhouse Platform Open (CE) у проекта есть только основной неймспейс.

Если приложению нужно несколько неймспейсов (например, отдельное для кеша или очередей), добавьте их в проект ресурсом ProjectNamespace. ProjectNamespace создаётся в основном неймспейсе проекта; итоговый неймспейс получает имя <имя проекта>-<spec.name>:

apiVersion: deckhouse.io/v1alpha3
kind: ProjectNamespace
metadata:
  name: cache
  namespace: my-project
spec:
  name: cache   # Будет создан неймспейс my-project-cache.

Проверить состав проекта можно по его статусу:

d8 k get project my-project -o jsonpath='{.status.namespaces}'

Правила работы с ProjectNamespace:

  • Поле spec.name неизменяемо: чтобы переименовать неймспейс, удалите ProjectNamespace и создайте новый.
  • Итоговое имя <имя проекта>-<spec.name> не может быть длиннее 63 символов (ограничение Kubernetes на имена неймспейсов).
  • Создавать ProjectNamespace можно только в основном неймспейсе проекта. «Вложить» его в дополнительный неймспейс или чужой проект нельзя.
  • Итоговое имя должно быть свободно. Запрос отклоняется, если неймспейс с таким именем существует и не относится к этому проекту, если так называется проект или если это имя уже занял другой ресурс ProjectNamespace. Например, ProjectNamespace a-backend проекта team и ProjectNamespace backend проекта team-a претендуют на одно имя team-a-backend.
  • Запрос также отклоняется, если ServiceAccount из неймспейса с итоговым именем всё ещё указаны среди субъектов ClusterProjectRoleBinding или ProjectRoleBinding другого проекта, к имени которого итоговое имя добавляет дефис и суффикс (team для team-a-backend проекта team-a). Сначала удалите эти субъекты из привязки. ProjectRoleBinding этого же проекта не мешает, и указанные в нём ServiceAccount снова получают права, когда неймспейс создаётся заново.
  • При удалении ProjectNamespace удаляется его неймспейс. При удалении проекта удаляются все его неймспейсы.
  • Неймспейс с итоговым именем, который не относится к этому проекту, не забирается в проект, даже если он появился уже после создания ProjectNamespace. Такой ProjectNamespace не становится готовым, а его удаление этот неймспейс не трогает.
  • Удалить проект может только пользователь, которому разрешено удалять каждый его неймспейс (глагол delete для namespaces), то есть основной неймспейс и все неймспейсы с лейблом projects.deckhouse.io/project: <имя проекта>. Иначе запрос отклоняется, и в отказе назван неймспейс, который пользователю удалять нельзя. Несуществующий неймспейс не проверяется. Те, кого вебхук Project пропускает без проверки (см. «Кто обходит валидацию»), удаляют проекты без этой проверки.

Что распространяется на дополнительные неймспейсы

Автоматически действует во всех неймспейсах проекта (и в основном, и в дополнительных):

  • Доступ: привязки ProjectRoleBinding и ClusterProjectRoleBinding, включая автоматический доступ администраторов проекта. При добавлении нового неймспейса все существующие привязки разворачиваются в него без каких-либо действий со стороны пользователя.
  • Namespaced-объекты шаблона: сетевая политика (networkPolicy.mode: Isolated) и настройка сбора логов (logShipping) создаются в каждом неймспейсе проекта. Сетевая изоляция при этом разрешает трафик между неймспейсами одного проекта. Helm-шаблон resourcesTemplate создаёт свои объекты в основном неймспейсе, если в объекте не указан другой неймспейс проекта. Так же поступает manifests, объекты которого не применяются, пока один из них указывает неймспейс вне проекта.
  • Кластерные политики шаблона (OperationPolicy, SecurityPolicy из allowedUIDs/allowedGIDs): выбирают неймспейсы по лейблу projects.deckhouse.io/project, то есть покрывают весь проект.
  • Квота проекта: ResourceQuota d8-project-quota с лимитами квоты проекта создаётся в каждом неймспейсе проекта.
  • Наследуемые лейблы: профиль безопасности подов (security.deckhouse.io/pod-policy), расширенный мониторинг (extended-monitoring.deckhouse.io/enabled), сканирование уязвимостей (security-scanning.deckhouse.io/enabled), лейбл шаблона (projects.deckhouse.io/project-template) и лейблы, которые шаблон задаёт через namespaceMetadata.labels, синхронизируются с основного неймспейса на дополнительные. Для шаблона с resourcesTemplate это лейблы, которые его Helm-текст ставит на основной неймспейс. Синхронизация полная: если функцию выключили или лейбл убрали в шаблоне, лейбл снимется и с дополнительных неймспейсов. Лейблы шаблона перечислены в аннотации projects.deckhouse.io/template-labels каждого неймспейса проекта; их меняют через Project или его ProjectTemplate, а прямая правка такого лейбла на дополнительном неймспейсе откатывается. Благодаря лейблу шаблона правила доступности cluster-wide-ресурсов тоже действуют во всех неймспейсах проекта.

Действуют только в основном неймспейсе:

  • аннотации из namespaceMetadata шаблона;
  • лейблы и аннотации, поставленные на основной неймспейс напрямую или GitOps-инструментом, в том числе те, что были на неймспейсе до того, как он стал проектом, кроме перечисленных выше лейблов профиля безопасности, мониторинга и сканирования;
  • лейблы отслеживания GitOps-инструментов (app.kubernetes.io/instance, argocd.argoproj.io/*, kustomize.toolkit.fluxcd.io/*, helm.toolkit.fluxcd.io/*, kapp.k14s.io/*), даже если их задаёт шаблон;
  • аннотации размещения на узлах (из полей nodeSelector и tolerations шаблона).

Лейблы отслеживания GitOps-инструментов не наследуются, потому что GitOps-инструмент считал бы дополнительный неймспейс с такими лейблами своим и мог бы его удалить. Модуль распознаёт только перечисленные ключи. Собственный ключ отслеживания, заданный через шаблон (например, ключ из параметра application.instanceLabelKey в Argo CD), наследуется.

Когда неймспейс становится проектом автоматически, его собственные лейблы и аннотации остаются на нём и не копируются в Project, поэтому дополнительные неймспейсы проекта их не наследуют. Исключение составляют лейблы профиля безопасности, мониторинга и сканирования. При переходе в проект они становятся параметрами проекта и наследуются, как в любом проекте. Чтобы другой лейбл такого неймспейса был и на дополнительных неймспейсах, задайте его в spec.parameters.namespace.labels ресурса Project либо поставьте его на каждый дополнительный неймспейс напрямую.

Встроенные шаблоны, на которых создаются такие проекты, контроллер перезаписывает, поэтому лейбл, добавленный в их namespaceMetadata.labels, там не сохраняется. Политика выдачи ресурсов, namespaceSelector которой выбирает такой лейбл, не распространяется на новые дополнительные неймспейсы, пока лейбл не задан в Project. Чтобы политика действовала на весь проект, выберите его через projectSelector.

Лейблы неймспейсов проекта

Лейбл Основной Дополнительные Назначение
projects.deckhouse.io/project: <PROJECT_NAME> ✓ ✓ Принадлежность к проекту — общий лейбл всех неймспейсов проекта
projects.deckhouse.io/project-namespace: <spec.name> — ✓ Признак дополнительного неймспейса (имя ресурса ProjectNamespace)
projects.deckhouse.io/project-template: <PROJECT_TEMPLATE_NAME> ✓ ✓ Шаблон проекта; по нему применяются правила доступности cluster-wide-ресурсов
heritage: multitenancy-manager ✓ ✓ Неймспейс управляется контроллером проектов: его spec, поле finalizers и лейблы из этой таблицы меняются через Project; остальные лейблы и аннотации можно менять напрямую
projects.deckhouse.io/quota: pending, projects.deckhouse.io/quota: enforced ✓ ✓ Неймспейс входит в проект с квотой; лейбл ставит только контроллер
quota.projects.deckhouse.io/vm: enforced, quota.projects.deckhouse.io/lb: enforced ✓ ✓ В квоте проекта есть ключи виртуальных машин или балансировщиков нагрузки
security.deckhouse.io/pod-policy, extended-monitoring.deckhouse.io/enabled, security-scanning.deckhouse.io/enabled ✓ ✓ (наследуются) Политики и функции из шаблона проекта
Лейблы из namespaceMetadata.labels шаблона ✓ ✓ (наследуются) Лейблы шаблона проекта. Перечислены в аннотации projects.deckhouse.io/template-labels неймспейса и меняются через Project или его ProjectTemplate
Любой другой лейбл, поставленный на неймспейс напрямую или GitOps-инструментом, в том числе лейбл, который был на неймспейсе до того, как он стал проектом — — Модуль его не ставит. Релиз проекта не откатывает и не возвращает его, дополнительные неймспейсы его не наследуют

Общий лейбл projects.deckhouse.io/project позволяет выбирать неймспейсы проекта командой get ns. Чтобы получить все неймспейсы проекта (основной и дополнительные), используйте команду:

d8 k get ns -l projects.deckhouse.io/project=my-project

Получить только дополнительные неймспейсы проекта:

d8 k get ns -l 'projects.deckhouse.io/project=my-project,projects.deckhouse.io/project-namespace'

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

d8 k get ns -l 'projects.deckhouse.io/project=my-project,!projects.deckhouse.io/project-namespace'

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

Неймспейс, созданный напрямую (например, d8 k create ns my-app), становится проектом с тем же именем:

  • шаблон подбирается по тому, что на неймспейсе уже есть: secure — при лейбле security-scanning.deckhouse.io/enabled, default — при security.deckhouse.io/pod-policy или extended-monitoring.deckhouse.io/enabled, иначе simple;
  • параметры проекта заполняются из текущего состояния неймспейса, поэтому внутри него ничего не меняется: сетевая политика остаётся неограниченной, а Pod Security Standard сохраняет то значение, которое уже было;
  • дальше источником истины становится проект, и он редактируется как любой другой. Удалить неймспейс проекта напрямую нельзя: запрос отклоняется с сообщением Manual modification is forbidden. Чтобы убрать окружение, удалите Project: d8 k delete project <NAME> удаляет вместе с ним неймспейс и возвращает управление, когда неймспейс исчезнет. Удалить Project может только пользователь, которому разрешено удалять его неймспейс (подробнее — в разделе «Дополнительные неймспейсы проекта»).

Создать неймспейс напрямую пользователи могут, только пока параметр allowNamespacesWithoutProjects равен true (значение по умолчанию). При false напрямую неймспейсы создают только администраторы кластера (system:masters, system:sudouser), Deckhouse, контроллер модуля и системные компоненты (подробнее — в разделе «Кто обходит валидацию»). Остальные пользователи создают Project или ProjectNamespace.

Каждый такой неймспейс становится отдельным проектом, как бы он ни назывался. Из неймспейсов app и app-staging получаются два проекта, и app-staging не становится дополнительным неймспейсом проекта app. Проект создаёт контроллер, поэтому предупреждение admission-вебхука до автора неймспейса не доходит. Вместо него контроллер отправляет Warning-событие NamedLikeAdditionalNamespace на новый проект и на неймспейс. События объектов уровня кластера хранятся в неймспейсе default, поэтому для их чтения нужен доступ к событиям в нём: d8 k -n default get events --field-selector reason=NamedLikeAdditionalNamespace. Такие пары показывает алерт MultitenancyManagerProjectNamedLikeAdditionalNamespace, подробнее в разделе «Правила именования проектов».

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

Чтобы ни один неймспейс не остался вне проекта, ValidatingAdmissionPolicy d8-multitenancy-manager-namespace-adoption запрещает создавать неймспейс с именем длиннее 61 символа, с префиксом upmeter- или с именем deckhouse, а также ставить на неймспейс лейбл heritage: upmeter. Политика действует при любом значении allowNamespacesWithoutProjects и пропускает тех же пользователей и группы, что и политика d8-multitenancy-manager-namespace-creation; они перечислены в разделе «Кто обходит валидацию». Неймспейс, который 10 минут остаётся без проекта, например пока ни одна реплика контроллера модуля не лидирует, вызывает алерт D8NamespaceNotAdopted. Метрику для алерта отдают поды контроллера, поэтому, пока ни один из них не Ready, алерт не срабатывает.

Политика не меняет уже существующие неймспейсы, поэтому неймспейс, созданный до неё с одним из таких имён или с лейблом heritage: upmeter, остаётся вне всех проектов. Чтобы вывести список неймспейсов, которые не входят ни в один проект и не являются системными, выполните:

d8 k get namespaces -l '!projects.deckhouse.io/project,heritage!=deckhouse' -o name | grep -Ev '^namespace/(d8-|kube-|default$|upmeter-probe-namespace-)'

В списке окажутся неймспейсы, для которых проект не создаётся: с именем длиннее 61 символа, deckhouse, с другими именами upmeter-* и с лейблом heritage: upmeter. Среди них могут быть неймспейсы агента upmeter, изменять которые нельзя. Чтобы вернуть неймспейс в проект, снимите с него лейбл heritage: upmeter (если имя не начинается с upmeter-), и контроллер создаст проект. Другой вариант — перенести нагрузку в неймспейс с другим именем. Неймспейс с пустым лейблом projects.deckhouse.io/project в список не попадает, такие неймспейсы выводит d8 k get namespaces -l 'projects.deckhouse.io/project='.

При превращении в проект неймспейс, который из-за лейбла мониторинга или сканирования получает шаблон default или secure и у которого нет лейбла security.deckhouse.io/pod-policy, получает podSecurityProfile: "". Проект не ставит на него этот лейбл, и к нему по-прежнему применяется политика по умолчанию модуля admission-policy-engine. Неймспейс, у которого значение лейбла отличается от baseline, restricted и privileged, тоже получает podSecurityProfile: "", а сам лейбл остаётся на нём без изменений. Неймспейс без всех этих лейблов получает шаблон simple, который не задаёт профиль и не имеет параметра podSecurityProfile.

Чтобы позже сменить профиль, задайте podSecurityProfile в проекте. Проект на шаблоне simple сначала переведите на default с networkPolicy: NotRestricted, requiredRequests: false и extendedMonitoringEnabled: false, чтобы больше ничего не изменилось.

Неймспейс, который уже принадлежит другому Helm-релизу (его аннотация meta.helm.sh/release-name указывает не на релиз проекта), не перехватывается: проект получает условие HelmOwnership с именем чужого релиза и повторяет попытку, а неймспейс остаётся как есть. Чтобы проект продолжил работу, удалите чужой релиз или его аннотации владения.

Уже существующие RoleBinding и AuthorizationRule внутри неймспейса после перехода в проект продолжают работать. Namespace Admin не копируется в .spec.administrators и не становится d8:project:admin: эта роль ещё управляет ProjectRoleBinding, а это шире, чем Admin внутри одного неймспейса. Чтобы руководитель команды стал администратором проекта, оператор платформы добавляет его в .spec.administrators или создаёт ProjectRoleBinding. Роль Admin неймспейса разрешает на объект Namespace только get, list и watch.

Лейблы и аннотации, которые ставит модуль, — heritage, projects.deckhouse.io/*, quota.projects.deckhouse.io/vm, quota.projects.deckhouse.io/lb, security.deckhouse.io/pod-policy, extended-monitoring.deckhouse.io/enabled, security-scanning.deckhouse.io/enabled, app.kubernetes.io/managed-by, meta.helm.sh/*, аннотации node-selector и tolerations — меняются через Project и его шаблон; любой другой лейбл или аннотацию (istio-injection, лейбл Pod Security, служебную аннотацию GitOps-инструмента) можно по-прежнему поставить прямо на Namespace, если это позволяет RBAC, и контроллер их не трогает. spec и поле finalizers объекта Namespace, как и его удаление, остаются за контроллером.

Это относится и к лейблам и аннотациям, которые были на неймспейсе до того, как он стал проектом. Они не копируются в проект при его создании, поэтому релиз проекта ими не владеет, и контроллер не откатывает их изменения и не возвращает удалённые. Они остаются на основном неймспейсе, а дополнительные неймспейсы проекта их не наследуют. Если такой лейбл нужен и на дополнительном неймспейсе, задайте его в spec.parameters.namespace.labels ресурса Project или поставьте его на этот неймспейс напрямую.

Исключение — аннотации node-selector и tolerations. Они принадлежат модулю, поэтому при переходе в проект копируются в параметр namespace.annotations проекта, и менять или удалять их нужно там. Лейблы профиля безопасности, мониторинга и сканирования становятся параметрами проекта, и дополнительные неймспейсы их наследуют. Лейблы extended-monitoring.deckhouse.io/enabled и security-scanning.deckhouse.io/enabled сохраняют значение "true", если оно было на неймспейсе. Любое другое значение, в том числе "false", заменяется пустым, потому что при переходе в проект функция включается, если на неймспейсе есть такой лейбл, с любым значением.

Сам лейбл projects.deckhouse.io/project ставит только контроллер: неймспейс, созданный вручную с этим лейблом, отклоняется, в том числе с пустым значением, поэтому нельзя сделать так, чтобы неймспейс выглядел принадлежащим чужому проекту. Неймспейс принадлежит только проекту, который назван в лейбле: неймспейс без лейбла или с пустым значением не засчитывается проекту с тем же именем. Неймспейс, на котором пустое значение уже стоит, в проект не переводится: раньше пустое значение исключало неймспейс из перехода в проект, и так остаётся, пока лейбл не уберут.

Например:

  1. Создайте новый неймспейс:

    d8 k create ns test
    
  2. Убедитесь, что проект создался:

    d8 k get projects
    

    В списке проектов появится новый проект, соответствующий неймспейсу:

    NAME        STATE      PROJECT TEMPLATE   DESCRIPTION                                            AGE
    deckhouse   Deployed   virtual            This is a virtual project                              181d
    default     Deployed   virtual            This is a virtual project                              181d
    test        Deployed   simple                                                                    1m
    

Чтобы сменить шаблон такого проекта, укажите другой шаблон в .spec.projectTemplateName.

Если в неймспейсе уже есть объект того же типа и с тем же именем, что и объект, который создаёт новый шаблон, например NetworkPolicy isolated, проект переходит в состояние Error, а условие ResourcesUpgraded называет этот объект. Сначала удалите или переименуйте его.

Стандартные поля проекта

Администраторы проекта и квота ресурсов задаются в полях Project и работают с любым шаблоном (включая simple):

  • .spec.administrators — список субъектов (kind: User или kind: Group и name), получающих административный доступ к проекту. Контроллер реализует этот доступ через автоматически создаваемый ProjectRoleBinding в неймспейсе проекта. Имя не может содержать управляющие символы и переводы строк и не может начинаться с system:multitenancy-manager:, префикса пользователей, от имени которых действует контроллер. Обновление, которое оставляет такое имя прежним, принимается с предупреждением.
  • .spec.quota — набор жёстких лимитов ResourceQuota (например, requests.cpu, limits.memory) на весь проект. Контроллер превращает его в ProjectQuotaStatus проекта и сообщает в .status.usage потребление, просуммированное по неймспейсам проекта; очистка поля удаляет соответствующий ProjectQuotaStatus. Для изменения поля нужно право задавать квоту проекта, а его ключи подчиняются правилам квоты проекта. Для memory и storage должна быть указана единица измерения (например 2Gi). Числа без единицы измерения означают байты, и все они, кроме 0, отклоняются. Обновление, которое оставляет такое значение прежним, принимается с предупреждением (admission warning), поэтому проект, квота которого пришла из чисел без единиц в parameters.resourceQuota, можно редактировать и по-прежнему применять без изменений. Создание через deckhouse.io/v1alpha2 с такими числами в parameters.resourceQuota тоже принимается с предупреждением, поэтому такой манифест может создать проект заново, например из резервной копии.
apiVersion: deckhouse.io/v1alpha3
kind: Project
metadata:
  name: my-project
spec:
  projectTemplateName: simple
  administrators:
    - kind: Group
      name: k8s-admins
  quota:
    requests.cpu: "5"
    requests.memory: 5Gi
    limits.cpu: "10"
    limits.memory: 10Gi

Helm-шаблон в resourcesTemplate, который создаёт ResourceQuota или AuthorizationRule, продолжает их создавать рядом с ResourceQuota и ProjectRoleBinding, которые создают стандартные поля. Под в таком проекте должен укладываться в каждую ResourceQuota своего неймспейса, а доступ, который выдают такие AuthorizationRule, добавляется к доступу из стандартных полей.

Квота проекта

Квота проекта — единый лимит на сумму потребления ресурсов по всем неймспейсам проекта, включая дополнительные. Она задаётся в поле .spec.quota проекта:

apiVersion: deckhouse.io/v1alpha3
kind: Project
metadata:
  name: my-project
spec:
  projectTemplateName: default
  quota:
    requests.cpu: "20"
    requests.memory: 40Gi
    projectNamespaces: "3"

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

Как применяется квота:

  • Контроллер создаёт ResourceQuota d8-project-quota с лимитами spec.hard в каждом неймспейсе проекта, в том числе добавленном позже. Этот объект ResourceQuota считает потребление своего неймспейса, поэтому ни один неймспейс в одиночку не использует больше, чем весь проект.
  • Неймспейс, в котором действует квота, получает лейбл projects.deckhouse.io/quota: enforced, когда kube-controller-manager рассчитал его d8-project-quota. Неймспейс, созданный для ProjectNamespace, до этого с момента создания несёт projects.deckhouse.io/quota: pending, а основной неймспейс проекта, который ещё не развёрнут, получает этот лейбл, когда применяется квота проекта, поэтому манифесты шаблона тоже ждут квоту, сколько бы ни длились неудачные первые попытки развернуть проект. Основной неймспейс развёрнутого проекта (в состоянии Deployed), например при обновлении модуля или при назначении квоты работающему проекту, не удерживается. Лейбл ставит только контроллер.
  • В неймспейсе с лейблом projects.deckhouse.io/quota: pending политика допуска d8-multitenancy-manager-quota-pending отклоняет объекты пользователей, пока d8-project-quota не рассчитан, а ProjectNamespace показывает Ready=False. После создания неймспейса это занимает секунды. В неймспейсе с лейблом projects.deckhouse.io/quota: enforced политика допуска d8-multitenancy-manager-quota-guard отклоняет объекты, которые считает квота, пока в d8-project-quota нет ни одного рассчитанного лимита или пока у него есть scopes. Лимит, добавленный в уже рассчитанную квоту, ничего не задерживает: он начинает действовать, когда kube-controller-manager его рассчитал, а до тех пор Enforced равно False с причиной KeyRollout.
  • ProjectQuotaStatus удаляется в два шага: финализатор projects.deckhouse.io/project-quota держит объект, пока контроллер не снимет лейбл с неймспейсов, и только потом вместе с ним удаляются объекты ResourceQuota d8-project-quota. С неймспейса, который удаляется, лейбл снимается сразу, чтобы объекты, ожидающие финализатор, например заявки на тома под защитой от удаления, можно было обновлять. Если модуль отключён раньше, чем финализатор снят, снимите его вручную.
  • В статусе ProjectQuotaStatus видны сумма потребления по неймспейсам (status.used), число неймспейсов и 50 неймспейсов, ближе всего подошедших к лимиту. Потребление каждого неймспейса — в его ResourceQuota d8-project-quota:

    d8 k get resourcequota -A -l projects.deckhouse.io/project=my-project
    
  • В неймспейсе с лейблом projects.deckhouse.io/quota: enforced создание объекта, после которого потребление всего проекта выходит за лимит, отклоняется с HTTP 403:

    admission webhook "quota-ledger.multitenancy-manager.deckhouse.io" denied the request: exceeded quota: d8-project-quota, project my-project: requested: requests.cpu=500m, used: requests.cpu=19800m, limited: requests.cpu=20 (3 namespaces)
    

    Вебхук, который называется счётчиком квот, хранит сумму каждого проекта в памяти своего лидера в контейнере quota-ledger пода модуля. Пока не отвечает ни одна реплика (несколько секунд при смене лидера), создание учитываемого квотой объекта в неймспейсе проекта с квотой завершается ошибкой project quota ledger unavailable (<CAUSE>), retry; удаления, работающие объекты и неймспейсы без квоты это не затрагивает. Deployment или Job повторяют такое создание сами. Тот же ответ сразу, с причиной too many approvals of the project are not confirmed yet, получает запись, которой пришлось бы ждать подтверждения прежних одобрений своего проекта, пока от того же API-сервера уже ждут две записи: третья ожидающая запись проекта от одного API-сервера получает 503, и её контроллер повторяет запрос.

  • Для запроса с --dry-run=server сумма не проверяется: API-сервер не записывает потребление при пробном запуске. Квота неймспейса при этом проверяется.
  • Условие Enforced говорит, действует ли квота во всех неймспейсах, а условие Exceeded — превышен ли какой-то лимит. Лимит можно опустить ниже текущего потребления: изменение принимается с предупреждением, ничто из работающего не вытесняется, а Exceeded становится True с причиной HardLowered. В этом случае срабатывает алерт D8ProjectQuotaExceeded.

Ключи квоты проекта

Поле .spec.quota принимает такие ключи:

  • cpu, memory, ephemeral-storage, pods, requests.* и limits.* для CPU, памяти и эфемерного хранилища, requests.storage, requests.hugepages-<SIZE>, запросы расширенных ресурсов (например, requests.nvidia.com/gpu);
  • services, services.loadbalancers, services.nodeports, persistentvolumeclaims, configmaps, secrets, replicationcontrollers;
  • <CLASS>.storageclass.storage.k8s.io/requests.storage и <CLASS>.storageclass.storage.k8s.io/persistentvolumeclaims, <CLASS>.deviceclass.resource.k8s.io/devices;
  • count/<RESOURCE>[.<GROUP>] для namespaced-ресурса, который обслуживает API-сервер, например count/ingresses.networking.k8s.io;
  • projectNamespaces — псевдоним count/projectnamespaces.deckhouse.io: число объектов ProjectNamespace проекта, то есть его дополнительных неймспейсов. В ResourceQuota псевдоним раскрывается, а в самом объекте остаётся как записан.
  • ключи виртуальных машин и балансировщиков нагрузки, которые не считает ни один ResourceQuota.

Отклоняются ключи resourcequotas и count/resourcequotas (d8-project-quota сам занимает по одному в каждом неймспейсе), счётчик cluster-wide-ресурса вроде count/namespaces, ресурс с опечаткой в обслуживаемой группе, ключ count/ ресурса, у которого нет одного из глаголов create, list, watch и delete, и ключи с зарезервированным префиксом projectquota.deckhouse.io/. Ключ count/ группы, которую API-сервер ещё не обслуживает, принимается с предупреждением: его ничто не считает, пока не включён модуль, предоставляющий группу, и до тех пор Enforced равно False с причиной KeyNotServed. Изменение, которое сохраняет уже имеющийся у объекта ключ, принимается с предупреждением, даже если сейчас такой ключ был бы отклонён.

Новый ключ в действующей квоте начинает работать, когда d8-project-quota каждого неймспейса рассчитан с ним; до тех пор Enforced равно False с причиной KeyRollout.

Поды и заявки на тома с лейблами resource-quota-overrides.deckhouse.io/*, которые ставят контроллеры платформы, считаются так, как их считает ResourceQuota.

Виртуальные машины в квоте проекта

Если включён модуль virtualization, квота проекта ограничивает виртуальные машины проекта по их спецификации. Эти ключи не считает ни один ResourceQuota, поэтому в d8-project-quota они не попадают: счётчик квот проверяет каждое создание VirtualMachine и каждое изменение её spec в неймспейсах проекта, в квоте которого они есть, и сам считает виртуальные машины по таким ключам:

  • virtualmachines.virtualization.deckhouse.io/cores — сумма spec.cpu.cores;
  • virtualmachines.virtualization.deckhouse.io/cpu — гарантированный CPU, сумма ядер × spec.cpu.coreFraction; пустое spec.cpu.coreFraction или Auto считается как целые ядра;
  • virtualmachines.virtualization.deckhouse.io/memory — сумма spec.memory.size;
  • virtualmachines.virtualization.deckhouse.io/gpus — число GPU в spec.gpus;
  • <GPU_CLASS>.gpuclass.virtualization.deckhouse.io/gpus — число GPU класса GPUClass <GPU_CLASS>.

Число виртуальных машин ограничивает обычный ключ count/virtualmachines.virtualization.deckhouse.io.

В ключах выше учитывается каждая виртуальная машина, в том числе остановленная: остановленную вручную машину могут запустить в любой момент. В них не учитывается только машина с runPolicy: AlwaysOff, которую намеренно держат выключенной; ключ count/virtualmachines.virtualization.deckhouse.io считает и такие машины. Изменение, которое не увеличивает ни один ключ, например уменьшение машины или её остановка, никогда не отклоняется по квоте и проходит, даже когда счётчик квот не отвечает; остальные создания и изменения spec требуют ответа счётчика. Изменение только метаданных машины счётчик не вызывает. Уменьшенная спецификация освобождает квоту, только когда машина начинает с ней работать: до перезапуска, который её применяет, машина учитывается с теми ядрами и памятью, с которыми работает (status.resources), и с GPU, которые показывают изменения в status.restartAwaitingChanges. Пока модуль virtualization не обработал изменение спецификации, машина учитывается так же, как до него. Неймспейсы такого проекта несут лейбл quota.projects.deckhouse.io/vm: enforced, его ставит контроллер. Пока модуль virtualization выключен, ключи ничего не считают, а Enforced равно False с причиной KeyNotServed. Квота принимается с предупреждением, если API-сервер не обслуживает VirtualMachine.

Под виртуальной машины учитывается и в requests.* и limits.*, а во время миграции — дважды. Квота, в которой есть и ключи виртуальных машин, и ключи подов (cpu, memory, requests.*, limits.*), принимается с предупреждением. Ограничивайте виртуальные машины их ключами, а контейнеры — requests.* и limits.*.

Балансировщики нагрузки в квоте проекта

Квота проекта ограничивает сервисы типа LoadBalancer проекта по классу, по пулу и по числу внешних адресов. Эти ключи не считает ни один ResourceQuota, поэтому в d8-project-quota они не попадают: счётчик квот проверяет каждое создание сервиса, который имеет или имел тип LoadBalancer, и каждое изменение его spec или аннотаций network.deckhouse.io/metal-load-balancer-class, network.deckhouse.io/l2-load-balancer-external-ips-count, network.deckhouse.io/load-balancer-ips и network.deckhouse.io/load-balancer-pool в неймспейсах проекта, в квоте которого они есть, и сам считает сервисы по таким ключам:

  • <CLASS>.loadbalancerclass.network.deckhouse.io/services — число балансировщиков нагрузки класса <CLASS>;
  • <CLASS>.loadbalancerclass.network.deckhouse.io/addresses — внешние адреса класса <CLASS>;
  • <POOL>.loadbalancerpool.network.deckhouse.io/addresses — адреса из пула <POOL> режима BGP;
  • loadbalancers.network.deckhouse.io/addresses — все внешние адреса проекта.

Число балансировщиков нагрузки любого класса ограничивает обычный ключ services.loadbalancers.

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

  • класс, к которому модуль metallb привязал сервис в его статусе, даже если такого MetalLoadBalancerClass нет;
  • spec.loadBalancerClass, если такой MetalLoadBalancerClass существует;
  • аннотация network.deckhouse.io/metal-load-balancer-class, если такой MetalLoadBalancerClass существует;
  • MetalLoadBalancerClass с isDefault: true;
  • spec.loadBalancerClass без проверки — класс другого контроллера балансировщиков нагрузки;
  • default — балансировщики нагрузки облачного провайдера.

Если API-сервер не обслуживает MetalLoadBalancerClass, классы не проверяются: класс — это spec.loadBalancerClass, иначе default, а аннотация, которую читает только модуль metallb, не учитывается. Включение или выключение модуля metallb счётчик квот замечает в течение 30 секунд и пересчитывает балансировщики нагрузки без перезапуска.

Сервис с аннотацией network.deckhouse.io/load-balancer-pool занимает один адрес этого пула. Остальные сервисы занимают столько адресов, сколько указано в аннотации network.deckhouse.io/l2-load-balancer-external-ips-count, если это число больше единицы, и один адрес, если в аннотации другое значение. Аннотация network.deckhouse.io/load-balancer-ips только выбирает, какие адреса займёт сервис, так их назначает модуль metallb.

Каждый сервис типа LoadBalancer считает собственные адреса, даже если он делит адрес с другими сервисами по аннотации network.deckhouse.io/load-balancer-shared-ip-key: два сервиса на одном адресе занимают в квоте два адреса. Неймспейсы такого проекта несут лейбл quota.projects.deckhouse.io/lb: enforced, его ставит контроллер.

Кластеры, в которых Deckhouse Platform не управляет control plane

Сумма по неймспейсам проекта ограничивается только там, где control plane кластера ведёт Deckhouse Platform (включён модуль control-plane-manager). В остальных кластерах политики допуска d8-multitenancy-manager-quota-pending и d8-multitenancy-manager-quota-guard не создаются, каждый ProjectQuotaStatus сообщает Enforced=False с причиной ControlPlaneNotManaged, а об этом говорит алерт D8ProjectQuotaNotSupported. У каждого неймспейса при этом остаётся свой ResourceQuota d8-project-quota, поэтому ни один неймспейс в одиночку не использует больше квоты всего проекта.

Как поделить квоту проекта между неймспейсами

Администратор проекта может создавать в неймспейсах проекта свои ResourceQuota. Такая квота только сужает квоту проекта: объект должен укладываться в каждый ResourceQuota своего неймспейса. Квота администратора проекта не может называться d8-project-quota и не может ограничивать resourcequotas или count/resourcequotas. ResourceQuota d8-project-quota, созданный не контроллером, или со scopes контроллер удаляет и создаёт заново.

Например, чтобы неймспейс my-project-db получал не больше четверти CPU проекта:

apiVersion: v1
kind: ResourceQuota
metadata:
  name: db-share
  namespace: my-project-db
spec:
  hard:
    requests.cpu: "5"

Кто управляет квотами

Чтобы изменить .spec.quota проекта, нужно право update на projects/quota в группе deckhouse.io для этого проекта. Его выдаёт capability d8:system-capability:multitenancy-manager:manage_quotas, которую включают роль IAM manager и роли выше. Право проверяет вебхук Project, поэтому тот, кто может создавать и менять проекты, не выбирает себе квоту сам. ProjectQuotaStatus пишет только контроллер; все остальные, в том числе администраторы кластера, могут его только читать. Потребление в статусе d8-project-quota пишет Kubernetes; от других писателей оно защищено там, где control plane ведёт Deckhouse Platform.

Когда квота проекта отказывает

Что означает ответ:

Ответ Что это значит
403 ... exceeded quota: d8-project-quota, project <PROJECT_NAME>: requested: ..., used: ..., limited: ... (<N> namespaces) Сумма проекта <PROJECT_NAME> вышла бы за квоту проекта. Поднимите лимиты в .spec.quota проекта или удалите лишнее; status.topNamespaces его ProjectQuotaStatus показывает, где потребление.
403 ... exceeded quota: d8-project-quota, requested: ... (без project) Потребление одного этого неймспейса вместе с объектом вышло бы за лимит проекта, который содержит каждый ResourceQuota d8-project-quota. Плагин квот API-сервера отклоняет объект до проверки суммы проекта.
503 ... project quota ledger unavailable (<CAUSE>), retry Счётчик ненадолго не отвечает, например при смене лидера. Повторите запрос; если это длится дольше минуты, воспользуйтесь описанием алерта D8ProjectQuotaLedgerDown.
500 ... failed calling webhook "quota-ledger.multitenancy-manager.deckhouse.io": ... или с quota-vm.multitenancy-manager.deckhouse.io, quota-lb.multitenancy-manager.deckhouse.io API-сервер не достучался до счётчика: не запущена ни одна реплика, сеть или сертификат. Пока Service указывает на замороженного лидера, плагин квот API-сервера повторяет вызов, поэтому каждое такое создание ждёт примерно до 8 секунд, пока адрес лидера не уберут из Service: примерно за 3,5 секунды это делает вторая реплика, примерно до 15 секунд — Deckhouse, если не отвечает ни одна реплика.
403 ... ValidatingAdmissionPolicy 'd8-multitenancy-manager-quota-pending' ... ResourceQuota d8-project-quota нового неймспейса ещё не рассчитан. Повторите через несколько секунд; если это затянулось, посмотрите условие Enforced в ProjectQuotaStatus проекта и проверьте контроллер и kube-controller-manager.
403 ... ValidatingAdmissionPolicy 'd8-multitenancy-manager-quota-guard' ... ResourceQuota d8-project-quota неймспейса отсутствует, имеет scopes или ещё совсем не рассчитан. Повторите через несколько секунд; иначе проверьте контроллер и kube-controller-manager.
500 ... resource quota evaluation timed out Перегружена проверка квот в API-сервере, подробнее — в описании алерта D8ResourceQuotaAdmissionDegraded.

Новый дополнительный неймспейс несколько секунд отклоняет объекты пользователей, пока его d8-project-quota не рассчитан. То же происходит в неймспейсе, где действует квота, если его d8-project-quota пропал: пока контроллер не создаст его заново, отклоняются и объекты system:sudouser. Из пользователей удалить d8-project-quota может только system:sudouser.

Если счётчик не даёт создавать объекты проектов и причину быстро не устранить, выполняйте шаги по порядку, пока создание объектов не заработает:

  1. Если создание объектов завершается ошибкой 503 ... project quota ledger unavailable, реплика отвечает, и приостановка счётчика помогает. В течение секунды каждая запущенная реплика начинает пропускать записи без подсчёта, а каждый ProjectQuotaStatus показывает Enforced=False с причиной Suspended. Удаление ConfigMap возобновляет проверку; через 15 минут о ней напомнит алерт D8ProjectQuotaSuspended.

    d8 k -n d8-multitenancy-manager create configmap quota-ledger-suspend --from-literal=reason="<REASON>"
    d8 k -n d8-multitenancy-manager delete configmap quota-ledger-suspend
    

    Вместо <REASON> укажите, почему проверка приостановлена.

  2. Если создание объектов завершается ошибкой 500 ... failed calling webhook "quota-ledger.multitenancy-manager.deckhouse.io", API-серверы не достают до отвечающей реплики, как при сработавшем алерте D8ProjectQuotaLedgerDown, и приостановка не помогает: удалите вебхук счётчика от имени system:sudouser. Проверка прекращается в течение секунды, и каждый ProjectQuotaStatus показывает Enforced=False с причиной WebhookMissing. Deckhouse Platform сам обнаружит, что вебхука модуля нет, и вернёт его примерно за 4 минуты, поэтому это лишь даёт время устранить причину, а не выключает проверку.

    d8 k --as=system:sudouser delete validatingwebhookconfiguration d8-multitenancy-manager-quota-ledger
    

    Проверьте, что вебхук вернулся: d8 k get validatingwebhookconfiguration d8-multitenancy-manager-quota-ledger.

  3. Отключите модуль multitenancy-manager. Проверка перестаёт действовать вместе со всем остальным, что модуль делает для проектов.

Перед выполнением drain рабочих узлов кластера с квотами проектов (вытеснением подов с узлов командой d8 k drain или при обновлении узлов) убедитесь, что у счётчика есть лидер (d8_multitenancy_quota_ledger_leader) и не срабатывает алерт D8ProjectQuotaLedgerCanaryFailing: пока счётчик не отвечает, поды на замену вытесненным в неймспейсах проектов с квотой не создаются.

Предоставление доступа внутри проекта

Чтобы предоставить доступ к неймспейсам проекта пользователям помимо администраторов проекта, используйте привязки ролей, которые ссылаются на кластерные роли и автоматически разворачиваются в нужные неймспейсы проектов:

  • ProjectRoleBinding (namespaced-ресурс, короткое имя prb) — предоставляет роль в рамках одного проекта. Должен создаваться в главном неймспейсе проекта (имя которого совпадает с именем проекта). Контроллер создаёт RoleBinding в каждом неймспейсе этого проекта.
  • ClusterProjectRoleBinding (cluster-wide-ресурс, короткое имя cprb) — предоставляет роль во всех проектах, кроме виртуальных. Контроллер создаёт RoleBinding в каждом неймспейсе каждого проекта и сообщает количество затронутых проектов в .status.boundProjects.

roleRef должен ссылаться на ClusterRole, имя которой начинается с одного из разрешённых префиксов (d8:project:, d8:namespace:, d8:project-capability:, d8:namespace-capability:, d8:custom:). Описание ролей — в документации модуля user-authz.

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

  • Защита от повышения привилегий: создать привязку может только пользователь, у которого есть право привязывать (bind) указанную роль; право проверяется по имени роли. У администратора проекта (d8:project:admin) есть bind ровно на восемь ролей: d8:project:viewer, d8:project:user, d8:project:manager, d8:project:admin, d8:namespace:viewer, d8:namespace:user, d8:namespace:manager и d8:namespace:admin. Привязка к любой другой роли — кастомной d8:custom:*, роли-capability (d8:*-capability:*), d8:project:superadmin — для администратора проекта отклоняется, даже если роль уже его собственных полномочий, потому что право bind на это имя ему никто не выдал. Такие привязки создаёт администратор кластера, либо он отдельной ClusterRole выдаёт администраторам проекта право bind на собственную роль.
  • Роль должна существовать: привязка к несуществующей роли отклоняется.
  • ServiceAccount в качестве субъекта ProjectRoleBinding должен принадлежать неймспейсу этого же проекта. Подходят основной неймспейс, дополнительные неймспейсы и неймспейс, который занял ресурс ProjectNamespace этого проекта. Неймспейс отдельного проекта, который только называется как дополнительный (<проект>-*), не подходит. При обновлении привязки ServiceAccount, который уже есть в сохранённой привязке, повторно не отклоняется. Если его неймспейс больше не относится к проекту, ответ содержит предупреждение, что этот ServiceAccount не получает прав по привязке.
  • Системные и подсистемные роли (d8:system:*, d8:subsystem:*), а также произвольные роли вне перечисленных префиксов через проектные привязки выдать нельзя.
  • Роли с аннотацией rbac.deckhouse.io/disabled-for-direct-use-in-projects: "true" запрещены для выдачи в проектах. Эту аннотацию администратор кластера может поставить на роль, чтобы прекратить её использование: при этом существующие привязки продолжают работать, но новые не создаются. Если такую роль использует шаблон проекта, проект переходит в статус Error с пояснением в условии TemplateRolesAllowed.

Контроллер проверяет ServiceAccount по тому же правилу каждый раз, когда обновляет RoleBinding привязки ProjectRoleBinding, а также когда неймспейс появляется, удаляется или переходит в другой проект. Субъект, который указывает на ServiceAccount, попадает в RoleBinding, только пока неймспейс этих ServiceAccount является основным неймспейсом проекта или существует, не удаляется и несёт лейбл projects.deckhouse.io/project с именем проекта. Кроме субъектов вида ServiceAccount, это касается субъекта User с именем system:serviceaccount:<неймспейс>:<имя> и субъекта Group с именем system:serviceaccounts:<неймспейс>, которые RBAC сопоставляет с теми же ServiceAccount. Остальных пользователей и групп это не касается. Поэтому ServiceAccount удалённого дополнительного неймспейса не получает прав, если имя этого неймспейса позже займёт отдельный проект.

Исключённые субъекты остаются в .spec.subjects. Условие SubjectsBound привязки принимает значение False и перечисляет их, а при изменении этого списка отправляется Warning-событие SubjectsLeftOut. Условие Ready остаётся True, так как для остальных субъектов привязка продолжает работать. Когда неймспейс снова относится к проекту, например после повторного создания удалённого ProjectNamespace, субъекты снова получают права без изменения привязки. Проверить условие можно по статусу привязки:

d8 k -n my-project get projectrolebinding ci -o jsonpath='{.status.conditions[?(@.type=="SubjectsBound")]}'

Привязка d8-administrators, создаваемая контроллером из поля .spec.administrators, управляется только контроллером — редактировать её вручную нельзя. Чтобы изменить состав администраторов, измените поле .spec.administrators проекта.

Описанное выше правило для ServiceAccount к этой привязке не применяется. Администратор, заданный как User system:serviceaccount:<неймспейс>:<имя> или Group system:serviceaccounts:<неймспейс>, получает права во всех неймспейсах проекта, к какому бы проекту ни относился этот неймспейс, так как администраторов проекта задаёт только тот, кому разрешено изменять Project. Удалите такого администратора из проекта до удаления его неймспейса, иначе права получат ServiceAccount неймспейса, который позже создадут под тем же именем.

Следующие привязки выдают пользователю viewer@example.com роль d8:project:viewer во всех неймспейсах проекта my-project, а группе platform — ту же роль во всех проектах, кроме виртуальных:

---
apiVersion: deckhouse.io/v1alpha3
kind: ProjectRoleBinding
metadata:
  name: viewers
  namespace: my-project
spec:
  subjects:
    - kind: User
      name: viewer@example.com
  roleRef:
    kind: ClusterRole
    name: d8:project:viewer
---
apiVersion: deckhouse.io/v1alpha3
kind: ClusterProjectRoleBinding
metadata:
  name: platform-viewers
spec:
  subjects:
    - kind: Group
      name: platform
  roleRef:
    kind: ClusterRole
    name: d8:project:viewer

Роли, доступные в RoleBinding внутри проекта

Кроме проектных привязок, внутри неймспейса проекта можно использовать и обычный RoleBinding — тогда роль действует только в этом одном неймспейсе. Но в проектах набор ролей, доступных для обычного RoleBinding, ограничен: разрешены только кластерные роли с лейблом rbac.deckhouse.io/delegatable: "true". Из встроенных это роли d8:namespace:* и d8:project:*, а также роли уровней доступа упрощённой ролевой модели (user-authz:user, user-authz:privileged-user, user-authz:editor, user-authz:admin).

RoleBinding на любую другую кластерную роль (например, cluster-admin, системные роли или capabilities) в проекте будет отклонён с сообщением references "<роль>" which is not available to project. Это защита от обхода изоляции проекта через привязку к слишком широкой роли.

Чтобы использовать в проектах собственную роль, добавьте на неё лейбл rbac.deckhouse.io/delegatable: "true":

d8 k label clusterrole d8:custom:namespace:developer rbac.deckhouse.io/delegatable=true

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

Структурированные шаблоны

Шаблон проекта deckhouse.io/v1alpha2 описывается структурированными полями. Вы декларативно указываете, какие настройки получат неймспейсы проекта. Контроллер сам создаёт из этих полей нужные объекты (сетевые политики, политики безопасности, настройки сбора логов и т. д.) в каждом неймспейсе проекта и поддерживает их в актуальном состоянии. Другие объекты неймспейсов проекта описываются в manifests.

Доступные поля (все — необязательные; полный справочник — в описании ресурса ProjectTemplate):

Поле Что настраивает
podSecurityStandard Профиль безопасности подов: Privileged, Baseline или Restricted. Параметр с пустым значением не задаёт профиль
networkPolicy.mode Сетевая изоляция: Isolated (трафик разрешён только внутри проекта и от системных компонентов платформы) или NotRestricted
features.monitoring Расширенный мониторинг неймспейсов проекта
features.vulnerabilityScanning Сканирование образов контейнеров на уязвимости
logShipping.clusterDestinationRef Сбор логов подов проекта в указанное хранилище (ClusterLogDestination)
nodeSelector, tolerations Размещение подов основного неймспейса на выделенных узлах
allowedUIDs, allowedGIDs Допустимые диапазоны UID/GID контейнеров проекта
runtimeAudit.enabled Аудит обращений процессов проекта к ядру Linux
namespaceMetadata.labels, namespaceMetadata.annotations Дополнительные лейблы и аннотации неймспейсов проекта. Лейблы, которыми управляет модуль, здесь задать нельзя. Шаблон или Project с таким лейблом отклоняется. Шаблон или Project, в котором такой лейбл уже есть, можно изменять, пока лейбл остаётся прежним. Лейбл не применяется, и ответ API предупреждает об этом
resources, grantPolicies Выдача cluster-wide-ресурсов через шаблон проекта
manifests Другие объекты в неймспейсах проекта, которые применяются с правами администратора проекта. Подробнее — в разделе «Описание других объектов в manifests»
parametersSchema.openAPIV3Schema Схема параметров, которые задаются при создании проекта

Пример структурированного шаблона:

apiVersion: deckhouse.io/v1alpha2
kind: ProjectTemplate
metadata:
  name: my-template
spec:
  title: "Шаблон команды"
  description: "Изолированный проект с мониторингом"
  podSecurityStandard: Baseline
  networkPolicy:
    mode: Isolated
  features:
    monitoring: true
    vulnerabilityScanning: true

Параметризация шаблона

Параметром можно задать следующие поля шаблона: podSecurityStandard, networkPolicy.mode, features.monitoring, features.vulnerabilityScanning, logShipping.clusterDestinationRef, nodeSelector, tolerations, allowedUIDs, allowedGIDs, runtimeAudit.enabled, namespaceMetadata.labels и namespaceMetadata.annotations. Вместо конкретного значения укажите {fromParam: <имя параметра>} и объявите параметр в parametersSchema. Значение не обязательно должно быть скалярным: параметром может быть и словарь (nodeSelector, namespaceMetadata.labels), и список (tolerations), и объект (allowedUIDs). Остальные поля — title, description, resources, grantPolicies и сам parametersSchema — принимают только конкретные значения. Тогда каждый проект задаёт своё значение в .spec.parameters, а если значение не задано — используется default из схемы.

apiVersion: deckhouse.io/v1alpha2
kind: ProjectTemplate
metadata:
  name: my-parametrized-template
spec:
  podSecurityStandard:
    fromParam: securityProfile
  networkPolicy:
    mode:
      fromParam: networkMode
  parametersSchema:
    openAPIV3Schema:
      type: object
      properties:
        securityProfile:
          type: string
          enum: [Baseline, Restricted]
          default: Baseline
        networkMode:
          type: string
          enum: [Isolated, NotRestricted]
          default: Isolated

Проект, использующий такой шаблон:

apiVersion: deckhouse.io/v1alpha3
kind: Project
metadata:
  name: my-project
spec:
  projectTemplateName: my-parametrized-template
  parameters:
    securityProfile: Restricted

Шаблон, в parametersSchema которого по-прежнему объявлены параметры administrators и resourceQuota, продолжает принимать проекты. Схема объявляет их по имени или через additionalProperties, которое принимает все параметры, не названные в схеме, если оно принимает эти два параметра в том виде, в каком их содержит Project v1alpha2. Параметры проекта проверяются по такой схеме вместе с .spec.administrators и .spec.quota, разложенными обратно в parameters.administrators и parameters.resourceQuota так, как их раскладывает вебхук конвертации для v1alpha2. Значение квоты проверяется в первой форме, которую принимает схема, сначала в каноническом написании (например, 1Gi для 1024Mi), затем как число (например, 1000 для 1k), затем с другой единицей измерения (например, 2000m для 2, если в схеме указано pattern: ^[0-9]+m$). Обязательное поле, которое в проекте пустое, проверяется в пустом виде ([] для администраторов, {} для квоты). Helm-шаблон в resourcesTemplate и manifests получают в .parameters параметры, разложенные так же, поэтому шаблон, написанный для проектов v1alpha2, по-прежнему рендерит из них свои объекты. Значение квоты попадает в шаблон в той форме, в которой оно проверяется, поэтому для схемы, принимающей строки, ноль передаётся строкой "0", и with и if считают его заданным. Структурированные поля эти значения как параметры не получают.

Схема, которая не называет параметры administrators и resourceQuota и не принимает неназванные параметры через additionalProperties, их не объявляет, и схемы встроенных шаблонов их тоже не объявляют. Для шаблона с такой схемой эти параметры не дают доступа и не задают квоту. Проект, в котором они есть, например пустой список или квота с числом 0, которые вебхук конвертации оставляет в parameters, продолжает работать, и его можно изменять. Изменение, которое оставляет такое значение прежним, в том числе при переходе на другой шаблон, который их тоже не объявляет, принимается с предупреждением, как и пустой список и квота, в которой нет значений, кроме числа 0. Любое другое новое или изменённое значение отклоняется. Вместо этого укажите администраторов в .spec.administrators и квоту в .spec.quota. В манифесте v1alpha2 запишите их в том виде, в котором вебхук конвертации переносит их в эти поля. Любой другой параметр, который схема не объявляет, по-прежнему отклоняется.

Ссылки fromParam проверяются при создании и изменении шаблона: ссылка на параметр, не определённый в шаблоне, или параметр несовместимого типа (например, строковый параметр для булева поля) будет отклонена.

Тип объявленного параметра проверяется и там, где схема разрешает необъявленные ключи с помощью additionalProperties или x-kubernetes-preserve-unknown-fields. Ссылка на необъявленный ключ допускается только в таких местах, и тип такого ключа не проверяется.

Параметр requiredRequests контроллер читает по имени, без fromParam. Если шаблон объявляет его в parametersSchema с типом boolean и для проекта он равен true, контроллер создаёт OperationPolicy в режиме Deny, которая требует задавать CPU и memory requests у подов во всех неймспейсах проекта. Шаблон, в котором параметр не объявлен, такую политику не создаёт, даже если схема шаблона разрешает additionalProperties, а проект задаёт requiredRequests необъявленным ключом. Чтобы политика действовала, пока проект её не выключит, объявите параметр с default: true, как в шаблонах default, secure и secure-with-dedicated-nodes:

spec:
  parametersSchema:
    openAPIV3Schema:
      type: object
      properties:
        requiredRequests:
          type: boolean
          default: true

Проверки шаблонов

Для действий над шаблонами существуют следующие правила:

  • Шаблон нельзя удалить, пока его использует хотя бы один проект или пока он ещё применён хотя бы к одному неймспейсу проекта. Если проект перешёл на другой шаблон, старый шаблон остаётся, пока контроллер не применит новый.
  • Изменение шаблона автоматически применяется ко всем проектам, созданным из него.
  • Вместо структурированных полей шаблон может описывать свои объекты Helm-текстом в поле resourcesTemplate. Такой шаблон рендерится через Helm с именем проекта (.projectName), именем шаблона (.projectTemplateName) и параметрами проекта (.parameters), и resourcesTemplate нельзя задать вместе с полями, которые рендерят объекты в неймспейсах, или с manifests. Шаблон, который используют проекты, сохраняет непустое resourcesTemplate, пока изменение не задаст такие поля или manifests вместо него. Что такое изменение или перевод проекта на другой шаблон делает с объектами, созданными Helm-текстом, описано в разделе «Переход проекта с Helm-текста». Проект, параметры которого превращаются в объекты или ключи отрендеренных манифестов, а не в значения, отклоняется, поэтому заключайте в кавычки каждую подстановку. Эта форма устарела, и поле resourcesTemplate будет удалено из deckhouse.io/v1alpha2 вместе с deckhouse.io/v1alpha1 в одном из следующих релизов. Алерт MultitenancyManagerHelmProjectTemplate называет каждый шаблон, кроме встроенных, который всё ещё рендерится из Helm-текста. Описывайте новые шаблоны структурированными полями и manifests, а существующие переведите так, как описано в разделе «Перевод шаблона с Helm-текста».
  • Шаблон не может получить новое resourcesTemplate ни через одну из версий. Создание шаблона с непустым resourcesTemplate и изменение, которое задаёт его шаблону с пустым resourcesTemplate, отклоняются. Шаблон, у которого есть Helm-текст, сохраняет его, и текст можно менять через любую из двух версий, пока deckhouse.io/v1alpha1 может описать весь шаблон. Поэтому шаблон с Helm-текстом нельзя создать заново, например из манифеста, выгруженного из другого кластера, из резервной копии или из Git после удаления шаблона. Сначала переведите такой шаблон на структурированные поля и manifests.
  • Версия deckhouse.io/v1alpha1 ресурса ProjectTemplate обслуживается и помечена как устаревшая, и API-сервер возвращает предупреждение на каждый запрос через неё. Шаблон создаётся только через deckhouse.io/v1alpha2, а создание через deckhouse.io/v1alpha1 отклоняется. Шаблоны, созданные через deckhouse.io/v1alpha1 раньше, читаются, меняются и удаляются через неё, как и прежде. В этой версии есть поля description, parametersSchema и resourcesTemplate, и deckhouse.io/v1alpha2 сохраняет все три, поэтому шаблон, записанный как v1alpha1, читается без изменений. Изменение через v1alpha1 шаблона, в котором есть поля, которых нет в v1alpha1, например title, grantPolicies, podSecurityStandard или manifests, отклоняется, потому что оно стёрло бы их. Меняйте такой шаблон через deckhouse.io/v1alpha2.

Описание других объектов в manifests

Структурированные поля описывают настройки, которые нужны большинству проектов. Другие объекты неймспейсов проекта, например рабочие нагрузки и объекты ConfigMap, RoleBinding или LimitRange, описываются в поле manifests. Это текст в формате go template с функциями helm, как и resourcesTemplate, и шаблон может задать его вместе со структурированными полями.

manifests и resourcesTemplate различаются тем, с чьими правами создаются объекты. Helm-текст из resourcesTemplate контроллер устанавливает как Helm-релиз со своими правами, которые действуют во всём кластере. Поэтому такой текст может создать любой объект уровня кластера, кроме неймспейса, и любой объект в неймспейсах проекта. Объекты из manifests контроллер применяет от имени пользователя проекта, у которого есть роль d8:project:admin в неймспейсах проекта. Поэтому шаблон получает права администратора проекта, а не права контроллера.

Текст получает имя проекта в .projectName, имя шаблона в .projectTemplateName и параметры проекта, дополненные значениями по умолчанию из parametersSchema, в .parameters, то есть те же значения, что и resourcesTemplate. Проект, параметры которого превращаются в объекты или ключи отрендеренных манифестов, а не в значения, отклоняется, поэтому заключайте в кавычки каждую подстановку. Текст рендерится без доступа к кластеру, поэтому функция lookup ничего не находит. Шаблон проекта могут прочитать и пользователи без доступа к его проектам, в том числе пользователи с уровнем доступа User, поэтому не помещайте в manifests секретные значения.

Объекты применяются по следующим правилам:

  • Контроллер создаёт в основном неймспейсе проекта ProjectRoleBinding d8-manifests. Он выдаёт пользователю system:multitenancy-manager:project:<PROJECT_NAME> роль d8:project:admin во всех неймспейсах проекта.
  • Объекты применяются, когда эта привязка стала Ready для своего текущего поколения, а у ClusterRole d8:project:admin появились агрегированные правила. До этого условие ManifestsApplied проекта говорит, чего ждут объекты, а проект остаётся в состоянии Deployed.
  • Каждый объект применяется через server-side apply от имени этого пользователя с менеджером полей multitenancy-manager/manifests. Объект без metadata.namespace создаётся в основном неймспейсе проекта. Объект может создаваться и в дополнительном неймспейсе проекта, в том числе в неймспейсе, который создаёт ProjectNamespace из тех же manifests, как описано в разделе «Дополнительные неймспейсы в manifests».
  • Каждый объект получает лейблы projects.deckhouse.io/project: <PROJECT_NAME> и projects.deckhouse.io/source: manifests, а .status.manifestObjects проекта перечисляет объекты.
  • Уже существующий объект применяется, только если он принадлежит проекту, то есть если его перечисляет .status.manifestObjects, если переход с Helm-текста оставил его в .status.keptObjects или если на нём есть оба лейбла. Любой другой объект остаётся нетронутым, как описано в разделе «Ограничения manifests».
  • Объекты не получают лейбл heritage: multitenancy-manager. Вместо него они получают лейбл projects.deckhouse.io/source: manifests и, как объекты из структурированных полей и из Helm-текста, меняются только через шаблон. Политика d8-multitenancy-manager-manifests-objects не даёт создать, изменить или удалить такой объект никому, в том числе администраторам проекта и кластера. Это могут сделать только пользователь, от имени которого применяются manifests проекта, контроллер, ServiceAccount неймспейсов d8-* и компоненты кластера. Перезапустить rollout рабочей нагрузки может любой, кому разрешено её изменять, если единственное изменение — аннотация kubectl.kubernetes.io/restartedAt у шаблона пода. metadata.resourceVersion, metadata.generation и metadata.managedFields не сравниваются, потому что их записывает API-сервер. В течение 10 минут контроллер применяет объекты снова и возвращает поля, которые задаёт шаблон, если их изменило что-то ещё.
  • Объект, который шаблон больше не рендерит, удаляется от имени того же пользователя после того, как применены остальные объекты, и только если ни один из них не был отклонён или оставлен нетронутым. Он удаляется через ту версию, в которой API-сервер обслуживает его тип, даже если объект применялся через другую. Объект, с которого сняли один из двух лейблов, и объект, неймспейс которого больше не принадлежит проекту, исчезают из списка и остаются на месте. Снять лейбл могут только ServiceAccount неймспейсов d8-*, в том числе контроллер, и компоненты кластера. Пользователь, от имени которого применяются manifests, может снять только лейбл projects.deckhouse.io/source.
  • Когда одно изменение заставляет релиз проекта рендерить объект, который применили manifests, с тем же типом, неймспейсом и именем, релиз забирает объект себе, и объект остаётся в кластере. Пока обновление не завершится, объект есть в .status.handingOver и нет в .status.manifestObjects. Если обновление не развернуло объект, он возвращается под управление manifests, и .status.manifestObjects снова его перечисляет.
  • Если то же изменение заставляет релиз рендерить другой объект, который уже есть без признаков владения этого релиза и не принадлежит manifests, Helm не может забрать этот объект. Признаки владения — лейбл app.kubernetes.io/managed-by: Helm и аннотация meta.helm.sh/release-name с именем релиза проекта. Контроллер тогда не запускает обновление и не меняет объекты manifests, а условие ResourcesUpgraded проекта называет объект, который мешает обновлению. Передача продолжится, когда этот объект удалят или на нём появятся признаки владения.
  • Когда из шаблона убирают manifests или проект переводят на шаблон без этого поля, объекты удаляются, а затем удаляется привязка d8-manifests. Когда удаляют проект, сначала удаляется привязка, а объекты удаляются вместе с неймспейсами.

Привязывать пользователей, имена которых начинаются с system:multitenancy-manager:, может только контроллер. RoleBinding, ClusterRoleBinding, ProjectRoleBinding, ClusterProjectRoleBinding, AuthorizationRule или ClusterAuthorizationRule, в котором указан такой пользователь или такая группа, отклоняется для всех остальных, кроме сборщика мусора и system:sudouser (подробнее в разделе «Кто обходит валидацию»). Привязать такого пользователя может и Helm-текст в resourcesTemplate, потому что контроллер устанавливает его со своими правами. В остальном объекты шаблона получают права привязки d8-manifests и права, которые кластер выдаёт каждому аутентифицированному пользователю (группа system:authenticated). По той же причине проект не может указать такого пользователя или такую группу среди своих администраторов, ни в .spec.administrators, ни в параметре administrators. Имя, которое у проекта уже есть, принимается с предупреждением, поэтому проект по-прежнему можно редактировать и это имя можно удалить.

Следующий шаблон задаёт профиль безопасности подов и сетевую изоляцию структурированными полями и создаёт в manifests два объекта, LimitRange с лимитами по умолчанию из параметров проекта и ConfigMap с именами проекта и его шаблона:

apiVersion: deckhouse.io/v1alpha2
kind: ProjectTemplate
metadata:
  name: team-with-limits
spec:
  podSecurityStandard: Baseline
  networkPolicy:
    mode: Isolated
  parametersSchema:
    openAPIV3Schema:
      type: object
      properties:
        defaultCPU:
          type: string
          default: 500m
        defaultMemory:
          type: string
          default: 512Mi
  manifests: |
    apiVersion: v1
    kind: LimitRange
    metadata:
      name: container-defaults
    spec:
      limits:
        - type: Container
          default:
            cpu: {{ .parameters.defaultCPU | quote }}
            memory: {{ .parameters.defaultMemory | quote }}
    ---
    apiVersion: v1
    kind: ConfigMap
    metadata:
      name: project-info
    data:
      project: {{ .projectName | quote }}
      template: {{ .projectTemplateName | quote }}

Когда условие ManifestsApplied равно True, в основном неймспейсе каждого проекта этого шаблона есть LimitRange container-defaults и ConfigMap project-info. Чтобы проверить условие и вывести применённые объекты, используйте команды:

d8 k get project <PROJECT_NAME> -o jsonpath='{.status.conditions[?(@.type=="ManifestsApplied")]}'
d8 k get project <PROJECT_NAME> -o jsonpath='{range .status.manifestObjects[*]}{.kind} {.namespace}/{.name}{"\n"}{end}'

Дополнительные неймспейсы в manifests

manifests может создавать дополнительные неймспейсы проекта объектами ProjectNamespace и в том же тексте класть в них объекты. ProjectNamespace без metadata.namespace создаётся в основном неймспейсе проекта, а его неймспейс называется <PROJECT_NAME>-<spec.name>, поэтому объект в нём указывает неймспейс как {{ .projectName }}-<spec.name>.

При первом рендере такого неймспейса ещё нет, поэтому объекты применяются в два шага:

  • Объекты ProjectNamespace и объекты уже существующих неймспейсов применяются сразу.
  • Объекты неймспейса, который создаёт ProjectNamespace из тех же manifests, ждут, пока неймспейс появится и в нём появится привязка d8-manifests. До этого условие ManifestsApplied равно False и называет, чего ждут объекты, а проект остаётся в состоянии Deployed. Удаляемый неймспейс условие называет отдельно от ещё не созданного. Если ProjectNamespace не Ready, в условие попадает сообщение его Ready=False. Объекты, которые ждут, остаются. Объекты, которые manifests больше не описывает, удаляются. Проект пересчитывается, когда неймспейс создан и когда в нём появилась привязка, поэтому объекты применяются без каких-либо действий.
  • Когда ProjectNamespace пропадает из manifests, он удаляется, а его неймспейс удаляется вместе со всем содержимым. Объекты manifests в этом неймспейсе уходят из .status.manifestObjects без отдельного удаления.

Объект в неймспейсе, который не принадлежит проекту и который не создаёт ProjectNamespace из тех же manifests, отклоняется, как описано в разделе «Ограничения manifests». Создание или изменение проекта, manifests которого рендерит такой объект, принимается с предупреждением, которое называет этот неймспейс.

Следующие manifests создают неймспейс backend и кладут в него ConfigMap:

manifests: |
  apiVersion: deckhouse.io/v1alpha3
  kind: ProjectNamespace
  metadata:
    name: backend
  spec:
    name: backend
  ---
  apiVersion: v1
  kind: ConfigMap
  metadata:
    name: backend-settings
    namespace: "{{ .projectName }}-backend"
  data:
    team: {{ .parameters.team | quote }}

Ограничения manifests

manifests позволяет сделать только то, что может сделать администратор проекта в его неймспейсах. Действуют следующие ограничения:

  • Текст, который не рендерится для проекта, например из-за синтаксической ошибки или обязательного значения (required), которое проект не задаёт, принимается при записи шаблона, потому что в этот момент шаблон не рендерится. Такой проект переходит в состояние Error, ManifestsApplied называет ошибку, а создание или изменение проекта отклоняется, пока текст не начнёт рендериться. Изменение manifests сразу доходит до всех проектов шаблона, поэтому сначала проверьте его на копии шаблона с одним проектом.
  • Объект уровня кластера, объект в неймспейсе, который не принадлежит проекту и который не создаёт ProjectNamespace из тех же manifests, объект с лейблом heritage: multitenancy-manager или heritage: deckhouse, объект без metadata.name и объект, который текст рендерит дважды, отклоняются. Пока в рендере есть такой объект, не применяется ни один из его объектов, проект переходит в состояние Error, а условие ManifestsApplied называет этот объект.
  • Уже существующий объект, который не принадлежит проекту, например созданный администратором проекта вручную, не меняется, не попадает в список и позже не удаляется. Остальные объекты применяются, но ничего не удаляется, проект переходит в состояние Error, ManifestsApplied называет этот объект, а контроллер проверяет его снова каждую минуту. Чтобы передать объект под управление manifests, добавьте на него лейблы projects.deckhouse.io/project: <PROJECT_NAME> и projects.deckhouse.io/source: manifests или удалите его, чтобы manifests создал его заново. Добавить лейблы может только пользователь, которому разрешено изменять объекты этого типа во всех неймспейсах, например администратор кластера. AuthorizationRule с уровнем доступа Admin так не удаляйте, потому что manifests его не создаёт. Добавьте на него лейблы.
  • Объект, создание которого роль d8:project:admin не разрешает, API-сервер отклоняет с кодом 403 Forbidden. Например, это RoleBinding на роль, которую администратор проекта не может привязать, и объект типа, который роль не покрывает. Остальные объекты применяются, проект переходит в состояние Error, ManifestsApplied называет отклонённый объект, а контроллер повторяет попытку с растущим интервалом.
  • AuthorizationRule с уровнем доступа Admin отклоняется, когда manifests создаёт его, повышает до этого уровня уже существующий или добавляет субъекты в существующий с этим уровнем, хотя роль d8:project:admin это разрешает. Администраторы проекта задаются в .spec.administrators объекта Project. AuthorizationRule с уровнем User, PrivilegedUser или Editor применяется, как и другие объекты. Проект переходит в состояние Error, как и для объекта, который роль не разрешает, а создание или изменение проекта, manifests которого рендерит отклоняемый AuthorizationRule, принимается с предупреждением, которое его называет. Создание шаблона, manifests которого описывает AuthorizationRule, и изменение таких manifests принимаются с предупреждением об этом отказе. Уже существующий AuthorizationRule, например оставленный на месте при переходе с Helm-текста, переходит под управление manifests и меняется, как и другие объекты, если manifests не повышает его до уровня Admin и не добавляет в него субъекты на этом уровне.
  • Объект типа, который API-сервер не обслуживает, не даёт применить ни один объект. Проект переходит в состояние Error, а контроллер повторяет попытку каждую минуту, например пока включается модуль, который добавляет этот тип.
  • manifests нельзя задать вместе с resourcesTemplate.
  • В deckhouse.io/v1alpha1 нет места для manifests, поэтому запись через deckhouse.io/v1alpha1 в шаблон, в котором это поле есть, отклоняется.
  • Лейблы projects.deckhouse.io/skip-heritage-label и projects.deckhouse.io/unmanaged из Helm-текста не действуют на объекты из manifests.

manifests не создаёт объекты уровня кластера. Чтобы выдать проектам шаблона доступ к cluster-wide-ресурсам, используйте resources и grantPolicies. Другие объекты уровня кластера администратор кластера создаёт вне шаблона.

Перевод шаблона с Helm-текста

Шаблон с Helm-текстом в resourcesTemplate продолжает работать, но эта форма устарела. Поле resourcesTemplate будет удалено из deckhouse.io/v1alpha2 вместе с deckhouse.io/v1alpha1 в одном из следующих релизов, а получить новое не может ни один шаблон (подробнее в разделе «Проверки шаблонов»). Алерт MultitenancyManagerHelmProjectTemplate называет каждый такой шаблон, кроме встроенных. Ничто в кластере не переписывает такой шаблон, поэтому переведите его на структурированные поля и manifests там, откуда он применяется, например в Git или в CI.

Встроенные шаблоны default, secure и secure-with-dedicated-nodes — структурированные и принимают те же параметры, что их Helm-тексты, кроме administrators и resourceQuota, поэтому по ним видно, как текст переводится на поля. Поле берёт значение параметра через {fromParam: <PARAMETER_NAME>}, поэтому проекты сохраняют свои параметры. В таблице показано, куда переносятся объекты такого текста:

Объект Helm-текста Замена
Лейбл security.deckhouse.io/pod-policy неймспейса из параметра podSecurityProfile podSecurityStandard: {fromParam: podSecurityProfile}
Объекты NetworkPolicy параметра networkPolicy networkPolicy.mode: {fromParam: networkPolicy}
Лейбл extended-monitoring.deckhouse.io/enabled параметра extendedMonitoringEnabled features.monitoring: {fromParam: extendedMonitoringEnabled}
Лейбл security-scanning.deckhouse.io/enabled параметра securityScanningEnabled features.vulnerabilityScanning: {fromParam: securityScanningEnabled}
PodLoggingConfig параметра clusterLogDestinationName logShipping.clusterDestinationRef: {fromParam: clusterLogDestinationName}
SecurityPolicy параметров allowedUIDs и allowedGIDs allowedUIDs: {fromParam: allowedUIDs} и allowedGIDs: {fromParam: allowedGIDs}
FalcoAuditRules параметра runtimeAuditEnabled runtimeAudit.enabled: {fromParam: runtimeAuditEnabled}
Другие лейблы и аннотации неймспейса namespaceMetadata.labels и namespaceMetadata.annotations, во встроенных шаблонах из параметров namespace.labels и namespace.annotations
Размещение на выделенных узлах nodeSelector и tolerations, во встроенных шаблонах из параметров dedicatedNodes.nodeSelector и dedicatedNodes.defaultTolerations
Объекты AuthorizationRule параметра administrators .spec.administrators каждого Project
Другие объекты AuthorizationRule с уровнем доступа Admin .spec.administrators каждого Project, потому что manifests не создаёт AuthorizationRule с этим уровнем
ResourceQuota all-pods параметра resourceQuota .spec.quota каждого Project
OperationPolicy required-requests-*, которая отклоняет поды без запросов CPU и памяти Параметр requiredRequests, объявленный с type: boolean и default: true, чтобы сохранить политику, или с default: false, чтобы её не было
Любой другой объект в неймспейсах проекта, например рабочая нагрузка, ConfigMap, RoleBinding, LimitRange или AuthorizationRule с другим уровнем доступа manifests
Объект уровня кластера Замены в шаблоне нет. Доступ к cluster-wide-ресурсам задаётся через resources и grantPolicies

Например, у существующего шаблона team есть следующий Helm-текст, который задаёт профиль безопасности подов из параметра и создаёт LimitRange в основном неймспейсе каждого проекта. Создать такой шаблон заново нельзя, поэтому манифест только показывает исходное состояние:

apiVersion: deckhouse.io/v1alpha1
kind: ProjectTemplate
metadata:
  name: team
spec:
  parametersSchema:
    openAPIV3Schema:
      type: object
      properties:
        podSecurityProfile:
          type: string
          enum: [Baseline, Restricted]
          default: Baseline
  resourcesTemplate: |
    apiVersion: v1
    kind: Namespace
    metadata:
      name: {{ .projectName | quote }}
      labels:
        security.deckhouse.io/pod-policy: {{ .parameters.podSecurityProfile | lower | quote }}
    ---
    apiVersion: v1
    kind: LimitRange
    metadata:
      name: container-defaults
      namespace: {{ .projectName | quote }}
    spec:
      limits:
        - type: Container
          default:
            cpu: 500m
            memory: 512Mi

В структурированной форме профиль переносится в podSecurityStandard, а LimitRange в manifests. Текст не рендерил OperationPolicy required-requests-*, поэтому шаблон объявляет параметр requiredRequests с default: false:

apiVersion: deckhouse.io/v1alpha2
kind: ProjectTemplate
metadata:
  name: team
spec:
  podSecurityStandard:
    fromParam: podSecurityProfile
  parametersSchema:
    openAPIV3Schema:
      type: object
      properties:
        podSecurityProfile:
          type: string
          enum: [Baseline, Restricted]
          default: Baseline
        requiredRequests:
          type: boolean
          default: false
  manifests: |
    apiVersion: v1
    kind: LimitRange
    metadata:
      name: container-defaults
    spec:
      limits:
        - type: Container
          default:
            cpu: 500m
            memory: 512Mi

После перехода неймспейс каждого проекта сохраняет свой лейбл, LimitRange остаётся на месте, а manifests берёт его под управление и снимает с него аннотации Helm.

Шаблон, который не используют проекты, можно удалить, и алерт исчезнет вместе с ним. Если шаблон является неизменённой копией встроенного шаблона, вместо этого переведите его проекты на встроенный шаблон в .spec.projectTemplateName, а затем удалите копию. Чтобы перевести шаблон, который используют проекты, выполните следующие шаги:

  1. Найдите проекты шаблона, которые всё ещё задают administrators или resourceQuota в .spec.parameters:

    d8 k get projects -l projects.deckhouse.io/project-template=<PROJECT_TEMPLATE_NAME> -o json | jq -r '.items[] | select((.spec.parameters // {}) | has("administrators") or has("resourceQuota")) | .metadata.name'
    

    Эти значения не получают стандартных полей и не передаются. Сначала перенесите их в .spec.administrators и .spec.quota, и только в той мере, в какой они значат там то же самое. .spec.administrators выдаёт пользователям и группам роль d8:project:admin, поэтому администратору с другим уровнем доступа или другим типом субъекта нужен собственный ProjectRoleBinding. .spec.quota применяет каждый заданный в нём лимит, включая 0, поэтому не переносите лимит, который текст не рендерил, например 0, который он пропускал.

  2. Настройте каждый инструмент, который записывает шаблон, например GitOps-инструмент или генератор, на запись через deckhouse.io/v1alpha2. Когда у шаблона появляется поле, которое deckhouse.io/v1alpha1 не может описать, например manifests, запись шаблона через deckhouse.io/v1alpha1 отклоняется, потому что она стёрла бы это поле.

  3. Запишите шаблон как deckhouse.io/v1alpha2 с полями из таблицы и с manifests, без resourcesTemplate, одним изменением. Сохраните в parametersSchema параметры, которые задают проекты. Объявите параметр requiredRequests с type: boolean, с default: true, если текст рендерил OperationPolicy required-requests-*, и с default: false, если не рендерил, чтобы проекты по-прежнему отклоняли или пропускали поды без запросов CPU и памяти. Шаблон, который используют проекты, не может потерять resourcesTemplate, если вместо него не заданы структурированные поля или manifests.

  4. Проверьте каждый проект после перехода. Его условие HandoverPending удаляется, когда заменённые объекты удалены, условие ManifestsApplied говорит, применены ли объекты из manifests, а .status.keptObjects перечисляет объекты, оставленные на месте:

    d8 k get project <PROJECT_NAME> -o jsonpath='{range .status.conditions[*]}{.type}={.status}: {.message}{"\n"}{end}{range .status.keptObjects[*]}{.kind} {.namespace}/{.name}{"\n"}{end}'
    
  5. Решите, что делать с каждым объектом, который остаётся в .status.keptObjects, как описано в разделе «Переход проекта с Helm-текста». Объект, который manifests рендерит с тем же типом, неймспейсом и именем, исчезает из списка, когда manifests берёт его под управление, и с этого момента содержит то, что рендерит manifests.

Переход проекта с Helm-текста

Релиз проекта, отрендеренный из Helm-текста в resourcesTemplate, содержит всё, что отрендерил этот текст. Проект переходит на структурированные поля, когда его шаблон получает структурированные поля или manifests вместо resourcesTemplate, когда проект переводят на структурированный шаблон и когда встроенный шаблон, который был Helm-текстом, переписывается структурированными полями. После этого релиз содержит только то, что рендерят структурированные поля. Объект Helm-текста, который структурированные поля рендерят с тем же типом и именем, остаётся в релизе и обновляется на месте. С остальными объектами Helm-текста контроллер поступает так, как описано ниже, и из них сразу удаляется только AuthorizationRule, в котором больше нет никого из .spec.administrators.

Объекты AuthorizationRule и ResourceQuota, которые заменяют стандартные поля, проходят передачу, поэтому администраторы ни на миг не теряют доступ, а неймспейс не остаётся без квоты. Это объекты AuthorizationRule, созданные релизом, которые выдают уровень доступа Admin и ничего больше пользователям и группам, каждый из которых администратор проекта, и объекты ResourceQuota основного неймспейса без scopes, каждый лимит которых .spec.quota задаёт тем же значением или меньшим. Передача идёт в следующем порядке:

  1. Project получает условие HandoverPending со значением True. Затем объекты получают аннотацию helm.sh/resource-policy: keep и аннотацию projects.deckhouse.io/kept-by-handover: "true", поэтому обновление релиза их не удаляет.
  2. ProjectRoleBinding d8-administrators и ResourceQuota d8-project-quota создаются до обновления релиза.
  3. Сохранённые объекты удаляются, когда в d8-administrators указаны администраторы из .spec.administrators и он стал Ready для своего текущего metadata.generation, у ClusterRole d8:project:admin появились агрегированные правила, а в d8-project-quota заданы лимиты из .spec.quota и она посчитана, но не раньше чем через 2 минуты после того, как d8-administrators стал Ready, и после начала передачи. До этого у администраторов есть обе роли, а действует более строгая из квот. Условие HandoverPending говорит, чего ждёт передача, и удаляется, когда сохранённые объекты удалены.

Сохранённый AuthorizationRule, в котором больше нет никого из .spec.administrators, выдаёт только отозванный доступ и удаляется сразу. Субъект, удалённый из .spec.administrators, сразу удаляется и из сохранённого AuthorizationRule, в котором есть другие администраторы. Сохранённая квота, которую .spec.quota к концу передачи больше не покрывает, потому что лимит в .spec.quota подняли выше её лимита или убрали, остаётся на месте, как объекты ниже. Условие HandoverPending хранится в статусе Project, поэтому замена Project (например, kubectl replace или Argo CD с опцией Replace=true) его не теряет. Если сохранённые объекты остаются дольше 30 минут, алерт MultitenancyManagerProjectHandoverStuck называет проект и говорит, что проверить.

Каждый другой объект Helm-текста, который структурированные поля не рендерят, остаётся на месте вместо удаления. Например, это объекты AuthorizationRule других субъектов или другого уровня доступа, в том числе те, которые текст рендерит для ролей из своих параметров, квота, которую .spec.quota не покрывает, объекты RoleBinding, сетевые политики и рабочие нагрузки с их томами.

  • Такой объект работает как раньше. Правило или привязка продолжают выдавать доступ, квота продолжает действовать, рабочая нагрузка продолжает работать.
  • Проект им больше не управляет. Объект получает аннотацию helm.sh/resource-policy: keep и лейбл projects.deckhouse.io/kept-from-helm-template: "true" и теряет лейбл heritage: multitenancy-manager. Пока на объекте стоит лейбл, менять и удалять его может только тот, кто может сделать то же с объектами этого типа во всём кластере, например администратор кластера. Пользователи проекта не могут, поэтому сетевая политика или квота из текста продолжают на них действовать. На подресурсы scale и status защита не распространяется: кто может масштабировать объекты этого типа или менять их статус в неймспейсе, может делать это и с оставленным объектом. Это важно только для оставленных рабочих нагрузок.
  • Project перечисляет его в .status.keptObjects, а алерт MultitenancyManagerProjectKeepsHelmTemplateObjects называет проект. Объект исчезает из списка, когда его удаляют или снимают с него лейбл. Когда шаблон снова рендерит объект того же типа и с тем же именем, релиз проекта забирает объект обратно. Тогда контроллер снимает лейбл, возвращает лейбл heritage: multitenancy-manager и снимает аннотацию helm.sh/resource-policy: keep, если шаблон не задаёт её сам.
  • Когда manifests шаблона рендерит объект того же типа с тем же неймспейсом и именем, контроллер применяет его от имени пользователя проекта и берёт объект под управление. После этого объект содержит то, что рендерит manifests. Поле, которое задавал Helm-текст и не задаёт manifests, удаляется, в том числе аннотации Helm, например helm.sh/resource-policy: keep и meta.helm.sh/*, а также лейбл projects.deckhouse.io/kept-from-helm-template. Поле, которое на объекте задал кто-то другой, остаётся. Объект исчезает из .status.keptObjects.
  • Когда проект удаляют, объект удаляется вместе с ним. Объект в неймспейсе проекта удаляется вместе с неймспейсом, а объект уровня кластера, на котором ещё стоит лейбл, удаляет контроллер.

Опишите то, что ещё нужно, в шаблоне или в проекте, например ProjectRoleBinding или лимитом в .spec.quota, и удалите оставленный объект, или снимите лейбл, чтобы передать объект проекту, после чего менять и удалять его смогут и пользователи проекта. Объект в неймспейсе проекта можно вместо этого описать в manifests шаблона, и manifests возьмёт его под управление. Объект уровня кластера без лейбла остаётся и после удаления проекта. Доступ, который выдаёт оставленный объект, прекращается только после удаления объекта. Чтобы вывести оставленные объекты проекта, используйте команду:

d8 k get project <PROJECT_NAME> -o jsonpath='{range .status.keptObjects[*]}{.kind} {.namespace}/{.name}{"\n"}{end}'

Изменение Helm-текста и перевод проекта на другой шаблон с Helm-текстом удаляют объекты, которые новый текст не рендерит, кроме объектов AuthorizationRule и ResourceQuota, которые заменяют стандартные поля. Они проходят ту же передачу.

Администраторы и квота, которые всё ещё заданы в .spec.parameters, потому что их не удалось перенести в .spec.administrators и .spec.quota, не получают стандартных полей. Их объекты AuthorizationRule и их квота не передаются, и переход оставляет их на месте. Перенесите такие значения в стандартные поля до перехода.

После передачи у администраторов вместо уровня доступа Admin роль d8:project:admin. Эти роли выдают разные права. В частности, доступ, который пользовательские ClusterRole с аннотацией user-authz.deckhouse.io/access-level добавляли к уровню доступа Admin, в d8:project:admin не входит. Чтобы выдать такой доступ, создайте собственную роль и привяжите её через ProjectRoleBinding.

Перенос объекта релиза в manifests

Структурированный шаблон рендерит свои объекты в релиз проекта. Если одно изменение заставляет manifests рендерить объект, который содержал релиз, с тем же типом, неймспейсом и именем, обновление релиза удалило бы объект, а manifests создали бы его заново. Проект на это время остался бы без объекта. Например, NetworkPolicy с именем isolated, когда networkPolicy.mode убирают, а эту NetworkPolicy рендерят manifests.

Контроллер оставляет объект на месте. Перед обновлением он добавляет аннотацию helm.sh/resource-policy: keep и лейбл projects.deckhouse.io/kept-from-helm-template: "true" и записывает объект в .status.keptObjects, так же как переход с Helm-текста оставляет объект. В том же согласовании manifests применяют объект от имени пользователя проекта, снимают лейбл и убирают объект из списка. После этого объект содержит то, что рендерят manifests. Поле, которое задал релиз и не задают manifests, удаляется. Поле, которое задал кто-то другой, остаётся.

Если manifests не могут применить объект, например потому что API-сервер отклоняет тип или возвращает 403 Forbidden, объект остаётся в .status.keptObjects. Алерт MultitenancyManagerProjectKeepsHelmTemplateObjects называет проект. Объект продолжает работать, и менять или удалять его может только тот, кто может сделать то же с объектами этого типа во всём кластере, пока manifests не заберут его или с него не снимут лейбл.

Объект, который релиз перестаёт содержать и который manifests не рендерят, обновление удаляет.

Создание собственного шаблона для проекта

Для создания своего шаблона:

  1. Возьмите за основу один из шаблонов по умолчанию, например, default.
  2. Скопируйте его в отдельный файл, например, my-project-template.yaml при помощи команды:

    d8 k get projecttemplates default -o yaml > my-project-template.yaml
    
  3. Отредактируйте файл my-project-template.yaml и измените структурированные поля, объекты в manifests и схему входных параметров под свои задачи.
  4. Измените имя шаблона в поле .metadata.name.
  5. Удалите из файла лейбл heritage, поля metadata.resourceVersion, metadata.uid, metadata.creationTimestamp, metadata.generation, metadata.managedFields и раздел status.
  6. Примените полученный шаблон командой:

    d8 k apply -f my-project-template.yaml
    
  7. Проверьте доступность нового шаблона с помощью команды:

    d8 k get projecttemplates <NEW_TEMPLATE_NAME>
    

Лейблы для объектов Helm-текста

Следующие лейблы меняют то, как модуль обрабатывает объекты Helm-текста в resourcesTemplate. Такой текст есть только у существующих шаблонов, потому что ни один шаблон не может получить новое resourcesTemplate. Объекты из manifests никогда не получают лейбл heritage: multitenancy-manager, и модуль не читает на них эти лейблы.

Пропуск лейбла heritage

По умолчанию каждый объект Helm-текста получает лейбл heritage: multitenancy-manager. С этим лейблом объект могут изменить только те, кто перечислен в разделе «Кто обходит валидацию». Чтобы разрешить изменение объекта (например, для совместимости с другими системами или чтобы самостоятельно контролировать создаваемые объекты), добавьте на него лейбл projects.deckhouse.io/skip-heritage-label.

Пример:

---
apiVersion: v1
kind: ConfigMap
metadata:
  name: my-config
  namespace: {{ .projectName }}
  labels:
    projects.deckhouse.io/skip-heritage-label: "true"
    app: my-app
data:
  key: value

В этом случае объект получает лейблы projects.deckhouse.io/project и projects.deckhouse.io/project-template, но не получает лейбл heritage: multitenancy-manager.

Исключение объектов из управления

Чтобы исключить объект из управления модулем (например, если он управляется вручную или другим контроллером), добавьте на него лейбл projects.deckhouse.io/unmanaged.

Пример:

---
apiVersion: v1
kind: Secret
metadata:
  name: external-secret
  namespace: {{ .projectName }}
  labels:
    projects.deckhouse.io/unmanaged: "true"
type: Opaque
data:
  token: <base64-encoded-value>

Объекты с лейблом projects.deckhouse.io/unmanaged:

  • создаются только один раз, при первой установке релиза проекта, поэтому объект, добавленный в шаблон позже, в существующих проектах не создаётся;
  • не обновляются при изменении шаблона;
  • не отслеживаются в статусе проекта;
  • получают лейблы projects.deckhouse.io/project и projects.deckhouse.io/project-template, но не получают лейбл heritage: multitenancy-manager;
  • получают аннотацию helm.sh/resource-policy: keep, поэтому релиз проекта их не удаляет.

После создания объект с лейблом unmanaged не зависит от шаблона и должен управляться вручную.

Реализация валидации изменений объектов с помощью пользовательского лейбла

Модуль multitenancy-manager использует ValidatingAdmissionPolicy для защиты объектов с лейблом heritage: multitenancy-manager от ручных изменений. Вы можете реализовать аналогичную валидацию для объектов с любым лейблом.

Как работает валидация в multitenancy-manager

Происходит валидация объектов с лейблом heritage: multitenancy-manager. Для этого используются следующие ресурсы:

  1. ValidatingAdmissionPolicy — определяет правила валидации:
    • Операции: CREATE, UPDATE и DELETE; группа system:masters исключением не является;
    • Проверка: менять такой объект могут только контроллер модуля и идентичности, которые пропускает эта политика (подробнее — в разделе «Кто обходит валидацию»). Для неймспейса проекта также разрешено обновление, меняющее только лейблы и аннотации вне ключей, которыми управляет модуль (подробнее — в разделе «Автоматическое создание проекта для неймспейса»);
    • Применяется ко всем ресурсам и API группам.
  2. ValidatingAdmissionPolicyBinding — определяет на какие объекты распространяется валидация:
    • Использует namespaceSelector и objectSelector для выбора ресурсов по лейблу heritage: multitenancy-manager.

Кто обходит валидацию

У вебхуков и политик модуля разные списки исключений:

  • Вебхуки Project и ProjectTemplate пропускают без проверки компоненты платформы — API-сервер (system:apiserver), ServiceAccount Deckhouse (d8-system:deckhouse), этого модуля (d8-multitenancy-manager:multitenancy-manager) и user-authz (d8-user-authz:controller), все ServiceAccount неймспейсов d8-system, kube-system и d8-user-authz, kubelet (system:nodes) — и пользователя system:sudouser. Все остальные проверяются, включая группу system:masters.
  • Вебхуки ProjectRoleBinding, ProjectNamespace и ClusterProjectRoleBinding не пропускают никого и проверяют каждый запрос. Особые права в них есть только у ServiceAccount контроллера и Deckhouse; system:sudouser и system:masters там — обычные пользователи.
  • Описанная выше ValidatingAdmissionPolicy пропускает контроллер модуля; пользователей system:apiserver, system:kube-controller-manager, system:kube-scheduler, system:volume-scheduler, dhctl, observability и system:sudouser; группы system:nodes, system:serviceaccounts:kube-system и system:serviceaccounts:d8-system (но не d8-user-authz); а также rollout restart нагрузки проекта, который меняет только аннотацию kubectl.kubernetes.io/restartedAt у шаблона пода. Всем остальным отказывает, включая system:masters.
  • ValidatingAdmissionPolicy d8-multitenancy-manager-manifests-objects охраняет объекты с лейблом projects.deckhouse.io/source: manifests. Она пропускает контроллер модуля; пользователей system:apiserver, system:kube-controller-manager, system:kube-scheduler, system:volume-scheduler, dhctl, observability и system:sudouser; группы system:nodes, system:serviceaccounts:kube-system и system:serviceaccounts:d8-system. Любой ServiceAccount, имя которого начинается с system:serviceaccount:d8-, может создавать, изменять и удалять такие объекты. Пользователь system:multitenancy-manager:project:<PROJECT_NAME> может создавать, изменять и удалять объекты этого проекта. Разрешён rollout restart, который меняет только аннотацию kubectl.kubernetes.io/restartedAt у шаблона пода. Обновление, которое добавляет лейбл projects.deckhouse.io/source: manifests вместе с лейблом projects.deckhouse.io/project на объект, у которого ещё нет лейбла projects.deckhouse.io/source: manifests, разрешено тому, кто может обновлять такой ресурс во всём кластере. Всем остальным она отказывает, включая system:masters.
  • ValidatingAdmissionPolicy, которая резервирует пользователей, от имени которых действует контроллер (имена, начинающиеся с system:multitenancy-manager:, подробнее в разделе «Описание других объектов в manifests»), пропускает контроллер модуля, сборщик мусора, который работает от имени system:serviceaccount:kube-system:generic-garbage-collector или system:kube-controller-manager, и system:sudouser. Всем остальным, кто указывает такого пользователя или такую группу в привязке, она отказывает, включая остальные ServiceAccount kube-system и system:masters.
  • ValidatingAdmissionPolicy d8-multitenancy-manager-namespace-creation проверяет создание неймспейсов и действует, только пока параметр allowNamespacesWithoutProjects равен false. Она пропускает API-сервер (system:apiserver), ServiceAccount Deckhouse (d8-system:deckhouse), этого модуля (d8-multitenancy-manager:multitenancy-manager) и агента upmeter (d8-upmeter:upmeter-agent), все ServiceAccount неймспейсов d8-system и kube-system, группы system:masters и system:nodes, а также пользователя system:sudouser. В отличие от списков выше, её список включает system:masters, поэтому администраторы кластера по-прежнему создают неймспейсы напрямую. Все остальные могут создать только неймспейс default.
  • ValidatingAdmissionPolicy d8-multitenancy-manager-namespace-adoption при любом значении allowNamespacesWithoutProjects запрещает создавать неймспейс с именем длиннее 61 символа, с префиксом upmeter- или с именем deckhouse и ставить на неймспейс лейбл heritage: upmeter. Она пропускает тех же пользователей и группы, что и политика d8-multitenancy-manager-namespace-creation.
  • ValidatingAdmissionPolicy d8-multitenancy-manager-manifests проверяет только пользователей, от имени которых контроллер применяет manifests, то есть имена, начинающиеся с system:multitenancy-manager:project:, и не даёт им создавать AuthorizationRule с уровнем доступа Admin, повышать его до этого уровня или добавлять субъекты в такой AuthorizationRule. Больше никого она не проверяет.
  • ValidatingAdmissionPolicy d8-multitenancy-manager-v1alpha1-template-create отклоняет любое создание ProjectTemplate через deckhouse.io/v1alpha1 и никого не пропускает, включая system:sudouser, system:masters и компоненты платформы. Новое resourcesTemplate через deckhouse.io/v1alpha2 отклоняет вебхук ProjectTemplate, поэтому те, кого этот вебхук пропускает, в том числе system:sudouser, по-прежнему могут так создать шаблон с Helm-текстом.
  • ValidatingAdmissionPolicy d8-multitenancy-manager-namespace-ownership сохраняет лейбл projects.deckhouse.io/project и лейблы и аннотации, которые модуль ставит на неймспейс проекта. Она пропускает только контроллер модуля и d8-system:deckhouse. Всем остальным она отказывает, включая system:sudouser и system:masters.
  • ValidatingAdmissionPolicy d8-multitenancy-manager-project-grants охраняет объекты ClusterResourceGrantPolicy, которые контроллер создаёт из spec.grants объекта Project. Она запрещает создавать объект с именем, которое начинается с project-, а также создавать, менять и удалять объект с лейблом multitenancy.deckhouse.io/managed-by-project. Она пропускает контроллер этого модуля, d8-system:deckhouse, system:sudouser и ServiceAccount неймспейса kube-system, в том числе сборщик мусора. Всем остальным она отказывает, включая system:masters.
  • ValidatingAdmissionPolicy d8-multitenancy-manager-kept-objects охраняет объекты из .status.keptObjects проекта. Она пропускает контроллер модуля, пользователей с именами, начинающимися с system:multitenancy-manager:, system:sudouser, а также системных пользователей и группы политики, которая охраняет объекты с лейблом heritage: multitenancy-manager. Остальные могут изменить такой объект, только если им разрешено то же изменение во всём кластере.

Вебхуки /is-granted и /defaults, которые проверяют запись объектов со ссылками на cluster-wide-ресурсы в неймспейсах проектов (подробнее — в разделе «Управление доступом к cluster-wide-ресурсам»), пропускают system:masters вместе с компонентами платформы. Вебхук /protect оставляет AvailableClusterResource доступным только для чтения. Он пропускает контроллер, компоненты платформы и system:masters.

Администратор, которому требуется действовать в обход вебхука Project или ProjectTemplate, политики, которая охраняет объекты с лейблом heritage: multitenancy-manager, политики d8-multitenancy-manager-manifests-objects или политики, которая резервирует пользователей, от имени которых действует контроллер, делает это явно от имени system:sudouser, например командой d8 k --as system:sudouser …. Такой обход виден в audit-логе. Для ProjectRoleBinding, ProjectNamespace и ClusterProjectRoleBinding, для создания ProjectTemplate через deckhouse.io/v1alpha1, а также для лейблов и аннотаций неймспейса, которые сохраняет политика d8-multitenancy-manager-namespace-ownership, аналогичной возможности нет.

Создание собственной валидации

Для реализации валидации для ресурсов с другим лейблом (например, heritage: my-custom-label):

  1. Создайте файл с манифестами ресурсов ValidatingAdmissionPolicy и ValidatingAdmissionPolicyBinding:

    apiVersion: admissionregistration.k8s.io/v1
    kind: ValidatingAdmissionPolicy
    metadata:
      name: my-custom-label-validation
    spec:
      failurePolicy: Fail
      matchConstraints:
        resourceRules:
          - apiGroups:   ["*"]
            apiVersions: ["*"]
            operations:  ["CREATE", "UPDATE", "DELETE"]
            resources:   ["*"]
            scope: "*"
      matchConditions:
        # Пропускает компоненты кластера, как и политика модуля.
        - name: exclude-system-groups
          expression: '!(["system:nodes", "system:serviceaccounts:kube-system", "system:serviceaccounts:d8-system"].exists(e, (e in request.userInfo.groups)))'
        - name: exclude-system-users
          expression: '!(["system:apiserver", "system:kube-controller-manager", "system:kube-scheduler"].exists(e, (e == request.userInfo.username)))'
      variables:
        # В запросе DELETE нет object, есть только oldObject.
        - name: subject
          expression: 'object == null ? oldObject : object'
      validations:
        - expression: 'request.userInfo.username == "system:serviceaccount:my-namespace:my-service-account"' # Замените на ваш ServiceAccount.
          reason: Forbidden
          messageExpression: 'variables.subject.kind == ''Namespace'' ? ''This resource is managed by '' + variables.subject.metadata.name + '' system. Manual modification is forbidden.''
            : ''This resource is managed by '' + variables.subject.metadata.namespace + '' system. Manual modification is forbidden.'''
    ---
    apiVersion: admissionregistration.k8s.io/v1
    kind: ValidatingAdmissionPolicyBinding
    metadata:
      name: my-custom-label-validation
    spec:
      policyName: my-custom-label-validation
      validationActions: [Deny, Audit]
      matchResources:
        objectSelector:
          matchLabels:
            heritage: my-custom-label
    
  2. Настройте параметры валидации:

    • policyName — уникальное имя политики (должно совпадать в ValidatingAdmissionPolicy и ValidatingAdmissionPolicyBinding);
    • request.userInfo.username — имя ServiceAccount, которому разрешено изменять объекты (замените на ваш ServiceAccount);
    • heritage: my-custom-label — значение лейбла heritage для ваших ресурсов (замените на ваше значение). Значения multitenancy-manager и deckhouse использовать запрещено;
    • failurePolicy — что делать, если политику не удалось вычислить, например при ошибке выражения: Fail — отклонить запрос, Ignore — пропустить его. Проверка, которая вернула false, при действии Deny отклоняет запрос в любом случае;
    • matchConditions — запросы, которые политика не проверяет. Оставьте в этом списке компоненты кластера, иначе политика заблокирует удаление неймспейсов и сборку мусора для объектов с лейблом;
    • validationActions — действия валидации:
      • Deny — отклонять неразрешённые операции,
      • Audit — записывать операции в audit-лог.
  3. Примените политику:

    d8 k apply -f my-validation-policy.yaml
    
  4. Убедитесь, что ваши ресурсы имеют соответствующий лейбл heritage:

    apiVersion: v1
    kind: ConfigMap
    metadata:
      name: my-resource
      labels:
        heritage: my-custom-label
    

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

Модуль позволяет управлять доступом проектов к cluster-wide-ресурсам, таким как StorageClass, ClusterIssuer, ClusterRole и другим.

Описание механизма, используемых ресурсов и cluster-wide-ресурсов, зарегистрированных платформой, приведено на странице описания модуля.

Далее приведены основные сценарии настройки и использования механизма.

Как политика выбирает неймспейсы

У ресурса ClusterResourceGrantPolicy (multitenancy.deckhouse.io/v1alpha2) два селектора: projectSelector и namespaceSelector. Политика применяется к неймспейсу проекта, если совпали все заданные в ней селекторы:

  • projectSelector сопоставляется с лейблами объекта Project. Он выбирает сразу все неймспейсы проекта, в том числе дополнительный неймспейс, созданный позже, поэтому используйте его, чтобы выбрать проект целиком. Модуль ставит на каждый Project лейблы projects.deckhouse.io/project: <PROJECT_NAME> и projects.deckhouse.io/project-template: <PROJECT_TEMPLATE_NAME>, поэтому проект можно выбрать и по имени, и по шаблону. На виртуальных проектах есть только первый из этих лейблов. Эти два лейбла нельзя изменить на имя другого проекта или шаблона. Манифест, который заменяет Project целиком, может их не содержать. Такой запрос принимается с предупреждением, и модуль возвращает лейблы. Лейбл шаблона на Project меняется сразу вместе со spec.projectTemplateName. Тот же лейбл на неймспейсах показывает шаблон, который к ним применён, и по нему служебные политики шаблона выбирают неймспейсы.
  • namespaceSelector сопоставляется с лейблами объекта Namespace. Он сужает выбор до части неймспейсов выбранных проектов или, если projectSelector не задан, всех проектов. Например, он может выбрать только основной неймспейс (лейбла projects.deckhouse.io/project-namespace нет) или только неймспейсы с лейблом шаблона.
  • Политика, у которой не задан ни один селектор, сама по себе не выбирает ни одного проекта. Это библиотечная политика, которую подключают к проекту через grantPolicies его ProjectTemplate или самого Project (spec.grants.grantPolicies). Явно пустой селектор ({}) выбирает всё.

Неймспейсы виртуальных проектов deckhouse и default не выбираются никогда, даже селектором {}.

Дополнительный неймспейс создаёт пользователь проекта, и на нём есть только лейблы, которые ставит модуль, и лейблы шаблона проекта. Поэтому политика, которая ограничивает ресурс через namespaceSelector, может не распространяться на новый дополнительный неймспейс. Так бывает, если селектор опирается на лейбл, поставленный на неймспейс вручную, на лейбл шаблона, значение которого на основном неймспейсе изменили вручную, или на projects.deckhouse.io/project-namespace, значение которого — выбранное пользователем имя. Если в GrantableClusterResourceDefinition ресурса задано defaultAvailability: All (значение по умолчанию), такому неймспейсу доступны все ресурсы этого типа.

Политика сообщает об этом в условии NewNamespacesCovered. Условие проверяет namespaceSelector на лейблах, которые получил бы новый дополнительный неймспейс каждого охваченного проекта. Запрещённые имена считаются ограничением при любом значении defaultAvailability. Список разрешённых или availabilityDefault: None считается ограничением, только если defaultAvailability равно All.

Не выбирайте неймспейсы по лейблу projects.deckhouse.io/project-namespace без projectSelector. Пользователь любого проекта может создать ProjectNamespace с именем, которое ожидает такой namespaceSelector. Тогда политика начнёт действовать в его проекте и откроет там доступ к разрешённым ею ресурсам.

Версия multitenancy.deckhouse.io/v1alpha1 по-прежнему обслуживается. Её projectSelector сопоставляется с лейблами неймспейса и соответствует namespaceSelector версии v1alpha2. Для projectSelector версии v1alpha2 в v1alpha1 поля нет, поэтому клиент v1alpha1 видит его как JSON в аннотации multitenancy.deckhouse.io/v1alpha2-project-selector. Политика с такой аннотацией выбирает проекты по ней, хотя её projectSelector в v1alpha1 пуст.

Чтобы перевести манифест политики с v1alpha1 на v1alpha2, переименуйте её projectSelector в namespaceSelector. Не меняйте одну apiVersion. Тогда тот же projectSelector сопоставляется с лейблами Project, поэтому селектор по лейблу, который есть только у неймспейса, например kubernetes.io/metadata.name или лейбл из namespaceMetadata, ничего не выбирает, и политика молча перестаёт действовать на эти неймспейсы.

Меняя такую политику через v1alpha1, сохраняйте аннотацию. d8 k apply и d8 k edit её сохраняют, а d8 k replace с манифестом без аннотации удаляет projectSelector. Чтобы вернуться к старому манифесту v1alpha1 после того, как вы задали projectSelector версии v1alpha2, удалите аннотацию явно, потому что d8 k apply старого манифеста её не удаляет.

Для администраторов кластера

Ниже приведены примеры настройки доступа проектов к cluster-wide-ресурсам с помощью ClusterResourceGrantPolicy.

В примерах ниже проекты выбираются через projectSelector по лейблу на Project, поэтому политика охватывает все неймспейсы проекта.

Поскольку в сопоставлении участвуют лейблы Project и его неймспейсов, от права менять эти лейблы зависит, какие политики применяются. Лейблы Project меняют с правом d8:system-capability:multitenancy-manager:edit, которое есть у менеджера подсистемы iam. Это же право позволяет создавать и изменять политики. Лейблы неймспейса меняют с правом d8:subsystem-capability:cluster:manage_resources, которое есть у менеджера подсистемы cluster. Проектные роли d8:project:* и d8:namespace:* неймспейсы только читают.

Ограничение StorageClass для проекта

Чтобы разрешить проектам использовать только StorageClass с именами fast-ssd и standard, а fast-ssd использовать по умолчанию, создайте следующий ClusterResourceGrantPolicy:

apiVersion: multitenancy.deckhouse.io/v1alpha2
kind: ClusterResourceGrantPolicy
metadata:
  name: production-storage
spec:
  projectSelector:
    matchLabels:
      environment: production
  resources:
    - resourceName: storageclasses
      default: fast-ssd
      allowed:
        - fast-ssd
        - standard

При создании PersistentVolumeClaim без значения spec.storageClassName в это поле автоматически подставляется fast-ssd. Если указан StorageClass, которого нет в списке разрешённых, он заменяется на fast-ssd, потому что для StorageClass используется режим подстановки значения по умолчанию Coerce. Это относится и к классу, который подставил встроенный admission-контроллер Kubernetes. О замене сообщается предупреждением (admission warning) в ответе на запрос, поэтому в выводе d8 k видны и исходное значение, и подставленное. Если у проекта нет StorageClass по умолчанию, такой PersistentVolumeClaim отклоняется.

PersistentVolumeClaim, который восстанавливает том из снимка или клонирует другой том (задан spec.dataSource или spec.dataSourceRef), сохраняет свой StorageClass: класс должен обслуживаться CSI-драйвером источника, поэтому он не заменяется значением по умолчанию для проекта. Если такой StorageClass проекту недоступен, PersistentVolumeClaim отклоняется с пояснением; укажите StorageClass, доступный проекту.

Чтобы проверить, какие StorageClass доступны проекту, выполните следующую команду:

d8 k get available storageclasses -n <PROJECT_NAME> -o yaml

При включённом модуле storage-foundation версии 1.0.3 или новее определение storageclasses и GrantableClusterResourceReference storageclasses-pvc регистрирует он, и они могут отличаться от описанных здесь, см. документацию этого модуля.

Ограничение ClusterIssuer для проекта

Чтобы разрешить проектам использовать только ClusterIssuer с именами letsencrypt-prod и vault-issuer, а letsencrypt-prod использовать по умолчанию, создайте следующий ClusterResourceGrantPolicy:

apiVersion: multitenancy.deckhouse.io/v1alpha2
kind: ClusterResourceGrantPolicy
metadata:
  name: production-issuers
spec:
  projectSelector:
    matchLabels:
      environment: production
  resources:
    - resourceName: clusterissuers
      default: letsencrypt-prod
      allowed:
        - letsencrypt-prod
        - vault-issuer

Политика применяется к ClusterIssuer, указанному одним из следующих способов:

  • в поле .spec.issuerRef.name ресурса Certificate, если в .spec.issuerRef.kind указано ClusterIssuer;
  • в аннотации cert-manager.io/cluster-issuer ресурса Ingress.

При создании Certificate с ClusterIssuer без значения .spec.issuerRef.name в это поле автоматически подставляется letsencrypt-prod. Если указан ClusterIssuer, которого нет в списке разрешённых, создание Certificate отклоняется.

Для аннотации cert-manager.io/cluster-issuer значение по умолчанию не подставляется. Если аннотация указана, её значение проверяется по тому же списку разрешённых ClusterIssuer.

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

Ограничение ClusterRole для проекта

По умолчанию RoleBinding в неймспейсе проекта может ссылаться на любую ClusterRole с лейблом rbac.deckhouse.io/delegatable: "true" и ни на какую другую. Политика не может сделать доступной ClusterRole без этого лейбла. Чтобы использовать такую ClusterRole в проектах, добавьте на неё лейбл (подробнее — в разделе «Роли, доступные в RoleBinding внутри проекта»).

Чтобы разрешить проектам команды payments использовать только ClusterRole my-custom-role и ClusterRole с лейблом shared: "true", создайте следующий ClusterResourceGrantPolicy:

apiVersion: multitenancy.deckhouse.io/v1alpha2
kind: ClusterResourceGrantPolicy
metadata:
  name: extra-roles
spec:
  projectSelector:
    matchLabels:
      team: payments
  resources:
    - resourceName: clusterroles
      allowed:
        - my-custom-role
      allowedSelector:
        matchLabels:
          shared: "true"

В RoleBinding этих проектов можно использовать только эти ClusterRole, и только те из них, на которых есть лейбл rbac.deckhouse.io/delegatable: "true". Остальные делегируемые ClusterRole, например d8:project:* и d8:namespace:*, в них становятся недоступны, в том числе в RoleBinding, которые создают manifests шаблона. Поэтому перечислите в политике все роли, которые привязывают эти проекты. ProjectRoleBinding и ClusterProjectRoleBinding это не затрагивает: их RoleBinding создаёт контроллер.

Лейбл rbac.deckhouse.io/delegatable: "true" обязателен для каждой ClusterRole, указанной в политике: регистрация clusterroles исключает роли без него из всех проектов, а исключение имеет приоритет над allowed и allowedSelector. Запись политики, указывающая роль без лейбла, ничего не предоставляет. Контроллер сообщает об этом в условии AllowedEffective статуса ClusterResourceGrantPolicy, указывая имя роли в сообщении:

d8 k get clusterresourcegrantpolicy extra-roles -o jsonpath='{.status.conditions[?(@.type=="AllowedEffective")]}'

При создании или изменении RoleBinding указанная в нём ClusterRole проверяется на доступность проекту. Значение ClusterRole автоматически не подставляется.

Ограничение LoadBalancerClass для сервиса

Чтобы разрешить проектам использовать только LoadBalancerClass со значениями internal-lb и edge-lb, а internal-lb использовать по умолчанию, создайте следующий ClusterResourceGrantPolicy:

apiVersion: multitenancy.deckhouse.io/v1alpha2
kind: ClusterResourceGrantPolicy
metadata:
  name: lb-classes
spec:
  projectSelector:
    matchLabels:
      environment: staging
  resources:
    - resourceName: loadbalancerclasses
      default: internal-lb
      allowed:
        - internal-lb
        - edge-lb

В отличие от StorageClass, ClusterIssuer и ClusterRole, ресурс LoadBalancerClass не является отдельным ресурсом Kubernetes. Политика определяет допустимые значения поля .spec.loadBalancerClass для сервисов типа LoadBalancer.

При создании Service типа LoadBalancer без значения .spec.loadBalancerClass в это поле автоматически подставляется internal-lb. Если указано значение, которого нет в списке разрешённых, создание Service отклоняется.

На Service других типов политика не распространяется.

Предоставление доступа ко всем ресурсам определённого типа

Чтобы разрешить определённым проектам использовать все ресурсы выбранного типа без явного перечисления, установите availabilityDefault: All.

Следующая политика разрешает всем проектам с лейблом environment: sandbox использовать любые StorageClass:

apiVersion: multitenancy.deckhouse.io/v1alpha2
kind: ClusterResourceGrantPolicy
metadata:
  name: open-storage-for-sandbox
spec:
  projectSelector:
    matchLabels:
      environment: sandbox
  resources:
    - resourceName: storageclasses
      availabilityDefault: All

Зарегистрированные ресурсы по умолчанию доступны всем проектам, поэтому availabilityDefault: All действует только там, где ресурс ограничивает другая политика. В этом случае оно отменяет списки allowed и allowedSelector всех политик, применяемых к проекту, включая политики его шаблона. denied, deniedSelector и фильтры excluded регистрации продолжают действовать. Ресурсы, попадающие под фильтры reserved регистрации, остаются недоступными — см. «Выдача зарезервированного ресурса».

Обычно для управления доступом достаточно явно указывать разрешённые ресурсы с помощью allowed или allowedSelector. Используйте параметр availabilityDefault: All, если выбранным проектам необходимо предоставить доступ ко всем ресурсам указанного типа.

Выдача зарезервированного ресурса

GrantableClusterResourceDefinition может пометить некоторые ресурсы как зарезервированные с помощью reserved. Зарезервированный ресурс по умолчанию недоступен проектам, даже если остальные ресурсы этого типа доступны. Он становится доступен проекту, только если применимая к проекту политика указывает его в allowed или выбирает через allowedSelector. availabilityDefault: All и defaultAvailability не делают его доступным. denied, deniedSelector и фильтры excluded и здесь имеют приоритет над allowed и allowedSelector.

allowedSelector открывает все зарезервированные ресурсы, которые он выбирает. Поэтому широкий или отрицательный селектор (Exists, NotIn, DoesNotExist), написанный для обычных ресурсов, выдаёт и попавшие под него зарезервированные. Чтобы выдать зарезервированный ресурс, укажите его имя в allowed или используйте селектор, явно выбирающий именно его.

В примерах ниже регистрация myclusterresources резервирует ресурсы premium и internal.

Чтобы выдать зарезервированный ресурс, не сужая остальные ресурсы этого типа, укажите его в allowed и задайте availabilityDefault: All:

apiVersion: multitenancy.deckhouse.io/v1alpha2
kind: ClusterResourceGrantPolicy
metadata:
  name: grant-premium
spec:
  projectSelector:
    matchLabels:
      tier: critical
  resources:
    - resourceName: myclusterresources
      allowed:
        - premium
      availabilityDefault: All

Выбранные проекты получают все незарезервированные ресурсы этого типа и premium. Ресурс internal остаётся недоступным, так как availabilityDefault: All не открывает зарезервированные ресурсы. Кроме того, availabilityDefault: All отменяет списки allowed и allowedSelector других политик, применяемых к проекту (см. «Предоставление доступа ко всем ресурсам определённого типа»).

allowed без availabilityDefault, как и в любой другой политике, делает недоступными все ресурсы вне своего списка. Если проект должен оставаться ограниченным списком, например политикой своего шаблона, выдайте зарезервированный ресурс только через allowed: списки allowed всех политик, применяемых к проекту, складываются. Другой вариант — перечислить в одной политике все нужные проекту ресурсы, включая зарезервированный.

Чтобы зарезервированный ресурс стал значением по умолчанию проекта, укажите его и в allowed, и в default одной записи. Значение по умолчанию, которое проекту недоступно, не используется. Это касается и зарезервированного ресурса, отмеченного как значение по умолчанию через defaultFrom: он становится значением по умолчанию проекта только там, где его разрешает политика.

В таблице показано, что получает проект при типичных сочетаниях политик. Регистрация резервирует premium и internal, исключает system через excluded и задаёт defaultAvailability: All. На ресурсе premium есть лейбл tier: critical. В столбце «Политики проекта» перечислены записи всех политик, применяемых к проекту.

Политики проекта standard premium (зарезервирован) internal (зарезервирован) system (исключён)
Нет доступен — — —
availabilityDefault: All доступен — — —
allowed: [premium] — доступен — —
allowed: [premium] и availabilityDefault: All доступен доступен — —
allowedSelector, выбирающий tier: critical — доступен — —
allowed: [standard] в политике шаблона и allowed: [premium] в другой политике доступен доступен — —
allowed: [premium] и denied: [premium] в другой политике — — — —
allowed: [system] — — — —
allowed: [system] и availabilityDefault: All доступен — — —

Запрет отдельных ресурсов

Чтобы запретить проектам использовать отдельные ресурсы, оставив остальные доступными, используйте параметр denied или deniedSelector.

Следующая политика запрещает проектам с лейблом environment: dev использовать StorageClass с именами expensive-nvme и archived-hdd:

apiVersion: multitenancy.deckhouse.io/v1alpha2
kind: ClusterResourceGrantPolicy
metadata:
  name: deny-expensive-storage
spec:
  projectSelector:
    matchLabels:
      environment: dev
  resources:
    - resourceName: storageclasses
      denied:
        - expensive-nvme
        - archived-hdd

Запрет имеет приоритет над разрешением. Если ресурс соответствует одновременно denied или deniedSelector и allowed или allowedSelector, он считается недоступным.

Управление доступом с помощью селекторов лейблов

Чтобы управлять доступом к ресурсам без перечисления их имён, используйте параметры allowedSelector и deniedSelector. Селекторы позволяют разрешать или запрещать ресурсы на основе их лейблов.

Следующая политика разрешает проектам с лейблом tier: shared использовать StorageClass с лейблом shared: "true", за исключением StorageClass с лейблом deprecated: "true":

apiVersion: multitenancy.deckhouse.io/v1alpha2
kind: ClusterResourceGrantPolicy
metadata:
  name: shared-storage-only
spec:
  projectSelector:
    matchLabels:
      tier: shared
  resources:
    - resourceName: storageclasses
      allowedSelector:
        matchLabels:
          shared: "true"
      deniedSelector:
        matchLabels:
          deprecated: "true"

Выдача cluster-wide-ресурсов через шаблон проекта

Правила доступности cluster-wide-ресурсов можно задавать прямо в структурированном шаблоне — тогда они автоматически применяются ко всем проектам, созданным из этого шаблона:

  • spec.resources — правила «внутри» шаблона: тот же формат, что и resources в ClusterResourceGrantPolicy (имя ресурса, allowed/allowedSelector, default);
  • spec.grantPolicies — список имён библиотечных политик ClusterResourceGrantPolicy. Библиотечная политика описывает переиспользуемый набор правил и не задаёт ни projectSelector, ни namespaceSelector, потому что проекты, к которым её применять, определяет ссылающийся шаблон. Так, например, политику «корпоративные StorageClass» может поддерживать один администратор, а использовать — несколько шаблонов.

Следующий шаблон ограничивает StorageClass для своих проектов и подключает библиотечную политику:

apiVersion: deckhouse.io/v1alpha2
kind: ProjectTemplate
metadata:
  name: my-template
spec:
  resources:
    - resourceName: storageclasses
      allowed: ["standard"]
      default: standard
  grantPolicies:
    # Библиотечная ClusterResourceGrantPolicy без селекторов.
    - corporate-issuers

Для каждого источника контроллер создаёт служебную политику с именем template-<шаблон>-<источник> (для spec.resources — template-<шаблон>-inline). Шаблон, который ссылается на политику с именем inline, отклоняется, как и шаблон, имена служебных политик которого совпали бы с именами политик другого шаблона. Ссылка на несуществующую политику или на политику с любым из селекторов отклоняется при создании и изменении шаблона. Служебная политика выбирает неймспейсы проектов шаблона через namespaceSelector по их лейблу projects.deckhouse.io/project-template. Этот лейбл ставится при применении шаблона, поэтому после перехода проекта на другой шаблон правила старого шаблона действуют, пока контроллер не применит новый.

Выдача cluster-wide-ресурсов одному проекту

Проекту можно выдать собственные cluster-wide-ресурсы в дополнение к тем, что даёт его шаблон, — в поле spec.grants объекта Project. Формат поля тот же, что у полей шаблона: resources с самими правилами и grantPolicies с именами библиотечных политик ClusterResourceGrantPolicy.

apiVersion: deckhouse.io/v1alpha3
kind: Project
metadata:
  name: my-project
spec:
  projectTemplateName: my-template
  grants:
    resources:
      - resourceName: storageclasses
        allowed: ["fast"]
    grantPolicies:
      - corporate-issuers

Для каждого источника контроллер создаёт служебную политику с именем project-<PROJECT_NAME>-<SOURCE> (для resources — project-<PROJECT_NAME>-inline). Её владелец — проект, а projectSelector выбирает проект по лейблу projects.deckhouse.io/project, поэтому политика действует во всех неймспейсах проекта, в том числе созданных позже. Удаление проекта удаляет его служебные политики. Правила проекта и его шаблона складываются так же, как правила любых двух политик: разрешённые ресурсы суммируются, а ресурс, запрещённый одной из них, остаётся недоступным.

Поле работает по таким правилам:

  • Для изменения spec.grants нужно право на создание объектов ClusterResourceGrantPolicy, то же, что и для создания такой политики напрямую. Пользователь, который может только менять проект, не может выдать ему cluster-wide-ресурсы.
  • Ссылки и имена проверяются так же, как у шаблона. Ссылка на политику с именем inline, на несуществующую политику или на политику с селектором отклоняется. Пустой или недопустимый allowedSelector или deniedSelector в resources отклоняется. Отклоняются и значения spec.grants, из которых получились бы служебные политики с именами, совпадающими с политикой, не принадлежащей проекту, или со служебными политиками другого проекта, а также значения, из которых получилась бы служебная политика с недопустимым именем объекта: так бывает при очень длинном имени политики, на которую ссылаются.
  • Если служебную политику не удаётся применить или политика, на которую ссылаются, позже удалена, контроллер записывает событие Warning на Project. Остальные источники остаются применёнными, а источник, убранный из spec.grants, всё равно отзывается. Политика, созданная заново, подхватывается без ожидания.
  • Имена, начинающиеся с project-, зарезервированы за служебными политиками, а служебная политика меняется только через spec.grants своего проекта.
  • В deckhouse.io/v1alpha2 нет места для этого поля, поэтому изменение проекта, у которого задан spec.grants, через эту версию, в том числе запись его статуса, отклоняется: оно стёрло бы это поле. Меняйте такой проект через deckhouse.io/v1alpha3.

Для пользователей проекта

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

Просмотр доступных cluster-wide-ресурсов

В неймспейсе каждого проекта автоматически создаётся ресурс AvailableClusterResource для каждого зарегистрированного ресурса. С их помощью можно узнать, какие cluster-wide-ресурсы доступны проекту и какой ресурс используется по умолчанию.

Чтобы посмотреть все доступные cluster-wide-ресурсы проекта, выполните следующую команду:

d8 k get available -n <PROJECT_NAME>

Пример вывода:

NAME                KIND         DEFAULT      AVAILABLE   AGE
storageclasses      StorageClass fast-ssd     2           5m
clusterissuers      ClusterIssuer letsencrypt 2           5m

Чтобы просмотреть подробную информацию о ресурсах определённого типа (например, StorageClass), выполните следующую команду:

d8 k get available storageclasses -n <PROJECT_NAME> -o yaml

Пример вывода (сокращённо):

status:
  grantedResourceKind: StorageClass
  default: fast-ssd
  availableCount: 2
  available:
    - name: fast-ssd
      default: true
      fields:
        provisioner: rbd.csi.ceph.com
        reclaimPolicy: Delete
        volumeBindingMode: WaitForFirstConsumer
        allowVolumeExpansion: true
    - name: hdd
      fields:
        provisioner: local.csi.storage.deckhouse.io
        reclaimPolicy: Retain
        volumeBindingMode: WaitForFirstConsumer

Поле status.available[].fields содержит значения некоторых полей каждого доступного ресурса, чтобы ресурс можно было выбрать без доступа к нему самому. Какие поля выводить, выбирает модуль, который регистрирует ресурс, — в параметре spec.catalogFields своего GrantableClusterResourceDefinition. Для StorageClass это provisioner, reclaimPolicy, volumeBindingMode и allowVolumeExpansion. Значение сохраняет свой тип JSON (например, allowVolumeExpansion — логическое значение). Поле, значения которого в ресурсе нет, не выводится: в примере выше у hdd нет allowVolumeExpansion. Изменение cluster-wide-ресурса обычно появляется в AvailableClusterResource в течение 30 секунд.

AvailableClusterResource существует, пока существует соответствующий GrantableClusterResourceDefinition: при удалении GrantableClusterResourceDefinition его AvailableClusterResource удаляется из неймспейсов всех проектов.

Отказ в использовании cluster-wide-ресурса

Если cluster-wide-ресурс недоступен проекту при создании объекта или при изменении, которое задаёт новое значение, запрос отклоняется с сообщением:

[multitenancy] <KIND> "<OBJECT_NAME>" references "<RESOURCE_NAME>" which is not available to project "<PROJECT_NAME>". Ask the cluster administrator to grant it.

В этом случае проверьте доступные ресурсы с помощью AvailableClusterResource. Используйте ресурс из списка доступных или попросите администратора кластера открыть проекту доступ к нужному ресурсу.

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

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

Например, если для StorageClass по умолчанию задан fast-ssd, при создании PersistentVolumeClaim без .spec.storageClassName в это поле может быть автоматически подставлено значение fast-ssd.

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

Проекты без значения по умолчанию

Значение по умолчанию проекта показывается в status.default AvailableClusterResource, а среди имён в status.available оно отмечено полем default: true. Их нет в следующих случаях:

  • в политике не задан default, а в регистрации нет defaultFrom;
  • ресурс задаётся списком значений, а не объектами кластера, и defaultFrom к нему не применяется;
  • defaultFrom задан, но аннотация со значением true есть не ровно у одного объекта;
  • значение по умолчанию задано, но проекту недоступно, например StorageClass кластера по умолчанию не входит в выданные проекту имена или значение по умолчанию — зарезервированный ресурс, который ни одна политика не разрешает проекту.

Тогда поле остаётся пустым, и объект создаётся или отклоняется по обычным правилам.

Для разработчиков модулей

Настройка проверки ссылки на cluster-wide-ресурс

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

Например, чтобы настроить проверку StorageClass, указанного в поле .spec.storageClassName ресурса PostgresDatabase, добавьте в Helm-чарт модуля следующий объект:

apiVersion: multitenancy.deckhouse.io/v1alpha1
kind: GrantableClusterResourceReference
metadata:
  name: postgresdatabases-storageclasses
  labels:
    heritage: deckhouse
    module: postgres
spec:
  grantableClusterResourceName: storageclasses
  rule:
    apiGroups: ["postgres.example.com"]
    apiVersions: ["*"]
    resources: ["postgresdatabases"]
  fieldPaths:
    - path: $.spec.storageClassName
      defaulting: Coerce

В этом примере storageclasses — имя существующего GrantableClusterResourceDefinition, а Coerce позволяет при создании PostgresDatabase подставить доступный проекту StorageClass по умолчанию, если значение отсутствует или недоступно проекту.

Если ресурсы из rule хранят ссылку по разным путям, ограничьте элементы fieldPaths конкретными ресурсами с помощью параметра resources. Например, Job и CronJob хранят имя PriorityClass по разным путям. В этом случае, когда PriorityClass зарегистрирован как priorityclasses, воспользуйтесь следующим примером:

apiVersion: multitenancy.deckhouse.io/v1alpha1
kind: GrantableClusterResourceReference
metadata:
  name: jobs-priorityclasses
  labels:
    heritage: deckhouse
    module: my-module
spec:
  grantableClusterResourceName: priorityclasses
  rule:
    apiGroups: ["batch"]
    apiVersions: ["v1"]
    resources: ["jobs", "cronjobs"]
  fieldPaths:
    - resources: ["jobs"]
      path: $.spec.template.spec.priorityClassName
    - resources: ["cronjobs"]
      path: $.spec.jobTemplate.spec.template.spec.priorityClassName

Для каждого объекта используется самый специфичный из подходящих элементов fieldPaths: элемент, ограниченный resources, приоритетнее элементов, ограниченных только apiGroups или apiVersions, и элемента без ограничений, который применяется ко всем остальным ресурсам из rule. * в resources не ограничивает элемент: это то же самое, что не указывать параметр.

Элемент, условие match которого для объекта не выполняется, пропускается, а из одинаково ограниченных элементов элемент с match приоритетнее элемента без него. Поэтому несколько элементов с одним path могут обрабатывать разные объекты одного ресурса, каждый со своим режимом подстановки: reference storageclasses-pvc проверяет StorageClass у PersistentVolumeClaim с spec.dataSource или spec.dataSourceRef в режиме None, а у остальных PersistentVolumeClaim — в режиме Coerce. Текст параметра message добавляется к отказу в создании объекта для этого элемента.

Описание параметров GrantableClusterResourceReference, режимов подстановки значений по умолчанию, условий match и настройки ресурсов с несколькими API-версиями приведено в описании ресурса.

Регистрация нового cluster-wide-ресурса

Чтобы добавить управление доступом к новому cluster-wide-ресурсу, выполните следующее:

  1. Создайте ресурс GrantableClusterResourceDefinition, чтобы зарегистрировать cluster-wide-ресурс в механизме управления доступом.
  2. Создайте один или несколько объектов GrantableClusterResourceReference, чтобы определить поля, в которых используются ссылки на него.

    Например, чтобы зарегистрировать ресурс MyClusterResource, добавьте в Helm-чарт модуля следующий объект:

    apiVersion: multitenancy.deckhouse.io/v1alpha1
    kind: GrantableClusterResourceDefinition
    metadata:
      name: myclusterresources
      labels:
        heritage: deckhouse
        module: my-module
    spec:
      grantedResource:
        apiGroup: my.example.com
        kind: MyClusterResource
      enforcement: Managed
      defaultAvailability: All
      excluded:
        - matchExpressions:
            - key: my.example.com/internal
              operator: Exists
    

    В этом примере зарегистрированные ресурсы по умолчанию доступны проектам. Ресурсы с лейблом my.example.com/internal исключаются из доступных.

    Чтобы оставить некоторые ресурсы недоступными по умолчанию, но позволить администратору выдавать их отдельным проектам, укажите их в reserved вместо excluded. Администратор выдаёт такой ресурс, как описано в разделе «Выдача зарезервированного ресурса».

    В grantedResource можно указать только cluster-scoped-ресурс. Определение namespaced-ресурса (например, Secret) отклоняется при создании и изменении. Если такое определение всё же сохранено, оно не обрабатывается: ни один проект не получает его AvailableClusterResource, а условие GrantedResourceValid равно False (подробнее — в разделе «Проверка состояния регистрации ресурса»). Ресурс, CRD которого ещё не установлена, принимается: его область видимости проверяется, когда ресурс начинает обслуживаться.

    Описание параметров GrantableClusterResourceDefinition и доступных режимов управления приведено в описании ресурса.

  3. После регистрации cluster-wide-ресурса настройте ссылки на него с помощью GrantableClusterResourceReference, как описано в подразделе «Настройка проверки ссылки на cluster-wide-ресурс».

Вывод полей ресурса для проектов

Пользователи проекта видят доступные cluster-wide-ресурсы в AvailableClusterResource (подробнее — в разделе «Просмотр доступных cluster-wide-ресурсов»), но обычно не могут читать сами ресурсы. Чтобы им было проще выбрать, перечислите выводимые поля в spec.catalogFields GrantableClusterResourceDefinition. Контроллер копирует значения этих полей из каждого доступного ресурса в status.available[].fields AvailableClusterResource.

Пример:

apiVersion: multitenancy.deckhouse.io/v1alpha1
kind: GrantableClusterResourceDefinition
metadata:
  name: myclusterresources
spec:
  grantedResource:
    apiGroup: my.example.com
    kind: MyClusterResource
  catalogFields:
    - name: tier
      path: $.spec.tier
    - name: region
      path: $.metadata.labels['my.example.com/region']

Правила:

  • name — ключ в fields в формате lowerCamelCase; path — singular query JSONPath по RFC 9535, выбирающий одно значение: только имена полей и индексы массивов, без wildcard (*), рекурсивного спуска (..), срезов и фильтров.
  • Пути, которые читают metadata.managedFields, аннотацию kubectl.kubernetes.io/last-applied-configuration или содержащее их родительское поле (например, $.metadata), указывать нельзя: в этих полях хранится копия всего ресурса.
  • Можно указать не более 10 полей.
  • Значение длиннее 512 байт в JSON-сериализации не выводится; поле, значения которого в ресурсе нет, тоже не выводится.
  • Если список status.available одного AvailableClusterResource с полями всех ресурсов занимал бы в JSON-сериализации больше 512 КиБ, полей в нём не будет, но имена и значение по умолчанию останутся.
  • catalogFields работает только для определений с grantedResource, и этот ресурс должен быть cluster-scoped.
  • Значения видны всем пользователям каждого проекта, которому доступен ресурс. Указывайте только несекретные данные.

Некорректные пути и catalogFields без grantedResource отклоняются при создании и изменении GrantableClusterResourceDefinition и отражаются в его условии CatalogFieldsValid. Значения, пропущенные из-за размера, зависят от ресурсов и проекта, поэтому о них сообщают предупреждающие события CatalogFieldsSkipped на GrantableClusterResourceDefinition:

d8 k describe grantableclusterresourcedefinition myclusterresources

Использование x-deckhouse-grantable-resource в настройках приложений Deckhouse Platform

Для управления доступом к cluster-wide-ресурсам в настройках приложений Deckhouse Platform используйте OpenAPI-расширение x-deckhouse-grantable-resource. В этом случае deckhouse-контроллер автоматически проверяет доступность указанного ресурса и при необходимости подставляет значение по умолчанию. Создавать GrantableClusterResourceReference вручную не требуется.

Описание расширения и примеры использования приведены в разделе «Настройки приложения».

Проверка состояния регистрации ресурса

Состояние GrantableClusterResourceDefinition и связанных с ним ресурсов GrantableClusterResourceReference можно проверить в поле status:

  • GrantableClusterResourceDefinition.status.references — содержит список связанных ресурсов GrantableClusterResourceReference и информацию о ресурсах, к которым они применяются;
  • GrantableClusterResourceReference.status.bound — указывает, найден ли соответствующий GrantableClusterResourceDefinition;
  • GrantableClusterResourceReference.status.conditions[Bound] — True с причиной Resolved, если определение найдено, или False с причиной UnknownResource, если его нет. Причина UnknownResource может указывать на ошибку в имени GrantableClusterResourceDefinition или на отсутствие необходимой регистрации;
  • GrantableClusterResourceReference.status.conditions[FieldPathsValid] — проходят ли spec.fieldPaths проверки, выполняемые при создании и изменении объекта (причины Valid, InvalidFieldPaths; в сообщении перечислены все проблемы). False означает, что объект сохранён в обход этих проверок; некорректные пути при проверке доступности пропускаются;
  • GrantableClusterResourceDefinition.status.conditions[GrantedResourceValid] — может ли быть обработан spec.grantedResource. True с причиной ClusterScoped для cluster-scoped-ресурса или ValueBacked для определения без grantedResource; False с причиной Namespaced для namespaced-ресурса, который не обрабатывается; Unknown с причиной KindNotServed, пока ресурс не обслуживается (например, его CRD ещё не установлена), или MappingFailed, если определить его область видимости не удалось;
  • GrantableClusterResourceDefinition.status.conditions[CatalogFieldsValid] — проходят ли spec.catalogFields проверки, выполняемые при создании и изменении объекта (причины Valid, InvalidCatalogFields; в сообщении перечислены все проблемы). У определения без catalogFields условие равно True. О значениях, пропущенных из-за размера, сообщают события CatalogFieldsSkipped (подробнее — в разделе «Вывод полей ресурса для проектов»).

Пример:

d8 k get grantableclusterresourcedefinition myclusterresources -o jsonpath='{range .status.conditions[*]}{.type}={.status} ({.reason}): {.message}{"\n"}{end}'