From 433949ab5714843ef210cfae02b707585c5b86e5 Mon Sep 17 00:00:00 2001 From: codex Date: Sat, 25 Jul 2026 19:39:40 +0200 Subject: [PATCH] Import supporting rail-kubernetes docs --- docs/README.md | 5 + docs/canary-helm-template.md | 55 ++++++ docs/overlay-repo-pattern.md | 179 ++++++++++++++++++ docs/promote-rollback-onboarding.md | 71 +++++++ docs/railiance-run-command.md | 52 +++++ docs/source-import-plan.md | 13 +- docs/stage2-deploy-observe.md | 49 +++++ ...-K8S-WP-0001-bootstrap-and-wave1-import.md | 7 + 8 files changed, 423 insertions(+), 8 deletions(-) create mode 100644 docs/canary-helm-template.md create mode 100644 docs/overlay-repo-pattern.md create mode 100644 docs/promote-rollback-onboarding.md create mode 100644 docs/railiance-run-command.md create mode 100644 docs/stage2-deploy-observe.md diff --git a/docs/README.md b/docs/README.md index 1c50899..eaff010 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,6 +1,11 @@ # rail-kubernetes Docs - `app-toml-contract.md` — canonical workload declaration contract for the rail +- `overlay-repo-pattern.md` — compatibility-era overlay pattern on the path to `rapp-*` +- `canary-helm-template.md` — stage-aware canary/stable chart pattern - `deployment-lifecycle.md` — canonical stage 1 / 2 / 3 lifecycle contract +- `stage2-deploy-observe.md` — stage 2 command behavior contract +- `promote-rollback-onboarding.md` — representative lifecycle command path +- `railiance-run-command.md` — stage 1 command behavior contract - `wave-1-contract.md` — current rail contract and boundary summary - `source-import-plan.md` — source material and migration direction from existing repos diff --git a/docs/canary-helm-template.md b/docs/canary-helm-template.md new file mode 100644 index 0000000..54d4ce1 --- /dev/null +++ b/docs/canary-helm-template.md @@ -0,0 +1,55 @@ +# Canary Helm Template + +Generated Railiance overlays include a stage-aware Helm chart for Stage 2 +canaries and Stage 3 stable promotion. + +The chart keeps stable and canary release identities explicit: + +- `railiance.stableRelease` names the current stable release; +- `railiance.canaryRelease` names the Stage 2 candidate release; +- `railiance.stage` selects the rendered identity, labels, and selectors; +- `railiance.previousStable` records rollback context before promotion. + +## Traffic Shape + +The default Stage 2 values use an isolated canary ingress: + +```yaml +railiance: + stage: canary + traffic: + mode: isolated + +ingress: + enabled: true +``` + +This creates canary Deployment, Service, and Ingress resources without changing +the stable release. For environments that use Traefik weighted routing, set: + +```yaml +railiance: + traffic: + mode: weighted + provider: traefik + stableWeight: 95 + canaryWeight: 5 +``` + +The chart then renders a `TraefikService` and `IngressRoute` that split traffic +between the stable and canary services. Other ingress controllers can use the +same stable/canary values layout with controller-specific annotations or a later +provider template. + +## Observability And Safety + +Generated workloads include: + +- Prometheus-compatible scrape annotations on pods and services; +- readiness and liveness HTTP probes; +- conservative resource requests/limits for single-node clusters; +- separate `values/stage2-canary.yaml` and `values/stage3-production.yaml` so + canary exposure and stable promotion can be reviewed independently. + +Run `tests/stage2-template.sh` in the overlay repo before any Stage 2 attempt. +It verifies the scaffold and runs `helm template` when Helm is available. diff --git a/docs/overlay-repo-pattern.md b/docs/overlay-repo-pattern.md new file mode 100644 index 0000000..f3cc109 --- /dev/null +++ b/docs/overlay-repo-pattern.md @@ -0,0 +1,179 @@ +# Railiance Overlay Repo Pattern + +A Railiance overlay repo wraps a third-party upstream application without +forking Railiance deployment logic into the upstream source repository. + +The overlay repo owns the Railiance deployment contract, promotion evidence, +Helm/Kubernetes overlay, values, probes, and runbooks. The upstream repository +remains the source of application code and release artifacts. + +This pattern is a compatibility-era scaffolding model inside the +`rail-kubernetes` migration. Long-term first-class package ownership should +move toward `rapp-*` repos. Until the `rapp-*` path is fully materialized, the +overlay structure remains a useful generic pattern for Kubernetes-managed +workloads. + +## Goals + +- Keep upstream code and Railiance deployment mechanics separate. +- Make Stage 1, Stage 2, Stage 3, and rollback behavior reproducible from Git. +- Declare all platform dependencies, health checks, and secret references in + `railiance/app.toml` without plaintext secret values. +- Allow third-party applications to adopt the staged promotion lifecycle without + requiring changes to their upstream repositories. + +## Repo Layout + +A generated compatibility overlay repo should look like this: + +```text +-railiance-overlay/ + README.md + railiance/ + app.toml + upstream.toml + charts/ + / + Chart.yaml + values.yaml + templates/ + deployment.yaml + service.yaml + values/ + stage1.yaml + stage2-canary.yaml + stage3-production.yaml + patches/ + upstream/.gitkeep + tests/ + stage1.sh + runbooks/ + rollback.md + docs/ + promotion.md +``` + +When a workload graduates into a durable package repo, the preferred target is +to keep the same contract surfaces while moving the repo identity toward +`rapp-`. + +## Ownership Boundary + +The overlay repo owns: + +- `railiance/app.toml` staged promotion declaration; +- Railiance-specific Helm chart, values, probes, and runbooks; +- canary and promotion evidence expectations; +- secret references by approved route and target object name; +- compatibility notes for a specific upstream revision or release line. + +The upstream repo owns: + +- application source code; +- upstream build and release artifacts; +- upstream tests and release notes; +- upstream vulnerability and license notices. + +The overlay must not vendor upstream source by default. If a patch is required, +store the patch under `patches/upstream/` and record why the patch exists, when +it can be retired, and which upstream issue or release should replace it. + +## Required Files + +### `railiance/app.toml` + +This file follows `docs/app-toml-contract.md` and +`schemas/railiance-app.schema.json` from `rail-kubernetes`. It is the primary +machine-readable contract for promotion tooling. + +### `railiance/upstream.toml` + +This file records non-secret upstream identity: + +```toml +[upstream] +url = "https://example.com/vendor/app.git" +revision = "v1.2.3" +tracking = "tag" +license = "see-upstream" +notes = "Railiance overlay only; upstream code is not vendored here." +``` + +`revision` should be immutable where possible: tag, commit SHA, release id, or +image digest. Mutable branches are acceptable only before a workload becomes a +Stage 2 candidate. + +### `charts//` + +The chart is the Railiance deployment wrapper. It may start as a thin Helm +chart around an upstream image and grow only as required by the promotion gates. +Generated charts include stable/canary release identities, Prometheus-compatible +annotations, HTTP probes, resource limits, isolated canary ingress, and optional +Traefik weighted routing. Production-specific choices stay in `values/` files. + +### `values/` + +Stage values separate local validation, canary, and production settings: + +- `stage1.yaml`: local or dry-run defaults; +- `stage2-canary.yaml`: limited exposure canary defaults; +- `stage3-production.yaml`: stable production defaults. + +Secret values do not belong in these files. Use Kubernetes Secret, +ExternalSecret, OpenBao, KeyCape, or another approved route and record only the +reference name. + +### `tests/stage1.sh` And `tests/stage2-template.sh` + +Stage 1 should be runnable without production credentials. The generated script +performs syntax and Helm rendering checks when the relevant tools are available. + +Stage 2 template validation verifies the canary scaffold, stable/canary values, +Prometheus annotations, rollback labels, and Helm rendering when Helm is +available. Workload-specific tests can extend either script. + +### `runbooks/rollback.md` + +Rollback instructions must exist before Stage 2. Early overlays may include a +placeholder, but it must name the intended rollback target and verification +check. + +## Creation Tool + +During the migration window, the compatibility scaffold still comes from: + +```bash +railiance-cluster/tools/create_railiance_overlay_repo.sh \ + --app-id forgejo \ + --name "Forgejo" \ + --owner railiance-forge \ + --criticality critical \ + --upstream-url https://codeberg.org/forgejo/forgejo.git \ + --upstream-revision v12.0.0 \ + --out-dir /tmp/forgejo-railiance-overlay +``` + +The tool writes only local files. It does not call Gitea, clone upstream code, +fetch secrets, or push Git remotes. + +Long-term, the generic scaffolding behavior should move under the rail and/or +become `rapp-*`-aware rather than preserving the overlay name forever. + +## Promotion Use + +1. Generate or update the overlay repo. +2. Fill in accurate image, namespace, health, dependency, and rollback fields. +3. Validate `railiance/app.toml` against the schema. +4. Run `tests/stage1.sh` and `tests/stage2-template.sh`. +5. Use later Stage 2 and Stage 3 commands to deploy, observe, promote, and + rollback. + +## Safety Rules + +- No plaintext secrets in `railiance/app.toml`, values files, tests, runbooks, + or generated evidence. +- Do not hide deployment logic in upstream source patches. +- Do not promote mutable upstream branches to Stage 2/3 without an explicit + operator exception. +- Production-critical overlays require human approval before canary exposure and + production promotion. diff --git a/docs/promote-rollback-onboarding.md b/docs/promote-rollback-onboarding.md new file mode 100644 index 0000000..99ced46 --- /dev/null +++ b/docs/promote-rollback-onboarding.md @@ -0,0 +1,71 @@ +# Promote, Rollback, And Onboarding + +This guide shows the representative Railiance lifecycle for an overlay repo. +Commands default to plan mode so the path is repeatable before cluster access or +operator approval exists. + +## Stage 1 + +```bash +bin/railiance run /path/to/overlay --pretty +``` + +Stage 1 validates `railiance/app.toml`, local commands, and local checks. Save +the JSON result as non-secret evidence before Stage 2. + +## Stage 2 + +```bash +bin/railiance deploy --stage 2 /path/to/overlay --plan --pretty +bin/railiance observe --stage 2 /path/to/overlay --plan --pretty +``` + +When Helm, kubectl, cluster access, and approval evidence are ready: + +```bash +bin/railiance deploy --stage 2 /path/to/overlay --apply --approval-id +bin/railiance observe --stage 2 /path/to/overlay --live --pretty +``` + +For critical workloads, Stage 2 apply must not run until the operator has +approved canary exposure and rollback context is known. + +## Stage 3 + +```bash +bin/railiance promote /path/to/overlay --plan --pretty +bin/railiance rollback /path/to/overlay --plan --pretty +``` + +Promotion plan mode emits a `railiance.stage3-promote-result.v1` JSON result +with stable release identity, chart and values paths, previous-stable target, +expected evidence, and approval requirements. + +Rollback plan mode emits a `railiance.stage3-rollback-result.v1` JSON result +with rollback strategy, release identity, verification text, and apply-time +requirements. + +When approval evidence and Helm access are ready: + +```bash +bin/railiance promote /path/to/overlay --apply --approval-id +bin/railiance rollback /path/to/overlay --apply --approval-id --revision +``` + +Stage 3 apply fails closed if the chart or values are missing, previous stable +is not recorded, Helm is unavailable, or approval evidence is missing. Rollback +apply fails closed if the rollback strategy is missing, Helm is unavailable, +approval evidence is missing, or a Helm revision is required but absent. + +## Human Approval Points + +Critical infrastructure workloads require explicit operator approval before: + +- Stage 2 canary exposure; +- Stage 3 stable promotion; +- rollback apply, unless an incident runbook defines a narrower break-glass + process and records the evidence id. + +Progress notes should include only non-secret result summaries: schema version, +status, release, namespace, approval id, check counts, and command byte counts. +Do not paste command logs, kubeconfigs, tokens, or private service output. diff --git a/docs/railiance-run-command.md b/docs/railiance-run-command.md new file mode 100644 index 0000000..7390e2a --- /dev/null +++ b/docs/railiance-run-command.md @@ -0,0 +1,52 @@ +# Railiance Run Command + +`bin/railiance run` executes Stage 1 local validation for a repository that +contains `railiance/app.toml`. + +The command is intentionally local and conservative: + +- reads `railiance/app.toml` using the `railiance.app.v1` contract; +- runs `[stages.stage1].commands` from the app directory; +- evaluates Stage 1 check ids listed in `[stages.stage1].checks` when they can + be checked locally; +- emits a machine-readable `railiance.run-result.v1` JSON result; +- records command references, exit codes, durations, and output byte counts, + but not shell text or command stdout/stderr content; +- strips credentials, query strings, and fragments from URLs before reporting HTTP + check results. + +## Usage + +```bash +bin/railiance run /path/to/app-or-overlay --pretty +bin/railiance run . --json-out .railiance/stage1-result.json +``` + +The process exits `0` only when all Stage 1 commands and required checks pass. +Optional checks may be skipped without failing the run. For example, an optional +local health endpoint can be declared before a local server command exists. + +## Supported Local Checks + +- `command`: runs the check `run` command in the app directory. +- `http`: calls the declared URL and compares the HTTP status. +- `helm`: runs `helm template` when Helm is installed. Required Helm checks fail + if Helm is unavailable; optional Helm checks are skipped. + +Other check types are reported as skipped or failed depending on whether the +check is required. Stage 2 and Stage 3 checks are never executed by +`railiance run`. + +## Result Shape + +The JSON result includes: + +- app identity and source revision; +- contract path and app directory; +- command/check status summaries using contract references instead of raw shell + commands; +- expected evidence labels from Stage 1; +- timing and exit status metadata. + +The result is suitable for later promotion gates and State Hub progress notes, +without embedding secrets or verbose logs. diff --git a/docs/source-import-plan.md b/docs/source-import-plan.md index 591047f..892c0bd 100644 --- a/docs/source-import-plan.md +++ b/docs/source-import-plan.md @@ -10,6 +10,11 @@ Imported source documents from `railiance-cluster`: - `docs/deployment-lifecycle.md` - `docs/app-toml-contract.md` +- `docs/overlay-repo-pattern.md` +- `docs/canary-helm-template.md` +- `docs/stage2-deploy-observe.md` +- `docs/promote-rollback-onboarding.md` +- `docs/railiance-run-command.md` Imported source assets from `railiance-cluster`: @@ -18,14 +23,6 @@ Imported source assets from `railiance-cluster`: ## Pending First-Wave Imports -Expected source documents from `railiance-cluster`: - -- `docs/overlay-repo-pattern.md` -- `docs/canary-helm-template.md` -- `docs/stage2-deploy-observe.md` -- `docs/promote-rollback-onboarding.md` -- `docs/railiance-run-command.md` - Expected source assets from `railiance-cluster`: - `tools/create_railiance_overlay_repo.sh` diff --git a/docs/stage2-deploy-observe.md b/docs/stage2-deploy-observe.md new file mode 100644 index 0000000..b6e315b --- /dev/null +++ b/docs/stage2-deploy-observe.md @@ -0,0 +1,49 @@ +# Stage 2 Deploy And Observe + +`bin/railiance deploy --stage 2` and `bin/railiance observe --stage 2` provide +the repeatable command path for production canaries declared in +`railiance/app.toml`. + +Both commands default to non-mutating plan mode. + +## Deploy + +```bash +bin/railiance deploy --stage 2 /path/to/overlay --pretty +bin/railiance deploy --stage 2 /path/to/overlay --server-dry-run --pretty +bin/railiance deploy --stage 2 /path/to/overlay --apply --approval-id +``` + +Plan mode validates the local Stage 2 chart and values paths and emits a +`railiance.stage2-deploy-result.v1` JSON plan. It does not contact the cluster. + +`--server-dry-run` runs `helm upgrade --install --dry-run=server` when Helm and +cluster access are available. `--apply` runs the Helm canary apply path with +`--atomic --wait`. If Stage 2 declares `requires_approval = true`, apply mode +fails closed unless `--approval-id` is provided. + +The result records release identity, namespace, chart path, values path, +expected checks/evidence, precheck status, and command byte counts. It does not +embed Helm or kubectl logs. + +## Observe + +```bash +bin/railiance observe --stage 2 /path/to/overlay --pretty +bin/railiance observe --stage 2 /path/to/overlay --live --pretty +``` + +Plan mode emits the rollout, pod selector, ingress selector, health URL, and +metrics targets that live observation will query. + +Live mode uses `kubectl` to check rollout status, deployment JSON, canary pods, +ingress/routing resources, and pod metrics when metrics-server is available. +Metrics unavailability is reported separately so a canary can fail for rollout +or readiness problems without hiding missing observability. + +## Safety + +Stage 2 remains blocked when required local paths are missing, Helm is missing +for dry-run/apply, `kubectl` is missing for live observe, or approval evidence +is missing for an apply that requires approval. Use the emitted JSON as +non-secret evidence in State Hub progress notes. diff --git a/workplans/RAIL-K8S-WP-0001-bootstrap-and-wave1-import.md b/workplans/RAIL-K8S-WP-0001-bootstrap-and-wave1-import.md index 2c4237a..a1712a1 100644 --- a/workplans/RAIL-K8S-WP-0001-bootstrap-and-wave1-import.md +++ b/workplans/RAIL-K8S-WP-0001-bootstrap-and-wave1-import.md @@ -79,6 +79,13 @@ still pending. `examples/railiance/app.toml`. Helper command surfaces and the remaining supporting docs are still pending. +2026-07-25: Imported the remaining generic supporting docs from +`railiance-cluster`: `docs/overlay-repo-pattern.md`, +`docs/canary-helm-template.md`, `docs/stage2-deploy-observe.md`, +`docs/promote-rollback-onboarding.md`, and +`docs/railiance-run-command.md`. Helper scripts and command implementations +remain pending. + ## T03 - Prepare the compatibility handoff from `railiance-cluster` ```task