railiance-cluster/docs/overlay-repo-pattern.md

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.

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 overlay repo should look like this:

<app>-railiance-overlay/
  README.md
  railiance/
    app.toml
    upstream.toml
  charts/
    <app>/
      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

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 railiance-cluster. It is the primary machine-readable contract for promotion tooling.

railiance/upstream.toml

This file records non-secret upstream identity:

[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/<app>/

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

Use:

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.

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 T06-T07 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.