Стадия жизненного цикла модуля: Preview
Шаблоны проектов, доступные по умолчанию
В 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
Создание проекта
Чтобы создать проект, выполните следующие шаги:
- Создайте Project с указанием имени шаблона проекта в поле .spec.projectTemplateName.
- Задайте стандартные поля .spec.administrators и .spec.quota. Они работают с любым шаблоном.
-
В параметре .spec.parameters ресурса Project укажите значения параметров для секции .spec.parametersSchema.openAPIV3Schema ресурса ProjectTemplate.
Пример Project, созданного из шаблона
defaultProjectTemplate: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».
-
Для проверки статуса проекта выполните команду:
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и ProjectNamespacebackendпроекта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 ставит только контроллер: неймспейс, созданный вручную с этим лейблом, отклоняется, в том числе с пустым значением, поэтому нельзя сделать так, чтобы неймспейс выглядел принадлежащим чужому проекту. Неймспейс принадлежит только проекту, который назван в лейбле: неймспейс без лейбла или с пустым значением не засчитывается проекту с тем же именем.
Неймспейс, на котором пустое значение уже стоит, в проект не переводится: раньше пустое значение исключало неймспейс из перехода в проект, и так остаётся, пока лейбл не уберут.
Например:
-
Создайте новый неймспейс:
d8 k create ns test -
Убедитесь, что проект создался:
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держит объект, пока контроллер не снимет лейбл с неймспейсов, и только потом вместе с ним удаляются объекты ResourceQuotad8-project-quota. С неймспейса, который удаляется, лейбл снимается сразу, чтобы объекты, ожидающие финализатор, например заявки на тома под защитой от удаления, можно было обновлять. Если модуль отключён раньше, чем финализатор снят, снимите его вручную. -
В статусе ProjectQuotaStatus видны сумма потребления по неймспейсам (
status.used), число неймспейсов и 50 неймспейсов, ближе всего подошедших к лимиту. Потребление каждого неймспейса — в его ResourceQuotad8-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.
Если счётчик не даёт создавать объекты проектов и причину быстро не устранить, выполняйте шаги по порядку, пока создание объектов не заработает:
-
Если создание объектов завершается ошибкой
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>укажите, почему проверка приостановлена. -
Если создание объектов завершается ошибкой
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. -
Отключите модуль
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для своего текущего поколения, а у ClusterRoled8: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, а затем удалите копию.
Чтобы перевести шаблон, который используют проекты, выполните следующие шаги:
-
Найдите проекты шаблона, которые всё ещё задают
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, который он пропускал. -
Настройте каждый инструмент, который записывает шаблон, например GitOps-инструмент или генератор, на запись через
deckhouse.io/v1alpha2. Когда у шаблона появляется поле, котороеdeckhouse.io/v1alpha1не может описать, напримерmanifests, запись шаблона черезdeckhouse.io/v1alpha1отклоняется, потому что она стёрла бы это поле. -
Запишите шаблон как
deckhouse.io/v1alpha2с полями из таблицы и сmanifests, безresourcesTemplate, одним изменением. Сохраните вparametersSchemaпараметры, которые задают проекты. Объявите параметрrequiredRequestsсtype: boolean, сdefault: true, если текст рендерил OperationPolicyrequired-requests-*, и сdefault: false, если не рендерил, чтобы проекты по-прежнему отклоняли или пропускали поды без запросов CPU и памяти. Шаблон, который используют проекты, не может потерятьresourcesTemplate, если вместо него не заданы структурированные поля илиmanifests. -
Проверьте каждый проект после перехода. Его условие
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}' -
Решите, что делать с каждым объектом, который остаётся в
.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 задаёт тем же значением или меньшим. Передача идёт в следующем порядке:
- Project получает условие
HandoverPendingсо значениемTrue. Затем объекты получают аннотациюhelm.sh/resource-policy: keepи аннотациюprojects.deckhouse.io/kept-by-handover: "true", поэтому обновление релиза их не удаляет. - ProjectRoleBinding
d8-administratorsи ResourceQuotad8-project-quotaсоздаются до обновления релиза. - Сохранённые объекты удаляются, когда в
d8-administratorsуказаны администраторы из.spec.administratorsи он сталReadyдля своего текущегоmetadata.generation, у ClusterRoled8: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 не рендерят, обновление удаляет.
Создание собственного шаблона для проекта
Для создания своего шаблона:
- Возьмите за основу один из шаблонов по умолчанию, например,
default. -
Скопируйте его в отдельный файл, например,
my-project-template.yamlпри помощи команды:d8 k get projecttemplates default -o yaml > my-project-template.yaml - Отредактируйте файл
my-project-template.yamlи измените структурированные поля, объекты вmanifestsи схему входных параметров под свои задачи. - Измените имя шаблона в поле
.metadata.name. - Удалите из файла лейбл
heritage, поляmetadata.resourceVersion,metadata.uid,metadata.creationTimestamp,metadata.generation,metadata.managedFieldsи разделstatus. -
Примените полученный шаблон командой:
d8 k apply -f my-project-template.yaml -
Проверьте доступность нового шаблона с помощью команды:
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.
Для этого используются следующие ресурсы:
- ValidatingAdmissionPolicy — определяет правила валидации:
- Операции:
CREATE,UPDATEиDELETE; группаsystem:mastersисключением не является; - Проверка: менять такой объект могут только контроллер модуля и идентичности, которые пропускает эта политика (подробнее — в разделе «Кто обходит валидацию»). Для неймспейса проекта также разрешено обновление, меняющее только лейблы и аннотации вне ключей, которыми управляет модуль (подробнее — в разделе «Автоматическое создание проекта для неймспейса»);
- Применяется ко всем ресурсам и API группам.
- Операции:
- 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. Всем остальным, кто указывает такого пользователя или такую группу в привязке, она отказывает, включая остальные ServiceAccountkube-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):
-
Создайте файл с манифестами ресурсов 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 -
Настройте параметры валидации:
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-лог.
-
Примените политику:
d8 k apply -f my-validation-policy.yaml -
Убедитесь, что ваши ресурсы имеют соответствующий лейбл
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-ресурсу, выполните следующее:
- Создайте ресурс GrantableClusterResourceDefinition, чтобы зарегистрировать cluster-wide-ресурс в механизме управления доступом.
-
Создайте один или несколько объектов 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 и доступных режимов управления приведено в описании ресурса.
- После регистрации 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}'