Управляемый (tenant) Kubernetes

Как развернуть и использовать изолированные управляемые Kubernetes-кластеры в Cozystack.

Управляемый Kubernetes в Cozystack

Если вам нужно развернуть собственное контейнеризованное приложение в Cozystack, лучше всего размещать его в управляемом Kubernetes-кластере.

Cozystack разворачивает Kubernetes-as-a-Service и управляет им как самостоятельным приложением внутри изолированной среды каждого тенант. В Cozystack такие кластеры называются тенант-кластерами Kubernetes, а базовый кластер Cozystack — management-кластером или root-кластером. Тенант-кластеры полностью отделены от management-кластера и предназначены для приложений конкретного tenant или приложений, разработанных заказчиком.

Внутри тенант-кластера пользователи могут использовать сервисы LoadBalancer и быстро заказывать persistent volumes по мере необходимости. Control plane работает в контейнерах, а worker nodes разворачиваются как виртуальные машины; всем этим управляет приложение.

Kubernetes version in tenant clusters is independent of Kubernetes in the management cluster. Users can select the supported patch versions from 1.31 to 1.35.

Зачем использовать управляемый Kubernetes-кластер

Kubernetes стал отраслевым стандартом: он предоставляет единый и понятный API, а для конфигурации в основном использует YAML. Благодаря этому команды проще понимают Kubernetes и работают с ним, а управление инфраструктурой становится более предсказуемым.

Kubernetes использует устойчивые архитектурные паттерны и обеспечивает непрерывное восстановление системы в любых сценариях за счёт механизма reconciliation. Кроме того, он позволяет прозрачно масштабироваться на множество серверов и снимает проблемы, характерные для сложных и устаревших API традиционных платформ виртуализации. Управляемый сервис убирает необходимость разрабатывать собственные решения или изменять исходный код, экономя время и усилия.

Управляемый сервис Kubernetes в Cozystack дает удобный способ эффективно управлять серверными рабочими нагрузками.

Начало работы

Когда тенант-кластер Kubernetes готов, получите kubeconfig для работы с ним. Это можно сделать через UI или запросом kubectl:

  • Откройте дашборд Cozystack, переключитесь в свой тенант, найдите и откройте страницу приложения. Скопируйте один из config-файлов из раздела Secrets.

  • Выполните следующую команду, используя kubeconfig management-кластера:

    kubectl get secret -n tenant-<name> kubernetes-<clusterName>-admin-kubeconfig -o go-template='{{ printf "%s\n" (index .data "admin.conf" | base64decode) }}' > admin.conf
    

Доступно несколько вариантов kubeconfig:

  • admin.conf — стандартный kubeconfig для доступа к новому кластеру. С его помощью можно создавать дополнительных пользователей Kubernetes.
  • admin.svc — тот же token, что и в admin.conf, но адрес API server указывает на внутреннее имя service. Используйте его для приложений, которые работают внутри кластера и которым нужен доступ к API.
  • super-admin.conf — похож на admin.conf, но с расширенными административными правами. Предназначен для диагностики неисправностей и задач обслуживания кластера.
  • super-admin.svc — то же, что super-admin.conf, но с указанием на внутренний адрес API server.

Детали реализации

Тенант-кластер Kubernetes в Cozystack по сути является Kubernetes-in-Kubernetes. При его развертывании используются следующие компоненты:

  • Kamaji Control Plane: Kamaji — open-source проект, который упрощает развертывание Kubernetes control planes в виде pod внутри root-кластера. Каждый control plane pod включает базовые компоненты вроде kube-apiserver, controller-manager и scheduler, что помогает эффективно использовать multi-tenancy и ресурсы.

  • Etcd Cluster: A dedicated etcd cluster is deployed using the cozystack etcd-operator (etcd-operator.cozystack.io/v1alpha2). It provides reliable and scalable key-value storage for the Kubernetes control plane.

  • Worker Nodes: виртуальные машины создаются через KubeVirt и используются как worker nodes. Эти ноды настроены на присоединение к тенант-кластеру Kubernetes, что позволяет разворачивать workload и управлять ими. Диски worker нод автоматически определяют размер блока базового тома и подстраиваются под него (blockSize.matchVolume), чтобы обеспечить совместимость с backend-системами хранения данных, которые используют секторы не по 512 байт, например LINSTOR DRBD с 4Kn-дисками.

  • Cluster API: Cozystack использует Kubernetes Cluster API для подготовки компонентов кластера.

Такая архитектура обеспечивает изолированные, масштабируемые и эффективные тенант-среды Kubernetes.

Справочные материалы по компонентам, которые используются в этом сервисе:

Изменения, нарушающие обратную совместимость

  • ephemeralStorage переименовано в diskSize (v1.4): поле nodeGroups[name].ephemeralStorage было переименовано в nodeGroups[name].diskSize. Существующие кластеры прозрачно мигрируются платформенной миграцией 41 во время pre-upgrade хука — никаких ручных действий не требуется. Новые значения следует записывать в diskSize. Существующие ВМ обновляются поочерёдно (rolling-update) через CAPI при применении новых значений. С переходом воркеров на Talos в этом релизе поле теперь задаёт размер единственного системного диска (образ ОС Talos, потоково загружаемый с factory.talos.dev, состояние kubelet, кэш образов containerd, локальные PVC local-path) — макет с disk-kubelet PVC, использовавшийся до Talos, был удалён. Состояние на этом единственном диске сохраняется при перезапусках одной и той же ВМ (перезапуск virt-launcher, перезагрузка гостевой ОС, сбой узла); при замене ВМ через CAPI (например, изменение поля nodeGroup, устранение неисправности через MachineHealthCheck) выделяется новый диск.

  • Изолированные (air-gapped) воркеры тенантов (Фаза 1 перехода на Talos): загрузка воркеров тенантов переходит с Ubuntu containerDisk + kubeadm на образ диска Talos OS, получаемый по HTTP через CDI, и ссылку на инсталлятор вида .../installer/.... Оба источника теперь можно переопределить — задайте talos.imageFactoryURL (по умолчанию https://factory.talos.dev) на самостоятельно размещённую Image Factory, кэширующее зеркало или внутренний HTTP-файловый сервер, а talos.installerRepository (по умолчанию factory.talos.dev/installer) — на зеркалированный реестр. Секрет *-patch-containerd, рендерящийся через Helm, который ранее передавал платформенную конфигурацию registries.mirrors воркерам тенантов (через монтирование сертификатов containerd certs.d в шаблоне kubeadm), не имеет потребителя в machineconfig Talos и был удалён в этом релизе; загрузка образов контейнеров внутри гостевой системы (поды, скачивающие образы из реестров внутри кластера тенанта) до сих пор не поддерживает переопределение registries.mirrors на уровне тенанта — это будет восстановлено в Фазе 2 через параметры machine.registries.mirrors. Таким образом тенант со строгим egress теперь может зеркалировать образ Talos OS и инсталлятор, но ограниченные по скорости загрузки образов реестра внутри гостевой системы остаются задачей Фазы 2 — заведите issue, если это вам необходимо, а функциональность ещё не реализована.

  • Устранение неисправностей воркеров через MachineHealthCheck включено по умолчанию (Фаза 1 перехода на Talos): параметр maxUnhealthy в MHC для воркеров изменился с жёстко заданного 0 (устранение неисправностей фактически было отключено) на настраиваемый nodeHealthCheck.maxUnhealthy со значением по умолчанию "50%". Теперь CAPI автоматически устраняет неисправности (удаляет и заменяет) неисправные Machine воркеров, пока хотя бы 50% группы остаётся исправным. Значение "50%" намеренно оставляет запас для временно неисправных узлов во время перехода с kubeadm на Talos и медленной первой загрузки с factory.talos.dev; установите nodeHealthCheck.maxUnhealthy: "0%", чтобы сохранить прежнее поведение с отключённым устранением неисправностей, до тех пор пока ваш парк узлов не стабилизируется на воркерах Talos.

  • Управляемые через GitOps ресурсы Kubernetes тенантов должны обновить spec.version в Git (Фаза 1 перехода на Talos): платформенная миграция 46 патчит существующие объекты kuberneteses.apps.cozystack.io с v1.30 на v1.31 (версия v1.30 вышла из матрицы поддержки Talos↔Kubernetes). Когда ресурс Kubernetes тенанта реконсилируется из Git (Flux/Argo), следующая реконсиляция источника повторно применяет version: v1.30 поверх патча миграции 46, что затем срабатывает на защите _versions.tpl чарта, и HelmRelease завершается с ошибкой. Обновите spec.version до v1.31 (или новее) в вашем Git-источнике до или вместе с обновлением платформы. Тенанты, управляемые через API или дашборд, не требуют никаких действий — миграция 46 обрабатывает их автоматически.

  • StorageClass-ы LINSTOR с удалённым доступом автоматически распространяются на тенантов (v1.5): StorageClass-ы LINSTOR инфраструктурного кластера, у которых linstor.csi.linbit.com/allowRemoteVolumeAccess не равен "false", создаются внутри каждого тенанта под тем же именем (предоставляются через csi.kubevirt.io). Предупреждение при обновлении: удалите любой вручную созданный StorageClass тенанта, чьё имя совпадает с распространяемым инфраструктурным классом (например, самодельный replicated), перед обновлением, иначе распространяемый класс не сможет быть создан, и релиз CSI тенанта не сойдётся. Инфраструктурные классы, которые должны оставаться локальными для узла, должны явно иметь allowRemoteVolumeAccess: "false" — отсутствующая аннотация считается признаком доступности для удалённого доступа. Распространение вычисляется во время рендеринга HelmRelease, поэтому классы, добавленные или удалённые на инфраструктурном кластере после создания тенанта, распространяются только при следующей реконсиляции этого тенанта.

  • Worker pools split into KubernetesNodes (Phase 2): spec.nodeGroups, spec.nodeHealthCheck and spec.maxNodeProvisionTime are removed from the Kubernetes CR — worker pools are now separate KubernetesNodes resources (one HelmRelease per pool; see the kubernetes-nodes chart), on which spec.cluster and spec.storageClass are immutable (self == oldSelf). Existing pools are adopted automatically on upgrade by platform migration 56 with no worker-VM churn. Consequences: (1) the Kubernetes CR’s WorkloadsReady condition is now control-plane-only — worker health is reported on each KubernetesNodes resource, so a dashboard or kubectl wait watching the parent no longer reflects worker readiness; (2) enabling addons.ingressNginx now requires a pool carrying roles: [ingress-nginx] (the implicit default md0 is gone — without such a pool the controller DaemonSet schedules nothing); (3) do not edit Kubernetes CRs during a platform upgrade — a mid-window parent render can transiently fail Helm ownership validation while migration 56 re-annotates worker objects, and self-heals once the new chart artifact lands; (4) when deleting a cluster, delete its KubernetesNodes pools before the parent Kubernetes resource, so each pool’s pre-delete unpin hook can run while the tenant apiserver and the CAPI CRDs still exist — deleting the parent first can leave the pool release reconciling CAPI objects against a cluster that is being torn down (in the pre-split monolith the pools were part of the parent release and died with it; they are now separate resources with their own lifecycle); (5) the removed fields (nodeGroups, nodeHealthCheck, maxNodeProvisionTime) are still accepted and stored on an already-upgraded Kubernetes CR — the adoption migration deliberately leaves them in place rather than rewriting parent values mid-upgrade — but they have no effect: editing them (for example scaling via spec.nodeGroups.<pool>.minReplicas) does nothing, and the API returns an admission warning pointing you at the KubernetesNodes resources. A cluster name is also capped at 32 characters so every pool’s KubernetesNodes release name fits the 53-character Helm limit. ComputePlane clusters (the computeplane module) are affected the same way: their worker pools are rendered as separate per-pool KubernetesNodes releases too (materialised directly by the module rather than adopted), so the same pool-name length limit applies to their nodeGroups keys.

  • controlPlane.apiServer.extraArgs refuses flags the tenant control plane owns (Kamaji 26.9.4-edge): the tenant control plane now sets a list of kube-apiserver flags itself and drops an extraArgs entry naming one, where the previous build let the entry win. The entry stops taking effect once the new build reconciles the control plane, whatever the chart renders. Two of those flags have a field the control plane renders them from, and the chart moves an entry written as --flag=value into it while the field is empty: --enable-admission-plugins into controlPlane.apiServer.admissionControllers, --kubelet-preferred-address-types into controlPlane.kubelet.preferredAddressTypes. The KamajiControlPlane CRD accepts only the plugin names it lists, so a plugin outside that list that the apiserver leaves off by default can no longer be enabled, and a moved name outside it fails when the KamajiControlPlane is applied, with an error that names it, rather than at render. The chart refuses to render any other entry naming one of the flags, so a tenant carrying one stops reconciling until the entry is removed; the description of controlPlane.apiServer.extraArgs lists the flags. The same Kamaji update passes every extraArgs entry to the apiserver, so repeats of a flag no longer collapse to the last one: naming the kube feature gates both bare and kube:-prefixed across entries, or giving two --emulated-version entries that name kube, now stops the apiserver from starting. The chart refuses neither, in any spec.oidc.mode: both reach the apiserver as written. Keep one spelling for kube gate terms and one kube emulated version.

The top-level storageClass field is annotated as immutable in the chart schema — see docs/storage-immutability.md for the contract and which consumers enforce it. The per-pool worker storageClass now lives on the KubernetesNodes resource (see the kubernetes-nodes chart).

Proxmox substrate: credentials, privileges and tenant scope

On substrate: proxmox two components authenticate to the hypervisor, and both run in the management cluster, in the tenant’s namespace: the CSI controller (<release>-pcsi-controller) and the cloud-controller-manager (<release>-pccm). The tenant cluster gets the CSI node plugin, the CSIDriver object and the storage classes, none of which carry a credential. proxmox.csi.credentialsSecretName and proxmox.ccm.credentialsSecretName name Secrets in the management cluster with the keys url, token_id, token_secret and region; the tenant cannot read them, and nothing copies them into the tenant cluster.

Keeping the token out of the tenant is half of the isolation. The tenant is cluster-admin of its own cluster, and the controllers act on what the tenant’s objects tell them: the CSI controller attaches the disk a PV’s volumeHandle names to the VM a node’s ID names, and deletes the disk a PV names, with no check that either belongs to this cluster. Under the privileges the upstream charts document — granted on / — one tenant’s objects can make the controller attach, detach or delete another tenant’s disks. The per-cluster volume owner id (vm-<id>-pvc-…) makes leftovers attributable; it does not scope anything.

What contains it is one Proxmox ACL per tenant, on a resource pool. Create a pool for the tenant on the hypervisor, set proxmox.pool to its name on every KubernetesNodes pool of the tenant’s cluster — capmox adds each worker VM to it as it is cloned, replacements included, so the ACL follows every VM without being granted again — and give the tenant’s tokens their privileges on that pool and on a storage dedicated to the tenant:

ComponentPrivilegesPath
CSI controllerVM.Audit, VM.Config.Disk/pool/<proxmox.pool>
CSI controllerDatastore.Allocate, Datastore.AllocateSpace, Datastore.Audit/storage/<the tenant's storage>: Datastore.Allocate on a storage reaches every volume on it
CCMVM.Audit, VM.GuestAgent.Audit/pool/<proxmox.pool>: a NotReady node whose VM the token cannot see is reported as gone, and the CCM deletes it
CCMSys.Audit/

Grant these to the user that owns the tokens as well as to the tokens themselves: Proxmox caps a privilege-separated token at its user’s permissions, so a token whose user holds nothing has nothing, whatever its own ACL says. pveum user token permissions <user> <token> --path /pool/<proxmox.pool> shows the set that actually applies.

A storage shared between tenants cannot be scoped: Datastore.Allocate on it is what deletes volumes and also what lets any volume on it be attached. Without proxmox.pool there is no VM-level scope either: a token that reaches the tenant’s VMs then reaches every VM on the hypervisor. What the pool-and-storage scope still leaves open is the tenant’s own disks, which the tenant can attach, detach and delete through the controller — the same reach a cluster-admin of the tenant has anyway.

proxmox.insecure defaults to false: the controllers verify the hypervisor’s certificate. A stock Proxmox VE install serves a self-signed one, so either set insecure: true for it or install a certificate the management cluster trusts.

Параметры

Общие параметры

NameDescriptionTypeValue
storageClassDefault StorageClass inside the tenant cluster. Remote-accessible LINSTOR classes are auto-propagated to the tenant under the same name.stringreplicated

Application-specific Parameters

NameDescriptionTypeValue
versionKubernetes major.minor version to deploystringv1.35
hostExternal hostname for Kubernetes cluster. Defaults to <cluster-name>.<tenant-host> if empty.string""

Substrate

NameDescriptionTypeValue
substrateWhich infrastructure provider backs this cluster’s worker VMs. kubevirt runs them inside this cluster; proxmox runs them on an external Proxmox VE cluster through capmox. The control plane is Kamaji either way — this selects the infrastructure half only. Must match the substrate of every KubernetesNodes pool attached to this cluster: the pools reference this cluster’s infrastructure object by kind, and a mismatch leaves their Machines unreconciled. Switching an existing cluster is not supported; create a new one.stringkubevirt
proxmoxProxmox substrate settings.object{}
proxmox.allowedNodesProxmox nodes capmox may place VMs on. Empty means every node in the Proxmox cluster.[]string[]
proxmox.dnsServersNameservers written into each worker’s network config. Required by the ProxmoxCluster schema.[]string[]
proxmox.insecureSkip verification of the Proxmox API server certificate in the CCM and the CSI controller, both of which run in the management cluster. Default false: the certificate is verified unless an operator turns that off. A stock Proxmox VE install serves a self-signed one, so set true for it, or install a certificate the management cluster trusts.boolfalse
proxmox.ipv4ConfigAddress pool for workers. capmox assigns static addresses and has no DHCP mode, so this is required rather than optional.object{}
proxmox.ipv4Config.addressesRanges or CIDRs, e.g. ["10.0.0.120-10.0.0.170"]. capmox turns these into an InClusterIPPool, so they must not overlap any DHCP range on the same L2 or two workers will answer to one address.[]string[]
proxmox.ipv4Config.gatewayDefault gateway for the workers.string""
proxmox.ipv4Config.prefixNetmask prefix length.int24
proxmox.ccmProxmox cloud-controller-manager settings.object{}
proxmox.ccm.credentialsSecretNameSecret in THIS namespace holding the controller’s Proxmox API credentials under the keys url, token_id, token_secret and region. May name the same Secret as csi.credentialsSecretName; it is a separate knob so the two can hold separate tokens, since this one only reads VM inventory while the driver attaches and detaches disks.string""
proxmox.csiProxmox CSI driver settings.object{}
proxmox.csi.enabledInstall the driver. Without it a Proxmox-backed tenant has no way to provision PersistentVolumes at all.booltrue
proxmox.csi.credentialsSecretNameSecret in THIS namespace holding the driver’s Proxmox API credentials under the keys url, token_id, token_secret and region. The parent chart composes them into the controller’s config file here, in the management cluster; nothing reaches the tenant, and no token is written into a rendered manifest. Distinct from the capmox credentials on purpose: the driver attaches and detaches disks, which is a different blast radius from creating VMs.string""
proxmox.csi.storageClassesStorageClasses to create in the tenant.[]object[]
proxmox.csi.storageClasses[i].nameStorageClass name inside the tenant cluster.string""
proxmox.csi.storageClasses[i].storageProxmox storage id the volumes are created on (as it appears in pvesm status).string""
proxmox.csi.storageClasses[i].fstypeFilesystem the driver formats volumes with: ext4 or xfs.string""
proxmox.csi.storageClasses[i].ssdMark volumes as SSD-backed, which changes the discard/cache defaults Proxmox applies.boolfalse
proxmox.csi.storageClasses[i].reclaimPolicyDelete or Retain.string""

Cluster Addons

NameDescriptionTypeValue
addonsCluster addons configuration.object{}
addons.certManagerCert-manager addon.object{}
addons.certManager.enabledEnable cert-manager.boolfalse
addons.certManager.valuesOverrideCustom Helm values overrides.object{}
addons.ciliumCilium CNI plugin. Always installed as the tenant cluster’s CNI; this section only overrides its Helm values.object{}
addons.cilium.valuesOverrideCustom Helm values overrides.object{}
addons.gatewayAPIGateway API addon.object{}
addons.gatewayAPI.enabledEnable Gateway API.boolfalse
addons.ingressNginxIngress-NGINX controller.object{}
addons.ingressNginx.enabledEnable the controller (requires nodes labeled ingress-nginx).boolfalse
addons.ingressNginx.exposeMethodMethod to expose the controller. Allowed values: Proxied, LoadBalancer.stringProxied
addons.ingressNginx.hostsDomains routed to this tenant cluster when exposeMethod is Proxied.[]string[]
addons.ingressNginx.valuesOverrideCustom Helm values overrides.object{}
addons.gpuOperatorNVIDIA GPU Operator.object{}
addons.gpuOperator.enabledВключить GPU Operator.boolfalse
addons.gpuOperator.valuesOverrideПользовательские переопределения значений Helm.object{}
addons.hamiHAMi GPU virtualization middleware.object{}
addons.hami.enabledВключить HAMi (требует GPU Operator).boolfalse
addons.hami.valuesOverrideПользовательские переопределения значений Helm.object{}
addons.monitoringAgentsMonitoring agents.object{}
addons.monitoringAgents.enabledEnable monitoring agents.boolfalse
addons.monitoringAgents.valuesOverrideCustom Helm values overrides.object{}
addons.verticalPodAutoscalerVertical Pod Autoscaler. Installed and removed together with addons.monitoringAgents.enabled; this section only overrides its Helm values.object{}
addons.verticalPodAutoscaler.valuesOverrideCustom Helm values overrides.object{}
addons.veleroVelero backup/restore addon.object{}
addons.velero.enabledEnable Velero.boolfalse
addons.velero.valuesOverrideCustom Helm values overrides.object{}
addons.corednsCoreDNS addon. Always installed as the tenant cluster’s DNS; this section only overrides its Helm values.object{}
addons.coredns.valuesOverrideCustom Helm values overrides.object{}
addons.ouroborosHairpin-NAT fix for ingress-nginx with PROXY-protocol.object{}
addons.ouroboros.enabledEnable ouroboros. Requires addons.ingressNginx.enabled (chart-render fail otherwise). Only useful when PROXY-protocol is wired on the tenant ingress-nginx via valuesOverride.boolfalse
addons.ouroboros.valuesOverrideCustom Helm values overrides. Operator-key wins over cozystack defaults.object{}

Конфигурация Kubernetes Control Plane

NameDescriptionTypeValue
controlPlaneKubernetes control-plane configuration.object{}
controlPlane.replicasNumber of control-plane replicas.int2
controlPlane.apiServerAPI Server configuration.object{}
controlPlane.apiServer.resourcesCPU and memory resources for API Server.object{}
controlPlane.apiServer.resources.cpuCPU available.quantity""
controlPlane.apiServer.resources.memoryMemory (RAM) available.quantity""
controlPlane.apiServer.resourcesPresetPreset if resources omitted.stringc1.medium
controlPlane.apiServer.extraArgsExtra command-line flags appended to the tenant kube-apiserver, passed through to KamajiControlPlane spec.apiServer.extraArgs. For OIDC use spec.oidc.mode — this passthrough is the escape hatch for unrelated apiserver flags. The tenant control plane sets each of the following flags itself and drops an entry naming one before the apiserver sees it. The chart moves an --enable-admission-plugins= entry into controlPlane.apiServer.admissionControllers and a --kubelet-preferred-address-types= entry into controlPlane.kubelet.preferredAddressTypes while that field is empty, and refuses any other entry naming one of them: --advertise-address, --client-ca-file, --enable-admission-plugins, --service-cluster-ip-range, --kubelet-client-certificate, --kubelet-client-key, --kubelet-preferred-address-types, --proxy-client-cert-file, --proxy-client-key-file, --requestheader-allowed-names, --requestheader-client-ca-file, --secure-port, --service-account-key-file, --service-account-signing-key-file, --tls-cert-file, --tls-private-key-file, --etcd-servers, --etcd-cafile, --etcd-certfile, --etcd-keyfile, --etcd-prefix, --etcd-compaction-interval, --egress-selector-config-file. When spec.oidc.mode is not None the chart also renders OIDC flags here, reads what you have written on them, and refuses some combinations outright; docs/oidc-tenant.md carries which flags, which combinations, and why. Do NOT add legacy --oidc-* flags here when spec.oidc.mode is not None; the chart injects --authentication-config and the apiserver refuses to boot with both. Empty by default (no change to current behavior).[]string[]
controlPlane.apiServer.admissionControllersAdmission plugins the tenant kube-apiserver enables, passed through to KamajiControlPlane spec.admissionControllers, which the control plane renders as --enable-admission-plugins. A non-empty list replaces the control plane’s default set instead of adding to it. The kube-apiserver enables these plugins in addition to its own default ones, so leaving a plugin out does not turn it off; to turn one off, name it in --disable-admission-plugins in controlPlane.apiServer.extraArgs and keep it out of this list, since the apiserver refuses to start with a plugin in both, and the control plane’s default set names several. Empty by default, which keeps that default set, taken from the TenantControlPlane CRD: CertificateApproval, CertificateSigning, CertificateSubjectRestriction, DefaultIngressClass, DefaultStorageClass, DefaultTolerationSeconds, LimitRanger, MutatingAdmissionWebhook, NamespaceLifecycle, PersistentVolumeClaimResize, Priority, ResourceQuota, RuntimeClass, ServiceAccount, StorageObjectInUseProtection, TaintNodesByCondition, ValidatingAdmissionWebhook. NodeRestriction is not in it.[]string[]
controlPlane.apiServer.extraVolumesExtra volumes added to the control-plane Deployment, passed through to KamajiControlPlane spec.deployment.extraVolumes. Use to mount a ConfigMap or Secret holding an AuthenticationConfiguration file referenced by extraArgs. Each item is a core/v1 Volume, but because the control-plane pod runs on the management cluster only configMap and secret sources are allowed (host-reaching sources like hostPath/csi and token-projection via projected are rejected); each volume must have a unique, non-empty name and exactly one source. The names talos-ca and talos-tls-cert are reserved by the chart. Empty by default.[]object[]
controlPlane.apiServer.extraVolumeMountsExtra volume mounts added to the tenant kube-apiserver container, passed through to KamajiControlPlane spec.apiServer.extraVolumeMounts. Each name must reference a volume declared in extraVolumes; the chart-managed talos secret volumes cannot be mounted. Each item is a core/v1 VolumeMount. Empty by default.[]object[]
controlPlane.controllerManagerController Manager configuration.object{}
controlPlane.controllerManager.resourcesCPU and memory resources for Controller Manager.object{}
controlPlane.controllerManager.resources.cpuCPU available.quantity""
controlPlane.controllerManager.resources.memoryMemory (RAM) available.quantity""
controlPlane.controllerManager.resourcesPresetPreset if resources omitted.stringt1.micro
controlPlane.schedulerScheduler configuration.object{}
controlPlane.scheduler.resourcesCPU and memory resources for Scheduler.object{}
controlPlane.scheduler.resources.cpuCPU available.quantity""
controlPlane.scheduler.resources.memoryMemory (RAM) available.quantity""
controlPlane.scheduler.resourcesPresetPreset if resources omitted.stringt1.micro
controlPlane.konnectivityKonnectivity configuration.object{}
controlPlane.konnectivity.serverKonnectivity Server configuration.object{}
controlPlane.konnectivity.server.resourcesCPU and memory resources for Konnectivity.object{}
controlPlane.konnectivity.server.resources.cpuCPU available.quantity""
controlPlane.konnectivity.server.resources.memoryMemory (RAM) available.quantity""
controlPlane.konnectivity.server.resourcesPresetPreset if resources omitted.stringt1.micro
controlPlane.kubeletKubelet connection settings.object{}
controlPlane.kubelet.preferredAddressTypesNode address types the tenant kube-apiserver tries, in order, when it connects to a kubelet, passed through to KamajiControlPlane spec.kubelet.preferredAddressTypes, which the control plane renders as --kubelet-preferred-address-types. The KamajiControlPlane CRD rejects a repeated name. Empty by default, which renders InternalIP, ExternalIP, or the list of a --kubelet-preferred-address-types= entry in controlPlane.apiServer.extraArgs when there is one.[]string[]

Talos Worker Image

NameDescriptionTypeValue
talosTalos worker image configuration.object{}
talos.versionTalos release used for worker OS image and installer. Must satisfy the chart’s Talos<->Kubernetes support matrix against the chosen version.stringv1.13.6
talos.schematicIDTalos image-factory schematic ID. Defaults to the cozystack-tested vanilla schematic. Operators using custom schematics (system extensions, kernel args) override here.stringce4c980550dd2ab1b17bbf2b08801c7eb59418eafe8f279833297925d67c7515
talos.imageFactoryURLBase URL of the Talos Image Factory that serves the worker OS disk image (the openstack-amd64.raw.xz raw artifact streamed in by CDI over HTTP). Defaults to the public factory. Point at a self-hosted Image Factory, a caching mirror, or an internal HTTP file server for air-gapped, rate-limited, or flaky-egress environments. No trailing slash.stringhttps://factory.talos.dev
talos.installerRepositoryOCI repository prefix for the Talos installer image used by the in-guest talos-reconcile upgrade Job. Resolved as <installerRepository>/<schematicID>:<version>. Defaults to the public factory’s installer path. Override for air-gapped or mirrored registries. No trailing slash.stringfactory.talos.dev/installer
talos.registryMirrorsTalos machine.registries.mirrors passthrough for worker nodes: a map of upstream registry host to { endpoints: [ ... ] }. Empty by default, so workers pull container images (the Talos kubelet image included) directly from the upstream registry. Point a host such as ghcr.io at an in-cluster pull-through mirror for air-gapped, rate-limited, or flaky-egress environments so a worker’s boot does not depend on live public egress. Talos still falls back to the upstream registry unless a host also sets skipFallback: true, so a mirror alone does not enforce air-gap.object{}

OIDC

NameDescriptionTypeValue
oidcOIDC authentication and per-user RBAC for the tenant kube-apiserver. See docs/oidc-tenant.md for the operator guide.object{}
oidc.modeIdentity mode. None: no OIDC, only the static admin kubeconfig works. System: trust the platform Keycloak realm (cozy by default) via a per-cluster public client with audience binding; zero-config default. CustomConfig: trust a tenant-supplied issuer directly (BYO); cozy is not in the path.stringNone
oidc.customConfigTenant-supplied AuthenticationConfiguration; consumed only when mode: CustomConfig.object{}
oidc.customConfig.configInline AuthenticationConfiguration YAML (apiserver.config.k8s.io/v1beta1). The chart writes the value verbatim into a Secret mounted at /etc/kubernetes/authentication-config/config.yaml on the kube-apiserver. Mutually exclusive with secretRef.name.string""
oidc.customConfig.secretRefReference to an existing Secret in the tenant namespace carrying the AuthenticationConfiguration.object{}
oidc.customConfig.secretRef.nameName of an existing Secret in the tenant (release) namespace whose config.yaml key holds an apiserver.config.k8s.io/v1beta1 AuthenticationConfiguration. Mutually exclusive with customConfig.config.string""
oidc.usersUsers granted access to the tenant cluster; each entry produces one ClusterRoleBinding inside the tenant cluster. Works for both System and CustomConfig modes.[]object[]
oidc.users[i].emailEmail address matched against the email claim from the issuer. Used verbatim as the User: subject in the ClusterRoleBinding inside the tenant cluster. The email claim is a built-in OIDC scope requested explicitly by the chart-generated kubectl oidc-login kubeconfig; every conformant OIDC provider (cozy realm included) emits it.string""
oidc.users[i].roleRole to bind: admin maps to ClusterRole/cluster-admin, view maps to ClusterRole/view.string{}

Parameter examples and reference

resources and resourcesPreset

resources sets explicit CPU and memory configurations for each replica. Every resource it leaves unset is taken from the preset defined in resourcesPreset.

resources:
  cpu: 4000m
  memory: 4Gi

resourcesPreset задает именованную конфигурацию CPU и memory для каждой реплики. Эта настройка игнорируется, если задано соответствующее значение resources.

Preset nameCPUmemory
nano250m128Mi
micro500m256Mi
small1512Mi
medium11Gi
large22Gi
xlarge44Gi
2xlarge88Gi

Ресурсы типа инстанса

В Cozystack доступны следующие ресурсы для типов инстансов:

ИмяvCPUsПамять
cx1.2xlarge816Gi
cx1.2xlarge1gi816Gi
cx1.4xlarge1632Gi
cx1.4xlarge1gi1632Gi
cx1.8xlarge3264Gi
cx1.8xlarge1gi3264Gi
cx1.large24Gi
cx1.large1gi24Gi
cx1.medium12Gi
cx1.medium1gi12Gi
cx1.xlarge48Gi
cx1.xlarge1gi48Gi
d1.2xlarge832Gi
d1.2xmedium24Gi
d1.4xlarge1664Gi
d1.8xlarge32128Gi
d1.large28Gi
d1.medium14Gi
d1.micro11Gi
d1.nano1512Mi
d1.small12Gi
d1.xlarge416Gi
gn1.2xlarge832Gi
gn1.4xlarge1664Gi
gn1.8xlarge32128Gi
gn1.xlarge416Gi
m1.2xlarge864Gi
m1.2xlarge1gi864Gi
m1.4xlarge16128Gi
m1.4xlarge1gi16128Gi
m1.8xlarge32256Gi
m1.8xlarge1gi32256Gi
m1.large216Gi
m1.large1gi216Gi
m1.xlarge432Gi
m1.xlarge1gi432Gi
n1.2xlarge1632Gi
n1.4xlarge3264Gi
n1.8xlarge64128Gi
n1.large48Gi
n1.medium44Gi
n1.xlarge816Gi
o1.2xlarge832Gi
o1.4xlarge1664Gi
o1.8xlarge32128Gi
o1.large28Gi
o1.medium14Gi
o1.micro11Gi
o1.nano1512Mi
o1.small12Gi
o1.xlarge416Gi
rt1.2xlarge832Gi
rt1.4xlarge1664Gi
rt1.8xlarge32128Gi
rt1.large28Gi
rt1.medium14Gi
rt1.micro11Gi
rt1.small12Gi
rt1.xlarge416Gi
u1.2xlarge832Gi
u1.2xmedium24Gi
u1.4xlarge1664Gi
u1.8xlarge32128Gi
u1.large28Gi
u1.medium14Gi
u1.micro11Gi
u1.nano1512Mi
u1.small12Gi
u1.xlarge416Gi

Серия U: Universal

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

U — сокращение от “Universal”, то есть серия рассчитана на универсальные рабочие нагрузки.

VM этих типов инстансов делят физические CPU-ядра с другими VM по принципу разделения процессорного времени.

Характеристики серии U

Особенности этой серии:

  • Burstable CPU performance - рабочая нагрузка имеет базовый уровень вычислительной производительности, но может кратковременно превышать его при наличии свободных вычислительных ресурсов.
  • vCPU-To-Memory Ratio (1:4) - соотношение vCPU к memory 1:4, чтобы снизить уровень шума на каждой ноде.

Серия O: Overcommitted

Серия O основана на серии U; единственное отличие — избыточное выделение памяти.

O — сокращение от “Overcommitted”.

Характеристики Серии O

Особенности этой серии:

  • Burstable CPU performance - рабочая нагрузка имеет базовый уровень вычислительной производительности, но может кратковременно превышать его при наличии свободных ресурсов хоста.
  • Overcommitted Memory - память используется с избытком, чтобы получить более высокую плотность размещения рабочей нагрузки.
  • vCPU-To-Memory Ratio (1:4) - соотношение vCPU к memory 1:4, чтобы снизить уровень шума каждой ноды.

Серия CX: Compute Exclusive

Серия CX предоставляет выделенные вычислительные ресурсы для приложений с высокой нагрузкой на CPU.

CX — сокращение от “Compute Exclusive”.

Выделенные ресурсы предоставляются вычислительным потокам виртуальной машины. Чтобы это обеспечить, запрашиваются дополнительные ядра (в зависимости от количества дисков и NIC), которые разгружают IO потоки с ядрами, выделенных под рабочие нагрузки. Кроме того, в этой серии топологии NUMA используемых ядер передается в VM.

Характеристики серии CX

Особенности этой серии:

  • Hugepages - hugepages используются для повышения производительности памяти.
  • Dedicated CPU - физические ядра эксклюзивно назначаются каждому vCPU, чтобы дать рабочей нагрузки фиксированные и высокие гарантии вычислительной мощности.
  • Isolated emulator threads - потоки эмулятора гипервизора изолируются от vCPU, чтобы снизить влияние эмуляции на рабочую нагрузку.
  • vNUMA - физическая топология NUMA отражается внутри гостевой VM, чтобы оптимизировать использование кеша на стороне гостевой VM.
  • vCPU-To-Memory Ratio (1:2) - соотношение vCPU к memory 1:2.

Серия M: Memory

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

M — сокращение от “Memory”.

Характеристики серии M

Особенности этой серии:

  • Hugepages - hugepages используются для повышения производительности памяти.
  • Burstable CPU performance - рабочая нагрузка имеет базовый уровень вычислительной производительности, но может кратковременно превышать его при наличии свободных ресурсов хоста.
  • vCPU-To-Memory Ratio (1:8) - соотношение vCPU к memory 1:8, чтобы заметно снизить уровень шума каждой ноды.

Серия RT: RealTime

Серия RT предоставляет ресурсы для приложений реального времени, например Oslat.

RT — сокращение от “realtime”.

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

Характеристики серии RT

Особенности этой серии:

  • Hugepages - hugepages используются для повышения производительности памяти.
  • Dedicated CPU - физические ядра эксклюзивно назначаются каждому vCPU, чтобы дать рабочей нагрузки фиксированные и высокие гарантии вычислительной мощности.
  • Isolated emulator threads - потоки эмулятора гипервизора изолируются от vCPU, чтобы снизить влияние эмуляции на рабочую нагрузку.
  • vCPU-To-Memory Ratio (1:4) - соотношение vCPU к memory 1:4 начиная с размера medium.

Kubernetes Worker Node Pools

Reference for KubernetesNodes, the resource that adds a pool of worker nodes to a managed Kubernetes cluster.

OIDC authentication for kubectl

Give tenant users per-identity kubectl access to a Managed Kubernetes cluster with per-cluster audience isolation.

GPU Sharing с HAMi

Как включить дробное разделение GPU в tenant-кластерах Kubernetes с помощью HAMi.

Backups with the Velero addon

Enable the Velero addon in a tenant Kubernetes cluster, point it at a SeaweedFS bucket, and back up and restore workloads.

Running Tenant Kubernetes Workers on Proxmox VE

Run the worker nodes of managed Kubernetes clusters on an external Proxmox VE cluster instead of KubeVirt, using the Cluster API Proxmox provider, the Proxmox cloud-controller-manager and the Proxmox CSI driver.

Как перенести реплики etcd в tenant-кластерах

Как перенести реплики tenant-кластеров etcd, которые используются tenant-кластерами Kubernetes.

Last modified 2026-11-03: translate 1.7 (726310fa)