77 lines
2.6 KiB
Markdown
77 lines
2.6 KiB
Markdown
# Cluster Compatibility Handoff
|
|
|
|
## Purpose
|
|
|
|
Define the migration-window handoff between `railiance-cluster` and
|
|
`rail-kubernetes` for the generic workload lifecycle surface.
|
|
|
|
Wave 1 makes `rail-kubernetes` the durable owner of the generic Kubernetes
|
|
rail contract. `railiance-cluster` remains the S2 substrate owner and keeps a
|
|
thin compatibility shim so current operators do not need a flag day.
|
|
|
|
## Canonical Command Owner
|
|
|
|
Use `rail-kubernetes/bin/railiance` as the canonical entrypoint for these
|
|
generic rail commands:
|
|
|
|
- `create-overlay`
|
|
- `run`
|
|
- `deploy`
|
|
- `observe`
|
|
- `promote`
|
|
- `rollback`
|
|
|
|
New behavior, docs, and fixes for those commands should land in
|
|
`rail-kubernetes` first.
|
|
|
|
## Cluster-Side Compatibility Shim
|
|
|
|
During the migration window, `railiance-cluster/bin/railiance` keeps the same
|
|
six command names but resolves them in this order:
|
|
|
|
1. If `RAILIANCE_RAIL_KUBERNETES_BIN` is set, use that executable path.
|
|
2. Else, if a sibling checkout exists at `../rail-kubernetes/bin/railiance`,
|
|
delegate to it.
|
|
3. Else, fall back to the temporary compatibility copies still present in
|
|
`railiance-cluster`.
|
|
|
|
If `RAILIANCE_RAIL_KUBERNETES_BIN` is set but not executable, the cluster-side
|
|
shim fails closed rather than silently using a different path.
|
|
|
|
This keeps existing `railiance-cluster/bin/railiance ...` invocations working
|
|
while shifting canonical ownership to `rail-kubernetes`.
|
|
|
|
## What Still Stays Outside The Handoff
|
|
|
|
The compatibility shim does not expand the rail boundary.
|
|
|
|
Still retained in `railiance-cluster` as S2 substrate operations:
|
|
|
|
- `backup`
|
|
- `preflight`
|
|
|
|
Still present in `railiance-cluster` but outside the `rail-kubernetes` handoff:
|
|
|
|
- shared bootstrap helpers such as `doctor`, `plan-host`, `cloudinit`,
|
|
`init-repo`, `build-spore`, `seed-local`, and `checklist`
|
|
- workload-specific helpers such as `deploy-triage-robustness` and
|
|
`admin-sync-smoke`
|
|
|
|
Those commands need their own long-term placement review; they are not part of
|
|
the generic rail contract.
|
|
|
|
## Operator Migration Path
|
|
|
|
Operators can move without changing command arguments:
|
|
|
|
1. Clone `rail-kubernetes` alongside `railiance-cluster`, or set
|
|
`RAILIANCE_RAIL_KUBERNETES_BIN` to the preferred checkout.
|
|
2. Continue using `railiance-cluster/bin/railiance` during the migration window
|
|
if needed; it will delegate when the rail repo is available.
|
|
3. Prefer `rail-kubernetes/docs/` as the canonical documentation surface for
|
|
the six generic lifecycle commands.
|
|
|
|
## Exit Condition
|
|
|
|
The migration window can end once current operator entrypoints and automation
|
|
no longer depend on the cluster-side fallback copies.
|