Skip to content

Commit 457ba39

Browse files
committed
docs(backups): stop presenting admin-only demo steps as tenant work
The kafka and nats walkthroughs put steps 03, 04, 06, 07 and cleanup under the tenant persona, and the scenario docs and helper comments had the tenant create the backup Secret. The scripts read, create and delete Secrets, wait on HelmReleases, COSI objects and operator resources, exec into a CLI Pod, read Pod logs, and delete the Backup and the cluster-scoped BackupClass and strategy. The tenant roles grant none of that, so a tenant following the docs hit Forbidden at the first read. The tables now say admin and name the part a tenant admin can do on its own, and the scenario docs say the same. Assisted-by: LLM Signed-off-by: Aleksei Sviridkin <[email protected]>
1 parent 30e0541 commit 457ba39

14 files changed

Lines changed: 32 additions & 39 deletions

‎examples/backups/kafka/00-helpers.sh‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -309,7 +309,7 @@ topic_replication_factor() {
309309
# Create the "<app>-backup-s3" Secret the Job strategy Pod consumes, from the
310310
# bucket coordinates cached by 03-create-bucket.sh. The generic Job strategy -
311311
# unlike the app-specific drivers - has no chart support to emit this Secret,
312-
# so the tenant provides it. Called for the source app (step 04) and the
312+
# so the demo provides it. Called for the source app (step 04) and the
313313
# restore target (step 07). The S3 endpoint's CA, when 03-create-bucket.sh
314314
# cached one, rides along as ca.crt: the strategy Pod mounts that key and
315315
# verifies the endpoint against it instead of disabling verification.

‎examples/backups/kafka/01-create-strategy.sh‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -82,7 +82,7 @@ spec:
8282
value: "{{ .Release.Namespace }}"
8383
- name: MODE
8484
value: "{{ .Mode }}"
85-
# S3 coordinates from the tenant-provided <release>-backup-s3 Secret
85+
# S3 coordinates from the demo-provided <release>-backup-s3 Secret
8686
# (created by create_s3_secret in 00-helpers.sh from the Bucket).
8787
- name: AWS_ACCESS_KEY_ID
8888
valueFrom:
@@ -169,7 +169,7 @@ spec:
169169
170170
# curl --aws-sigv4 signs the request (SigV4) so no separate S3
171171
# client image is needed. The certificate is verified: against the
172-
# CA projected from the Secret when the tenant supplied one, else
172+
# CA projected from the Secret when it carries one, else
173173
# against the image's trust store. \${CA_OPT} and \${CONNECT_TO}
174174
# are deliberately unquoted so an empty value expands to no
175175
# argument.

‎examples/backups/kafka/03-create-bucket.sh‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
#!/bin/bash
22
# Step 03: Provision an in-cluster Bucket and cache its S3 coordinates. The
33
# generic Job strategy has no chart support to emit a backup Secret, so the
4-
# tenant materialises the "<app>-backup-s3" Secret itself. This step only
4+
# demo materialises the "<app>-backup-s3" Secret itself. This step only
55
# caches the coordinates; create_s3_secret (00-helpers.sh) turns them into
66
# per-app Secrets in steps 04 and 07.
77
set -euo pipefail

‎examples/backups/kafka/90-scenario-admin-prepare.md‎

Lines changed: 2 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,14 @@
11
# Scenario: Cluster admin prepares Kafka topic-data backups
22

3-
A cluster administrator performs the cluster-level preparation once. Tenants
4-
will then be able to back up and restore the topic data of their Kafka
5-
applications by referencing the BackupClass created here, with no further
6-
admin action.
3+
A cluster administrator performs the cluster-level preparation once. Tenant admins can then back up and restore the topic data of their Kafka applications with a `BackupJob` or `RestoreJob` that references the BackupClass created here. The demo scripts around those jobs still need admin access, because they create Secrets and work through a CLI Pod; the README's step table says which part of each step a tenant admin can do.
74

85
## Prerequisites
96

107
- A running Cozystack cluster with the backup-controller and
118
backupstrategy-controller installed.
129
- `kubectl` access with permissions to create cluster-scoped
1310
`Job.strategy.backups.cozystack.io` and `BackupClass.backups.cozystack.io`.
14-
- Reachable S3-compatible storage. The demo uses the in-cluster `Bucket` app
15-
(step 03); the tenant turns its coordinates and the endpoint's CA into a
16-
`<app>-backup-s3` Secret that the strategy Pod reads (step 04 / 07).
11+
- Reachable S3-compatible storage. The demo uses the in-cluster `Bucket` app (step 03), and steps 04 and 07 turn its coordinates and the endpoint's CA into a `<app>-backup-s3` Secret that the strategy Pod reads. Creating that Secret needs admin access, since no tenant role grants `create` on `secrets`.
1712

1813
## Steps
1914

‎examples/backups/kafka/91-scenario-user-backup.md‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,13 @@
22

33
This scenario assumes the admin steps (`01-...`, `02-...`) have already run.
44

5+
The user's own action here, at the tenant admin level, is the `BackupJob` in step 05, plus creating the `Bucket` and the `Kafka`. Steps 03 and 04 as scripted need admin access: they read and create Secrets, wait on HelmReleases and operator resources, and seed the topic through a CLI Pod, which no tenant role allows. The README's step table has the details.
6+
57
## Prerequisites
68

79
- Tenant namespace (default: `tenant-root`, the tenant whose Pods can reach
810
the in-cluster seaweedfs; see the README).
9-
- A Cozystack `Bucket` (step 03) and the `<app>-backup-s3` Secret derived from
10-
it (step 04). The generic `Job` strategy has no chart support to emit this
11-
Secret, so the tenant creates it from the bucket's `BucketInfo` plus the S3
12-
endpoint's CA (see `create_s3_secret` in `00-helpers.sh`).
11+
- A Cozystack `Bucket` (step 03) and the `<app>-backup-s3` Secret derived from it (step 04). The generic `Job` strategy has no chart support to emit this Secret, so step 04 creates it from the bucket's `BucketInfo` plus the S3 endpoint's CA (see `create_s3_secret` in `00-helpers.sh`). Creating it needs admin access.
1312
- A `Kafka` application with at least one plain (neither compacted nor
1413
transactional) topic holding data.
1514

‎examples/backups/kafka/92-scenario-user-restore.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@ Two restore variants are supported. Both append: the strategy recreates a
44
topic only if it is absent and then replays every record, so it refuses a
55
target topic that already holds data.
66

7+
The user's own action in both variants, at the tenant admin level, is the `RestoreJob`, plus the second `Kafka` in variant B. The scripts as written need admin access: variant A deletes and checks the topic through a CLI Pod and reads the refused restore's Pod log, and variant B checks the topic the same way, creates the target's Secret and waits on its `HelmRelease` and Strimzi `Kafka`, none of which a tenant role allows. The README's step table has the details.
8+
79
## A. In-place restore
810

911
Restore back into the same Kafka application.

‎examples/backups/kafka/README.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -36,15 +36,15 @@ For a faithful, offset-preserving Kafka backup, prefer a volume-snapshot strateg
3636
| `00-helpers.sh` | Shared bash helpers, env defaults, and the kafka-CLI / S3-secret helpers; sourced by every step. | n/a |
3737
| `01-create-strategy.sh` | Creates the cluster-scoped `Job` strategy (the Kafka backup/restore `PodTemplateSpec`). | admin |
3838
| `02-create-backupclass.sh` | Maps `apps.cozystack.io/Kafka` to that strategy, with the `topics` parameter (and the optional `replicationFactor` override). | admin |
39-
| `03-create-bucket.sh` | Provisions a `Bucket` and caches its S3 coordinates plus the endpoint's CA into `.bucket-info.env` (chmod 600; raw access keys). `cleanup.sh` removes this file. | tenant, **plus admin** for the CA copy: it reads a Secret in `tenant-root`, which a tenant persona is not granted (see the TLS bullet above) |
40-
| `04-create-kafka.sh` | Provisions a two-broker `Kafka`, creates the `<app>-backup-s3` Secret, seeds a topic (replication factor 2) with sentinel messages. | tenant |
39+
| `03-create-bucket.sh` | Provisions a `Bucket` and caches its S3 coordinates plus the endpoint's CA into `.bucket-info.env` (chmod 600; raw access keys). `cleanup.sh` removes this file. | **admin**. A tenant admin can create the `Bucket` itself, but the script also waits on its `HelmRelease` and COSI objects, reads the `bucket-<name>-backup` Secret, and copies the CA from a Secret in `tenant-root` (see the TLS bullet above); no tenant role grants access to `helmreleases` or `objectstorage.k8s.io`, or `get` on those Secrets |
40+
| `04-create-kafka.sh` | Provisions a two-broker `Kafka`, creates the `<app>-backup-s3` Secret, seeds a topic (replication factor 2) with sentinel messages. | **admin**. A tenant admin can create the `Kafka` itself, but the script also waits on its `HelmRelease` and Strimzi `Kafka`, creates the Secret, and seeds the topic through a CLI Pod it execs into; no tenant role grants access to `helmreleases` or `kafkas.kafka.strimzi.io`, `create` on `secrets` or `pods`, or `pods/exec` |
4141
| `05-create-backupjob.sh` | Submits a `BackupJob`, waits for Succeeded and caches the resolved `Backup` name into `.backup-name.env`. | tenant |
42-
| `06-restore-in-place.sh` | Deletes the topic and restores it into the same instance via `RestoreJob`, then submits a second `RestoreJob` that must be refused because the topic is no longer empty. | tenant |
43-
| `07-restore-to-copy.sh` | Provisions a second two-broker `Kafka` and restores into it via `RestoreJob.spec.targetApplicationRef`. | tenant |
44-
| `cleanup.sh` | Removes everything created by the demo. | admin or tenant |
42+
| `06-restore-in-place.sh` | Deletes the topic and restores it into the same instance via `RestoreJob`, then submits a second `RestoreJob` that must be refused because the topic is no longer empty. | **admin**. A tenant admin can submit the two `RestoreJob`s, but the script deletes and checks the topic through the CLI Pod and reads the refusal from the restore Pod's log; no tenant role grants `create` on `pods` or `pods/exec`, or `get` on `pods/log` |
43+
| `07-restore-to-copy.sh` | Provisions a second two-broker `Kafka` and restores into it via `RestoreJob.spec.targetApplicationRef`. | **admin**, for the same reasons as step 04. The tenant admin's part is the second `Kafka` and the `RestoreJob` |
44+
| `cleanup.sh` | Removes everything created by the demo. | **admin**: it deletes Secrets, the `Backup`, and the cluster-scoped `BackupClass` and strategy, and no tenant role grants `delete` on any of them |
4545
| `run-all.sh` | Convenience runner that executes 01..07 in order. | demo |
4646

47-
The scenario walk-throughs `90-scenario-admin-prepare.md`, `91-scenario-user-backup.md` and `92-scenario-user-restore.md` describe the same steps from the admin's and the tenant's side.
47+
The scenario walk-throughs `90-scenario-admin-prepare.md`, `91-scenario-user-backup.md` and `92-scenario-user-restore.md` describe the same steps from the admin's and the tenant's side, and say which parts of the tenant's side need admin access.
4848

4949
## Running
5050

‎examples/backups/nats/00-helpers.sh‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -131,7 +131,7 @@ stream_message_count() {
131131
# Create the "<app>-backup-s3" Secret the Job strategy Pod consumes, from the
132132
# bucket coordinates cached by 03-create-bucket.sh. The generic Job strategy -
133133
# unlike the app-specific drivers - has no chart support to emit this Secret,
134-
# so the tenant provides it. Called for the source app (step 04) and the
134+
# so the demo provides it. Called for the source app (step 04) and the
135135
# restore target (step 07).
136136
create_s3_secret() {
137137
local app="$1"

‎examples/backups/nats/01-create-strategy.sh‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,7 @@ spec:
6464
value: "{{ if .Backup }}{{ .Backup.ApplicationRef.Name }}{{ end }}"
6565
- name: MODE
6666
value: "{{ .Mode }}"
67-
# S3 coordinates from the tenant-provided <release>-backup-s3 Secret
67+
# S3 coordinates from the demo-provided <release>-backup-s3 Secret
6868
# (created by create_s3_secret in 00-helpers.sh from the Bucket).
6969
- name: AWS_ACCESS_KEY_ID
7070
valueFrom:

‎examples/backups/nats/03-create-bucket.sh‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
#!/bin/bash
22
# Step 03: Provision an in-cluster Bucket and cache its S3 coordinates. Unlike
33
# the ClickHouse demo - where the chart emits the backup Secret from
4-
# spec.backup.* - the generic Job strategy has no chart support, so the tenant
4+
# spec.backup.* - the generic Job strategy has no chart support, so the demo
55
# materialises the "<app>-backup-s3" Secret itself. This step only caches the
66
# coordinates; create_s3_secret (00-helpers.sh) turns them into per-app Secrets
77
# in steps 04 and 07.

0 commit comments

Comments
 (0)