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

Управляемый 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.

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

• Kamaji Control Plane
• Kamaji — Cluster API
• github.com/clastix/kamaji
• KubeVirt
• github.com/kubevirt/kubevirt
• github.com/cozystack/etcd-operator
• Kubernetes Cluster API
• github.com/kubernetes-sigs/cluster-api-provider-kubevirt
• github.com/kubevirt/csi-driver

Breaking Changes

• ephemeralStorage renamed to diskSize (v1.4): The nodeGroups[name].ephemeralStorage field has been renamed to nodeGroups[name].diskSize. Existing clusters are migrated transparently by platform migration 41 during the pre-upgrade hook — no manual action is required. Newly written values should use diskSize. Existing VMs are rolling-updated via CAPI when the new values are applied. With the Talos worker rollover in this release the field now sizes the single system disk (Talos OS image streamed from factory.talos.dev, kubelet state, containerd image cache, local-path PVCs) — the pre-Talos disk-kubelet PVC layout was removed. State on that single disk persists across same-VM reboots (virt-launcher restart, guest reboot, node failure); VM replacement by CAPI (e.g. nodeGroup field change, MachineHealthCheck remediation) provisions a fresh disk.

• Air-gapped tenant workers (Phase 1 Talos rollover): tenant worker bootstrap moves from Ubuntu containerDisk + kubeadm to a Talos OS disk image fetched over HTTP by CDI and a .../installer/... installer reference. Both sources are now overridable — set talos.imageFactoryURL (default https://factory.talos.dev) to a self-hosted Image Factory, a caching mirror, or an internal HTTP file server, and talos.installerRepository (default factory.talos.dev/installer) to a mirrored registry. The Helm-rendered *-patch-containerd Secret that previously plumbed the platform-wide registries.mirrors config to tenant workers (via the kubeadm template’s containerd certs.d mount) has no consumer in the Talos machineconfig and was removed in this release; in-guest container-image pulls (pods pulling from registries inside the tenant cluster) still honour no per-tenant registries.mirrors override until Phase 2 restores it via machine.registries.mirrors knobs. So a strict-egress tenant can now mirror the Talos OS image and installer, but rate-limited in-guest registry pulls remain a Phase 2 follow-up — file an issue if you depend on this and it is not yet landed.

• Worker MachineHealthCheck remediation is now enabled by default (Phase 1 Talos rollover): the worker MHC maxUnhealthy moved from a hard-coded 0 (remediation effectively off) to a configurable nodeHealthCheck.maxUnhealthy defaulting to "50%". CAPI now auto-remediates (deletes and replaces) unhealthy worker Machines while at least 50% of a group stays healthy. "50%" deliberately leaves headroom for transient unhealthy nodes during the kubeadm→Talos rollover and slow first boots from factory.talos.dev; set nodeHealthCheck.maxUnhealthy: "0%" to keep the previous remediation-off behaviour until your fleet is stable on Talos workers.

• GitOps-managed tenant Kubernetes CRs must bump spec.version in Git (Phase 1 Talos rollover): platform migration 46 patches live kuberneteses.apps.cozystack.io objects from v1.30 to v1.31 (v1.30 left the Talos↔Kubernetes support matrix). When the tenant Kubernetes CR is reconciled from Git (Flux/Argo), the next source reconcile re-applies version: v1.30 over migration 46’s patch, which then trips the chart’s _versions.tpl guard and the HelmRelease fails. Update spec.version to v1.31 (or newer) in your Git source before/with the platform upgrade. Tenants managed via the API or dashboard need no action — migration 46 handles them.

• Remote-accessible LINSTOR StorageClasses are auto-propagated to tenants (v1.5): infra-cluster LINSTOR StorageClasses whose linstor.csi.linbit.com/allowRemoteVolumeAccess is not "false" are created inside each tenant under the same name (provisioned by csi.kubevirt.io). Upgrade caveat: delete any manually created tenant StorageClass whose name collides with a propagated infra class (e.g. a hand-made replicated) before upgrading, or the propagated class cannot be created and the tenant CSI release will not converge. Infra classes that must stay node-local need allowRemoteVolumeAccess: "false" set explicitly — an absent annotation is treated as remote-accessible. Propagation is evaluated at HelmRelease render time, so classes added or removed on the infra cluster after a tenant exists propagate only on that tenant’s next reconcile.

Поле верхнего уровня storageClass помечено в схеме чарта как неизменяемое (immutable) — описание контракта и того, какие потребители его применяют, см. в docs/storage-immutability.md. Поле уровня группы нод nodeGroups[name].storageClass намеренно не помечено неизменяемым: оно необязательное и не имеет значения по умолчанию, поэтому строгое правило self == oldSelf заблокировало бы любую будущую попытку задать его для уже существующей группы нод.

Parameters

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

Application-specific Parameters

Cluster Addons

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

Talos Worker Image

Node Health Check

OIDC

Parameter examples and reference

resources and resourcesPreset

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

resources:
  cpu: 4000m
  memory: 4Gi

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

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

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

Резервирование ресурсов Kubelet

Каждая группа нод поддерживает объект kubelet, который задает, сколько памяти и CPU kubelet резервирует для host OS и Kubernetes/system компонентов, работающих на worker ноде.

Если systemReservedMemory или kubeReservedMemory оставлены пустыми, они вычисляются автоматически по следующей формуле:

1. Определяется эффективный объем памяти ноды:
   • Если resources.memory задан явно, используется это значение.
   • Иначе ищется instanceType и используется его значение memory.guest.
   • Если недоступно ни то ни другое, используется минимальная резервация (256Mi).
2. Вычисляется 5% от эффективного объема памяти (в MiB, с округлением вниз).
3. Результат ограничивается диапазоном [256Mi, 1Gi]:
   • Ноды с 5 GiB или меньше получают минимальный резерв 256Mi.
   • Ноды с 20 GiB или больше получают максимальный резерв 1Gi.

По умолчанию systemReservedMemory и kubeReservedMemory получают одинаковое автоматически вычисленное значение.

CPU резервирование (systemReservedCpu, kubeReservedCpu) работают по той же схеме: 5% от effective CPU с ограничением диапазоном [50m, 500m]. Оба значения вычисляются автоматически, если оставлены пустыми.

Значения kubelet по умолчанию

Порог вытеснения можно задавать в процентах (например, 7%) или абсолютных значениях (например, 200Mi). Оба порога должны использовать один тип единиц. Жёсткий порог вытеснения должен быть строго меньше мягкого порога.

Параметры evictionSoftGracePeriod и evictionMinimumReclaim сейчас жёстко заданы в шаблоне и не могут быть переопределены через values.

Capacity Аннотации

Когда настроены резервации ресурсов kubelet, аннотации capacity.cluster-autoscaler.kubernetes.io/memory и capacity.cluster-autoscaler.kubernetes.io/cpu на MachineDeployments показывают распределяемые значения вместо полных ресурсов ноды. Доступная для подов память вычисляется как общий объём памяти за вычетом system-reserved, kube-reserved и eviction-hard. Доступное для подов CPU вычисляется как общее количество за вычетом system-reserved и kube-reserved. Так аннотации соответствуют значениям, которые cluster autoscaler использует в расчетах масштабирования.

При обновлении с версии без этой возможности autoscaler после обновления аннотации может увидеть уменьшенную капасити для каждой ноды, что способно запустить дополнительные операции scale-up. Обычно никаких действий не требуется — новые значения отражают фактическую память, доступную для scheduling workload.

Note: Если не задан ни resources.memory, ни instanceType, порог вытеснения (по умолчанию 7% hard / 10% soft) все равно применяются kubelet во время выполнения, но capacity аннотации не рендерится. Без этой аннотации cluster-autoscaler не учитывает эти резервации и может запланировать на ноду слишком много подов, что приведёт к срабатыванию вытеснения.

Пример: переопределение резерваций kubelet

nodeGroups:
  md0:
    instanceType: "u1.large"
    kubelet:
      systemReservedMemory: "256Mi"
      kubeReservedMemory: "256Mi"
      evictionHardMemory: "500Mi"
      evictionSoftMemory: "1Gi"

Серия 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.