From 13ae1498e48ceabe3b8a427388a2c01528fff05d Mon Sep 17 00:00:00 2001 From: ZDDC Date: Tue, 5 May 2026 08:33:04 -0500 Subject: [PATCH] docs(helm): describe dev chart's OverlayFS isolation in README + Chart.yaml The dev chart's overlay-isolation layer (added in 9765fa2) was not called out in helm/README.md or zddc-server-dev/Chart.yaml. Readers comparing the two charts saw "same shape but tracks main" without learning that the dev chart wraps the data PVC in OverlayFS so its writes never mutate the underlying store. Co-Authored-By: Claude Opus 4.7 (1M context) --- helm/README.md | 14 ++++++++++---- helm/zddc-server-dev/Chart.yaml | 13 ++++++++----- 2 files changed, 18 insertions(+), 9 deletions(-) diff --git a/helm/README.md b/helm/README.md index 155a289..3b58d7a 100644 --- a/helm/README.md +++ b/helm/README.md @@ -11,11 +11,15 @@ alpine + the freshly built static binary. | Chart | When to use | |---|---| -| **`zddc-server-prod/`** | Production. Pin `zddc.gitRef` to a stable tag (`zddc-server-vX.Y.Z`). Slower probe cadence; image-pull policy `IfNotPresent`. | -| **`zddc-server-dev/`** | Development / soak. Tracks `main` by default; `helm upgrade` triggers a pod recreate so each rollout pulls the latest commit. Faster probes; debug-level logging (request headers logged — sensitive). | +| **`zddc-server-prod/`** | Production. Pin `zddc.gitRef` to a stable tag (`zddc-server-vX.Y.Z`). Slower probe cadence; image-pull policy `IfNotPresent`. Mounts the data PVC directly RW at `ZDDC_ROOT`. | +| **`zddc-server-dev/`** | Development / soak. Tracks `main` by default; `helm upgrade` triggers a pod recreate so each rollout pulls the latest commit. Faster probes; debug-level logging (request headers logged — sensitive). Wraps the data PVC in **OverlayFS** (lower = PVC mounted RO, upper = ephemeral `emptyDir`) so dev-side writes never mutate the underlying store. Use this shape when the dev replica points at the same data as prod. | The chart values are nearly identical between the two; the differences -are encoded as defaults in each chart's `values.yaml.example`. +are encoded as defaults in each chart's `values.yaml.example`. The +dev chart's overlay-isolation layer is a structural difference, not a +values-level toggle — see `zddc-server-dev/templates/deployment.yaml` +for the privileged init container and the `data-readonly` / +`overlay-scratch` / `data` volume sandwich. ## Quick start @@ -55,7 +59,9 @@ helm upgrade zddc-server-dev helm/zddc-server-dev/ -f my-dev-values.yaml and starts the main container against that binary. - Wires the `ZDDC_*` environment-variable contract (root path, addr, email header, CORS allowlist, log level, index path). -- Mounts a caller-supplied PersistentVolumeClaim at `ZDDC_ROOT`. +- Mounts a caller-supplied PersistentVolumeClaim at `ZDDC_ROOT` (prod + chart) or as the OverlayFS lowerdir behind a merged `ZDDC_ROOT` + (dev chart). - Optionally creates an Ingress (`ingress.enabled: true`). **Does not:** diff --git a/helm/zddc-server-dev/Chart.yaml b/helm/zddc-server-dev/Chart.yaml index c758455..5c0b07d 100644 --- a/helm/zddc-server-dev/Chart.yaml +++ b/helm/zddc-server-dev/Chart.yaml @@ -1,11 +1,14 @@ apiVersion: v2 name: zddc-server-dev description: | - Development deployment of zddc-server. Same shape as zddc-server-prod - but tracks main HEAD (rebuilt on every pod restart), runs at debug - log level, has faster probe cadence for quick feedback, and uses - smaller resource limits. Intended for ephemeral / soak / preview - environments — not for production traffic. + Development deployment of zddc-server. Tracks main HEAD (rebuilt on + every pod restart), runs at debug log level, has faster probe + cadence for quick feedback, and uses smaller resource limits. + Wraps the data PVC in OverlayFS — lower (PVC) mounted RO, upper an + ephemeral emptyDir — so dev-side writes never mutate the underlying + store, making it safe to point at the same data PVC as prod. + Intended for ephemeral / soak / preview environments — not for + production traffic. type: application version: 0.1.0 appVersion: "main"