166 lines
5.2 KiB
Markdown
166 lines
5.2 KiB
Markdown
# 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:
|
|
|
|
```text
|
|
<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:
|
|
|
|
```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/<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:
|
|
|
|
```bash
|
|
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.
|