Kubernetes Resource Management#

Cozystack models resource management around three interlocking concerns:

1. Allocation ratios — platform-wide oversubscription multipliers that derive requests from user-supplied limits
2. cozy-lib template helpers — Helm library functions that apply those ratios consistently across every package
3. VPA bounds — minAllowed/maxAllowed policies expressed through those same helpers to ensure valid milliCPU values

Allocation Ratios#

Three ratios are defined in cozy-lib and read from the cozystack-values Secret at render time:

The platform chart writes all three into _cluster of the cozystack-values Secret 1, so every downstream package picks up operator-configured values instead of hardcoded defaults. This propagation was restored in PR #2296 after a Package CRD bundle restructure broke it.

The CPU ratio default of 10 means a pod requesting 2 vCPUs as its limit will have a CPU request of 200m — allowing ten such pods to be scheduled on a node with 2 physical cores before hitting the scheduler's bin-packing ceiling.

cozy-lib Resource Helpers#

All helpers live in packages/library/cozy-lib/templates/_resources.tpl.

cozy-lib.resources.sanitize#

The core helper 2. Accepts a flat resource map (no nested requests:/limits: sections — a render-time error is raised if those are present) and emits a fully-expanded requests/limits block:

• CPU: request = limit / cpuAllocationRatio, rounded up to the nearest whole milliCPU and emitted with the m suffix (e.g., 36m). The rounding prevents sub-milliCPU fractions that the VPA admission webhook rejects. 3
• Memory: request = limit / memoryAllocationRatio (default 1, so requests == limits)
• Ephemeral storage: request = limit / ephemeralStorageAllocationRatio
• All other resources (GPU device plugins, etc.): requests == limits

Usage:

{{ include "cozy-lib.resources.sanitize" (list .Values.resources $) }}

cozy-lib.resources.defaultingSanitize#

A wrapper 4 that fills missing cpu, memory, or ephemeral-storage from a named resource preset (e.g., "t1.nano") before calling sanitize. Useful for packages with optional per-component resource overrides.

cozy-lib.resources.flatten#

Converts the sanitized requests/limits map into the flat requests.cpu, limits.memory key format required by Kubernetes ResourceQuota objects 5.

cozy-lib.resources.javaHeap#

Derives JVM heap flags from a sanitized resource map 6: -Xmx = 75% of memory limit, -Xms = lesser of request or 25% of limit.

cozy-lib.resources.toFloat#

Unit-aware string-to-float converter 7 used internally. Understands both binary (Ki, Mi, Gi, …) and SI (m, k, M, …) suffixes.

VPA Resource Policy Configuration#

VPA bounds (minAllowed/maxAllowed) must satisfy the same milliCPU constraint as pod requests. The idiomatic Cozystack pattern routes the bound values through cozy-lib.resources.sanitize and extracts the requests section — this automatically applies the allocation ratio and rounds to whole milliCPU.

Example — etcd VPA 8:

resourcePolicy:
  containerPolicies:
  - containerName: etcd
    minAllowed: # computed from {cpu: "250m", memory: "256Mi"} via sanitize → requests
    maxAllowed: # computed from {cpu: "5000m", memory: "8Gi"} via sanitize → requests

The etcd VPA uses updateMode: Initial (not Auto) because Auto would evict running etcd members to apply recommendations, risking quorum disruption and triggering a Cilium IP-reuse leak. Initial sets requests only at pod creation 9.

Dedicated CPU Quota#

For dedicatedCPUPlacement workloads (KubeVirt cx* instance types and Guaranteed QoS pods), pinned cores cannot be oversubscribed. An optional dedicatedCPU key in tenant resourceQuotas is added 1:1 to both limits.cpu and requests.cpu, bypassing cpuAllocationRatio 10.

Example: cpu: 10, dedicatedCPU: 2 with default ratio 10 → limits.cpu=12, requests.cpu=3.

VM Pod Resources#

Worker node VM pods use cozy-lib.resources.sanitize for their pod-level ephemeral storage request (hardcoded to 2Gi limit, since persistent DataVolumes are not counted as pod ephemeral storage) 11. VM domain cpu.cores and memory.guest are set directly from resources.cpu/resources.memory values without going through the sanitizer, because KubeVirt manages VM sizing independently of the pod scheduler's bin-packing 12.

Key Files#