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:

If RAILIANCE_RAIL_KUBERNETES_BIN is set, use that executable path.
Else, if a sibling checkout exists at ../rail-kubernetes/bin/railiance, delegate to it.
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:

Clone rail-kubernetes alongside railiance-cluster, or set RAILIANCE_RAIL_KUBERNETES_BIN to the preferred checkout.
Continue using railiance-cluster/bin/railiance during the migration window if needed; it will delegate when the rail repo is available.
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.

2.6 KiB Raw Blame History