From ef2e2b0c4acd31d99f0b6d77cb8837877ae0cb04 Mon Sep 17 00:00:00 2001 From: "cozystack-ci[bot]" <274107086+cozystack-ci[bot]@users.noreply.github.com> Date: Wed, 3 Jun 2026 07:38:31 +0000 Subject: [PATCH] [docs] Update managed apps reference for v1.5.0-rc.1 Signed-off-by: cozystack-ci[bot] <274107086+cozystack-ci[bot]@users.noreply.github.com> --- .../en/docs/next/applications/clickhouse.md | 175 +++++++-- .../en/docs/next/applications/foundationdb.md | 79 ++-- content/en/docs/next/applications/harbor.md | 64 ++-- content/en/docs/next/applications/kafka.md | 68 ++-- content/en/docs/next/applications/mariadb.md | 81 ++-- content/en/docs/next/applications/mongodb.md | 88 ++++- content/en/docs/next/applications/nats.md | 36 +- content/en/docs/next/applications/openbao.md | 24 +- content/en/docs/next/applications/postgres.md | 253 +++++++++--- content/en/docs/next/applications/qdrant.md | 44 ++- content/en/docs/next/applications/rabbitmq.md | 26 +- content/en/docs/next/applications/redis.md | 38 +- content/en/docs/next/applications/tenant.md | 21 +- content/en/docs/next/kubernetes/_index.md | 361 +++++++++++------- content/en/docs/next/networking/http-cache.md | 36 +- .../en/docs/next/networking/tcp-balancer.md | 30 +- content/en/docs/next/networking/vpc.md | 2 +- content/en/docs/next/networking/vpn.md | 30 +- .../docs/next/operations/services/bootbox.md | 2 +- .../en/docs/next/operations/services/etcd.md | 70 +++- .../docs/next/operations/services/ingress.md | 20 +- .../services/monitoring/parameters.md | 2 +- .../next/operations/services/seaweedfs.md | 130 +++---- .../en/docs/next/virtualization/vm-disk.md | 4 +- .../docs/next/virtualization/vm-instance.md | 100 +++-- 25 files changed, 1149 insertions(+), 635 deletions(-) diff --git a/content/en/docs/next/applications/clickhouse.md b/content/en/docs/next/applications/clickhouse.md index df315859..3a763ca2 100644 --- a/content/en/docs/next/applications/clickhouse.md +++ b/content/en/docs/next/applications/clickhouse.md @@ -11,47 +11,128 @@ aliases: ClickHouse is an open source high-performance and column-oriented SQL database management system (DBMS). It is used for online analytical processing (OLAP). -### How to restore backup from S3 +## Backup orchestration -{{% alert color="warning" %}} -**Backups: prefer the `BackupClass` flow.** `backup.enabled` and the S3 fields (`s3Region`, `s3Bucket`, `endpoint`, `s3PathOverride`, `s3AccessKey`/`s3SecretKey` or `s3CredentialsSecret`) are still required — they materialise the in-pod `clickhouse-backup` sidecar that the Altinity backup strategy talks to. However, `backup.schedule`, `backup.cleanupStrategy`, and `backup.resticPassword` (which drive the legacy chart-managed CronJob doing dump + restic, and the matching restic restore flow documented below) are **superseded** by the Cozystack backups framework: define a `BackupClass` + `Altinity` strategy once, then drive scheduled backups via `Plan` and restores via `RestoreJob`. See [Application Backup and Recovery]({{% ref "/docs/next/applications/backup-and-recovery" %}}) (tenant guide) and [Managed Application Backup Configuration]({{% ref "/docs/next/operations/services/managed-app-backup-configuration" %}}) (admin setup). -{{% /alert %}} +Two backup paths coexist on the chart; pick one per release. -1. Find the snapshot: +### Recommended: BackupClass + Plan via the Altinity strategy - ```bash - restic -r s3:s3.example.org/clickhouse-backups/table_name snapshots - ``` +The cluster-scoped `Altinity` strategy +(`strategy.backups.cozystack.io/v1alpha1`) wraps +[Altinity's `clickhouse-backup`][altinity-clickhouse-backup] in a one-shot +`batch/v1.Job` per `BackupJob` / `RestoreJob`. It is engine-aware (FREEZE + +upload), supports both in-place and `targetApplicationRef` (to-copy) restore, +and does not require any in-chart `CronJob`. -2. Restore it: +Wiring per release: - ```bash - restic -r s3:s3.example.org/clickhouse-backups/table_name restore latest --target /tmp/ - ``` +1. Set `backup.enabled: true` plus the `s3*` (or `s3CredentialsSecret.name`) + fields on the chart values. The chart materialises a Secret named + `-backup-s3` carrying bucket coordinates and credentials. That + Secret is consumed by the chart-emitted `clickhouse-backup` sidecar + (rendered into the ClickHouseInstallation Pod by + `templates/clickhouse.yaml`); the strategy Pod itself is a curl/jq + client that reaches the sidecar's HTTP API on port 7171 and never + reads the Secret directly. +2. Cluster admin one-time installs an `Altinity` strategy and a `BackupClass` + that maps `apps.cozystack.io/ClickHouse` to it (see + `examples/backups/clickhouse/01-create-strategy.sh` and `02-create-backupclass.sh`). +3. Tenant creates a `Plan` (cron schedule) or submits an ad-hoc `BackupJob` + referencing the BackupClass. Restoring is a `RestoreJob` referencing the + resulting `Backup`; omit `targetApplicationRef` for in-place, set it to a + second ClickHouse instance for to-copy. -For more details, read [Restic: Effective Backup from Stdin](https://blog.aenix.io/restic-effective-backup-from-stdin-4bc1e8f083c1). +#### Bringing your own S3 credentials Secret + +Setting `backup.s3CredentialsSecret.name` makes the chart skip the +materialisation of `-backup-s3` and points the sidecar at the +referenced Secret instead. The Secret must hold the five S3 fields as +**separate string keys**, not a JSON blob; the per-key field names default +to `bucketName` / `endpoint` / `region` / `accessKey` / `secretKey` and +can be remapped via `backup.s3CredentialsSecret.{bucketKey,endpointKey,…}`. + +Example: + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: my-s3-creds + namespace: tenant-test +type: Opaque +stringData: + bucketName: my-clickhouse-archive + endpoint: https://s3.example.org + region: us-east-1 + accessKey: AKIAIOSFODNN7EXAMPLE + secretKey: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY +--- +# In ClickHouse values.yaml: +backup: + enabled: true + s3CredentialsSecret: + name: my-s3-creds +``` + +> The Cozystack `Bucket` app's BucketInfo Secret (`bucket--`, +> single `BucketInfo` key holding a JSON blob) is **not directly +> consumable** as `s3CredentialsSecret`. Either let the chart read the raw +> values via `backup.s3*` (as +> `examples/backups/clickhouse/03-create-bucket.sh` does — extract +> coordinates from BucketInfo and pass them to the chart values), or +> materialise an intermediate Secret with the five string keys above. + +### Legacy: chart-emitted Restic CronJob + +The chart still ships a CronJob that streams per-table `SHOW CREATE TABLE` ++ `SELECT * FORMAT TabSeparated` into a Restic repository. This path is +kept for backward compatibility; new installations should prefer the +BackupClass flow above. + +To opt in: + +1. Set `backup.enabled: true`, `backup.schedule: "0 2 * * *"` (or another + non-empty cron), `backup.s3*` and `backup.resticPassword`. +2. To restore manually: + + ```bash + restic -r s3:s3.example.org/clickhouse-backups/table_name snapshots + restic -r s3:s3.example.org/clickhouse-backups/table_name restore latest --target /tmp/ + ``` + + For more details, read + [Restic: Effective Backup from Stdin](https://blog.aenix.io/restic-effective-backup-from-stdin-4bc1e8f083c1). + +The legacy `backup.schedule`, `backup.cleanupStrategy`, and +`backup.resticPassword` values are deprecated and will be removed once the +Altinity strategy is the default in all reference deployments. The +chart-emitted CronJob renders only when `backup.schedule` is non-empty. + +[altinity-clickhouse-backup]: https://github.com/Altinity/clickhouse-backup + +> `storageClass` is annotated as immutable in the chart schema — see [`docs/storage-immutability.md`](../../../docs/storage-immutability.md) for the contract and which consumers enforce it. ## Parameters ### Common parameters -| Name | Description | Type | Value | -| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | ---------- | ------- | -| `replicas` | Number of ClickHouse replicas. | `int` | `2` | -| `shards` | Number of ClickHouse shards. | `int` | `1` | -| `resources` | Explicit CPU and memory configuration for each ClickHouse replica. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | -| `resources.cpu` | CPU available to each replica. | `quantity` | `""` | -| `resources.memory` | Memory (RAM) available to each replica. | `quantity` | `""` | -| `resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `small` | -| `size` | Persistent Volume Claim size available for application data. | `quantity` | `10Gi` | -| `storageClass` | StorageClass used to store the data. | `string` | `""` | +| Name | Description | Type | Value | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | ---------- | ---------- | +| `replicas` | Number of ClickHouse replicas. | `int` | `2` | +| `shards` | Number of ClickHouse shards. | `int` | `1` | +| `resources` | Explicit CPU and memory configuration for each ClickHouse replica. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | +| `resources.cpu` | CPU available to each replica. | `quantity` | `""` | +| `resources.memory` | Memory (RAM) available to each replica. | `quantity` | `""` | +| `resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `t1.small` | +| `size` | Persistent Volume Claim size available for application data. | `quantity` | `10Gi` | +| `storageClass` | StorageClass used to store the data. | `string` | `""` | ### Application-specific parameters @@ -67,28 +148,38 @@ For more details, read [Restic: Effective Backup from Stdin](https://blog.aenix. ### Backup parameters -| Name | Description | Type | Value | -| ------------------------ | ----------------------------------------------- | -------- | ------------------------------------------------------ | -| `backup` | Backup configuration. | `object` | `{}` | -| `backup.enabled` | Enable regular backups (default: false). | `bool` | `false` | -| `backup.s3Region` | AWS S3 region where backups are stored. | `string` | `us-east-1` | -| `backup.s3Bucket` | S3 bucket used for storing backups. | `string` | `s3.example.org/clickhouse-backups` | -| `backup.schedule` | Cron schedule for automated backups. | `string` | `0 2 * * *` | -| `backup.cleanupStrategy` | Retention strategy for cleaning up old backups. | `string` | `--keep-last=3 --keep-daily=3 --keep-within-weekly=1m` | -| `backup.s3AccessKey` | Access key for S3 authentication. | `string` | `` | -| `backup.s3SecretKey` | Secret key for S3 authentication. | `string` | `` | -| `backup.resticPassword` | Password for Restic backup encryption. | `string` | `` | +| Name | Description | Type | Value | +| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ------------------------------------------------------ | +| `backup` | Backup configuration. | `object` | `{}` | +| `backup.enabled` | Enable backup integration. Materialises the chart-emitted `-backup-s3` Secret consumed by the Altinity backup strategy and, when `schedule` is non-empty, also renders the legacy chart-managed CronJob. | `bool` | `false` | +| `backup.useSystemBucket` | Opt-in: when true, the chart-emitted `-backup-s3` Secret is skipped and the `clickhouse-backup` sidecar reads bucket coordinates + S3 credentials from the platform-projected `cozy-backups-creds` Secret. `S3_PATH` is set to `/` for cross-tenant isolation. Use together with the platform `cozy-default` BackupClass — tenants do not need to fill any `s3*` field below. | `bool` | `false` | +| `backup.s3Region` | DEPRECATED. Per-tenant S3 configuration is being phased out in favour of the platform-managed `cozy-default` BackupClass. Optional now so tenants on `useSystemBucket: true` can omit it. | `string` | `us-east-1` | +| `backup.s3Bucket` | DEPRECATED. Optional; see `s3Region`. | `string` | `s3.example.org/clickhouse-backups` | +| `backup.endpoint` | DEPRECATED. S3 endpoint URL for the legacy chart-emitted sidecar. | `string` | `""` | +| `backup.s3PathOverride` | DEPRECATED. Object-key prefix inside the legacy `s3Bucket`; the new platform flow scopes by namespace automatically. | `string` | `""` | +| `backup.schedule` | Legacy. Cron schedule for the chart-emitted CronJob that runs the dump+restic backup. Empty (default) skips the legacy CronJob; recommended when a `BackupClass` + `Plan` from `backups.cozystack.io` already drives backup orchestration via the Altinity strategy. | `string` | `""` | +| `backup.cleanupStrategy` | Legacy. Restic retention policy passed to the legacy CronJob (`restic forget …`). Unused by the Altinity strategy. | `string` | `--keep-last=3 --keep-daily=3 --keep-within-weekly=1m` | +| `backup.s3AccessKey` | DEPRECATED. Tenants no longer supply S3 keys; the platform-managed Bucket Secret is the source of truth. Optional now so `useSystemBucket: true` tenants can omit it. | `string` | `` | +| `backup.s3SecretKey` | DEPRECATED. Optional; see `s3AccessKey`. | `string` | `` | +| `backup.resticPassword` | Legacy. Password for Restic backup encryption used by the legacy CronJob. Unused by the Altinity strategy. | `string` | `` | +| `backup.s3CredentialsSecret` | DEPRECATED. Pre-existing Secret reference for the legacy chart-emitted sidecar. The platform flow projects `cozy-backups-creds` instead. | `object` | `{}` | +| `backup.s3CredentialsSecret.name` | Name of the Secret in the application namespace. Empty means the chart materialises `-backup-s3` from the legacy `s3*` fields. | `string` | `""` | +| `backup.s3CredentialsSecret.bucketKey` | Key in the Secret holding the bucket name. Defaults to `bucketName`. | `string` | `""` | +| `backup.s3CredentialsSecret.endpointKey` | Key in the Secret holding the S3 endpoint URL. Defaults to `endpoint`. | `string` | `""` | +| `backup.s3CredentialsSecret.regionKey` | Key in the Secret holding the S3 region. Defaults to `region`. | `string` | `""` | +| `backup.s3CredentialsSecret.accessKeyIDKey` | Key in the Secret holding the access key ID. Defaults to `accessKey`. | `string` | `""` | +| `backup.s3CredentialsSecret.secretAccessKeyKey` | Key in the Secret holding the secret access key. Defaults to `secretKey`. | `string` | `""` | ### ClickHouse Keeper parameters -| Name | Description | Type | Value | -| ---------------------------------- | ------------------------------------------------------------ | ---------- | ------- | -| `clickhouseKeeper` | ClickHouse Keeper configuration. | `object` | `{}` | -| `clickhouseKeeper.enabled` | Deploy ClickHouse Keeper for cluster coordination. | `bool` | `true` | -| `clickhouseKeeper.size` | Persistent Volume Claim size available for application data. | `quantity` | `1Gi` | -| `clickhouseKeeper.resourcesPreset` | Default sizing preset. | `string` | `micro` | -| `clickhouseKeeper.replicas` | Number of Keeper replicas. | `int` | `3` | +| Name | Description | Type | Value | +| ---------------------------------- | ------------------------------------------------------------ | ---------- | ---------- | +| `clickhouseKeeper` | ClickHouse Keeper configuration. | `object` | `{}` | +| `clickhouseKeeper.enabled` | Deploy ClickHouse Keeper for cluster coordination. | `bool` | `true` | +| `clickhouseKeeper.size` | Persistent Volume Claim size available for application data. | `quantity` | `1Gi` | +| `clickhouseKeeper.resourcesPreset` | Default sizing preset. | `string` | `t1.micro` | +| `clickhouseKeeper.replicas` | Number of Keeper replicas. | `int` | `3` | ## Parameter examples and reference diff --git a/content/en/docs/next/applications/foundationdb.md b/content/en/docs/next/applications/foundationdb.md index 71e94323..e50a75ff 100644 --- a/content/en/docs/next/applications/foundationdb.md +++ b/content/en/docs/next/applications/foundationdb.md @@ -6,7 +6,7 @@ weight: 50 @@ -64,20 +64,25 @@ resources: memory: "4Gi" ``` -### Backup (Optional) - -```yaml -backup: - enabled: true - s3: - bucket: "my-fdb-backups" - endpoint: "https://s3.amazonaws.com" - region: "us-east-1" - credentials: - accessKeyId: "AKIA..." - secretAccessKey: "..." - retentionPolicy: "7d" -``` +### Backups + +The recommended backup flow uses the Cozystack backups framework: a +cluster-scoped `BackupClass` binds `apps.cozystack.io/FoundationDB` to a +`strategy.backups.cozystack.io/FoundationDB` strategy, and tenants drive +runs via `BackupJob` / `RestoreJob`. See +[`examples/backups/foundationdb/`](../../../examples/backups/foundationdb/) +for an end-to-end walkthrough (admin setup, backup, in-place restore, +to-copy restore). + +The legacy in-chart `backup.*` values (`backup.enabled`, `backup.s3`, +`backup.retentionPolicy`) are **DEPRECATED** but still render the +original `FoundationDBBackup` CR unchanged when `backup.enabled=true`, +for backward compatibility. New deployments should leave +`backup.enabled=false` (the default) and use the BackupClass flow above. +Mixing the two on the same cluster is unsupported — the FoundationDB +operator only permits one running backup directory per cluster, and the +backup driver fails fast with `Ready=False/ConflictingInChartBackup` +when it sees a chart-rendered Running backup against the same target. ### Advanced Configuration @@ -86,8 +91,8 @@ backup: customParameters: - "knob_disable_posix_kernel_aio=1" -# Image type (unified is default and recommended for new deployments) -imageType: "unified" +# Image type (split is the default; matches existing clusters' effective value) +imageType: "split" # Enable automatic pod replacements automaticReplacements: true @@ -154,6 +159,8 @@ For issues related to FoundationDB itself, refer to the [FoundationDB documentat For Cozystack-specific issues, consult the Cozystack documentation or support channels. +> `storageClass` is annotated as immutable in the chart schema — see [`docs/storage-immutability.md`](../../../docs/storage-immutability.md) for the contract and which consumers enforce it. + ## Parameters ### Common parameters @@ -177,29 +184,29 @@ For Cozystack-specific issues, consult the Cozystack documentation or support ch | `resources` | Explicit CPU and memory configuration for each FoundationDB instance. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | | `resources.cpu` | CPU available to each instance. | `quantity` | `""` | | `resources.memory` | Memory (RAM) available to each instance. | `quantity` | `""` | -| `resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `medium` | -| `backup` | Backup configuration. | `object` | `{}` | -| `backup.enabled` | Enable backups. | `bool` | `false` | -| `backup.s3` | S3 configuration for backups. | `object` | `{}` | -| `backup.s3.bucket` | S3 bucket name. | `string` | `""` | -| `backup.s3.endpoint` | S3 endpoint URL. | `string` | `""` | -| `backup.s3.region` | S3 region. | `string` | `us-east-1` | -| `backup.s3.credentials` | S3 credentials. | `object` | `{}` | -| `backup.s3.credentials.accessKeyId` | S3 access key ID. | `string` | `""` | -| `backup.s3.credentials.secretAccessKey` | S3 secret access key. | `string` | `""` | -| `backup.retentionPolicy` | Retention policy for backups. | `string` | `7d` | +| `resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `c1.small` | +| `backup` | DEPRECATED Backup configuration (use the Cozystack backups framework: BackupClass + FoundationDB strategy). | `object` | `{}` | +| `backup.enabled` | DEPRECATED Enable in-chart backups (superseded by BackupClass + FoundationDB strategy). | `bool` | `false` | +| `backup.s3` | DEPRECATED S3 configuration for backups. | `object` | `{}` | +| `backup.s3.bucket` | DEPRECATED S3 bucket name. | `string` | `""` | +| `backup.s3.endpoint` | DEPRECATED S3 endpoint URL. | `string` | `""` | +| `backup.s3.region` | DEPRECATED S3 region. | `string` | `us-east-1` | +| `backup.s3.credentials` | DEPRECATED S3 credentials. | `object` | `{}` | +| `backup.s3.credentials.accessKeyId` | DEPRECATED S3 access key ID. | `string` | `""` | +| `backup.s3.credentials.secretAccessKey` | DEPRECATED S3 secret access key. | `string` | `""` | +| `backup.retentionPolicy` | DEPRECATED Retention policy for backups. | `string` | `7d` | | `monitoring` | Monitoring configuration. | `object` | `{}` | | `monitoring.enabled` | Enable WorkloadMonitor integration. | `bool` | `true` | ### FoundationDB configuration -| Name | Description | Type | Value | -| ---------------------------- | ------------------------------------------ | ---------- | --------- | -| `customParameters` | Custom parameters to pass to FoundationDB. | `[]string` | `[]` | -| `imageType` | Container image deployment type. | `string` | `unified` | -| `securityContext` | Security context for containers. | `object` | `{}` | -| `securityContext.runAsUser` | User ID to run the container. | `int` | `4059` | -| `securityContext.runAsGroup` | Group ID to run the container. | `int` | `4059` | -| `automaticReplacements` | Enable automatic pod replacements. | `bool` | `true` | +| Name | Description | Type | Value | +| ---------------------------- | ------------------------------------------ | ---------- | ------- | +| `customParameters` | Custom parameters to pass to FoundationDB. | `[]string` | `[]` | +| `imageType` | Container image deployment type. | `string` | `split` | +| `securityContext` | Security context for containers. | `object` | `{}` | +| `securityContext.runAsUser` | User ID to run the container. | `int` | `4059` | +| `securityContext.runAsGroup` | Group ID to run the container. | `int` | `4059` | +| `automaticReplacements` | Enable automatic pod replacements. | `bool` | `true` | diff --git a/content/en/docs/next/applications/harbor.md b/content/en/docs/next/applications/harbor.md index 13568e8e..779cb3e1 100644 --- a/content/en/docs/next/applications/harbor.md +++ b/content/en/docs/next/applications/harbor.md @@ -7,12 +7,14 @@ weight: 50 Harbor is an open-source trusted cloud-native registry project that stores, signs, and scans content. +> `storageClass` is annotated as immutable in the chart schema — see [`docs/storage-immutability.md`](../../../docs/storage-immutability.md) for the contract and which consumers enforce it. + ## Parameters ### Common parameters @@ -25,34 +27,34 @@ Harbor is an open-source trusted cloud-native registry project that stores, sign ### Component configuration -| Name | Description | Type | Value | -| ----------------------------- | -------------------------------------------------------------------------------------------------------- | ---------- | ------- | -| `core` | Core API server configuration. | `object` | `{}` | -| `core.resources` | Explicit CPU and memory configuration. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | -| `core.resources.cpu` | Number of CPU cores allocated. | `quantity` | `""` | -| `core.resources.memory` | Amount of memory allocated. | `quantity` | `""` | -| `core.resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `small` | -| `registry` | Container image registry configuration. | `object` | `{}` | -| `registry.resources` | Explicit CPU and memory configuration. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | -| `registry.resources.cpu` | Number of CPU cores allocated. | `quantity` | `""` | -| `registry.resources.memory` | Amount of memory allocated. | `quantity` | `""` | -| `registry.resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `small` | -| `jobservice` | Background job service configuration. | `object` | `{}` | -| `jobservice.resources` | Explicit CPU and memory configuration. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | -| `jobservice.resources.cpu` | Number of CPU cores allocated. | `quantity` | `""` | -| `jobservice.resources.memory` | Amount of memory allocated. | `quantity` | `""` | -| `jobservice.resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `nano` | -| `trivy` | Trivy vulnerability scanner configuration. | `object` | `{}` | -| `trivy.enabled` | Enable or disable the vulnerability scanner. | `bool` | `true` | -| `trivy.size` | Persistent Volume size for vulnerability database cache. | `quantity` | `5Gi` | -| `trivy.resources` | Explicit CPU and memory configuration. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | -| `trivy.resources.cpu` | Number of CPU cores allocated. | `quantity` | `""` | -| `trivy.resources.memory` | Amount of memory allocated. | `quantity` | `""` | -| `trivy.resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `nano` | -| `database` | PostgreSQL database configuration. | `object` | `{}` | -| `database.size` | Persistent Volume size for database storage. | `quantity` | `5Gi` | -| `database.replicas` | Number of database instances. | `int` | `2` | -| `redis` | Redis cache configuration. | `object` | `{}` | -| `redis.size` | Persistent Volume size for cache storage. | `quantity` | `1Gi` | -| `redis.replicas` | Number of Redis replicas. | `int` | `2` | +| Name | Description | Type | Value | +| ----------------------------- | -------------------------------------------------------------------------------------------------------- | ---------- | ---------- | +| `core` | Core API server configuration. | `object` | `{}` | +| `core.resources` | Explicit CPU and memory configuration. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | +| `core.resources.cpu` | Number of CPU cores allocated. | `quantity` | `""` | +| `core.resources.memory` | Amount of memory allocated. | `quantity` | `""` | +| `core.resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `t1.small` | +| `registry` | Container image registry configuration. | `object` | `{}` | +| `registry.resources` | Explicit CPU and memory configuration. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | +| `registry.resources.cpu` | Number of CPU cores allocated. | `quantity` | `""` | +| `registry.resources.memory` | Amount of memory allocated. | `quantity` | `""` | +| `registry.resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `t1.small` | +| `jobservice` | Background job service configuration. | `object` | `{}` | +| `jobservice.resources` | Explicit CPU and memory configuration. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | +| `jobservice.resources.cpu` | Number of CPU cores allocated. | `quantity` | `""` | +| `jobservice.resources.memory` | Amount of memory allocated. | `quantity` | `""` | +| `jobservice.resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `t1.nano` | +| `trivy` | Trivy vulnerability scanner configuration. | `object` | `{}` | +| `trivy.enabled` | Enable or disable the vulnerability scanner. | `bool` | `true` | +| `trivy.size` | Persistent Volume size for vulnerability database cache. | `quantity` | `5Gi` | +| `trivy.resources` | Explicit CPU and memory configuration. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | +| `trivy.resources.cpu` | Number of CPU cores allocated. | `quantity` | `""` | +| `trivy.resources.memory` | Amount of memory allocated. | `quantity` | `""` | +| `trivy.resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `t1.nano` | +| `database` | PostgreSQL database configuration. | `object` | `{}` | +| `database.size` | Persistent Volume size for database storage. | `quantity` | `5Gi` | +| `database.replicas` | Number of database instances. | `int` | `2` | +| `redis` | Redis cache configuration. | `object` | `{}` | +| `redis.size` | Persistent Volume size for cache storage. | `quantity` | `1Gi` | +| `redis.replicas` | Number of Redis replicas. | `int` | `2` | diff --git a/content/en/docs/next/applications/kafka.md b/content/en/docs/next/applications/kafka.md index 941a21f4..8caa945d 100644 --- a/content/en/docs/next/applications/kafka.md +++ b/content/en/docs/next/applications/kafka.md @@ -10,17 +10,21 @@ aliases: +> Both `kafka.storageClass` and `zookeeper.storageClass` are annotated as immutable in the chart schema — see [`docs/storage-immutability.md`](../../../docs/storage-immutability.md) for the contract and which consumers enforce it. + ## Parameters ### Common parameters -| Name | Description | Type | Value | -| ---------- | ------------------------------------------------ | ------ | ------- | -| `external` | Enable external access from outside the cluster. | `bool` | `false` | +| Name | Description | Type | Value | +| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | +| `external` | Enable external access from outside the cluster. | `bool` | `false` | +| `tls` | TLS configuration. Strimzi manages the cluster PKI automatically (no cert-manager is involved for this chart): the operator auto-creates `-cluster-ca-cert` and `-clients-ca-cert` secrets, both exposed for client trust setup. The internal TLS listener on 9093 is always on; this toggle only controls the external listener on 9094. | `object` | `{}` | +| `tls.enabled` | Enable TLS on the external listener. When unset, inherits the value of `external` (TLS is on when external access is enabled). Warning: setting this to false while external is true exposes Kafka over plaintext on a public IP via LoadBalancer. Strimzi does not provide authentication on this listener unless SCRAM, mTLS, or OAuth is separately configured. Use only in controlled networks. | `*bool` | `null` | ### Application-specific parameters @@ -36,30 +40,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` | `c1.small` | +| `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` | `c1.small` | +| `zookeeper.size` | Persistent Volume size for ZooKeeper. | `quantity` | `5Gi` | +| `zookeeper.storageClass` | StorageClass used to store the ZooKeeper data. | `string` | `""` | ## Parameter examples and reference @@ -78,15 +82,13 @@ resources: `resourcesPreset` sets named CPU and memory configurations for each replica. This setting is ignored if the corresponding `resources` value is set. -| Preset name | CPU | memory | -|-------------|--------|---------| -| `nano` | `250m` | `128Mi` | -| `micro` | `500m` | `256Mi` | -| `small` | `1` | `512Mi` | -| `medium` | `1` | `1Gi` | -| `large` | `2` | `2Gi` | -| `xlarge` | `4` | `4Gi` | -| `2xlarge` | `8` | `8Gi` | +Presets follow a cloud-style `.` naming convention. Five series cover the full CPU-to-memory ratio range (`t1` 1:0.5, `c1` 1:1, `s1` 1:2, `u1` 1:4, `m1` 1:8) and each series ships eight sizes (`nano` through `4xlarge`). The legacy flat names (`nano`, `micro`, `small`, `medium`, `large`, `xlarge`, `2xlarge`) remain accepted as deprecated aliases of their 1:1 instance-type equivalents. + +See [`docs/operations/resource-presets.md`](../../../docs/operations/resource-presets.md) for the full size matrix and the legacy-to-instance-type mapping. + +### Authentication + +This chart does not configure listener authentication. When TLS is enabled on the external listener, clients can connect without credentials. To require authentication, use Strimzi's `KafkaUser` resource with an appropriate `authentication` type (`tls`, `scram-sha-512`, or `oauth`) outside this chart. See the [Strimzi documentation on KafkaUser](https://strimzi.io/docs/operators/latest/overview.html#security-options_str) for details. ### topics diff --git a/content/en/docs/next/applications/mariadb.md b/content/en/docs/next/applications/mariadb.md index d7926735..ef7c5042 100644 --- a/content/en/docs/next/applications/mariadb.md +++ b/content/en/docs/next/applications/mariadb.md @@ -10,7 +10,7 @@ aliases: @@ -24,6 +24,8 @@ This managed service is controlled by mariadb-operator, ensuring efficient manag - Docs: https://mariadb.com/kb/en/documentation/ - GitHub: https://github.com/mariadb-operator/mariadb-operator +> `storageClass` is annotated as immutable in the chart schema — see [`docs/storage-immutability.md`](../../../docs/storage-immutability.md) for the contract and which consumers enforce it. + ## HowTos ### How to switch master/slave replica @@ -47,7 +49,21 @@ NAME READY STATUS PRIMARY POD AGE True Running app-db1-1 41d ``` -### How to restore backup: +### How to back up and restore a MariaDB application + +The recommended path is the Cozystack `BackupClass` / `Plan` / +`RestoreJob` flow with the operator-native `strategy.backups.cozystack.io/MariaDB` +strategy. See [examples/backups/mariadb](../../../examples/backups/mariadb/) +for a numbered, end-to-end walkthrough (bucket, source, strategy, +BackupClass, Plan, ad-hoc BackupJob, and both in-place + to-copy +RestoreJob fixtures). + +The chart's `backup.*` block (mariadb-dump + restic CronJob) is +**deprecated** and remains supported for backward compatibility only. +Existing tenants can keep using it unchanged; new deployments should +use the operator-native flow above. + +#### How to restore from a deprecated restic-based backup find snapshot: ```bash @@ -83,17 +99,17 @@ more details: ### Common parameters -| Name | Description | Type | Value | -| ------------------ | --------------------------------------------------------------------------------------------------------------------------------- | ---------- | ------- | -| `replicas` | Number of MariaDB replicas. | `int` | `2` | -| `resources` | Explicit CPU and memory configuration for each MariaDB replica. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | -| `resources.cpu` | CPU available to each replica. | `quantity` | `""` | -| `resources.memory` | Memory (RAM) available to each replica. | `quantity` | `""` | -| `resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `nano` | -| `size` | Persistent Volume Claim size available for application data. | `quantity` | `10Gi` | -| `storageClass` | StorageClass used to store the data. | `string` | `""` | -| `external` | Enable external access from outside the cluster. | `bool` | `false` | -| `version` | MariaDB major.minor version to deploy | `string` | `v11.8` | +| Name | Description | Type | Value | +| ------------------ | --------------------------------------------------------------------------------------------------------------------------------- | ---------- | --------- | +| `replicas` | Number of MariaDB replicas. | `int` | `2` | +| `resources` | Explicit CPU and memory configuration for each MariaDB replica. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | +| `resources.cpu` | CPU available to each replica. | `quantity` | `""` | +| `resources.memory` | Memory (RAM) available to each replica. | `quantity` | `""` | +| `resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `t1.nano` | +| `size` | Persistent Volume Claim size available for application data. | `quantity` | `10Gi` | +| `storageClass` | StorageClass used to store the data. | `string` | `""` | +| `external` | Enable external access from outside the cluster. | `bool` | `false` | +| `version` | MariaDB major.minor version to deploy | `string` | `v11.8` | ### Application-specific parameters @@ -109,22 +125,19 @@ more details: | `databases[name].roles.readonly` | List of users with read-only privileges. | `[]string` | `[]` | -### Backup parameters -{{% alert color="warning" %}} -**The chart-level `backup.*` values documented below are deprecated.** The legacy `mariadb-dump` + `restic` flow is superseded by the Cozystack backups framework: define a `BackupClass` + `MariaDB` strategy once, then drive backups via `BackupJob` / `Plan` and restores via `RestoreJob`. Existing tenants with `backup.enabled=true` continue to render the legacy resources unchanged. See [Application Backup and Recovery]({{% ref "/docs/next/applications/backup-and-recovery" %}}) (tenant guide) and [Managed Application Backup Configuration]({{% ref "/docs/next/operations/services/managed-app-backup-configuration" %}}) (admin setup). -{{% /alert %}} +### Backup parameters (DEPRECATED) -| Name | Description | Type | Value | -| ------------------------ | ----------------------------------------------- | -------- | ------------------------------------------------------ | -| `backup` | Backup configuration. | `object` | `{}` | -| `backup.enabled` | Enable regular backups (default: false). | `bool` | `false` | -| `backup.s3Region` | AWS S3 region where backups are stored. | `string` | `us-east-1` | -| `backup.s3Bucket` | S3 bucket used for storing backups. | `string` | `s3.example.org/mariadb-backups` | -| `backup.schedule` | Cron schedule for automated backups. | `string` | `0 2 * * *` | -| `backup.cleanupStrategy` | Retention strategy for cleaning up old backups. | `string` | `--keep-last=3 --keep-daily=3 --keep-within-weekly=1m` | -| `backup.s3AccessKey` | Access key for S3 authentication. | `string` | `` | -| `backup.s3SecretKey` | Secret key for S3 authentication. | `string` | `` | -| `backup.resticPassword` | Password for Restic backup encryption. | `string` | `` | +| Name | Description | Type | Value | +| ------------------------ | ----------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------ | +| `backup` | DEPRECATED: Backup configuration. Prefer the BackupClass / Plan flow under examples/backups/mariadb/. | `object` | `{}` | +| `backup.enabled` | DEPRECATED: Enable regular backups (default: false). | `bool` | `false` | +| `backup.s3Region` | DEPRECATED: AWS S3 region where backups are stored. | `string` | `us-east-1` | +| `backup.s3Bucket` | DEPRECATED: S3 bucket used for storing backups. | `string` | `s3.example.org/mariadb-backups` | +| `backup.schedule` | DEPRECATED: Cron schedule for automated backups. | `string` | `0 2 * * *` | +| `backup.cleanupStrategy` | DEPRECATED: Retention strategy for cleaning up old backups. | `string` | `--keep-last=3 --keep-daily=3 --keep-within-weekly=1m` | +| `backup.s3AccessKey` | DEPRECATED: Access key for S3 authentication. | `string` | `` | +| `backup.s3SecretKey` | DEPRECATED: Secret key for S3 authentication. | `string` | `` | +| `backup.resticPassword` | DEPRECATED: Password for Restic backup encryption. | `string` | `` | ## Parameter examples and reference @@ -143,15 +156,9 @@ resources: `resourcesPreset` sets named CPU and memory configurations for each replica. This setting is ignored if the corresponding `resources` value is set. -| Preset name | CPU | memory | -|-------------|--------|---------| -| `nano` | `250m` | `128Mi` | -| `micro` | `500m` | `256Mi` | -| `small` | `1` | `512Mi` | -| `medium` | `1` | `1Gi` | -| `large` | `2` | `2Gi` | -| `xlarge` | `4` | `4Gi` | -| `2xlarge` | `8` | `8Gi` | +Presets follow a cloud-style `.` naming convention. Five series cover the full CPU-to-memory ratio range (`t1` 1:0.5, `c1` 1:1, `s1` 1:2, `u1` 1:4, `m1` 1:8) and each series ships eight sizes (`nano` through `4xlarge`). The legacy flat names (`nano`, `micro`, `small`, `medium`, `large`, `xlarge`, `2xlarge`) remain accepted as deprecated aliases of their 1:1 instance-type equivalents. + +See [`docs/operations/resource-presets.md`](../../../docs/operations/resource-presets.md) for the full size matrix and the legacy-to-instance-type mapping. ### users diff --git a/content/en/docs/next/applications/mongodb.md b/content/en/docs/next/applications/mongodb.md index 6022b35e..e5f8ef14 100644 --- a/content/en/docs/next/applications/mongodb.md +++ b/content/en/docs/next/applications/mongodb.md @@ -10,7 +10,7 @@ aliases: @@ -49,21 +49,85 @@ 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 +``` + +> `storageClass` is annotated as immutable in the chart schema — see [`docs/storage-immutability.md`](../../../docs/storage-immutability.md) for the contract and which consumers enforce it. + ## Parameters ### Common parameters -| Name | Description | Type | Value | -| ------------------ | --------------------------------------------------------------------------------------------------------------------------------- | ---------- | ------- | -| `replicas` | Number of MongoDB replicas in replica set. | `int` | `3` | -| `resources` | Explicit CPU and memory configuration for each MongoDB replica. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | -| `resources.cpu` | CPU available to each replica. | `quantity` | `""` | -| `resources.memory` | Memory (RAM) available to each replica. | `quantity` | `""` | -| `resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `small` | -| `size` | Persistent Volume Claim size available for application data. | `quantity` | `10Gi` | -| `storageClass` | StorageClass used to store the data. | `string` | `""` | -| `external` | Enable external access from outside the cluster. | `bool` | `false` | -| `version` | MongoDB major version to deploy. | `string` | `v8` | +| Name | Description | Type | Value | +| ------------------ | --------------------------------------------------------------------------------------------------------------------------------- | ---------- | ---------- | +| `replicas` | Number of MongoDB replicas in replica set. | `int` | `3` | +| `resources` | Explicit CPU and memory configuration for each MongoDB replica. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | +| `resources.cpu` | CPU available to each replica. | `quantity` | `""` | +| `resources.memory` | Memory (RAM) available to each replica. | `quantity` | `""` | +| `resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `t1.small` | +| `size` | Persistent Volume Claim size available for application data. | `quantity` | `10Gi` | +| `storageClass` | StorageClass used to store the data. | `string` | `""` | +| `external` | Enable external access from outside the cluster. | `bool` | `false` | +| `version` | MongoDB major version to deploy. | `string` | `v8` | ### Sharding configuration diff --git a/content/en/docs/next/applications/nats.md b/content/en/docs/next/applications/nats.md index 87a03bfd..8dfc7a88 100644 --- a/content/en/docs/next/applications/nats.md +++ b/content/en/docs/next/applications/nats.md @@ -10,26 +10,30 @@ aliases: NATS is an open-source, simple, secure, and high performance messaging system. It provides a data layer for cloud native applications, IoT messaging, and microservices architectures. +> `storageClass` is annotated as immutable in the chart schema — see [`docs/storage-immutability.md`](../../../docs/storage-immutability.md) for the contract and which consumers enforce it. + ## Parameters ### Common parameters -| Name | Description | Type | Value | -| ------------------ | ------------------------------------------------------------------------------------------------------------------------------ | ---------- | ------- | -| `replicas` | Number of replicas. | `int` | `2` | -| `resources` | Explicit CPU and memory configuration for each NATS replica. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | -| `resources.cpu` | CPU available to each replica. | `quantity` | `""` | -| `resources.memory` | Memory (RAM) available to each replica. | `quantity` | `""` | -| `resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `nano` | -| `storageClass` | StorageClass used to store the data. | `string` | `""` | -| `external` | Enable external access from outside the cluster. | `bool` | `false` | +| Name | Description | Type | Value | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------ | ---------- | --------- | +| `replicas` | Number of replicas. | `int` | `2` | +| `resources` | Explicit CPU and memory configuration for each NATS replica. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | +| `resources.cpu` | CPU available to each replica. | `quantity` | `""` | +| `resources.memory` | Memory (RAM) available to each replica. | `quantity` | `""` | +| `resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `t1.nano` | +| `storageClass` | StorageClass used to store the data. | `string` | `""` | +| `external` | Enable external access from outside the cluster. | `bool` | `false` | +| `tls` | TLS configuration. When omitted, TLS follows the `external` flag. | `object` | `{}` | +| `tls.enabled` | Enable TLS. When omitted, TLS is enabled automatically when `external` is true. | `*bool` | `null` | ### Application-specific parameters @@ -62,13 +66,7 @@ resources: `resourcesPreset` sets named CPU and memory configurations for each replica. This setting is ignored if the corresponding `resources` value is set. -| Preset name | CPU | memory | -|-------------|--------|---------| -| `nano` | `250m` | `128Mi` | -| `micro` | `500m` | `256Mi` | -| `small` | `1` | `512Mi` | -| `medium` | `1` | `1Gi` | -| `large` | `2` | `2Gi` | -| `xlarge` | `4` | `4Gi` | -| `2xlarge` | `8` | `8Gi` | +Presets follow a cloud-style `.` naming convention. Five series cover the full CPU-to-memory ratio range (`t1` 1:0.5, `c1` 1:1, `s1` 1:2, `u1` 1:4, `m1` 1:8) and each series ships eight sizes (`nano` through `4xlarge`). The legacy flat names (`nano`, `micro`, `small`, `medium`, `large`, `xlarge`, `2xlarge`) remain accepted as deprecated aliases of their 1:1 instance-type equivalents. + +See [`docs/operations/resource-presets.md`](../../../docs/operations/resource-presets.md) for the full size matrix and the legacy-to-instance-type mapping. diff --git a/content/en/docs/next/applications/openbao.md b/content/en/docs/next/applications/openbao.md index e34ff54e..5b397084 100644 --- a/content/en/docs/next/applications/openbao.md +++ b/content/en/docs/next/applications/openbao.md @@ -7,27 +7,29 @@ weight: 50 OpenBAO is an open-source secrets management solution forked from HashiCorp Vault. It provides identity-based secrets and encryption management for cloud infrastructure. +> `storageClass` is annotated as immutable in the chart schema — see [`docs/storage-immutability.md`](../../../docs/storage-immutability.md) for the contract and which consumers enforce it. + ## Parameters ### Common parameters -| Name | Description | Type | Value | -| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ------- | -| `replicas` | Number of OpenBAO replicas. HA with Raft is automatically enabled when replicas > 1. Switching between standalone (file storage) and HA (Raft storage) modes requires data migration. | `int` | `1` | -| `resources` | Explicit CPU and memory configuration for each OpenBAO replica. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | -| `resources.cpu` | CPU available to each replica. | `quantity` | `""` | -| `resources.memory` | Memory (RAM) available to each replica. | `quantity` | `""` | -| `resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `small` | -| `size` | Persistent Volume Claim size for data storage. | `quantity` | `10Gi` | -| `storageClass` | StorageClass used to store the data. | `string` | `""` | -| `external` | Enable external access from outside the cluster. | `bool` | `false` | +| Name | Description | Type | Value | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ---------- | +| `replicas` | Number of OpenBAO replicas. HA with Raft is automatically enabled when replicas > 1. Switching between standalone (file storage) and HA (Raft storage) modes requires data migration. | `int` | `1` | +| `resources` | Explicit CPU and memory configuration for each OpenBAO replica. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | +| `resources.cpu` | CPU available to each replica. | `quantity` | `""` | +| `resources.memory` | Memory (RAM) available to each replica. | `quantity` | `""` | +| `resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `t1.small` | +| `size` | Persistent Volume Claim size for data storage. | `quantity` | `10Gi` | +| `storageClass` | StorageClass used to store the data. | `string` | `""` | +| `external` | Enable external access from outside the cluster. | `bool` | `false` | ### Application-specific parameters diff --git a/content/en/docs/next/applications/postgres.md b/content/en/docs/next/applications/postgres.md index f5d9a008..4ffa1bd9 100644 --- a/content/en/docs/next/applications/postgres.md +++ b/content/en/docs/next/applications/postgres.md @@ -10,7 +10,7 @@ aliases: @@ -27,35 +27,138 @@ This managed service is controlled by the CloudNativePG operator, ensuring effic ## Operations -{{% alert color="warning" %}} -**Backups: prefer the `BackupClass` flow.** The chart-level `backup.*` values documented below still configure the Barman object store and S3 credentials that backups read from, but the chart-emitted `ScheduledBackup` and the `bootstrap`-based recovery flow have been **superseded** by the Cozystack backups framework: define a `BackupClass` + `CNPG` strategy once, then drive scheduled backups via `Plan` and restores via `RestoreJob`. See [Application Backup and Recovery]({{% ref "/docs/next/applications/backup-and-recovery" %}}) (tenant guide) and [Managed Application Backup Configuration]({{% ref "/docs/next/operations/services/managed-app-backup-configuration" %}}) (admin setup). -{{% /alert %}} +PostgreSQL backups have two layers, and the recommended setup uses both +together rather than picking one: -### How to enable backups +| Layer | What it does | Configured via | +| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | +| **Archive plumbing** (chart, legacy) | Renders `spec.backup.barmanObjectStore` on the cnpg.io Cluster from helm-install onwards. CNPG starts postgres with `archive_command=barman-cloud-wal-archive`, every WAL switch ships to object storage, and any backup driver gets a complete WAL chain to start replay from. Renders only when `backup.enabled=true`, `useSystemBucket=false`, `destinationPath` is non-empty, AND inline-or-external creds are supplied. **Skipped in the platform `useSystemBucket=true` mode** — the CNPG backup driver SSA-patches `barmanObjectStore` onto the live Cluster at first BackupJob time; until that first BackupJob fires, `archive_command` is not active and WAL accumulates on the PVC. Fire an ad-hoc BackupJob immediately after enabling the flag on existing releases. | Legacy: `backup.enabled=true` plus `backup.destinationPath`, `backup.endpointURL`, and either `backup.s3AccessKey`+`backup.s3SecretKey` or `backup.s3CredentialsSecret`. Platform: `backup.enabled=true` plus `backup.useSystemBucket=true` — no S3 fields. | +| **Backup orchestration** (recommended) | Drives ad-hoc and scheduled backups, retention, and restores from `backups.cozystack.io` resources that can span multiple Postgres apps in a tenant. The driver SSA-merges its own `barmanObjectStore` shape over the chart's with `ForceOwnership` (so compression / serverName / target settings flow from the strategy template); chart-managed values cover the same destination so there is no tug-of-war on the live Cluster. | `strategy.backups.cozystack.io/CNPG` + `BackupClass` + `Plan` (recurring) or `BackupJob` (ad-hoc), restores via `RestoreJob` | +| Legacy chart-emitted scheduled backup | The chart can also emit a `cnpg.io/ScheduledBackup` directly. Superseded by the BackupClass + Plan path, kept around for clusters that did not migrate. **Off by default** - rendered only when both `backup.enabled` and `backup.schedule` are non-empty. With `backup.schedule=""` the archive plumbing still runs; only the chart-emitted scheduled backup is silent. | `backup.enabled=true` plus `backup.schedule` (CNPG 6-field cron, e.g. `"0 2 * * * *"`) | -To back up a PostgreSQL application, an external S3-compatible storage is required. +The **canonical setup** depends on whether the cluster ships the platform `cozy-default` BackupClass. -To start regular backups, update the application, setting `backup.enabled` to `true`, and fill in the path and credentials to an `backup.*`: +**Platform-managed flow (recommended for new clusters)** — opt in via `backup.useSystemBucket: true` and reference `cozy-default` from BackupJob/Plan/RestoreJob. The chart leaves S3 coordinates blank; the CNPG driver SSA-patches `barmanObjectStore` from the platform-managed bucket coordinates at first BackupJob time. ```yaml -## @param backup.enabled Enable regular backups -## @param backup.schedule Cron schedule for automated backups +spec: + backup: + enabled: true + useSystemBucket: true # platform projects cozy-backups-creds + driver SSA-patches barmanObjectStore +``` + +**Legacy chart-managed flow** — for clusters that pre-date the platform BackupClass or use a tuned non-default bucket. Provide all S3 coordinates inline (or via `s3CredentialsSecret.name`); `barmanObjectStore` renders from helm-install onwards. + +```yaml +spec: + backup: + enabled: true # archive WAL to object storage + destinationPath: s3://my-bucket/pg-src/ + endpointURL: https://seaweedfs-s3.tenant-foo:8333 + s3CredentialsSecret: + name: pg-src-cnpg-backup-creds + endpointCA: + name: pg-src-cnpg-backup-ca + # backup.schedule intentionally left empty - the BackupClass / Plan + # below drives recurring backups, no chart-emitted ScheduledBackup + # should compete with that schedule. +``` + +paired with a `strategy.backups.cozystack.io/CNPG` + `BackupClass` + `Plan` +in the same tenant. The end-to-end e2e fixture under +[`examples/backups/postgres/`](../../../examples/backups/postgres/) is the +canonical reference (`05-postgres-src.yaml` shows the chart side, +`10-cnpg-strategy.yaml` and `15-backupclass.yaml` show the orchestration +side, `25-backupjob-adhoc.yaml` and `40-restorejob-to-copy.yaml` show +ad-hoc backup and restore). + +> **Why both layers and not one?** WAL archive is a postmaster setting - +> CNPG can swap `archive_command` at runtime via SIGHUP, but any WAL that +> closed before the swap was "archived" by `archive_command=/bin/true` +> and is gone for good. A backup taken from such a cluster is missing +> the WAL its `begin_wal` points at, and recovery later fails with +> `WAL not found`. Letting the chart bootstrap `archive_command` from +> helm-install removes the race. + +### How to enable backups (preferred: BackupClass + Plan) + +End-to-end manifests live under [`examples/backups/postgres/`](../../../examples/backups/postgres/). +Briefly, the moving parts are: + +1. A `strategy.backups.cozystack.io/CNPG` describing the destination bucket + and templating the `barmanObjectStore` (including a Secret reference to + S3 credentials - the credentials never appear on the Postgres CR + `.spec`; see Security note below). +2. A `backups.cozystack.io/BackupClass` that names the strategy and is + selected by an `applicationRef` matching the Postgres app's `Kind`/`Name`. +3. A `backups.cozystack.io/Plan` (recurring) or `BackupJob` (ad-hoc) that + references the BackupClass. The controller materialises a + `Backup` artifact when the cnpg.io Backup completes; restores then + reference that Backup via `RestoreJob`. + +Both in-place restores (overwrite the source app's data) and to-copy +restores (restore into a separate target Postgres app in the same +namespace) are supported via the `RestoreJob.spec.targetApplicationRef` +field. + +> **Security:** With the BackupClass path, S3 credentials live in a +> tenant-readable Secret referenced from the strategy template. The CNPG +> driver forwards that Secret reference into the Postgres app's +> `spec.backup.s3CredentialsSecret` on restore, so access keys never land in +> the Postgres CR `.spec`, etcd object store, or `kubectl get -o yaml` +> output. Prefer this over the chart-managed path whenever possible. + +### How to enable chart-managed scheduled backups (legacy) + +The chart can also emit a `cnpg.io/ScheduledBackup` directly, without a +BackupClass. Superseded by the BackupClass + Plan path above and kept +around for clusters that did not migrate. It does not run by default - +`backup.schedule` defaults to an empty string, which gates the chart's +ScheduledBackup template off. To turn it on, fill in a CNPG 6-field cron +expression: + +```yaml +## @param backup.enabled Enable archive_command + render the chart-managed ScheduledBackup +## @param backup.schedule Cron schedule (CNPG 6-field). Empty means no chart-managed ScheduledBackup ## @param backup.retentionPolicy Retention policy ## @param backup.destinationPath Path to store the backup (i.e. s3://bucket/path/to/folder) ## @param backup.endpointURL S3 Endpoint used to upload data to the cloud ## @param backup.s3AccessKey Access key for S3, used for authentication ## @param backup.s3SecretKey Secret key for S3, used for authentication backup: - enabled: false + enabled: true retentionPolicy: 30d destinationPath: s3://bucket/path/to/folder/ endpointURL: http://minio-gateway-service:9000 - schedule: "0 2 * * * *" + schedule: "0 2 * * * *" # opt in - empty (the default) means no chart-managed schedule s3AccessKey: oobaiRus9pah8PhohL1ThaeTa4UVa7gu s3SecretKey: ju3eum4dekeich9ahM1te8waeGai0oog ``` -### How to recover a backup +### How to recover a backup (preferred: RestoreJob) + +For BackupClass-managed backups, create a `backups.cozystack.io/RestoreJob` +that references the desired `Backup`. See +[`examples/backups/postgres/35-restorejob-in-place.yaml`](../../../examples/backups/postgres/35-restorejob-in-place.yaml) +and +[`examples/backups/postgres/40-restorejob-to-copy.yaml`](../../../examples/backups/postgres/40-restorejob-to-copy.yaml). +On a to-copy restore the controller replaces the target app's +`spec.databases` and `spec.users` with the source-spec snapshot persisted +in `Backup.status.underlyingResources`, so the chart's post-install +init-job does not drop the recovered roles or databases. + +> **e2e coverage:** the CI e2e (`hack/e2e-apps/backup-postgres.bats`) +> exercises the same-namespace to-copy restore (Steps 0-7), which leaves +> the source running and is therefore the deterministic end-to-end signal. +> The cross-tenant variant (target Postgres in a different tenant from +> the source's seaweedfs) stays a manual / dev-cluster exercise — +> reachability is blocked by the per-tenant Cilium egress policy. The +> in-place restore code path is shipped and is covered at the unit level +> by `TestClusterHasRecoveryBootstrap_TerminatingCluster`, +> `TestCNPGBackupWALArchived`, `TestCNPGPurgeNeeded`, and the rest of the +> `internal/backupcontroller/cnpgstrategy_controller_test.go` suite. + +### How to recover a backup (chart-managed bootstrap) CloudNativePG supports point-in-time-recovery. Recovering a backup is done by creating a new database instance and restoring the data in it. @@ -80,30 +183,71 @@ See: - +> `storageClass` is annotated as immutable in the chart schema — see [`docs/storage-immutability.md`](../../../docs/storage-immutability.md) for the contract and which consumers enforce it. + +### TLS for server connections + +CNPG manages the cert chain end-to-end. The operator auto-generates a self-signed CA, signs server, client, and replication leaf certs from it, and rotates them as needed. The chart does not render any cert-manager `Issuer`/`Certificate` objects — that path is mutually exclusive with the operator-managed chain on the CNPG admission webhook. + +What the chart contributes: when TLS is on and `external: true`, the chart sets `spec.certificates.serverAltDNSNames` on the CNPG Cluster CR to inject the external hostname `.<_namespace.host>` into the auto-generated server certificate's SAN list. CNPG's default SAN coverage already includes the three built-in ClusterIP services (`-rw`, `-r`, `-ro`) across the four DNS forms (``, `.`, `..svc`, `..svc.`); only the external hostname needs to be added. + +The tri-state `tls.enabled` controls whether the chart injects `serverAltDNSNames`: + +- `tls.enabled: null` (the default) — TLS posture inherits from `external`. When `external: true`, the chart injects the external hostname into the operator-managed cert. +- `tls.enabled: true` with `external: true` — same effect as the default. +- `tls.enabled: true` with `external: false` — no `serverAltDNSNames` injection is needed (there is no external hostname to add); CNPG's auto-generated cert covers internal services. +- `tls.enabled: false` — the chart skips `serverAltDNSNames` injection. **Note:** CNPG keeps its built-in TLS on the wire regardless of this flag; this toggle only controls whether the external hostname is added to the cert. To force PostgreSQL to drop TLS entirely you would need to set `postgresql.parameters.ssl = "off"` at the CNPG layer, which is out of scope for this flag. + +**Retrieving the CA bundle** for client verification: + +CNPG bundles the CA certificate in every user-credentials Secret it creates under the key `ca.crt`. Retrieve it from the `-credentials` Secret, which is already accessible to tenants via the dashboard RBAC: + +```bash +kubectl --context --namespace \ + get secret -credentials \ + --output jsonpath='{.data.ca\.crt}' | base64 --decode +``` + +**Connecting with full verification** (psql example): + +```bash +psql "host= port=5432 dbname=app user=app \ + sslmode=verify-full sslrootcert=ca.crt" +``` + +For `sslmode=verify-full` to work, the CA bundle retrieved above must be saved to `ca.crt`. Without it, use `sslmode=require` (encrypts but does not verify the server certificate). + ## Parameters ### Common parameters -| Name | Description | Type | Value | -| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | ---------- | ------- | -| `replicas` | Number of Postgres replicas. | `int` | `2` | -| `resources` | Explicit CPU and memory configuration for each PostgreSQL replica. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | -| `resources.cpu` | CPU available to each replica. | `quantity` | `""` | -| `resources.memory` | Memory (RAM) available to each replica. | `quantity` | `""` | -| `resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `micro` | -| `size` | Persistent Volume Claim size available for application data. | `quantity` | `10Gi` | -| `storageClass` | StorageClass used to store the data. | `string` | `""` | -| `external` | Enable external access from outside the cluster. | `bool` | `false` | -| `version` | PostgreSQL major version to deploy | `string` | `v18` | +| Name | Description | Type | Value | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | ---------- | ---------- | +| `replicas` | Number of Postgres replicas. | `int` | `2` | +| `resources` | Explicit CPU and memory configuration for each PostgreSQL replica. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | +| `resources.cpu` | CPU available to each replica. | `quantity` | `""` | +| `resources.memory` | Memory (RAM) available to each replica. | `quantity` | `""` | +| `resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `t1.micro` | +| `size` | Persistent Volume Claim size available for application data. | `quantity` | `10Gi` | +| `storageClass` | StorageClass used to store the data. | `string` | `""` | +| `external` | Enable external access from outside the cluster. | `bool` | `false` | +| `version` | PostgreSQL major version to deploy | `string` | `v18` | + + +### TLS configuration + +| Name | Description | Type | Value | +| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------ | +| `tls` | TLS configuration for server connections. | `object` | `{}` | +| `tls.enabled` | Tri-state switch controlling whether the chart injects the external hostname into the operator-managed CNPG cert via spec.certificates.serverAltDNSNames. When omitted, the chart injects the SAN if `external: true` and skips it otherwise. Set explicitly to `true` to inject regardless of `external` (no-op when `external: false` since there is no external hostname to add). Set to `false` to skip injection. Note that CNPG keeps its built-in TLS on the wire regardless of this flag — this toggle only controls the chart-side SAN injection; to disable PostgreSQL TLS entirely set `postgresql.parameters.ssl = "off"` at the CNPG layer. | `*bool` | `null` | ### 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. Values may be strings or integers; integers are coerced to strings by the template (e.g. both `max_connections: 100` and `max_connections: "100"` are accepted). BLOCKED (enable arbitrary code execution): archive_command, restore_command, ssl_passphrase_command, archive_cleanup_command, recovery_end_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]intOrString` | `{}` | ### Quorum-based synchronous replication @@ -137,26 +281,35 @@ See: ### Backup parameters -| Name | Description | Type | Value | -| ------------------------ | ------------------------------------------------------ | -------- | ----------------------------------- | -| `backup` | Backup configuration. | `object` | `{}` | -| `backup.enabled` | Enable regular backups. | `bool` | `false` | -| `backup.schedule` | Cron schedule for automated backups. | `string` | `0 2 * * * *` | -| `backup.retentionPolicy` | Retention policy (e.g. "30d"). | `string` | `30d` | -| `backup.destinationPath` | Destination path for backups (e.g. s3://bucket/path/). | `string` | `s3://bucket/path/to/folder/` | -| `backup.endpointURL` | S3 endpoint URL for uploads. | `string` | `http://minio-gateway-service:9000` | -| `backup.s3AccessKey` | Access key for S3 authentication. | `string` | `` | -| `backup.s3SecretKey` | Secret key for S3 authentication. | `string` | `` | +| Name | Description | Type | Value | +| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ----------------------------------- | +| `backup` | Backup configuration. | `object` | `{}` | +| `backup.enabled` | Enable regular backups. | `bool` | `false` | +| `backup.useSystemBucket` | Opt-in: when true, the chart-emitted `-s3-creds` Secret is skipped AND `spec.backup.barmanObjectStore` is left UNSET in the chart-rendered Cluster — the cozy-default BackupClass driver SSA-patches the live Cluster with destinationPath/endpointURL/credentials when the first BackupJob runs. Consequence: `archive_command` is NOT active until that first BackupJob fires; WAL accumulates on the PVC in the meantime, so fire an ad-hoc BackupJob immediately after enabling the flag on existing releases. Use together with the platform `cozy-default` BackupClass — tenants do not need to fill `s3AccessKey`/`s3SecretKey` or `destinationPath`/`endpointURL`. The destination path automatically scopes to `s3://cozy-backups///`. | `bool` | `false` | +| `backup.schedule` | Legacy. Cron schedule (CNPG 6-field format) for the chart-emitted ScheduledBackup. Empty means no chart-managed schedule, which is the recommended setup when a `BackupClass` from `backups.cozystack.io` already drives backup orchestration. In the legacy chart-managed flow `spec.backup.barmanObjectStore` is rendered when `backup.enabled=true` AND `useSystemBucket=false` AND `destinationPath` is non-empty AND inline-or-external creds are supplied; in the platform `useSystemBucket=true` flow the chart skips emitting `barmanObjectStore` and the CNPG driver SSA-patches it onto the live Cluster at first BackupJob time. | `string` | `""` | +| `backup.retentionPolicy` | Retention policy (e.g. "30d"). | `string` | `30d` | +| `backup.destinationPath` | DEPRECATED. Per-tenant S3 configuration is superseded by the platform-managed `cozy-default` BackupClass and the `cozy-backups` system bucket. Leave empty for new installations; the BackupClass driver picks up the system-managed coordinates. Kept for in-place upgrade compatibility. | `string` | `s3://bucket/path/to/folder/` | +| `backup.endpointURL` | DEPRECATED. See `destinationPath`. | `string` | `http://minio-gateway-service:9000` | +| `backup.s3AccessKey` | DEPRECATED. Tenants no longer supply S3 keys; the system Bucket Secret is projected into the tenant namespace by the backup controller. Ignored when `s3CredentialsSecret.name` is set or `useSystemBucket` is true. The chart skips materialising `-s3-creds` whenever this field is empty so a default install does not leak placeholder credentials into the tenant namespace. | `string` | `""` | +| `backup.s3SecretKey` | DEPRECATED. See `s3AccessKey`. | `string` | `""` | +| `backup.s3CredentialsSecret` | DEPRECATED. Pre-existing Secret with S3 credentials. Use the platform-managed `cozy-default` BackupClass instead. When set, the chart references this Secret directly (legacy chart-managed flow). The CNPG backup driver writes this field on restore so credentials never land in the CR `.spec`. | `object` | `{}` | +| `backup.s3CredentialsSecret.name` | Name of the Secret in the application namespace. Empty means the chart materialises `-s3-creds` from `s3AccessKey`/`s3SecretKey`. | `string` | `""` | +| `backup.s3CredentialsSecret.accessKeyIDKey` | Key in the Secret holding the access key ID. Defaults to `AWS_ACCESS_KEY_ID`. | `string` | `""` | +| `backup.s3CredentialsSecret.secretAccessKeyKey` | Key in the Secret holding the secret access key. Defaults to `AWS_SECRET_ACCESS_KEY`. | `string` | `""` | +| `backup.endpointCA` | DEPRECATED. Pre-existing Secret with the CA bundle Barman should trust when reaching a self-signed S3 endpoint. Used for both backup and bootstrap recovery in the legacy chart-managed flow. | `object` | `{}` | +| `backup.endpointCA.name` | Name of the Secret in the application namespace. Empty means no endpointCA is emitted (Barman uses the system trust store). | `string` | `""` | +| `backup.endpointCA.key` | Key within the Secret containing the CA bundle. Defaults to `ca.crt`. | `string` | `""` | ### 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 @@ -175,15 +328,9 @@ resources: `resourcesPreset` sets named CPU and memory configurations for each replica. This setting is ignored if the corresponding `resources` value is set. -| Preset name | CPU | memory | -|-------------|--------|---------| -| `nano` | `250m` | `128Mi` | -| `micro` | `500m` | `256Mi` | -| `small` | `1` | `512Mi` | -| `medium` | `1` | `1Gi` | -| `large` | `2` | `2Gi` | -| `xlarge` | `4` | `4Gi` | -| `2xlarge` | `8` | `8Gi` | +Presets follow a cloud-style `.` naming convention. Five series cover the full CPU-to-memory ratio range (`t1` 1:0.5, `c1` 1:1, `s1` 1:2, `u1` 1:4, `m1` 1:8) and each series ships eight sizes (`nano` through `4xlarge`). The legacy flat names (`nano`, `micro`, `small`, `medium`, `large`, `xlarge`, `2xlarge`) remain accepted as deprecated aliases of their 1:1 instance-type equivalents. + +See [`docs/operations/resource-presets.md`](../../../docs/operations/resource-presets.md) for the full size matrix and the legacy-to-instance-type mapping. ### users diff --git a/content/en/docs/next/applications/qdrant.md b/content/en/docs/next/applications/qdrant.md index 17060afb..11934039 100644 --- a/content/en/docs/next/applications/qdrant.md +++ b/content/en/docs/next/applications/qdrant.md @@ -7,7 +7,7 @@ weight: 50 @@ -20,20 +20,30 @@ Service deploys Qdrant as a StatefulSet with automatic cluster mode when multipl - Docs: https://qdrant.tech/documentation/ - GitHub: https://github.com/qdrant/qdrant +> `storageClass` is annotated as immutable in the chart schema — see [`docs/storage-immutability.md`](../../../docs/storage-immutability.md) for the contract and which consumers enforce it. + ## Parameters ### Common parameters -| Name | Description | Type | Value | -| ------------------ | -------------------------------------------------------------------------------------------------------------------------------- | ---------- | ------- | -| `replicas` | Number of Qdrant replicas. Cluster mode is automatically enabled when replicas > 1. | `int` | `1` | -| `resources` | Explicit CPU and memory configuration for each Qdrant replica. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | -| `resources.cpu` | CPU available to each replica. | `quantity` | `""` | -| `resources.memory` | Memory (RAM) available to each replica. | `quantity` | `""` | -| `resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `small` | -| `size` | Persistent Volume Claim size available for vector data storage. | `quantity` | `10Gi` | -| `storageClass` | StorageClass used to store the data. | `string` | `""` | -| `external` | Enable external access from outside the cluster. | `bool` | `false` | +| Name | Description | Type | Value | +| ------------------ | -------------------------------------------------------------------------------------------------------------------------------- | ---------- | ---------- | +| `replicas` | Number of Qdrant replicas. Cluster mode is automatically enabled when replicas > 1. | `int` | `1` | +| `resources` | Explicit CPU and memory configuration for each Qdrant replica. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | +| `resources.cpu` | CPU available to each replica. | `quantity` | `""` | +| `resources.memory` | Memory (RAM) available to each replica. | `quantity` | `""` | +| `resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `t1.small` | +| `size` | Persistent Volume Claim size available for vector data storage. | `quantity` | `10Gi` | +| `storageClass` | StorageClass used to store the data. | `string` | `""` | +| `external` | Enable external access from outside the cluster. | `bool` | `false` | + + +### TLS parameters + +| Name | Description | Type | Value | +| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ------ | +| `tls` | TLS configuration. When omitted, the effective TLS state follows the value of `external`. | `object` | `{}` | +| `tls.enabled` | Enable TLS. When unset, inherits the value of `external` (TLS is on when external access is enabled). Set explicitly to `true` or `false` to override. | `*bool` | `null` | ## Parameter examples and reference @@ -52,12 +62,6 @@ resources: `resourcesPreset` sets named CPU and memory configurations for each replica. This setting is ignored if the corresponding `resources` value is set. -| Preset name | CPU | memory | -|-------------|--------|---------| -| `nano` | `250m` | `128Mi` | -| `micro` | `500m` | `256Mi` | -| `small` | `1` | `512Mi` | -| `medium` | `1` | `1Gi` | -| `large` | `2` | `2Gi` | -| `xlarge` | `4` | `4Gi` | -| `2xlarge` | `8` | `8Gi` | +Presets follow a cloud-style `.` naming convention. Five series cover the full CPU-to-memory ratio range (`t1` 1:0.5, `c1` 1:1, `s1` 1:2, `u1` 1:4, `m1` 1:8) and each series ships eight sizes (`nano` through `4xlarge`). The legacy flat names (`nano`, `micro`, `small`, `medium`, `large`, `xlarge`, `2xlarge`) remain accepted as deprecated aliases of their 1:1 instance-type equivalents. + +See [`docs/operations/resource-presets.md`](../../../docs/operations/resource-presets.md) for the full size matrix and the legacy-to-instance-type mapping. diff --git a/content/en/docs/next/applications/rabbitmq.md b/content/en/docs/next/applications/rabbitmq.md index 2326ba08..0ad22d35 100644 --- a/content/en/docs/next/applications/rabbitmq.md +++ b/content/en/docs/next/applications/rabbitmq.md @@ -10,7 +10,7 @@ aliases: @@ -23,21 +23,23 @@ The service utilizes official RabbitMQ operator. This ensures the reliability an - Github: https://github.com/rabbitmq/cluster-operator/ - Docs: https://www.rabbitmq.com/kubernetes/operator/operator-overview.html +> `storageClass` is annotated as immutable in the chart schema — see [`docs/storage-immutability.md`](../../../docs/storage-immutability.md) for the contract and which consumers enforce it. + ## Parameters ### Common parameters -| Name | Description | Type | Value | -| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | ---------- | ------- | -| `replicas` | Number of RabbitMQ replicas. | `int` | `3` | -| `resources` | Explicit CPU and memory configuration for each RabbitMQ replica. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | -| `resources.cpu` | CPU available to each replica. | `quantity` | `""` | -| `resources.memory` | Memory (RAM) available to each replica. | `quantity` | `""` | -| `resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `nano` | -| `size` | Persistent Volume Claim size available for application data. | `quantity` | `10Gi` | -| `storageClass` | StorageClass used to store the data. | `string` | `""` | -| `external` | Enable external access from outside the cluster. | `bool` | `false` | -| `version` | RabbitMQ major.minor version to deploy | `string` | `v4.2` | +| Name | Description | Type | Value | +| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | ---------- | --------- | +| `replicas` | Number of RabbitMQ replicas. | `int` | `3` | +| `resources` | Explicit CPU and memory configuration for each RabbitMQ replica. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | +| `resources.cpu` | CPU available to each replica. | `quantity` | `""` | +| `resources.memory` | Memory (RAM) available to each replica. | `quantity` | `""` | +| `resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `t1.nano` | +| `size` | Persistent Volume Claim size available for application data. | `quantity` | `10Gi` | +| `storageClass` | StorageClass used to store the data. | `string` | `""` | +| `external` | Enable external access from outside the cluster. | `bool` | `false` | +| `version` | RabbitMQ major.minor version to deploy | `string` | `v4.2` | ### Application-specific parameters diff --git a/content/en/docs/next/applications/redis.md b/content/en/docs/next/applications/redis.md index 855ca38d..3bbb8290 100644 --- a/content/en/docs/next/applications/redis.md +++ b/content/en/docs/next/applications/redis.md @@ -10,7 +10,7 @@ aliases: @@ -23,21 +23,23 @@ Service utilizes the Spotahome Redis Operator for efficient management and orche - Docs: https://redis.io/docs/ - GitHub: https://github.com/spotahome/redis-operator +> `storageClass` is annotated as immutable in the chart schema — see [`docs/storage-immutability.md`](../../../docs/storage-immutability.md) for the contract and which consumers enforce it. + ## Parameters ### Common parameters -| Name | Description | Type | Value | -| ------------------ | ------------------------------------------------------------------------------------------------------------------------------- | ---------- | ------- | -| `replicas` | Number of Redis replicas. | `int` | `2` | -| `resources` | Explicit CPU and memory configuration for each Redis replica. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | -| `resources.cpu` | CPU available to each replica. | `quantity` | `""` | -| `resources.memory` | Memory (RAM) available to each replica. | `quantity` | `""` | -| `resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `nano` | -| `size` | Persistent Volume Claim size available for application data. | `quantity` | `1Gi` | -| `storageClass` | StorageClass used to store the data. | `string` | `""` | -| `external` | Enable external access from outside the cluster. | `bool` | `false` | -| `version` | Redis major version to deploy | `string` | `v8` | +| Name | Description | Type | Value | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------- | ---------- | --------- | +| `replicas` | Number of Redis replicas. | `int` | `2` | +| `resources` | Explicit CPU and memory configuration for each Redis replica. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | +| `resources.cpu` | CPU available to each replica. | `quantity` | `""` | +| `resources.memory` | Memory (RAM) available to each replica. | `quantity` | `""` | +| `resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `t1.nano` | +| `size` | Persistent Volume Claim size available for application data. | `quantity` | `1Gi` | +| `storageClass` | StorageClass used to store the data. | `string` | `""` | +| `external` | Enable external access from outside the cluster. | `bool` | `false` | +| `version` | Redis major version to deploy | `string` | `v8` | ### Application-specific parameters @@ -63,12 +65,6 @@ resources: `resourcesPreset` sets named CPU and memory configurations for each replica. This setting is ignored if the corresponding `resources` value is set. -| Preset name | CPU | memory | -|-------------|--------|---------| -| `nano` | `250m` | `128Mi` | -| `micro` | `500m` | `256Mi` | -| `small` | `1` | `512Mi` | -| `medium` | `1` | `1Gi` | -| `large` | `2` | `2Gi` | -| `xlarge` | `4` | `4Gi` | -| `2xlarge` | `8` | `8Gi` | +Presets follow a cloud-style `.` naming convention. Five series cover the full CPU-to-memory ratio range (`t1` 1:0.5, `c1` 1:1, `s1` 1:2, `u1` 1:4, `m1` 1:8) and each series ships eight sizes (`nano` through `4xlarge`). The legacy flat names (`nano`, `micro`, `small`, `medium`, `large`, `xlarge`, `2xlarge`) remain accepted as deprecated aliases of their 1:1 instance-type equivalents. + +See [`docs/operations/resource-presets.md`](../../../docs/operations/resource-presets.md) for the full size matrix and the legacy-to-instance-type mapping. diff --git a/content/en/docs/next/applications/tenant.md b/content/en/docs/next/applications/tenant.md index e8b69af1..41f3a58e 100644 --- a/content/en/docs/next/applications/tenant.md +++ b/content/en/docs/next/applications/tenant.md @@ -10,7 +10,7 @@ aliases: @@ -88,15 +88,16 @@ tenant-u1 ### Common parameters -| Name | Description | Type | Value | -| ----------------- | -------------------------------------------------------------------------------------------------------------------------- | --------------------- | ------- | -| `host` | The hostname used to access tenant services (defaults to using the tenant name as a subdomain for its parent tenant host). | `string` | `""` | -| `etcd` | Deploy own Etcd cluster. | `bool` | `false` | -| `monitoring` | Deploy own Monitoring Stack. | `bool` | `false` | -| `ingress` | Deploy own Ingress Controller. | `bool` | `false` | -| `seaweedfs` | Deploy own SeaweedFS. | `bool` | `false` | -| `schedulingClass` | The name of a SchedulingClass CR to apply scheduling constraints for this tenant's workloads. | `string` | `""` | -| `resourceQuotas` | Define resource quotas for the tenant. | `map[string]quantity` | `{}` | +| Name | Description | Type | Value | +| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | ------- | +| `host` | The hostname used to access tenant services (defaults to using the tenant name as a subdomain for its parent tenant host). | `string` | `""` | +| `etcd` | Deploy own Etcd cluster. | `bool` | `false` | +| `monitoring` | Deploy own Monitoring Stack. | `bool` | `false` | +| `ingress` | Deploy own Ingress Controller. | `bool` | `false` | +| `gateway` | Deploy own Gateway API Gateway (backed by Cilium Gateway API controller). When unset (the default), the chart auto-enables the Gateway for tenants whose apex is derived from the parent (i.e. `host` is empty), and leaves it off for tenants with a custom non-derived apex. Set to `true` or `false` explicitly to override that auto-behaviour. Note: leave the key absent (do not write `gateway: null`) — the chart distinguishes "unset" via missing-key, not via null value, to satisfy the JSON schema generated from this comment. | `bool` | `false` | +| `seaweedfs` | Deploy own SeaweedFS. | `bool` | `false` | +| `schedulingClass` | The name of a SchedulingClass CR to apply scheduling constraints for this tenant's workloads. | `string` | `""` | +| `resourceQuotas` | Define resource quotas for the tenant. | `map[string]quantity` | `{}` | ## Configuration diff --git a/content/en/docs/next/kubernetes/_index.md b/content/en/docs/next/kubernetes/_index.md index 3f0d973e..a9e0a589 100644 --- a/content/en/docs/next/kubernetes/_index.md +++ b/content/en/docs/next/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,12 @@ 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`** (v1.4): The `nodeGroups[name].ephemeralStorage` field has been renamed to `nodeGroups[name].diskSize` to better reflect its purpose (persistent disk for kubelet and containerd data). 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 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. + +> The top-level `storageClass` field is annotated as immutable in the chart schema — see [`docs/storage-immutability.md`](../../../docs/storage-immutability.md) for the contract and which consumers enforce it. The per-node-group `nodeGroups[name].storageClass` field is intentionally **not** annotated immutable: it is optional and undefaulted, so a strict `self == oldSelf` rule would block any future attempt to set it on an existing node group. + ## Parameters ### Common Parameters @@ -105,85 +114,101 @@ 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). NOTE: deliberately not marked immutable — the field is optional and undefaulted, so a strict `self == oldSelf` rule would block any future attempt to set it on an existing node group. | `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 -| Name | Description | Type | Value | -| --------------------------------------------- | --------------------------------------------------------------------------- | ---------- | --------- | -| `addons` | Cluster addons configuration. | `object` | `{}` | -| `addons.certManager` | Cert-manager addon. | `object` | `{}` | -| `addons.certManager.enabled` | Enable cert-manager. | `bool` | `false` | -| `addons.certManager.valuesOverride` | Custom Helm values overrides. | `object` | `{}` | -| `addons.cilium` | Cilium CNI plugin. | `object` | `{}` | -| `addons.cilium.valuesOverride` | Custom Helm values overrides. | `object` | `{}` | -| `addons.gatewayAPI` | Gateway API addon. | `object` | `{}` | -| `addons.gatewayAPI.enabled` | Enable Gateway API. | `bool` | `false` | -| `addons.ingressNginx` | Ingress-NGINX controller. | `object` | `{}` | -| `addons.ingressNginx.enabled` | Enable the controller (requires nodes labeled `ingress-nginx`). | `bool` | `false` | -| `addons.ingressNginx.exposeMethod` | Method to expose the controller. Allowed values: `Proxied`, `LoadBalancer`. | `string` | `Proxied` | -| `addons.ingressNginx.hosts` | Domains routed to this tenant cluster when `exposeMethod` is `Proxied`. | `[]string` | `[]` | -| `addons.ingressNginx.valuesOverride` | Custom Helm values overrides. | `object` | `{}` | -| `addons.gpuOperator` | NVIDIA GPU Operator. | `object` | `{}` | -| `addons.gpuOperator.enabled` | Enable GPU Operator. | `bool` | `false` | -| `addons.gpuOperator.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` | `{}` | -| `addons.monitoringAgents` | Monitoring agents. | `object` | `{}` | -| `addons.monitoringAgents.enabled` | Enable monitoring agents. | `bool` | `false` | -| `addons.monitoringAgents.valuesOverride` | Custom Helm values overrides. | `object` | `{}` | -| `addons.verticalPodAutoscaler` | Vertical Pod Autoscaler. | `object` | `{}` | -| `addons.verticalPodAutoscaler.valuesOverride` | Custom Helm values overrides. | `object` | `{}` | -| `addons.velero` | Velero backup/restore addon. | `object` | `{}` | -| `addons.velero.enabled` | Enable Velero. | `bool` | `false` | -| `addons.velero.valuesOverride` | Custom Helm values overrides. | `object` | `{}` | -| `addons.coredns` | CoreDNS addon. | `object` | `{}` | -| `addons.coredns.valuesOverride` | Custom Helm values overrides. | `object` | `{}` | +| Name | Description | Type | Value | +| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- | --------- | +| `addons` | Cluster addons configuration. | `object` | `{}` | +| `addons.certManager` | Cert-manager addon. | `object` | `{}` | +| `addons.certManager.enabled` | Enable cert-manager. | `bool` | `false` | +| `addons.certManager.valuesOverride` | Custom Helm values overrides. | `object` | `{}` | +| `addons.cilium` | Cilium CNI plugin. | `object` | `{}` | +| `addons.cilium.valuesOverride` | Custom Helm values overrides. | `object` | `{}` | +| `addons.gatewayAPI` | Gateway API addon. | `object` | `{}` | +| `addons.gatewayAPI.enabled` | Enable Gateway API. | `bool` | `false` | +| `addons.ingressNginx` | Ingress-NGINX controller. | `object` | `{}` | +| `addons.ingressNginx.enabled` | Enable the controller (requires nodes labeled `ingress-nginx`). | `bool` | `false` | +| `addons.ingressNginx.exposeMethod` | Method to expose the controller. Allowed values: `Proxied`, `LoadBalancer`. | `string` | `Proxied` | +| `addons.ingressNginx.hosts` | Domains routed to this tenant cluster when `exposeMethod` is `Proxied`. | `[]string` | `[]` | +| `addons.ingressNginx.valuesOverride` | Custom Helm values overrides. | `object` | `{}` | +| `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` | `{}` | +| `addons.monitoringAgents` | Monitoring agents. | `object` | `{}` | +| `addons.monitoringAgents.enabled` | Enable monitoring agents. | `bool` | `false` | +| `addons.monitoringAgents.valuesOverride` | Custom Helm values overrides. | `object` | `{}` | +| `addons.verticalPodAutoscaler` | Vertical Pod Autoscaler. | `object` | `{}` | +| `addons.verticalPodAutoscaler.valuesOverride` | Custom Helm values overrides. | `object` | `{}` | +| `addons.velero` | Velero backup/restore addon. | `object` | `{}` | +| `addons.velero.enabled` | Enable Velero. | `bool` | `false` | +| `addons.velero.valuesOverride` | Custom Helm values overrides. | `object` | `{}` | +| `addons.coredns` | CoreDNS addon. | `object` | `{}` | +| `addons.coredns.valuesOverride` | Custom Helm values overrides. | `object` | `{}` | +| `addons.ouroboros` | Hairpin-NAT fix for ingress-nginx with PROXY-protocol. | `object` | `{}` | +| `addons.ouroboros.enabled` | Enable ouroboros. Requires addons.ingressNginx.enabled (chart-render fail otherwise). Only useful when PROXY-protocol is wired on the tenant ingress-nginx via valuesOverride. | `bool` | `false` | +| `addons.ouroboros.valuesOverride` | Custom Helm values overrides. Operator-key wins over cozystack defaults. | `object` | `{}` | ### 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` | `c1.medium` | +| `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` | `t1.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` | `t1.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` | `t1.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 @@ -202,70 +227,142 @@ resources: `resourcesPreset` sets named CPU and memory configurations for each replica. This setting is ignored if the corresponding `resources` value is set. -| Preset name | CPU | memory | -|-------------|--------|---------| -| `nano` | `250m` | `128Mi` | -| `micro` | `500m` | `256Mi` | -| `small` | `1` | `512Mi` | -| `medium` | `1` | `1Gi` | -| `large` | `2` | `2Gi` | -| `xlarge` | `4` | `4Gi` | -| `2xlarge` | `8` | `8Gi` | +Presets follow a cloud-style `.` naming convention. Five series cover the full CPU-to-memory ratio range (`t1` 1:0.5, `c1` 1:1, `s1` 1:2, `u1` 1:4, `m1` 1:8) and each series ships eight sizes (`nano` through `4xlarge`). The legacy flat names (`nano`, `micro`, `small`, `medium`, `large`, `xlarge`, `2xlarge`) remain accepted as deprecated aliases of their 1:1 instance-type equivalents. + +See [`docs/operations/resource-presets.md`](../../../docs/operations/resource-presets.md) for the full size matrix and the legacy-to-instance-type mapping. ### instanceType Resources The following instanceType resources are provided by Cozystack: -| Name | vCPUs | Memory | -|---------------|-------|--------| -| `cx1.2xlarge` | 8 | 16Gi | -| `cx1.4xlarge` | 16 | 32Gi | -| `cx1.8xlarge` | 32 | 64Gi | -| `cx1.large` | 2 | 4Gi | -| `cx1.medium` | 1 | 2Gi | -| `cx1.xlarge` | 4 | 8Gi | -| `gn1.2xlarge` | 8 | 32Gi | -| `gn1.4xlarge` | 16 | 64Gi | -| `gn1.8xlarge` | 32 | 128Gi | -| `gn1.xlarge` | 4 | 16Gi | -| `m1.2xlarge` | 8 | 64Gi | -| `m1.4xlarge` | 16 | 128Gi | -| `m1.8xlarge` | 32 | 256Gi | -| `m1.large` | 2 | 16Gi | -| `m1.xlarge` | 4 | 32Gi | -| `n1.2xlarge` | 16 | 32Gi | -| `n1.4xlarge` | 32 | 64Gi | -| `n1.8xlarge` | 64 | 128Gi | -| `n1.large` | 4 | 8Gi | -| `n1.medium` | 4 | 4Gi | -| `n1.xlarge` | 8 | 16Gi | -| `o1.2xlarge` | 8 | 32Gi | -| `o1.4xlarge` | 16 | 64Gi | -| `o1.8xlarge` | 32 | 128Gi | -| `o1.large` | 2 | 8Gi | -| `o1.medium` | 1 | 4Gi | -| `o1.micro` | 1 | 1Gi | -| `o1.nano` | 1 | 512Mi | -| `o1.small` | 1 | 2Gi | -| `o1.xlarge` | 4 | 16Gi | -| `rt1.2xlarge` | 8 | 32Gi | -| `rt1.4xlarge` | 16 | 64Gi | -| `rt1.8xlarge` | 32 | 128Gi | -| `rt1.large` | 2 | 8Gi | -| `rt1.medium` | 1 | 4Gi | -| `rt1.micro` | 1 | 1Gi | -| `rt1.small` | 1 | 2Gi | -| `rt1.xlarge` | 4 | 16Gi | -| `u1.2xlarge` | 8 | 32Gi | -| `u1.2xmedium` | 2 | 4Gi | -| `u1.4xlarge` | 16 | 64Gi | -| `u1.8xlarge` | 32 | 128Gi | -| `u1.large` | 2 | 8Gi | -| `u1.medium` | 1 | 4Gi | -| `u1.micro` | 1 | 1Gi | -| `u1.nano` | 1 | 512Mi | -| `u1.small` | 1 | 2Gi | -| `u1.xlarge` | 4 | 16Gi | +| Name | vCPUs | Memory | +|------------------|-------|--------| +| `cx1.2xlarge` | 8 | 16Gi | +| `cx1.2xlarge1gi` | 8 | 16Gi | +| `cx1.4xlarge` | 16 | 32Gi | +| `cx1.4xlarge1gi` | 16 | 32Gi | +| `cx1.8xlarge` | 32 | 64Gi | +| `cx1.8xlarge1gi` | 32 | 64Gi | +| `cx1.large` | 2 | 4Gi | +| `cx1.large1gi` | 2 | 4Gi | +| `cx1.medium` | 1 | 2Gi | +| `cx1.medium1gi` | 1 | 2Gi | +| `cx1.xlarge` | 4 | 8Gi | +| `cx1.xlarge1gi` | 4 | 8Gi | +| `d1.2xlarge` | 8 | 32Gi | +| `d1.2xmedium` | 2 | 4Gi | +| `d1.4xlarge` | 16 | 64Gi | +| `d1.8xlarge` | 32 | 128Gi | +| `d1.large` | 2 | 8Gi | +| `d1.medium` | 1 | 4Gi | +| `d1.micro` | 1 | 1Gi | +| `d1.nano` | 1 | 512Mi | +| `d1.small` | 1 | 2Gi | +| `d1.xlarge` | 4 | 16Gi | +| `gn1.2xlarge` | 8 | 32Gi | +| `gn1.4xlarge` | 16 | 64Gi | +| `gn1.8xlarge` | 32 | 128Gi | +| `gn1.xlarge` | 4 | 16Gi | +| `m1.2xlarge` | 8 | 64Gi | +| `m1.2xlarge1gi` | 8 | 64Gi | +| `m1.4xlarge` | 16 | 128Gi | +| `m1.4xlarge1gi` | 16 | 128Gi | +| `m1.8xlarge` | 32 | 256Gi | +| `m1.8xlarge1gi` | 32 | 256Gi | +| `m1.large` | 2 | 16Gi | +| `m1.large1gi` | 2 | 16Gi | +| `m1.xlarge` | 4 | 32Gi | +| `m1.xlarge1gi` | 4 | 32Gi | +| `n1.2xlarge` | 16 | 32Gi | +| `n1.4xlarge` | 32 | 64Gi | +| `n1.8xlarge` | 64 | 128Gi | +| `n1.large` | 4 | 8Gi | +| `n1.medium` | 4 | 4Gi | +| `n1.xlarge` | 8 | 16Gi | +| `o1.2xlarge` | 8 | 32Gi | +| `o1.4xlarge` | 16 | 64Gi | +| `o1.8xlarge` | 32 | 128Gi | +| `o1.large` | 2 | 8Gi | +| `o1.medium` | 1 | 4Gi | +| `o1.micro` | 1 | 1Gi | +| `o1.nano` | 1 | 512Mi | +| `o1.small` | 1 | 2Gi | +| `o1.xlarge` | 4 | 16Gi | +| `rt1.2xlarge` | 8 | 32Gi | +| `rt1.4xlarge` | 16 | 64Gi | +| `rt1.8xlarge` | 32 | 128Gi | +| `rt1.large` | 2 | 8Gi | +| `rt1.medium` | 1 | 4Gi | +| `rt1.micro` | 1 | 1Gi | +| `rt1.small` | 1 | 2Gi | +| `rt1.xlarge` | 4 | 16Gi | +| `u1.2xlarge` | 8 | 32Gi | +| `u1.2xmedium` | 2 | 4Gi | +| `u1.4xlarge` | 16 | 64Gi | +| `u1.8xlarge` | 32 | 128Gi | +| `u1.large` | 2 | 8Gi | +| `u1.medium` | 1 | 4Gi | +| `u1.micro` | 1 | 1Gi | +| `u1.nano` | 1 | 512Mi | +| `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 diff --git a/content/en/docs/next/networking/http-cache.md b/content/en/docs/next/networking/http-cache.md index 326c981b..f0868786 100644 --- a/content/en/docs/next/networking/http-cache.md +++ b/content/en/docs/next/networking/http-cache.md @@ -11,7 +11,7 @@ aliases: @@ -71,6 +71,8 @@ The deployment architecture is illustrated in the diagram below: - VTS module shows wrong upstream response time, [github.com/vozlt/nginx-module-vts#198](https://github.com/vozlt/nginx-module-vts/issues/198) +> `storageClass` is annotated as immutable in the chart schema — see [`docs/storage-immutability.md`](../../../docs/storage-immutability.md) for the contract and which consumers enforce it. + ## Parameters ### Common parameters @@ -91,26 +93,26 @@ The deployment architecture is illustrated in the diagram below: ### HAProxy parameters -| Name | Description | Type | Value | -| -------------------------- | -------------------------------------------------------------------------------------------------------- | ---------- | ------ | -| `haproxy` | HAProxy configuration. | `object` | `{}` | -| `haproxy.replicas` | Number of HAProxy replicas. | `int` | `2` | -| `haproxy.resources` | Explicit CPU and memory configuration. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | -| `haproxy.resources.cpu` | CPU available to each replica. | `quantity` | `""` | -| `haproxy.resources.memory` | Memory (RAM) available to each replica. | `quantity` | `""` | -| `haproxy.resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `nano` | +| Name | Description | Type | Value | +| -------------------------- | -------------------------------------------------------------------------------------------------------- | ---------- | --------- | +| `haproxy` | HAProxy configuration. | `object` | `{}` | +| `haproxy.replicas` | Number of HAProxy replicas. | `int` | `2` | +| `haproxy.resources` | Explicit CPU and memory configuration. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | +| `haproxy.resources.cpu` | CPU available to each replica. | `quantity` | `""` | +| `haproxy.resources.memory` | Memory (RAM) available to each replica. | `quantity` | `""` | +| `haproxy.resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `t1.nano` | ### Nginx parameters -| Name | Description | Type | Value | -| ------------------------ | -------------------------------------------------------------------------------------------------------- | ---------- | ------ | -| `nginx` | Nginx configuration. | `object` | `{}` | -| `nginx.replicas` | Number of Nginx replicas. | `int` | `2` | -| `nginx.resources` | Explicit CPU and memory configuration. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | -| `nginx.resources.cpu` | CPU available to each replica. | `quantity` | `""` | -| `nginx.resources.memory` | Memory (RAM) available to each replica. | `quantity` | `""` | -| `nginx.resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `nano` | +| Name | Description | Type | Value | +| ------------------------ | -------------------------------------------------------------------------------------------------------- | ---------- | --------- | +| `nginx` | Nginx configuration. | `object` | `{}` | +| `nginx.replicas` | Number of Nginx replicas. | `int` | `2` | +| `nginx.resources` | Explicit CPU and memory configuration. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | +| `nginx.resources.cpu` | CPU available to each replica. | `quantity` | `""` | +| `nginx.resources.memory` | Memory (RAM) available to each replica. | `quantity` | `""` | +| `nginx.resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `t1.nano` | ## Parameter examples and reference diff --git a/content/en/docs/next/networking/tcp-balancer.md b/content/en/docs/next/networking/tcp-balancer.md index bbc47b50..699af27d 100644 --- a/content/en/docs/next/networking/tcp-balancer.md +++ b/content/en/docs/next/networking/tcp-balancer.md @@ -11,7 +11,7 @@ aliases: @@ -27,14 +27,14 @@ Managed TCP Load Balancer Service efficiently utilizes HAProxy for load balancin ### Common parameters -| Name | Description | Type | Value | -| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ------- | -| `replicas` | Number of HAProxy replicas. | `int` | `2` | -| `resources` | Explicit CPU and memory configuration for each TCP Balancer replica. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | -| `resources.cpu` | CPU available to each replica. | `quantity` | `""` | -| `resources.memory` | Memory (RAM) available to each replica. | `quantity` | `""` | -| `resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `nano` | -| `external` | Enable external access from outside the cluster. | `bool` | `false` | +| Name | Description | Type | Value | +| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | ---------- | --------- | +| `replicas` | Number of HAProxy replicas. | `int` | `2` | +| `resources` | Explicit CPU and memory configuration for each TCP Balancer replica. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | +| `resources.cpu` | CPU available to each replica. | `quantity` | `""` | +| `resources.memory` | Memory (RAM) available to each replica. | `quantity` | `""` | +| `resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `t1.nano` | +| `external` | Enable external access from outside the cluster. | `bool` | `false` | ### Application-specific parameters @@ -67,12 +67,6 @@ resources: `resourcesPreset` sets named CPU and memory configurations for each replica. This setting is ignored if the corresponding `resources` value is set. -| Preset name | CPU | memory | -|-------------|--------|---------| -| `nano` | `250m` | `128Mi` | -| `micro` | `500m` | `256Mi` | -| `small` | `1` | `512Mi` | -| `medium` | `1` | `1Gi` | -| `large` | `2` | `2Gi` | -| `xlarge` | `4` | `4Gi` | -| `2xlarge` | `8` | `8Gi` | +Presets follow a cloud-style `.` naming convention. Five series cover the full CPU-to-memory ratio range (`t1` 1:0.5, `c1` 1:1, `s1` 1:2, `u1` 1:4, `m1` 1:8) and each series ships eight sizes (`nano` through `4xlarge`). The legacy flat names (`nano`, `micro`, `small`, `medium`, `large`, `xlarge`, `2xlarge`) remain accepted as deprecated aliases of their 1:1 instance-type equivalents. + +See [`docs/operations/resource-presets.md`](../../../docs/operations/resource-presets.md) for the full size matrix and the legacy-to-instance-type mapping. diff --git a/content/en/docs/next/networking/vpc.md b/content/en/docs/next/networking/vpc.md index 79d2ef19..5a3448e4 100644 --- a/content/en/docs/next/networking/vpc.md +++ b/content/en/docs/next/networking/vpc.md @@ -11,7 +11,7 @@ aliases: diff --git a/content/en/docs/next/networking/vpn.md b/content/en/docs/next/networking/vpn.md index 4ed8ab40..e4ef2cd5 100644 --- a/content/en/docs/next/networking/vpn.md +++ b/content/en/docs/next/networking/vpn.md @@ -11,7 +11,7 @@ aliases: @@ -34,14 +34,14 @@ Furthermore, Shadowbox is compatible with standard Shadowsocks clients, providin ### Common parameters -| Name | Description | Type | Value | -| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | ---------- | ------- | -| `replicas` | Number of VPN server replicas. | `int` | `2` | -| `resources` | Explicit CPU and memory configuration for each VPN server replica. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | -| `resources.cpu` | CPU available to each replica. | `quantity` | `""` | -| `resources.memory` | Memory (RAM) available to each replica. | `quantity` | `""` | -| `resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `nano` | -| `external` | Enable external access from outside the cluster. | `bool` | `false` | +| Name | Description | Type | Value | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | ---------- | --------- | +| `replicas` | Number of VPN server replicas. | `int` | `2` | +| `resources` | Explicit CPU and memory configuration for each VPN server replica. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | +| `resources.cpu` | CPU available to each replica. | `quantity` | `""` | +| `resources.memory` | Memory (RAM) available to each replica. | `quantity` | `""` | +| `resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `t1.nano` | +| `external` | Enable external access from outside the cluster. | `bool` | `false` | ### Application-specific parameters @@ -70,15 +70,9 @@ resources: `resourcesPreset` sets named CPU and memory configurations for each replica. This setting is ignored if the corresponding `resources` value is set. -| Preset name | CPU | memory | -|-------------|--------|---------| -| `nano` | `250m` | `128Mi` | -| `micro` | `500m` | `256Mi` | -| `small` | `1` | `512Mi` | -| `medium` | `1` | `1Gi` | -| `large` | `2` | `2Gi` | -| `xlarge` | `4` | `4Gi` | -| `2xlarge` | `8` | `8Gi` | +Presets follow a cloud-style `.` naming convention. Five series cover the full CPU-to-memory ratio range (`t1` 1:0.5, `c1` 1:1, `s1` 1:2, `u1` 1:4, `m1` 1:8) and each series ships eight sizes (`nano` through `4xlarge`). The legacy flat names (`nano`, `micro`, `small`, `medium`, `large`, `xlarge`, `2xlarge`) remain accepted as deprecated aliases of their 1:1 instance-type equivalents. + +See [`docs/operations/resource-presets.md`](../../../docs/operations/resource-presets.md) for the full size matrix and the legacy-to-instance-type mapping. ### users diff --git a/content/en/docs/next/operations/services/bootbox.md b/content/en/docs/next/operations/services/bootbox.md index cc77a0c4..23220a3f 100644 --- a/content/en/docs/next/operations/services/bootbox.md +++ b/content/en/docs/next/operations/services/bootbox.md @@ -6,7 +6,7 @@ linkTitle: "BootBox" diff --git a/content/en/docs/next/operations/services/etcd.md b/content/en/docs/next/operations/services/etcd.md index 70bf6234..ddfc2fe6 100644 --- a/content/en/docs/next/operations/services/etcd.md +++ b/content/en/docs/next/operations/services/etcd.md @@ -6,10 +6,61 @@ linkTitle: "Etcd" +## Backups + +**DEPRECATED:** the `backup.*` values block (`backup.enabled`, +`backup.schedule`, `backup.destinationPath`, ...) is superseded by the +Cozystack `BackupClass` flow driven by the `Etcd` strategy in +`strategy.backups.cozystack.io/v1alpha1`. New tenants should use a +`BackupJob` / `RestoreJob` against an `Etcd` strategy + `BackupClass` +instead — see `examples/backups/etcd/` for the end-to-end demo and +`internal/backupcontroller/etcdstrategy_controller.go` for the driver. +Existing tenants with `backup.enabled=true` continue to render the +legacy `EtcdBackupSchedule` + S3 credentials Secret unchanged — the +two flows coexist, the chart's scheduled backups have NOT stopped +working, and the `backup.*`-conditional rendered output is identical +to prior releases. + +### Upgrade note: `serverTrustedCASecret` is now set unconditionally + +This release adds `security.tls.serverTrustedCASecret: etcd-ca-tls` to +the rendered `EtcdCluster`. The field is required so that the +etcd-operator's `backup_agent` / `restore_agent` (v0.4.4+) trust the +server cert when they connect from their own pod via etcdctl — +without it the agent falls back to the system trust store and the +backup/restore handshake fails with "certificate signed by unknown +authority". The chart reuses the existing `etcd-ca-tls` Secret that +already issues every client/server cert today, so the field points at +material that has been present in the namespace since the cluster was +first deployed. On a Helm upgrade the etcd-operator observes the new +field and starts enforcing server-cert verification on its own client +connections; it does NOT roll the etcd member pods (the etcd container's +TLS configuration was already authoritative). Tenants who rely on the +backup-agent today will continue to need this field set, so leaving it +on by default keeps the chart consistent with the documented backup +path. + +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. This release bumps the bundled `packages/system/etcd-operator` chart from v0.4.3 to v0.4.5 (so the new `EtcdBackup.status.snapshot` field — added in v0.4.4 — and the restore-agent path fixes — added in v0.4.5 — are available to the strategy driver). The legacy `backup.enabled=true` path is unchanged by the bump and continues to function on v0.4.5 exactly as it did on v0.4.3. + +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 and ad-hoc backup**: the primary supported path is the +Cozystack `BackupClass` / `BackupJob` / `RestoreJob` flow described +above and demonstrated end-to-end under `examples/backups/etcd/`. The +driver suspends this chart's `HelmRelease` for the duration of an +in-place restore, deletes the live `EtcdCluster`, and re-creates it +with `spec.bootstrap.restore.source.s3` populated from the +`Backup` artefact's coordinates. The upstream `EtcdCluster.spec.bootstrap` +field and the one-shot `EtcdBackup` CR (v0.4.4) are NOT exposed +through this chart's values themselves; tenants who need to bypass +the BackupClass flow (e.g. an out-of-band recovery using a snapshot +that has no `Backup` artefact) can hand-apply the corresponding +custom resource manifest as an escape hatch. + ## Parameters ### Common parameters @@ -23,3 +74,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` | DEPRECATED: Backup configuration. The chart still renders the legacy EtcdBackupSchedule when backup.enabled=true, but new tenants should drive backups through a BackupClass bound to the Etcd strategy (strategy.backups.cozystack.io/v1alpha1). | `object` | `{}` | +| `backup.enabled` | DEPRECATED: Enable scheduled S3 backups. Use a BackupJob against an Etcd strategy instead. | `bool` | `false` | +| `backup.schedule` | DEPRECATED: Cron schedule for automated backups. Use a backups.cozystack.io/Plan instead. | `string` | `0 2 * * *` | +| `backup.destinationPath` | DEPRECATED: Destination path for backups (e.g. s3://bucket/path/). | `string` | `""` | +| `backup.endpointURL` | DEPRECATED: S3 endpoint URL for uploads. | `string` | `""` | +| `backup.region` | DEPRECATED: S3 region. | `string` | `""` | +| `backup.forcePathStyle` | DEPRECATED: Use path-style S3 URLs (required for MinIO and most S3-compatible providers). | `bool` | `true` | +| `backup.s3AccessKey` | DEPRECATED: Access key for S3 authentication. | `string` | `""` | +| `backup.s3SecretKey` | DEPRECATED: Secret key for S3 authentication. | `string` | `""` | +| `backup.successfulJobsHistoryLimit` | DEPRECATED: Number of successful backup jobs to retain. | `int` | `3` | +| `backup.failedJobsHistoryLimit` | DEPRECATED: Number of failed backup jobs to retain. | `int` | `1` | + diff --git a/content/en/docs/next/operations/services/ingress.md b/content/en/docs/next/operations/services/ingress.md index 45e03567..861b7873 100644 --- a/content/en/docs/next/operations/services/ingress.md +++ b/content/en/docs/next/operations/services/ingress.md @@ -6,7 +6,7 @@ linkTitle: "Ingress" @@ -14,13 +14,13 @@ source: https://github.com/cozystack/cozystack/blob/v1.3.0/packages/extra/ingres ### Common parameters -| Name | Description | Type | Value | -| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ------- | -| `replicas` | Number of ingress-nginx replicas. | `int` | `2` | -| `whitelist` | List of client networks. | `[]string` | `[]` | -| `cloudflareProxy` | Restoring original visitor IPs when Cloudflare proxied is enabled. | `bool` | `false` | -| `resources` | Explicit CPU and memory configuration for each ingress-nginx replica. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | -| `resources.cpu` | CPU available to each replica. | `quantity` | `""` | -| `resources.memory` | Memory (RAM) available to each replica. | `quantity` | `""` | -| `resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `micro` | +| Name | Description | Type | Value | +| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ---------- | +| `replicas` | Number of ingress-nginx replicas. | `int` | `2` | +| `whitelist` | List of client networks. | `[]string` | `[]` | +| `cloudflareProxy` | Restoring original visitor IPs when Cloudflare proxied is enabled. | `bool` | `false` | +| `resources` | Explicit CPU and memory configuration for each ingress-nginx replica. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | +| `resources.cpu` | CPU available to each replica. | `quantity` | `""` | +| `resources.memory` | Memory (RAM) available to each replica. | `quantity` | `""` | +| `resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `t1.micro` | diff --git a/content/en/docs/next/operations/services/monitoring/parameters.md b/content/en/docs/next/operations/services/monitoring/parameters.md index df7a627e..6b7af096 100644 --- a/content/en/docs/next/operations/services/monitoring/parameters.md +++ b/content/en/docs/next/operations/services/monitoring/parameters.md @@ -7,7 +7,7 @@ weight: 1 diff --git a/content/en/docs/next/operations/services/seaweedfs.md b/content/en/docs/next/operations/services/seaweedfs.md index 1db1b626..98b97716 100644 --- a/content/en/docs/next/operations/services/seaweedfs.md +++ b/content/en/docs/next/operations/services/seaweedfs.md @@ -6,7 +6,7 @@ linkTitle: "SeaweedFS" @@ -23,68 +23,68 @@ source: https://github.com/cozystack/cozystack/blob/v1.3.0/packages/extra/seawee ### SeaweedFS Components Configuration -| Name | Description | Type | Value | -| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------- | ------- | -| `db` | Database configuration. | `object` | `{}` | -| `db.replicas` | Number of database replicas. | `int` | `2` | -| `db.size` | Persistent Volume size. | `quantity` | `10Gi` | -| `db.storageClass` | StorageClass used to store the data. | `string` | `""` | -| `db.resources` | Explicit CPU and memory configuration. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | -| `db.resources.cpu` | Number of CPU cores allocated. | `quantity` | `""` | -| `db.resources.memory` | Amount of memory allocated. | `quantity` | `""` | -| `db.resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `small` | -| `master` | Master service configuration. | `object` | `{}` | -| `master.replicas` | Number of master replicas. | `int` | `3` | -| `master.resources` | Explicit CPU and memory configuration. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | -| `master.resources.cpu` | Number of CPU cores allocated. | `quantity` | `""` | -| `master.resources.memory` | Amount of memory allocated. | `quantity` | `""` | -| `master.resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `small` | -| `filer` | Filer service configuration. | `object` | `{}` | -| `filer.replicas` | Number of filer replicas. | `int` | `2` | -| `filer.resources` | Explicit CPU and memory configuration. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | -| `filer.resources.cpu` | Number of CPU cores allocated. | `quantity` | `""` | -| `filer.resources.memory` | Amount of memory allocated. | `quantity` | `""` | -| `filer.resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `small` | -| `filer.grpcHost` | The hostname used to expose or access the filer service externally. | `string` | `""` | -| `filer.grpcPort` | The port used to access the filer service externally. | `int` | `443` | -| `filer.whitelist` | A list of IP addresses or CIDR ranges that are allowed to access the filer service. | `[]string` | `[]` | -| `volume` | Volume service configuration. | `object` | `{}` | -| `volume.replicas` | Number of volume replicas. | `int` | `2` | -| `volume.size` | Persistent Volume size. | `quantity` | `10Gi` | -| `volume.storageClass` | StorageClass used to store the data. | `string` | `""` | -| `volume.diskType` | SeaweedFS disk type tag for the default volume servers (e.g., "hdd", "ssd"). | `string` | `""` | -| `volume.resources` | Explicit CPU and memory configuration. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | -| `volume.resources.cpu` | Number of CPU cores allocated. | `quantity` | `""` | -| `volume.resources.memory` | Amount of memory allocated. | `quantity` | `""` | -| `volume.resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `small` | -| `volume.zones` | A map of zones for MultiZone topology. Each zone can have its own number of replicas and size. | `map[string]object` | `{}` | -| `volume.zones[name].replicas` | Number of replicas in the zone. | `int` | `0` | -| `volume.zones[name].size` | Zone storage size. | `quantity` | `""` | -| `volume.zones[name].dataCenter` | SeaweedFS data center name for this zone. Defaults to the zone name. | `string` | `""` | -| `volume.zones[name].nodeSelector` | YAML nodeSelector for this zone (default: topology.kubernetes.io/zone: ). | `string` | `""` | -| `volume.zones[name].storageClass` | StorageClass used to store zone data. Defaults to volume.storageClass. | `string` | `""` | -| `volume.zones[name].pools` | A map of storage pools for this zone. Each pool creates a separate Volume StatefulSet per zone. | `map[string]object` | `{}` | -| `volume.zones[name].pools[name].diskType` | SeaweedFS disk type tag (e.g., "ssd", "hdd", "nvme"). | `string` | `""` | -| `volume.zones[name].pools[name].replicas` | Number of volume replicas. Defaults to volume.replicas (Simple) or zone.replicas/volume.replicas (MultiZone). | `int` | `0` | -| `volume.zones[name].pools[name].size` | Persistent Volume size. Defaults to volume.size (Simple) or zone.size/volume.size (MultiZone). | `quantity` | `""` | -| `volume.zones[name].pools[name].storageClass` | Kubernetes StorageClass for the pool. Defaults to volume.storageClass. | `string` | `""` | -| `volume.zones[name].pools[name].resources` | Explicit CPU and memory configuration. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | -| `volume.zones[name].pools[name].resources.cpu` | Number of CPU cores allocated. | `quantity` | `""` | -| `volume.zones[name].pools[name].resources.memory` | Amount of memory allocated. | `quantity` | `""` | -| `volume.zones[name].pools[name].resourcesPreset` | Default sizing preset used when `resources` is omitted. Defaults to volume.resourcesPreset. | `string` | `{}` | -| `volume.pools` | A map of storage pools. Each pool creates a separate Volume StatefulSet with its own disk type. | `map[string]object` | `{}` | -| `volume.pools[name].diskType` | SeaweedFS disk type tag (e.g., "ssd", "hdd", "nvme"). | `string` | `""` | -| `volume.pools[name].replicas` | Number of volume replicas. Defaults to volume.replicas (Simple) or zone.replicas/volume.replicas (MultiZone). | `int` | `0` | -| `volume.pools[name].size` | Persistent Volume size. Defaults to volume.size (Simple) or zone.size/volume.size (MultiZone). | `quantity` | `""` | -| `volume.pools[name].storageClass` | Kubernetes StorageClass for the pool. Defaults to volume.storageClass. | `string` | `""` | -| `volume.pools[name].resources` | Explicit CPU and memory configuration. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | -| `volume.pools[name].resources.cpu` | Number of CPU cores allocated. | `quantity` | `""` | -| `volume.pools[name].resources.memory` | Amount of memory allocated. | `quantity` | `""` | -| `volume.pools[name].resourcesPreset` | Default sizing preset used when `resources` is omitted. Defaults to volume.resourcesPreset. | `string` | `{}` | -| `s3` | S3 service configuration. | `object` | `{}` | -| `s3.replicas` | Number of S3 replicas. | `int` | `2` | -| `s3.resources` | Explicit CPU and memory configuration. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | -| `s3.resources.cpu` | Number of CPU cores allocated. | `quantity` | `""` | -| `s3.resources.memory` | Amount of memory allocated. | `quantity` | `""` | -| `s3.resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `small` | +| Name | Description | Type | Value | +| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------- | ---------- | +| `db` | Database configuration. | `object` | `{}` | +| `db.replicas` | Number of database replicas. | `int` | `2` | +| `db.size` | Persistent Volume size. | `quantity` | `10Gi` | +| `db.storageClass` | StorageClass used to store the data. | `string` | `""` | +| `db.resources` | Explicit CPU and memory configuration. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | +| `db.resources.cpu` | Number of CPU cores allocated. | `quantity` | `""` | +| `db.resources.memory` | Amount of memory allocated. | `quantity` | `""` | +| `db.resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `t1.small` | +| `master` | Master service configuration. | `object` | `{}` | +| `master.replicas` | Number of master replicas. | `int` | `3` | +| `master.resources` | Explicit CPU and memory configuration. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | +| `master.resources.cpu` | Number of CPU cores allocated. | `quantity` | `""` | +| `master.resources.memory` | Amount of memory allocated. | `quantity` | `""` | +| `master.resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `t1.small` | +| `filer` | Filer service configuration. | `object` | `{}` | +| `filer.replicas` | Number of filer replicas. | `int` | `2` | +| `filer.resources` | Explicit CPU and memory configuration. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | +| `filer.resources.cpu` | Number of CPU cores allocated. | `quantity` | `""` | +| `filer.resources.memory` | Amount of memory allocated. | `quantity` | `""` | +| `filer.resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `t1.small` | +| `filer.grpcHost` | The hostname used to expose or access the filer service externally. | `string` | `""` | +| `filer.grpcPort` | The port used to access the filer service externally. | `int` | `443` | +| `filer.whitelist` | A list of IP addresses or CIDR ranges that are allowed to access the filer service. | `[]string` | `[]` | +| `volume` | Volume service configuration. | `object` | `{}` | +| `volume.replicas` | Number of volume replicas. | `int` | `2` | +| `volume.size` | Persistent Volume size. | `quantity` | `10Gi` | +| `volume.storageClass` | StorageClass used to store the data. | `string` | `""` | +| `volume.diskType` | SeaweedFS disk type tag for the default volume servers (e.g., "hdd", "ssd"). | `string` | `""` | +| `volume.resources` | Explicit CPU and memory configuration. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | +| `volume.resources.cpu` | Number of CPU cores allocated. | `quantity` | `""` | +| `volume.resources.memory` | Amount of memory allocated. | `quantity` | `""` | +| `volume.resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `t1.small` | +| `volume.zones` | A map of zones for MultiZone topology. Each zone can have its own number of replicas and size. | `map[string]object` | `{}` | +| `volume.zones[name].replicas` | Number of replicas in the zone. | `int` | `0` | +| `volume.zones[name].size` | Zone storage size. | `quantity` | `""` | +| `volume.zones[name].dataCenter` | SeaweedFS data center name for this zone. Defaults to the zone name. | `string` | `""` | +| `volume.zones[name].nodeSelector` | YAML nodeSelector for this zone (default: topology.kubernetes.io/zone: ). | `string` | `""` | +| `volume.zones[name].storageClass` | StorageClass used to store zone data. Defaults to volume.storageClass. | `string` | `""` | +| `volume.zones[name].pools` | A map of storage pools for this zone. Each pool creates a separate Volume StatefulSet per zone. | `map[string]object` | `{}` | +| `volume.zones[name].pools[name].diskType` | SeaweedFS disk type tag (e.g., "ssd", "hdd", "nvme"). | `string` | `""` | +| `volume.zones[name].pools[name].replicas` | Number of volume replicas. Defaults to volume.replicas (Simple) or zone.replicas/volume.replicas (MultiZone). | `int` | `0` | +| `volume.zones[name].pools[name].size` | Persistent Volume size. Defaults to volume.size (Simple) or zone.size/volume.size (MultiZone). | `quantity` | `""` | +| `volume.zones[name].pools[name].storageClass` | Kubernetes StorageClass for the pool. Defaults to volume.storageClass. | `string` | `""` | +| `volume.zones[name].pools[name].resources` | Explicit CPU and memory configuration. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | +| `volume.zones[name].pools[name].resources.cpu` | Number of CPU cores allocated. | `quantity` | `""` | +| `volume.zones[name].pools[name].resources.memory` | Amount of memory allocated. | `quantity` | `""` | +| `volume.zones[name].pools[name].resourcesPreset` | Default sizing preset used when `resources` is omitted. Defaults to volume.resourcesPreset. | `string` | `{}` | +| `volume.pools` | A map of storage pools. Each pool creates a separate Volume StatefulSet with its own disk type. | `map[string]object` | `{}` | +| `volume.pools[name].diskType` | SeaweedFS disk type tag (e.g., "ssd", "hdd", "nvme"). | `string` | `""` | +| `volume.pools[name].replicas` | Number of volume replicas. Defaults to volume.replicas (Simple) or zone.replicas/volume.replicas (MultiZone). | `int` | `0` | +| `volume.pools[name].size` | Persistent Volume size. Defaults to volume.size (Simple) or zone.size/volume.size (MultiZone). | `quantity` | `""` | +| `volume.pools[name].storageClass` | Kubernetes StorageClass for the pool. Defaults to volume.storageClass. | `string` | `""` | +| `volume.pools[name].resources` | Explicit CPU and memory configuration. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | +| `volume.pools[name].resources.cpu` | Number of CPU cores allocated. | `quantity` | `""` | +| `volume.pools[name].resources.memory` | Amount of memory allocated. | `quantity` | `""` | +| `volume.pools[name].resourcesPreset` | Default sizing preset used when `resources` is omitted. Defaults to volume.resourcesPreset. | `string` | `{}` | +| `s3` | S3 service configuration. | `object` | `{}` | +| `s3.replicas` | Number of S3 replicas. | `int` | `2` | +| `s3.resources` | Explicit CPU and memory configuration. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` | +| `s3.resources.cpu` | Number of CPU cores allocated. | `quantity` | `""` | +| `s3.resources.memory` | Amount of memory allocated. | `quantity` | `""` | +| `s3.resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `t1.small` | diff --git a/content/en/docs/next/virtualization/vm-disk.md b/content/en/docs/next/virtualization/vm-disk.md index 6c85c78d..9ab5e47f 100644 --- a/content/en/docs/next/virtualization/vm-disk.md +++ b/content/en/docs/next/virtualization/vm-disk.md @@ -10,12 +10,14 @@ aliases: A Virtual Machine Disk +> `storageClass` is annotated as immutable in the chart schema — see [`docs/storage-immutability.md`](../../../docs/storage-immutability.md) for the contract and which consumers enforce it. + ## Parameters ### Common parameters diff --git a/content/en/docs/next/virtualization/vm-instance.md b/content/en/docs/next/virtualization/vm-instance.md index 958c945a..3edf85f8 100644 --- a/content/en/docs/next/virtualization/vm-instance.md +++ b/content/en/docs/next/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 @@ -197,20 +198,41 @@ The following instancetype resources are provided by Cozystack: Name | vCPUs | Memory -----|-------|------- cx1.2xlarge | 8 | 16Gi +cx1.2xlarge1gi | 8 | 16Gi cx1.4xlarge | 16 | 32Gi +cx1.4xlarge1gi | 16 | 32Gi cx1.8xlarge | 32 | 64Gi +cx1.8xlarge1gi | 32 | 64Gi cx1.large | 2 | 4Gi +cx1.large1gi | 2 | 4Gi cx1.medium | 1 | 2Gi +cx1.medium1gi | 1 | 2Gi cx1.xlarge | 4 | 8Gi +cx1.xlarge1gi | 4 | 8Gi +d1.2xlarge | 8 | 32Gi +d1.2xmedium | 2 | 4Gi +d1.4xlarge | 16 | 64Gi +d1.8xlarge | 32 | 128Gi +d1.large | 2 | 8Gi +d1.medium | 1 | 4Gi +d1.micro | 1 | 1Gi +d1.nano | 1 | 512Mi +d1.small | 1 | 2Gi +d1.xlarge | 4 | 16Gi gn1.2xlarge | 8 | 32Gi gn1.4xlarge | 16 | 64Gi gn1.8xlarge | 32 | 128Gi gn1.xlarge | 4 | 16Gi m1.2xlarge | 8 | 64Gi +m1.2xlarge1gi | 8 | 64Gi m1.4xlarge | 16 | 128Gi +m1.4xlarge1gi | 16 | 128Gi m1.8xlarge | 32 | 256Gi +m1.8xlarge1gi | 32 | 256Gi m1.large | 2 | 16Gi +m1.large1gi | 2 | 16Gi m1.xlarge | 4 | 32Gi +m1.xlarge1gi | 4 | 32Gi n1.2xlarge | 16 | 32Gi n1.4xlarge | 32 | 64Gi n1.8xlarge | 64 | 128Gi @@ -250,23 +272,26 @@ The following preference resources are provided by Cozystack: Name | Guest OS -----|--------- alpine | Alpine -centos.7 | CentOS 7 -centos.7.desktop | CentOS 7 centos.stream10 | CentOS Stream 10 centos.stream10.desktop | CentOS Stream 10 -centos.stream8 | CentOS Stream 8 -centos.stream8.desktop | CentOS Stream 8 -centos.stream8.dpdk | CentOS Stream 8 centos.stream9 | CentOS Stream 9 centos.stream9.desktop | CentOS Stream 9 centos.stream9.dpdk | CentOS Stream 9 cirros | Cirros +debian | Debian fedora | Fedora (amd64) fedora.arm64 | Fedora (arm64) +fedora.s390x | Fedora (s390x) +legacy | Legacy Guest +linux | Linux Guest +linux.efi | Linux EFI Guest +linux.virtiotransitional | Linux Virtio Transitional Guest opensuse.leap | OpenSUSE Leap opensuse.tumbleweed | OpenSUSE Tumbleweed -rhel.10 | Red Hat Enterprise Linux 10 Beta (amd64) -rhel.10.arm64 | Red Hat Enterprise Linux 10 Beta (arm64) +oraclelinux | Oracle Linux +rhel.10 | Red Hat Enterprise Linux 10 (amd64) +rhel.10.arm64 | Red Hat Enterprise Linux 10 (arm64) +rhel.10.s390x | Red Hat Enterprise Linux 10 (s390x) rhel.7 | Red Hat Enterprise Linux 7 rhel.7.desktop | Red Hat Enterprise Linux 7 rhel.8 | Red Hat Enterprise Linux 8 @@ -277,12 +302,15 @@ rhel.9.arm64 | Red Hat Enterprise Linux 9 (arm64) rhel.9.desktop | Red Hat Enterprise Linux 9 Desktop (amd64) rhel.9.dpdk | Red Hat Enterprise Linux 9 DPDK (amd64) rhel.9.realtime | Red Hat Enterprise Linux 9 Realtime (amd64) +rhel.9.s390x | Red Hat Enterprise Linux 9 (s390x) sles | SUSE Linux Enterprise Server ubuntu | Ubuntu windows.10 | Microsoft Windows 10 windows.10.virtio | Microsoft Windows 10 (virtio) windows.11 | Microsoft Windows 11 windows.11.virtio | Microsoft Windows 11 (virtio) +windows.2k12 | Microsoft Windows Server 2012/2012 R2 +windows.2k12.virtio | Microsoft Windows Server 2012/2012 R2 (virtio) windows.2k16 | Microsoft Windows Server 2016 windows.2k16.virtio | Microsoft Windows Server 2016 (virtio) windows.2k19 | Microsoft Windows Server 2019 @@ -291,3 +319,9 @@ windows.2k22 | Microsoft Windows Server 2022 windows.2k22.virtio | Microsoft Windows Server 2022 (virtio) windows.2k25 | Microsoft Windows Server 2025 windows.2k25.virtio | Microsoft Windows Server 2025 (virtio) +windows.2k3 | Microsoft Windows Server 2003 +windows.2k8 | Microsoft Windows Server 2008/2008 R2 +windows.2k8.virtio | Microsoft Windows Server 2008/2008 R2 (virtio) +windows.7 | Microsoft Windows 7 +windows.7.virtio | Microsoft Windows 7 (virtio) +windows.xp | Microsoft Windows XP