From 08500761fc0ac6edf94ace3a018c0d4cc28f2cae Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Thu, 7 May 2026 04:21:18 +0000 Subject: [PATCH] [docs] Update managed apps reference for v1.3 2026-05-07 04:21:18 Signed-off-by: github-actions[bot] --- .../en/docs/v1.3/applications/clickhouse.md | 2 +- .../en/docs/v1.3/applications/foundationdb.md | 2 +- content/en/docs/v1.3/applications/harbor.md | 2 +- content/en/docs/v1.3/applications/kafka.md | 42 ++--- content/en/docs/v1.3/applications/mariadb.md | 2 +- content/en/docs/v1.3/applications/mongodb.md | 64 ++++++- content/en/docs/v1.3/applications/nats.md | 2 +- content/en/docs/v1.3/applications/openbao.md | 2 +- content/en/docs/v1.3/applications/postgres.md | 24 +-- content/en/docs/v1.3/applications/qdrant.md | 2 +- content/en/docs/v1.3/applications/rabbitmq.md | 2 +- content/en/docs/v1.3/applications/redis.md | 2 +- content/en/docs/v1.3/applications/tenant.md | 2 +- content/en/docs/v1.3/kubernetes/_index.md | 161 +++++++++++++----- content/en/docs/v1.3/networking/http-cache.md | 2 +- .../en/docs/v1.3/networking/tcp-balancer.md | 2 +- content/en/docs/v1.3/networking/vpc.md | 2 +- content/en/docs/v1.3/networking/vpn.md | 2 +- .../docs/v1.3/operations/services/bootbox.md | 2 +- .../en/docs/v1.3/operations/services/etcd.md | 27 ++- .../docs/v1.3/operations/services/ingress.md | 16 +- .../services/monitoring/parameters.md | 2 +- .../v1.3/operations/services/seaweedfs.md | 2 +- .../en/docs/v1.3/virtualization/vm-disk.md | 2 +- .../docs/v1.3/virtualization/vm-instance.md | 53 +++--- 25 files changed, 301 insertions(+), 122 deletions(-) diff --git a/content/en/docs/v1.3/applications/clickhouse.md b/content/en/docs/v1.3/applications/clickhouse.md index 99d4c161..bff41f87 100644 --- a/content/en/docs/v1.3/applications/clickhouse.md +++ b/content/en/docs/v1.3/applications/clickhouse.md @@ -11,7 +11,7 @@ aliases: diff --git a/content/en/docs/v1.3/applications/foundationdb.md b/content/en/docs/v1.3/applications/foundationdb.md index 8faec7cc..362fe08a 100644 --- a/content/en/docs/v1.3/applications/foundationdb.md +++ b/content/en/docs/v1.3/applications/foundationdb.md @@ -6,7 +6,7 @@ weight: 50 diff --git a/content/en/docs/v1.3/applications/harbor.md b/content/en/docs/v1.3/applications/harbor.md index c21a59dc..26e43e56 100644 --- a/content/en/docs/v1.3/applications/harbor.md +++ b/content/en/docs/v1.3/applications/harbor.md @@ -7,7 +7,7 @@ weight: 50 diff --git a/content/en/docs/v1.3/applications/kafka.md b/content/en/docs/v1.3/applications/kafka.md index 08012650..d56e0164 100644 --- a/content/en/docs/v1.3/applications/kafka.md +++ b/content/en/docs/v1.3/applications/kafka.md @@ -10,7 +10,7 @@ aliases: @@ -36,30 +36,30 @@ source: https://github.com/cozystack/cozystack/blob/v1.3.0/packages/apps/kafka/R ### Kafka configuration -| Name | Description | Type | Value | -| ------------------------ | -------------------------------------------------------------------------------------------------------- | ---------- | ------- | -| `kafka` | Kafka configuration. | `object` | `{}` | -| `kafka.replicas` | Number of Kafka replicas. | `int` | `3` | -| `kafka.resources` | Explicit CPU and memory configuration. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | -| `kafka.resources.cpu` | CPU available to each replica. | `quantity` | `""` | -| `kafka.resources.memory` | Memory (RAM) available to each replica. | `quantity` | `""` | -| `kafka.resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `small` | -| `kafka.size` | Persistent Volume size for Kafka. | `quantity` | `10Gi` | -| `kafka.storageClass` | StorageClass used to store the Kafka data. | `string` | `""` | +| Name | Description | Type | Value | +| ------------------------ | -------------------------------------------------------------------------------------------------------- | ---------- | -------- | +| `kafka` | Kafka configuration. | `object` | `{}` | +| `kafka.replicas` | Number of Kafka replicas. | `int` | `3` | +| `kafka.resources` | Explicit CPU and memory configuration. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | +| `kafka.resources.cpu` | CPU available to each replica. | `quantity` | `""` | +| `kafka.resources.memory` | Memory (RAM) available to each replica. | `quantity` | `""` | +| `kafka.resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `medium` | +| `kafka.size` | Persistent Volume size for Kafka. | `quantity` | `10Gi` | +| `kafka.storageClass` | StorageClass used to store the Kafka data. | `string` | `""` | ### ZooKeeper configuration -| Name | Description | Type | Value | -| ---------------------------- | -------------------------------------------------------------------------------------------------------- | ---------- | ------- | -| `zookeeper` | ZooKeeper configuration. | `object` | `{}` | -| `zookeeper.replicas` | Number of ZooKeeper replicas. | `int` | `3` | -| `zookeeper.resources` | Explicit CPU and memory configuration. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | -| `zookeeper.resources.cpu` | CPU available to each replica. | `quantity` | `""` | -| `zookeeper.resources.memory` | Memory (RAM) available to each replica. | `quantity` | `""` | -| `zookeeper.resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `small` | -| `zookeeper.size` | Persistent Volume size for ZooKeeper. | `quantity` | `5Gi` | -| `zookeeper.storageClass` | StorageClass used to store the ZooKeeper data. | `string` | `""` | +| Name | Description | Type | Value | +| ---------------------------- | -------------------------------------------------------------------------------------------------------- | ---------- | -------- | +| `zookeeper` | ZooKeeper configuration. | `object` | `{}` | +| `zookeeper.replicas` | Number of ZooKeeper replicas. | `int` | `3` | +| `zookeeper.resources` | Explicit CPU and memory configuration. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | +| `zookeeper.resources.cpu` | CPU available to each replica. | `quantity` | `""` | +| `zookeeper.resources.memory` | Memory (RAM) available to each replica. | `quantity` | `""` | +| `zookeeper.resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `medium` | +| `zookeeper.size` | Persistent Volume size for ZooKeeper. | `quantity` | `5Gi` | +| `zookeeper.storageClass` | StorageClass used to store the ZooKeeper data. | `string` | `""` | ## Parameter examples and reference diff --git a/content/en/docs/v1.3/applications/mariadb.md b/content/en/docs/v1.3/applications/mariadb.md index 23acdb56..66ab2298 100644 --- a/content/en/docs/v1.3/applications/mariadb.md +++ b/content/en/docs/v1.3/applications/mariadb.md @@ -10,7 +10,7 @@ aliases: diff --git a/content/en/docs/v1.3/applications/mongodb.md b/content/en/docs/v1.3/applications/mongodb.md index 1407b6bd..390cb469 100644 --- a/content/en/docs/v1.3/applications/mongodb.md +++ b/content/en/docs/v1.3/applications/mongodb.md @@ -10,7 +10,7 @@ aliases: @@ -49,6 +49,68 @@ When `external: true` is enabled: On first install, the credentials secret will be empty until the Percona operator initializes the cluster. Run `helm upgrade` after MongoDB is ready to populate the credentials secret with the actual password. +### Data lifecycle + +When the MongoDB release is uninstalled, the operator finalizers reclaim release-scoped resources: + +**Reclaimed by the `percona.com/delete-psmdb-pvc` finalizer:** + +- All PVCs backing the replica set storage. Whether the underlying PersistentVolume and on-disk data are actually deleted depends on the StorageClass `reclaimPolicy` (`Delete` removes them, `Retain` leaves them for manual cleanup). +- Operator-managed secrets: + - `-percona-server-mongodb-users` — operator users credentials + - `internal-` — internal operator state + - `internal--users` — operator-internal users data + - `-mongodb-encryption-key` — at-rest encryption key + +**Reclaimed by `helm uninstall`:** + +- `-credentials` — connection string for application code +- `-user-` — per-user passwords +- `-s3-creds` — backup destination credentials (if backups are configured) + +**Not reclaimed automatically:** + +- TLS secrets `-ssl` and `-ssl-internal` (issued by cert-manager) remain in the namespace after uninstall. Delete them manually if no longer needed. + +**Recovery from a stuck deletion:** + +If the `psmdb-operator` is uninstalled before MongoDB CRs are deleted, the finalizers cannot run and the `PerconaServerMongoDB` CR hangs in `Terminating`. To recover, clear the finalizers manually: + +```bash +kubectl --namespace patch psmdb --type merge --patch '{"metadata":{"finalizers":[]}}' +``` + +Note that this skips the operator-driven cleanup — PVCs and operator-managed secrets will remain orphaned and must be removed manually. + +If you need to retain data, take a backup before deletion. Refer to the [Percona Operator for MongoDB documentation](https://docs.percona.com/percona-operator-for-mongodb/) for backup/restore workflows. + +### Upgrading from earlier versions + +Earlier versions of this chart referenced a namespace-shared system users secret (`percona-server-mongodb-users`). Upgrading to a release that scopes this secret per CR (`-percona-server-mongodb-users`) triggers a password rotation for the operator-managed system users. The rotation is performed in place by the Percona operator via `db.changeUserPassword()` against the running mongod (operator log: `Secret data changed. Updating users...`); pods are not restarted and the cluster stays available. + +**Rotated automatically on upgrade:** + +- The five operator-managed system accounts: `databaseAdmin`, `userAdmin`, `backup`, `clusterAdmin`, `clusterMonitor`. +- Secret `-percona-server-mongodb-users` (newly created, per-CR) and `internal--users` receive the new values. +- Secret `-credentials` is regenerated; its `password` and `uri` keys reflect the new `databaseAdmin` password. + +**Not affected:** + +- Custom users defined under `users:` in chart values. Their `-user-` secrets are not touched. +- The at-rest encryption key (`-mongodb-encryption-key`) and replica set keyfile (`-mongodb-keyfile`) are unchanged, so on-disk data remains readable. + +**Action required after upgrade:** + +Workloads that mount `-credentials` keep using the cached old password until they re-read the secret. Restart those pods, or run a controller such as [Reloader](https://github.com/stakater/Reloader) to roll them automatically. Without this, application connections fail with authentication errors once their existing sessions expire. + +**Orphaned legacy secret:** + +The previous namespace-shared secret `percona-server-mongodb-users` is no longer referenced by any MongoDB CR after upgrade, but the operator does not garbage-collect it. If multiple MongoDB releases in the same namespace previously shared it, all of them rotate to their own per-CR secrets — passwords are no longer shared across CRs in the namespace, which is the intended outcome. Confirm no other consumers reference it, then remove it manually: + +```bash +kubectl --namespace delete secret percona-server-mongodb-users +``` + ## Parameters ### Common parameters diff --git a/content/en/docs/v1.3/applications/nats.md b/content/en/docs/v1.3/applications/nats.md index daf1dcb1..687bc655 100644 --- a/content/en/docs/v1.3/applications/nats.md +++ b/content/en/docs/v1.3/applications/nats.md @@ -10,7 +10,7 @@ aliases: diff --git a/content/en/docs/v1.3/applications/openbao.md b/content/en/docs/v1.3/applications/openbao.md index 367aaf19..11d6c590 100644 --- a/content/en/docs/v1.3/applications/openbao.md +++ b/content/en/docs/v1.3/applications/openbao.md @@ -7,7 +7,7 @@ weight: 50 diff --git a/content/en/docs/v1.3/applications/postgres.md b/content/en/docs/v1.3/applications/postgres.md index 22b1fbcd..53d88a7c 100644 --- a/content/en/docs/v1.3/applications/postgres.md +++ b/content/en/docs/v1.3/applications/postgres.md @@ -10,7 +10,7 @@ aliases: @@ -95,11 +95,10 @@ See: ### Application-specific parameters -| Name | Description | Type | Value | -| --------------------------------------- | ---------------------------------------------------------------- | -------- | ----- | -| `postgresql` | PostgreSQL server configuration. | `object` | `{}` | -| `postgresql.parameters` | PostgreSQL server parameters. | `object` | `{}` | -| `postgresql.parameters.max_connections` | Maximum number of concurrent connections to the database server. | `int` | `100` | +| Name | Description | Type | Value | +| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | ----- | +| `postgresql` | PostgreSQL server configuration. | `object` | `{}` | +| `postgresql.parameters` | PostgreSQL server parameters. All values must be strings (quote numbers: "100"). BLOCKED (enable arbitrary code execution): archive_command, restore_command, ssl_passphrase_command, dynamic_library_path, local_preload_libraries, session_preload_libraries, shared_preload_libraries. Do NOT override CloudNativePG-managed parameters: archive_mode, primary_conninfo, wal_level, max_replication_slots. | `map[string]string` | `{}` | ### Quorum-based synchronous replication @@ -147,12 +146,13 @@ See: ### Bootstrap (recovery) parameters -| Name | Description | Type | Value | -| ------------------------ | ------------------------------------------------------------------- | -------- | ------- | -| `bootstrap` | Bootstrap configuration. | `object` | `{}` | -| `bootstrap.enabled` | Whether to restore from a backup. | `bool` | `false` | -| `bootstrap.recoveryTime` | Timestamp (RFC3339) for point-in-time recovery; empty means latest. | `string` | `""` | -| `bootstrap.oldName` | Previous cluster name before deletion. | `string` | `""` | +| Name | Description | Type | Value | +| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | +| `bootstrap` | Bootstrap configuration. | `object` | `{}` | +| `bootstrap.enabled` | Whether to restore from a backup. | `bool` | `false` | +| `bootstrap.recoveryTime` | Timestamp (RFC3339) for point-in-time recovery; empty means latest. | `string` | `""` | +| `bootstrap.oldName` | Previous cluster name before deletion. | `string` | `""` | +| `bootstrap.serverName` | Barman server name (S3 path prefix) used by the original cluster when writing backups. Set this only when the original cluster had an explicit barmanObjectStore.serverName that differed from its Kubernetes resource name. | `string` | `""` | ## Parameter examples and reference diff --git a/content/en/docs/v1.3/applications/qdrant.md b/content/en/docs/v1.3/applications/qdrant.md index faed70d7..9580e854 100644 --- a/content/en/docs/v1.3/applications/qdrant.md +++ b/content/en/docs/v1.3/applications/qdrant.md @@ -7,7 +7,7 @@ weight: 50 diff --git a/content/en/docs/v1.3/applications/rabbitmq.md b/content/en/docs/v1.3/applications/rabbitmq.md index 589524fe..856f38e6 100644 --- a/content/en/docs/v1.3/applications/rabbitmq.md +++ b/content/en/docs/v1.3/applications/rabbitmq.md @@ -10,7 +10,7 @@ aliases: diff --git a/content/en/docs/v1.3/applications/redis.md b/content/en/docs/v1.3/applications/redis.md index 4cbc69ab..67415a53 100644 --- a/content/en/docs/v1.3/applications/redis.md +++ b/content/en/docs/v1.3/applications/redis.md @@ -10,7 +10,7 @@ aliases: diff --git a/content/en/docs/v1.3/applications/tenant.md b/content/en/docs/v1.3/applications/tenant.md index db87d35d..c23c67ea 100644 --- a/content/en/docs/v1.3/applications/tenant.md +++ b/content/en/docs/v1.3/applications/tenant.md @@ -10,7 +10,7 @@ aliases: diff --git a/content/en/docs/v1.3/kubernetes/_index.md b/content/en/docs/v1.3/kubernetes/_index.md index f6038b90..4e9c5126 100644 --- a/content/en/docs/v1.3/kubernetes/_index.md +++ b/content/en/docs/v1.3/kubernetes/_index.md @@ -10,7 +10,7 @@ aliases: @@ -26,7 +26,7 @@ Within a tenant cluster, users can take advantage of LoadBalancer services and e The control-plane operates within containers, while the worker nodes are deployed as virtual machines, all seamlessly managed by the application. Kubernetes version in tenant clusters is independent of Kubernetes in the management cluster. -Users can select the latest patch versions from 1.28 to 1.33. +Users can select the supported patch versions from 1.30 to 1.35. ## Why Use a Managed Kubernetes Cluster? @@ -77,6 +77,9 @@ Deploying it involves the following components: - **Worker Nodes**: Virtual Machines are provisioned to serve as worker nodes using KubeVirt. These nodes are configured to join the tenant Kubernetes cluster, enabling the deployment and management of workloads. + Worker node disks automatically detect and match the underlying volume's block size + (`blockSize.matchVolume`) to ensure compatibility with storage backends that use + non-512-byte sectors, such as LINSTOR DRBD with 4Kn drives. - **Cluster API**: Cozystack is using the [Kubernetes Cluster API](https://cluster-api.sigs.k8s.io/) to provision the components of a cluster. @@ -94,6 +97,10 @@ See the reference for components utilized in this service: - [github.com/kubernetes-sigs/cluster-api-provider-kubevirt](https://github.com/kubernetes-sigs/cluster-api-provider-kubevirt) - [github.com/kubevirt/csi-driver](https://github.com/kubevirt/csi-driver) +## Breaking Changes + +- **`ephemeralStorage` renamed to `diskSize`**: The `nodeGroups[name].ephemeralStorage` field has been renamed to `nodeGroups[name].diskSize` to better reflect its purpose (persistent disk for kubelet and containerd data). There is no backward-compatibility fallback; users MUST update their configurations to use `diskSize` instead of `ephemeralStorage`. If `ephemeralStorage` is still present in values, Helm template rendering will fail with an error directing you to use `diskSize`. When upgrading the CRD directly (bypassing Helm), the unrecognized field is silently dropped and kubelet storage reverts to the default 20Gi. Existing VMs will be automatically rolling-updated via CAPI when the new values are applied. State 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 PVC. + ## Parameters ### Common Parameters @@ -105,21 +112,29 @@ See the reference for components utilized in this service: ### Application-specific Parameters -| Name | Description | Type | Value | -| ----------------------------------- | ---------------------------------------------------------------------------------------------- | ------------------- | ----------- | -| `nodeGroups` | Worker nodes configuration map. | `map[string]object` | `{...}` | -| `nodeGroups[name].minReplicas` | Minimum number of replicas. | `int` | `0` | -| `nodeGroups[name].maxReplicas` | Maximum number of replicas. | `int` | `10` | -| `nodeGroups[name].instanceType` | Virtual machine instance type. | `string` | `u1.medium` | -| `nodeGroups[name].ephemeralStorage` | Ephemeral storage size. | `quantity` | `20Gi` | -| `nodeGroups[name].roles` | List of node roles. | `[]string` | `[]` | -| `nodeGroups[name].resources` | CPU and memory resources for each worker node. | `object` | `{}` | -| `nodeGroups[name].resources.cpu` | CPU available. | `quantity` | `""` | -| `nodeGroups[name].resources.memory` | Memory (RAM) available. | `quantity` | `""` | -| `nodeGroups[name].gpus` | List of GPUs to attach (NVIDIA driver requires at least 4 GiB RAM). | `[]object` | `[]` | -| `nodeGroups[name].gpus[i].name` | Name of GPU, such as "nvidia.com/AD102GL_L40S". | `string` | `""` | -| `version` | Kubernetes major.minor version to deploy | `string` | `v1.35` | -| `host` | External hostname for Kubernetes cluster. Defaults to `.` if empty. | `string` | `""` | +| Name | Description | Type | Value | +| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | ----------- | +| `nodeGroups` | Worker nodes configuration map. | `map[string]object` | `{...}` | +| `nodeGroups[name].minReplicas` | Minimum number of replicas. | `int` | `0` | +| `nodeGroups[name].maxReplicas` | Maximum number of replicas. | `int` | `10` | +| `nodeGroups[name].instanceType` | Virtual machine instance type. | `string` | `u1.medium` | +| `nodeGroups[name].diskSize` | Persistent disk size for kubelet and containerd data. | `quantity` | `20Gi` | +| `nodeGroups[name].storageClass` | StorageClass for worker node persistent disks. When empty, uses the management cluster default StorageClass (the one annotated storageclass.kubernetes.io/is-default-class: true). | `string` | `""` | +| `nodeGroups[name].roles` | List of node roles. | `[]string` | `[]` | +| `nodeGroups[name].resources` | CPU and memory resources for each worker node. | `object` | `{}` | +| `nodeGroups[name].resources.cpu` | CPU available. | `quantity` | `""` | +| `nodeGroups[name].resources.memory` | Memory (RAM) available. | `quantity` | `""` | +| `nodeGroups[name].gpus` | List of GPUs to attach (NVIDIA driver requires at least 4 GiB RAM). | `[]object` | `[]` | +| `nodeGroups[name].gpus[i].name` | Name of GPU, such as "nvidia.com/AD102GL_L40S". | `string` | `""` | +| `nodeGroups[name].kubelet` | Kubelet resource reservations for this node group. | `object` | `{}` | +| `nodeGroups[name].kubelet.systemReservedMemory` | Memory reserved for host OS. Auto-computed from instanceType if empty. | `string` | `""` | +| `nodeGroups[name].kubelet.kubeReservedMemory` | Memory reserved for kubelet and container runtime. Auto-computed from instanceType if empty. | `string` | `""` | +| `nodeGroups[name].kubelet.systemReservedCpu` | CPU reserved for host OS. Auto-computed from instanceType if empty. | `string` | `""` | +| `nodeGroups[name].kubelet.kubeReservedCpu` | CPU reserved for kubelet and container runtime. Auto-computed from instanceType if empty. | `string` | `""` | +| `nodeGroups[name].kubelet.evictionHardMemory` | Hard eviction threshold for memory (absolute like 200Mi or percentage like 7%). | `string` | `7%` | +| `nodeGroups[name].kubelet.evictionSoftMemory` | Soft eviction threshold for memory (absolute like 1Gi or percentage like 10%). | `string` | `10%` | +| `version` | Kubernetes major.minor version to deploy | `string` | `v1.35` | +| `host` | External hostname for Kubernetes cluster. Defaults to `.` if empty. | `string` | `""` | ### Cluster Addons @@ -142,6 +157,9 @@ See the reference for components utilized in this service: | `addons.gpuOperator` | NVIDIA GPU Operator. | `object` | `{}` | | `addons.gpuOperator.enabled` | Enable GPU Operator. | `bool` | `false` | | `addons.gpuOperator.valuesOverride` | Custom Helm values overrides. | `object` | `{}` | +| `addons.hami` | HAMi GPU virtualization middleware. | `object` | `{}` | +| `addons.hami.enabled` | Enable HAMi (requires GPU Operator). | `bool` | `false` | +| `addons.hami.valuesOverride` | Custom Helm values overrides. | `object` | `{}` | | `addons.fluxcd` | FluxCD GitOps operator. | `object` | `{}` | | `addons.fluxcd.enabled` | Enable FluxCD. | `bool` | `false` | | `addons.fluxcd.valuesOverride` | Custom Helm values overrides. | `object` | `{}` | @@ -159,31 +177,33 @@ See the reference for components utilized in this service: ### Kubernetes Control Plane Configuration -| Name | Description | Type | Value | -| --------------------------------------------------- | ------------------------------------------------ | ---------- | ------- | -| `controlPlane` | Kubernetes control-plane configuration. | `object` | `{}` | -| `controlPlane.replicas` | Number of control-plane replicas. | `int` | `2` | -| `controlPlane.apiServer` | API Server configuration. | `object` | `{}` | -| `controlPlane.apiServer.resources` | CPU and memory resources for API Server. | `object` | `{}` | -| `controlPlane.apiServer.resources.cpu` | CPU available. | `quantity` | `""` | -| `controlPlane.apiServer.resources.memory` | Memory (RAM) available. | `quantity` | `""` | -| `controlPlane.apiServer.resourcesPreset` | Preset if `resources` omitted. | `string` | `large` | -| `controlPlane.controllerManager` | Controller Manager configuration. | `object` | `{}` | -| `controlPlane.controllerManager.resources` | CPU and memory resources for Controller Manager. | `object` | `{}` | -| `controlPlane.controllerManager.resources.cpu` | CPU available. | `quantity` | `""` | -| `controlPlane.controllerManager.resources.memory` | Memory (RAM) available. | `quantity` | `""` | -| `controlPlane.controllerManager.resourcesPreset` | Preset if `resources` omitted. | `string` | `micro` | -| `controlPlane.scheduler` | Scheduler configuration. | `object` | `{}` | -| `controlPlane.scheduler.resources` | CPU and memory resources for Scheduler. | `object` | `{}` | -| `controlPlane.scheduler.resources.cpu` | CPU available. | `quantity` | `""` | -| `controlPlane.scheduler.resources.memory` | Memory (RAM) available. | `quantity` | `""` | -| `controlPlane.scheduler.resourcesPreset` | Preset if `resources` omitted. | `string` | `micro` | -| `controlPlane.konnectivity` | Konnectivity configuration. | `object` | `{}` | -| `controlPlane.konnectivity.server` | Konnectivity Server configuration. | `object` | `{}` | -| `controlPlane.konnectivity.server.resources` | CPU and memory resources for Konnectivity. | `object` | `{}` | -| `controlPlane.konnectivity.server.resources.cpu` | CPU available. | `quantity` | `""` | -| `controlPlane.konnectivity.server.resources.memory` | Memory (RAM) available. | `quantity` | `""` | -| `controlPlane.konnectivity.server.resourcesPreset` | Preset if `resources` omitted. | `string` | `micro` | +| Name | Description | Type | Value | +| --------------------------------------------------- | --------------------------------------------------------------------------------------------- | ---------- | ------- | +| `controlPlane` | Kubernetes control-plane configuration. | `object` | `{}` | +| `controlPlane.replicas` | Number of control-plane replicas. | `int` | `2` | +| `controlPlane.apiServer` | API Server configuration. | `object` | `{}` | +| `controlPlane.apiServer.resources` | CPU and memory resources for API Server. | `object` | `{}` | +| `controlPlane.apiServer.resources.cpu` | CPU available. | `quantity` | `""` | +| `controlPlane.apiServer.resources.memory` | Memory (RAM) available. | `quantity` | `""` | +| `controlPlane.apiServer.resourcesPreset` | Preset if `resources` omitted. | `string` | `large` | +| `controlPlane.controllerManager` | Controller Manager configuration. | `object` | `{}` | +| `controlPlane.controllerManager.resources` | CPU and memory resources for Controller Manager. | `object` | `{}` | +| `controlPlane.controllerManager.resources.cpu` | CPU available. | `quantity` | `""` | +| `controlPlane.controllerManager.resources.memory` | Memory (RAM) available. | `quantity` | `""` | +| `controlPlane.controllerManager.resourcesPreset` | Preset if `resources` omitted. | `string` | `micro` | +| `controlPlane.scheduler` | Scheduler configuration. | `object` | `{}` | +| `controlPlane.scheduler.resources` | CPU and memory resources for Scheduler. | `object` | `{}` | +| `controlPlane.scheduler.resources.cpu` | CPU available. | `quantity` | `""` | +| `controlPlane.scheduler.resources.memory` | Memory (RAM) available. | `quantity` | `""` | +| `controlPlane.scheduler.resourcesPreset` | Preset if `resources` omitted. | `string` | `micro` | +| `controlPlane.konnectivity` | Konnectivity configuration. | `object` | `{}` | +| `controlPlane.konnectivity.server` | Konnectivity Server configuration. | `object` | `{}` | +| `controlPlane.konnectivity.server.resources` | CPU and memory resources for Konnectivity. | `object` | `{}` | +| `controlPlane.konnectivity.server.resources.cpu` | CPU available. | `quantity` | `""` | +| `controlPlane.konnectivity.server.resources.memory` | Memory (RAM) available. | `quantity` | `""` | +| `controlPlane.konnectivity.server.resourcesPreset` | Preset if `resources` omitted. | `string` | `micro` | +| `images` | Optional image overrides for air-gapped or rate-limited registries. | `object` | `{}` | +| `images.waitForKubeconfig` | Image used by the wait-for-kubeconfig init container. Empty falls back to images/busybox.tag. | `string` | `""` | ## Parameter examples and reference @@ -267,6 +287,63 @@ The following instanceType resources are provided by Cozystack: | `u1.small` | 1 | 2Gi | | `u1.xlarge` | 4 | 16Gi | +### Kubelet Resource Reservations + +Each node group supports a `kubelet` object that configures how much memory and CPU the kubelet reserves for the host OS and the Kubernetes/system components running on the worker node. + +When `systemReservedMemory` or `kubeReservedMemory` are left empty, they are **auto-computed** using the following formula: + +1. Determine the **effective memory** of the node: + - If `resources.memory` is explicitly set, use that value. + - Otherwise, look up the `instanceType` and use its `memory.guest` value. + - If neither is available, the reservation falls back to the minimum (256Mi). +2. Calculate **5%** of the effective memory (in MiB, rounded down). +3. **Clamp** the result to the range **[256Mi, 1Gi]**: + - Nodes with 5 GiB or less get the minimum 256Mi reservation. + - Nodes with 20 GiB or more get the maximum 1Gi reservation. + +Both `systemReservedMemory` and `kubeReservedMemory` receive the same auto-computed value by default. + +CPU reservations (`systemReservedCpu`, `kubeReservedCpu`) follow the same pattern: **5%** of effective CPU, clamped to **[50m, 500m]**. Both are auto-computed when left empty. + +#### Kubelet Defaults + +| Parameter | Default | Description | +| --- | --- | --- | +| `systemReservedMemory` | auto-computed | Memory reserved for host OS | +| `kubeReservedMemory` | auto-computed | Memory reserved for kubelet and container runtime | +| `systemReservedCpu` | auto-computed | CPU reserved for host OS | +| `kubeReservedCpu` | auto-computed | CPU reserved for kubelet and container runtime | +| `evictionHardMemory` | `7%` | Hard eviction threshold for memory | +| `evictionSoftMemory` | `10%` | Soft eviction threshold for memory | +| `evictionSoftGracePeriod` | `1m30s` *(hardcoded)* | Duration a soft eviction threshold must be breached before triggering eviction | +| `evictionMinimumReclaim` | `256Mi` *(hardcoded)* | Minimum amount of memory reclaimed per eviction action | + +Eviction thresholds can be specified as percentages (e.g., `7%`) or absolute values (e.g., `200Mi`). Both thresholds must use the same unit type. The hard threshold must be strictly less than the soft threshold. + +The `evictionSoftGracePeriod` and `evictionMinimumReclaim` parameters are currently hardcoded in the chart template and cannot be overridden through values. + +#### Capacity Annotation + +When kubelet resource reservations are configured, both the `capacity.cluster-autoscaler.kubernetes.io/memory` and `capacity.cluster-autoscaler.kubernetes.io/cpu` annotations on MachineDeployments report **allocatable** values instead of total node resources. Memory allocatable subtracts system-reserved, kube-reserved, and eviction-hard. CPU allocatable subtracts system-reserved and kube-reserved. This aligns the annotations with the values the cluster autoscaler uses in its scaling calculations. + +Upgrading from a version without this feature may cause the autoscaler to see reduced per-node capacity after the annotations are updated, which can trigger additional scale-up operations. No action is typically required — the new values reflect the actual memory available for workload scheduling. + +> **Note:** When neither `resources.memory` nor `instanceType` is set, eviction thresholds (default 7% hard / 10% soft) are still enforced by the kubelet at runtime, but the capacity annotation is not rendered. Without this annotation, the cluster-autoscaler has no visibility into these reservations and may over-schedule the node until evictions fire. + +#### Example: Override kubelet reservations + +```yaml +nodeGroups: + md0: + instanceType: "u1.large" + kubelet: + systemReservedMemory: "256Mi" + kubeReservedMemory: "256Mi" + evictionHardMemory: "500Mi" + evictionSoftMemory: "1Gi" +``` + ### U Series: Universal The U Series is quite neutral and provides resources for diff --git a/content/en/docs/v1.3/networking/http-cache.md b/content/en/docs/v1.3/networking/http-cache.md index 41a0588f..b45f5e4e 100644 --- a/content/en/docs/v1.3/networking/http-cache.md +++ b/content/en/docs/v1.3/networking/http-cache.md @@ -11,7 +11,7 @@ aliases: diff --git a/content/en/docs/v1.3/networking/tcp-balancer.md b/content/en/docs/v1.3/networking/tcp-balancer.md index 2f1d2b6d..be3c1b41 100644 --- a/content/en/docs/v1.3/networking/tcp-balancer.md +++ b/content/en/docs/v1.3/networking/tcp-balancer.md @@ -11,7 +11,7 @@ aliases: diff --git a/content/en/docs/v1.3/networking/vpc.md b/content/en/docs/v1.3/networking/vpc.md index 58ab71aa..4a7f6f7d 100644 --- a/content/en/docs/v1.3/networking/vpc.md +++ b/content/en/docs/v1.3/networking/vpc.md @@ -11,7 +11,7 @@ aliases: diff --git a/content/en/docs/v1.3/networking/vpn.md b/content/en/docs/v1.3/networking/vpn.md index d613e1cb..7525c5b3 100644 --- a/content/en/docs/v1.3/networking/vpn.md +++ b/content/en/docs/v1.3/networking/vpn.md @@ -11,7 +11,7 @@ aliases: diff --git a/content/en/docs/v1.3/operations/services/bootbox.md b/content/en/docs/v1.3/operations/services/bootbox.md index 642cd743..50b7b3ea 100644 --- a/content/en/docs/v1.3/operations/services/bootbox.md +++ b/content/en/docs/v1.3/operations/services/bootbox.md @@ -6,7 +6,7 @@ linkTitle: "BootBox" diff --git a/content/en/docs/v1.3/operations/services/etcd.md b/content/en/docs/v1.3/operations/services/etcd.md index 7b6860b1..b380e16d 100644 --- a/content/en/docs/v1.3/operations/services/etcd.md +++ b/content/en/docs/v1.3/operations/services/etcd.md @@ -6,10 +6,18 @@ linkTitle: "Etcd" +## Backups + +When `backup.enabled` is set to `true`, the chart renders an `EtcdBackupSchedule` (etcd.aenix.io/v1alpha1) and an S3 credentials `Secret`. The etcd-operator v0.4.3+ reconciles the schedule into a `CronJob` that periodically snapshots the cluster to S3. + +Enabling backup requires the following fields to be explicitly set (defaults are empty strings so that missing values fail fast at template render time): `backup.s3AccessKey`, `backup.s3SecretKey`, `backup.destinationPath` (must start with `s3://` and have no `//` segments), and `backup.endpointURL`. S3 credentials passed through plain values end up in the HelmRelease manifest — for production deployments prefer an external secret management tool (ESO, Sealed Secrets, etc.) over committing the keys to Git. + +**Restore** (`EtcdCluster.spec.bootstrap`) and the one-shot `EtcdBackup` custom resource shipped upstream in v0.4.3 are not yet exposed through this chart. Restoring from a snapshot or taking an ad-hoc backup currently requires hand-applying the corresponding custom resource manifest. + ## Parameters ### Common parameters @@ -23,3 +31,20 @@ source: https://github.com/cozystack/cozystack/blob/v1.3.0/packages/extra/etcd/R | `resources.cpu` | Number of CPU cores allocated. | `quantity` | `1000m` | | `resources.memory` | Amount of memory allocated. | `quantity` | `512Mi` | + +### Backup parameters + +| Name | Description | Type | Value | +| ----------------------------------- | ----------------------------------------------------------------------------- | -------- | ----------- | +| `backup` | Backup configuration. | `object` | `{}` | +| `backup.enabled` | Enable scheduled S3 backups. | `bool` | `false` | +| `backup.schedule` | Cron schedule for automated backups. | `string` | `0 2 * * *` | +| `backup.destinationPath` | Destination path for backups (e.g. s3://bucket/path/). | `string` | `""` | +| `backup.endpointURL` | S3 endpoint URL for uploads. | `string` | `""` | +| `backup.region` | S3 region. | `string` | `""` | +| `backup.forcePathStyle` | Use path-style S3 URLs (required for MinIO and most S3-compatible providers). | `bool` | `true` | +| `backup.s3AccessKey` | Access key for S3 authentication. | `string` | `""` | +| `backup.s3SecretKey` | Secret key for S3 authentication. | `string` | `""` | +| `backup.successfulJobsHistoryLimit` | Number of successful backup jobs to retain. | `int` | `3` | +| `backup.failedJobsHistoryLimit` | Number of failed backup jobs to retain. | `int` | `1` | + diff --git a/content/en/docs/v1.3/operations/services/ingress.md b/content/en/docs/v1.3/operations/services/ingress.md index 2aafd4d2..09414b67 100644 --- a/content/en/docs/v1.3/operations/services/ingress.md +++ b/content/en/docs/v1.3/operations/services/ingress.md @@ -6,7 +6,7 @@ linkTitle: "Ingress" @@ -24,3 +24,17 @@ source: https://github.com/cozystack/cozystack/blob/v1.3.0/packages/extra/ingres | `resources.memory` | Memory (RAM) available to each replica. | `quantity` | `""` | | `resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `micro` | + +## Exposure mode + +The ingress Service type is driven by the cluster-wide `publishing.exposure` value in the platform chart, not by any key in this package. Two modes exist: + +- `externalIPs` (default) has three rendered shapes: + - Release namespace matches `publishing.ingressName` AND `publishing.externalIPs` is non-empty → Service is `ClusterIP` with `Service.spec.externalIPs` set from that list and `externalTrafficPolicy: Cluster`. + - Release namespace matches `publishing.ingressName` but `publishing.externalIPs` is empty → Service falls back to `type: LoadBalancer` with `externalTrafficPolicy: Local`. + - Release namespace does not match `publishing.ingressName` (non-root tenants) → Service is `type: LoadBalancer` with `externalTrafficPolicy: Local`. + `Service.spec.externalIPs` is deprecated upstream in Kubernetes v1.36 (KEP-5707); plan migration before v1.40. +- `loadBalancer` — Service is `type: LoadBalancer` with `externalTrafficPolicy: Local`, and a `CiliumLoadBalancerIPPool` makes the addresses in `publishing.externalIPs` allocatable via Cilium LB IPAM. Requires `publishing.externalIPs` to contain at least one non-empty address (render fails otherwise) and assumes the addresses are already routed to a cluster node (floating IP / upstream router). See the inline comment on `publishing.exposure` in the platform chart for full caveats, including the note that switching the value on a running cluster causes the ingress Service to be recreated. + +This setting only migrates ingress-nginx away from `Service.spec.externalIPs`. Other cozystack components that use the same deprecated field (e.g. the `vpn` app) must be migrated separately before Kubernetes v1.40 flips the `AllowServiceExternalIPs` feature gate off. + diff --git a/content/en/docs/v1.3/operations/services/monitoring/parameters.md b/content/en/docs/v1.3/operations/services/monitoring/parameters.md index 277df6c7..39a5d589 100644 --- a/content/en/docs/v1.3/operations/services/monitoring/parameters.md +++ b/content/en/docs/v1.3/operations/services/monitoring/parameters.md @@ -7,7 +7,7 @@ weight: 1 diff --git a/content/en/docs/v1.3/operations/services/seaweedfs.md b/content/en/docs/v1.3/operations/services/seaweedfs.md index 0f7fd4ff..19a220af 100644 --- a/content/en/docs/v1.3/operations/services/seaweedfs.md +++ b/content/en/docs/v1.3/operations/services/seaweedfs.md @@ -6,7 +6,7 @@ linkTitle: "SeaweedFS" diff --git a/content/en/docs/v1.3/virtualization/vm-disk.md b/content/en/docs/v1.3/virtualization/vm-disk.md index e67a30d5..5f9cca26 100644 --- a/content/en/docs/v1.3/virtualization/vm-disk.md +++ b/content/en/docs/v1.3/virtualization/vm-disk.md @@ -10,7 +10,7 @@ aliases: diff --git a/content/en/docs/v1.3/virtualization/vm-instance.md b/content/en/docs/v1.3/virtualization/vm-instance.md index 95c71eb8..29cda0ff 100644 --- a/content/en/docs/v1.3/virtualization/vm-instance.md +++ b/content/en/docs/v1.3/virtualization/vm-instance.md @@ -10,7 +10,7 @@ aliases: @@ -50,31 +50,32 @@ virtctl ssh @ ### Common parameters -| Name | Description | Type | Value | -| ------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ---------- | ----------- | -| `external` | Enable external access from outside the cluster. | `bool` | `false` | -| `externalMethod` | Method to pass through traffic to the VM. | `string` | `PortList` | -| `externalPorts` | Ports to forward from outside the cluster. | `[]int` | `[22]` | -| `runStrategy` | Requested running state of the VirtualMachineInstance | `string` | `Always` | -| `instanceType` | Virtual Machine instance type. | `string` | `u1.medium` | -| `instanceProfile` | Virtual Machine preferences profile. | `string` | `ubuntu` | -| `disks` | List of disks to attach. | `[]object` | `[]` | -| `disks[i].name` | Disk name. | `string` | `""` | -| `disks[i].bus` | Disk bus type (e.g. "sata"). | `string` | `""` | -| `networks` | Networks to attach the VM to. | `[]object` | `[]` | -| `networks[i].name` | Network attachment name. | `string` | `""` | -| `subnets` | Deprecated: use networks instead. | `[]object` | `[]` | -| `subnets[i].name` | Network attachment name. | `string` | `""` | -| `gpus` | List of GPUs to attach (NVIDIA driver requires at least 4 GiB RAM). | `[]object` | `[]` | -| `gpus[i].name` | The name of the GPU resource to attach. | `string` | `""` | -| `cpuModel` | Model specifies the CPU model inside the VMI. List of available models https://github.com/libvirt/libvirt/tree/master/src/cpu_map | `string` | `""` | -| `resources` | Resource configuration for the virtual machine. | `object` | `{}` | -| `resources.cpu` | Number of CPU cores allocated. | `quantity` | `""` | -| `resources.memory` | Amount of memory allocated. | `quantity` | `""` | -| `resources.sockets` | Number of CPU sockets (vCPU topology). | `quantity` | `""` | -| `sshKeys` | List of SSH public keys for authentication. | `[]string` | `[]` | -| `cloudInit` | Cloud-init user data. | `string` | `""` | -| `cloudInitSeed` | Seed string to generate SMBIOS UUID for the VM. | `string` | `""` | +| Name | Description | Type | Value | +| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ----------- | +| `external` | Enable external access from outside the cluster. | `bool` | `false` | +| `externalMethod` | Method to pass through traffic to the VM. | `string` | `PortList` | +| `externalPorts` | Ports to forward from outside the cluster. | `[]int` | `[22]` | +| `externalAllowICMP` | Whether to accept ICMP traffic to the VM in PortList mode (preserves ping and PMTU discovery). No effect in WholeIP mode. Default true so ping behaves as users expect even when port filtering is in effect. | `bool` | `true` | +| `runStrategy` | Requested running state of the VirtualMachineInstance | `string` | `Always` | +| `instanceType` | Virtual Machine instance type. | `string` | `u1.medium` | +| `instanceProfile` | Virtual Machine preferences profile. | `string` | `ubuntu` | +| `disks` | List of disks to attach. | `[]object` | `[]` | +| `disks[i].name` | Disk name. | `string` | `""` | +| `disks[i].bus` | Disk bus type (e.g. "sata"). | `string` | `""` | +| `networks` | Networks to attach the VM to. | `[]object` | `[]` | +| `networks[i].name` | Network attachment name. | `string` | `""` | +| `subnets` | Deprecated: use networks instead. | `[]object` | `[]` | +| `subnets[i].name` | Network attachment name. | `string` | `""` | +| `gpus` | List of GPUs to attach (NVIDIA driver requires at least 4 GiB RAM). | `[]object` | `[]` | +| `gpus[i].name` | The name of the GPU resource to attach. | `string` | `""` | +| `cpuModel` | Model specifies the CPU model inside the VMI. List of available models https://github.com/libvirt/libvirt/tree/master/src/cpu_map | `string` | `""` | +| `resources` | Resource configuration for the virtual machine. | `object` | `{}` | +| `resources.cpu` | Number of CPU cores allocated. | `quantity` | `""` | +| `resources.memory` | Amount of memory allocated. | `quantity` | `""` | +| `resources.sockets` | Number of CPU sockets (vCPU topology). | `quantity` | `""` | +| `sshKeys` | List of SSH public keys for authentication. | `[]string` | `[]` | +| `cloudInit` | Cloud-init user data. | `string` | `""` | +| `cloudInitSeed` | Seed string to generate SMBIOS UUID for the VM. | `string` | `""` | ## U Series