Skip to content

Commit cca54d8

Browse files
lexfreiMatthieu ROBIN
andcommitted
docs(operations): resource presets reference
Document the five instance-type series (t1/c1/s1/u1/m1) introduced alongside the legacy preset deprecation, the per-size CPU and memory matrix, and the 1:1 legacy-to-instance-type mapping table that powers cozy-lib aliases, migration 39, and the operator-side deprecation warning. Single source of truth referenced from: - packages/library/cozy-lib/templates/_resourcepresets.tpl - packages/core/platform/images/migrations/migrations/39 - pkg/apis/apps/presets/legacy.go Includes an explicit callout that legacy `medium` (1 CPU / 1Gi) and instance-type `*.medium` (2 CPU) are not the same — same word, different resources. Replace inline preset tables in packages/apps/postgres/README.md and packages/apps/kafka/README.md with a short paragraph that names the five series and points at the canonical doc, since the per-app inline tables listed only the legacy seven and would drift further as the canonical matrix evolves. Co-authored-by: Matthieu ROBIN <[email protected]> Signed-off-by: Aleksei Sviridkin <[email protected]>
1 parent 55850aa commit cca54d8

3 files changed

Lines changed: 89 additions & 49 deletions

File tree

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Resource presets
2+
3+
Every cozystack app exposes a `resourcesPreset` field whose value selects a CPU and memory reservation. Presets follow a cloud-style `<series>.<size>` naming convention. Setting `resources:` explicitly overrides the preset.
4+
5+
## Series
6+
7+
| Series | CPU:Memory ratio | When to use |
8+
| ------ | ---------------- | ------------------------------------------------- |
9+
| `t1` | 1:0.5 | Tiny / burstable, low memory |
10+
| `c1` | 1:1 | Compute-balanced, CPU-bound workloads |
11+
| `s1` | 1:2 | Standard — proxies, caches, lightweight services |
12+
| `u1` | 1:4 | Universal — databases and messaging |
13+
| `m1` | 1:8 | Memory-heavy — search, analytics, large caches |
14+
15+
## Watch out: legacy and instance-type `medium` differ
16+
17+
Legacy `medium` had **1 CPU / 1Gi**. The new `*.medium` sizes have **2 CPU** (in any series). The names overlap but the resources do not. The migration table below stays correct — `medium → c1.small (1 CPU / 1Gi)` — but if you read the instance-type sizing matrix first and pick `c1.medium` "to keep things the same", you will double your CPU. When in doubt, consult the legacy-to-instance-type mapping at the bottom of this page.
18+
19+
## Sizes
20+
21+
| Size | CPU | t1 mem | c1 mem | s1 mem | u1 mem | m1 mem |
22+
| ---------- | ---- | ------ | ------ | ------ | ------ | ------ |
23+
| `nano` | 250m | 128Mi | 256Mi | 512Mi | 1Gi | 2Gi |
24+
| `micro` | 500m | 256Mi | 512Mi | 1Gi | 2Gi | 4Gi |
25+
| `small` | 1 | 512Mi | 1Gi | 2Gi | 4Gi | 8Gi |
26+
| `medium` | 2 | 1Gi | 2Gi | 4Gi | 8Gi | 16Gi |
27+
| `large` | 4 | 2Gi | 4Gi | 8Gi | 16Gi | 32Gi |
28+
| `xlarge` | 8 | 4Gi | 8Gi | 16Gi | 32Gi | 64Gi |
29+
| `2xlarge` | 16 | 8Gi | 16Gi | 32Gi | 64Gi | 128Gi |
30+
| `4xlarge` | 32 | 16Gi | 32Gi | 64Gi | 128Gi | 256Gi |
31+
32+
Ephemeral storage is 2Gi for every preset.
33+
34+
## Legacy flat names (deprecated)
35+
36+
The following short names existed before the instance-type rename and remain accepted for backward compatibility. They render exactly the CPU and memory they did before — the legacy block in `cozy-lib` returns the original values verbatim. The 1:1 mapping is:
37+
38+
| Legacy | CPU | Memory | Instance-type equivalent |
39+
| -------- | ---- | ------ | ------------------------ |
40+
| `nano` | 250m | 128Mi | `t1.nano` |
41+
| `micro` | 500m | 256Mi | `t1.micro` |
42+
| `small` | 1 | 512Mi | `t1.small` |
43+
| `medium` | 1 | 1Gi | `c1.small` |
44+
| `large` | 2 | 2Gi | `c1.medium` |
45+
| `xlarge` | 4 | 4Gi | `c1.large` |
46+
| `2xlarge`| 8 | 8Gi | `c1.xlarge` |
47+
48+
Legacy names are scheduled for removal in a future cozystack release. New manifests should use the instance-type form. `cozystack-api` emits a `klog` warning whenever an app CR carries a legacy value, naming the suggested replacement.
49+
50+
## Automatic migration
51+
52+
Platform upgrades run `migration 39` as a pre-upgrade hook. It walks every `HelmRelease` `spec.values` and every app CR under `apps.cozystack.io/v1alpha1`, rewriting legacy `resourcesPreset` values in place using the table above. The conversion is idempotent and best-effort: a failure on one object logs a warning and leaves the rest of the migration to complete. Set `MIGRATION_DRY_RUN=1` to preview the patches without applying them.

‎packages/apps/kafka/README.md‎

Lines changed: 23 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -22,30 +22,30 @@
2222

2323
### Kafka configuration
2424

25-
| Name | Description | Type | Value |
26-
| ------------------------ | -------------------------------------------------------------------------------------------------------- | ---------- | -------- |
27-
| `kafka` | Kafka configuration. | `object` | `{}` |
28-
| `kafka.replicas` | Number of Kafka replicas. | `int` | `3` |
29-
| `kafka.resources` | Explicit CPU and memory configuration. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` |
30-
| `kafka.resources.cpu` | CPU available to each replica. | `quantity` | `""` |
31-
| `kafka.resources.memory` | Memory (RAM) available to each replica. | `quantity` | `""` |
32-
| `kafka.resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `medium` |
33-
| `kafka.size` | Persistent Volume size for Kafka. | `quantity` | `10Gi` |
34-
| `kafka.storageClass` | StorageClass used to store the Kafka data. | `string` | `""` |
25+
| Name | Description | Type | Value |
26+
| ------------------------ | -------------------------------------------------------------------------------------------------------- | ---------- | ---------- |
27+
| `kafka` | Kafka configuration. | `object` | `{}` |
28+
| `kafka.replicas` | Number of Kafka replicas. | `int` | `3` |
29+
| `kafka.resources` | Explicit CPU and memory configuration. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` |
30+
| `kafka.resources.cpu` | CPU available to each replica. | `quantity` | `""` |
31+
| `kafka.resources.memory` | Memory (RAM) available to each replica. | `quantity` | `""` |
32+
| `kafka.resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `c1.small` |
33+
| `kafka.size` | Persistent Volume size for Kafka. | `quantity` | `10Gi` |
34+
| `kafka.storageClass` | StorageClass used to store the Kafka data. | `string` | `""` |
3535

3636

3737
### ZooKeeper configuration
3838

39-
| Name | Description | Type | Value |
40-
| ---------------------------- | -------------------------------------------------------------------------------------------------------- | ---------- | -------- |
41-
| `zookeeper` | ZooKeeper configuration. | `object` | `{}` |
42-
| `zookeeper.replicas` | Number of ZooKeeper replicas. | `int` | `3` |
43-
| `zookeeper.resources` | Explicit CPU and memory configuration. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` |
44-
| `zookeeper.resources.cpu` | CPU available to each replica. | `quantity` | `""` |
45-
| `zookeeper.resources.memory` | Memory (RAM) available to each replica. | `quantity` | `""` |
46-
| `zookeeper.resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `medium` |
47-
| `zookeeper.size` | Persistent Volume size for ZooKeeper. | `quantity` | `5Gi` |
48-
| `zookeeper.storageClass` | StorageClass used to store the ZooKeeper data. | `string` | `""` |
39+
| Name | Description | Type | Value |
40+
| ---------------------------- | -------------------------------------------------------------------------------------------------------- | ---------- | ---------- |
41+
| `zookeeper` | ZooKeeper configuration. | `object` | `{}` |
42+
| `zookeeper.replicas` | Number of ZooKeeper replicas. | `int` | `3` |
43+
| `zookeeper.resources` | Explicit CPU and memory configuration. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` |
44+
| `zookeeper.resources.cpu` | CPU available to each replica. | `quantity` | `""` |
45+
| `zookeeper.resources.memory` | Memory (RAM) available to each replica. | `quantity` | `""` |
46+
| `zookeeper.resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `c1.small` |
47+
| `zookeeper.size` | Persistent Volume size for ZooKeeper. | `quantity` | `5Gi` |
48+
| `zookeeper.storageClass` | StorageClass used to store the ZooKeeper data. | `string` | `""` |
4949

5050

5151
## Parameter examples and reference
@@ -64,15 +64,9 @@ resources:
6464
`resourcesPreset` sets named CPU and memory configurations for each replica.
6565
This setting is ignored if the corresponding `resources` value is set.
6666

67-
| Preset name | CPU | memory |
68-
|-------------|--------|---------|
69-
| `nano` | `250m` | `128Mi` |
70-
| `micro` | `500m` | `256Mi` |
71-
| `small` | `1` | `512Mi` |
72-
| `medium` | `1` | `1Gi` |
73-
| `large` | `2` | `2Gi` |
74-
| `xlarge` | `4` | `4Gi` |
75-
| `2xlarge` | `8` | `8Gi` |
67+
Presets follow a cloud-style `<series>.<size>` 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.
68+
69+
See [`docs/operations/resource-presets.md`](../../../docs/operations/resource-presets.md) for the full size matrix and the legacy-to-instance-type mapping.
7670

7771
### topics
7872

‎packages/apps/postgres/README.md‎

Lines changed: 14 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -162,17 +162,17 @@ See:
162162

163163
### Common parameters
164164

165-
| Name | Description | Type | Value |
166-
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | ---------- | ------- |
167-
| `replicas` | Number of Postgres replicas. | `int` | `2` |
168-
| `resources` | Explicit CPU and memory configuration for each PostgreSQL replica. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` |
169-
| `resources.cpu` | CPU available to each replica. | `quantity` | `""` |
170-
| `resources.memory` | Memory (RAM) available to each replica. | `quantity` | `""` |
171-
| `resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `micro` |
172-
| `size` | Persistent Volume Claim size available for application data. | `quantity` | `10Gi` |
173-
| `storageClass` | StorageClass used to store the data. | `string` | `""` |
174-
| `external` | Enable external access from outside the cluster. | `bool` | `false` |
175-
| `version` | PostgreSQL major version to deploy | `string` | `v18` |
165+
| Name | Description | Type | Value |
166+
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | ---------- | ---------- |
167+
| `replicas` | Number of Postgres replicas. | `int` | `2` |
168+
| `resources` | Explicit CPU and memory configuration for each PostgreSQL replica. When omitted, the preset defined in `resourcesPreset` is applied. | `object` | `{}` |
169+
| `resources.cpu` | CPU available to each replica. | `quantity` | `""` |
170+
| `resources.memory` | Memory (RAM) available to each replica. | `quantity` | `""` |
171+
| `resourcesPreset` | Default sizing preset used when `resources` is omitted. | `string` | `t1.micro` |
172+
| `size` | Persistent Volume Claim size available for application data. | `quantity` | `10Gi` |
173+
| `storageClass` | StorageClass used to store the data. | `string` | `""` |
174+
| `external` | Enable external access from outside the cluster. | `bool` | `false` |
175+
| `version` | PostgreSQL major version to deploy | `string` | `v18` |
176176

177177

178178
### Application-specific parameters
@@ -260,15 +260,9 @@ resources:
260260
`resourcesPreset` sets named CPU and memory configurations for each replica.
261261
This setting is ignored if the corresponding `resources` value is set.
262262

263-
| Preset name | CPU | memory |
264-
|-------------|--------|---------|
265-
| `nano` | `250m` | `128Mi` |
266-
| `micro` | `500m` | `256Mi` |
267-
| `small` | `1` | `512Mi` |
268-
| `medium` | `1` | `1Gi` |
269-
| `large` | `2` | `2Gi` |
270-
| `xlarge` | `4` | `4Gi` |
271-
| `2xlarge` | `8` | `8Gi` |
263+
Presets follow a cloud-style `<series>.<size>` 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.
264+
265+
See [`docs/operations/resource-presets.md`](../../../docs/operations/resource-presets.md) for the full size matrix and the legacy-to-instance-type mapping.
272266

273267
### users
274268

0 commit comments

Comments
 (0)