diff --git a/README.md b/README.md index ac81c8b..c0012ea 100644 --- a/README.md +++ b/README.md @@ -7,20 +7,23 @@ cluster facts that downstream workload rails depend on. This repo is the Kubernetes substrate owner, not the long-term home for the generic workload-on-Kubernetes contract. The staged workload lifecycle, -`railiance/app.toml`, and overlay/wrapper scaffolding still live here as a -compatibility layer and are being prepared for extraction to a future -`rail-kubernetes` repo. +`railiance/app.toml`, and overlay/wrapper scaffolding now belong canonically to +`rail-kubernetes`; this repo keeps only a migration-window compatibility shim +and temporary compatibility copies while the split completes. ## Current Boundary - S2-owned here: k3s bootstrap, Helm and kubeconfig access, cluster-level backup/preflight, smoke checks, and published substrate expectations. -- Transitional here only: generic Stage 1/2/3 workload lifecycle semantics, - `railiance/app.toml`, canary/promotion CLI commands, and overlay scaffolding. +- Transitional here only: the compatibility shim and temporary copies for the + generic Stage 1/2/3 workload lifecycle, `railiance/app.toml`, canary and + promotion CLI commands, and overlay scaffolding. - Reviewed move map: [docs/rail-kubernetes-extraction-map.md](docs/rail-kubernetes-extraction-map.md) - Published substrate profile: [docs/rail-kubernetes-substrate-profile.md](docs/rail-kubernetes-substrate-profile.md) +- Compatibility shim: + [docs/rail-kubernetes-compatibility-shim.md](docs/rail-kubernetes-compatibility-shim.md) ## Quick Start diff --git a/WORK-RECORDS.md b/WORK-RECORDS.md index 9db6547..d4a927a 100644 --- a/WORK-RECORDS.md +++ b/WORK-RECORDS.md @@ -13,7 +13,7 @@ | workplan | RAIL-BS-WP-0009 | finished | — | workplans/RAIL-BS-WP-0009-activity-core-admin-sync-smoke.md | | workplan | RAIL-BS-WP-0010 | finished | — | workplans/RAIL-BS-WP-0010-weekly-legacy-meter-review-rollout.md | | workplan | RAIL-BS-WP-0011 | finished | — | workplans/RAIL-BS-WP-0011-legacy-meter-8h-capture-image-reconcile.md | -| workplan | RAIL-BS-WP-0012 | active | — | workplans/RAIL-BS-WP-0012-rail-kubernetes-extraction.md | +| workplan | RAIL-BS-WP-0012 | finished | — | workplans/RAIL-BS-WP-0012-rail-kubernetes-extraction.md | | task | RAIL-BS-WP-0007-T01 | todo | — | workplans/RAIL-BS-WP-0007-threephoenix-ha-cluster.md | | task | RAIL-BS-WP-0007-T02 | todo | — | workplans/RAIL-BS-WP-0007-threephoenix-ha-cluster.md | | task | RAIL-BS-WP-0007-T03 | todo | — | workplans/RAIL-BS-WP-0007-threephoenix-ha-cluster.md | @@ -39,4 +39,4 @@ | task | RAIL-BS-WP-0012-T01 | done | — | workplans/RAIL-BS-WP-0012-rail-kubernetes-extraction.md | | task | RAIL-BS-WP-0012-T02 | done | — | workplans/RAIL-BS-WP-0012-rail-kubernetes-extraction.md | | task | RAIL-BS-WP-0012-T03 | done | — | workplans/RAIL-BS-WP-0012-rail-kubernetes-extraction.md | -| task | RAIL-BS-WP-0012-T04 | wait | — | workplans/RAIL-BS-WP-0012-rail-kubernetes-extraction.md | +| task | RAIL-BS-WP-0012-T04 | done | — | workplans/RAIL-BS-WP-0012-rail-kubernetes-extraction.md | diff --git a/bin/railiance b/bin/railiance index 1fabd75..2849968 100755 --- a/bin/railiance +++ b/bin/railiance @@ -5,6 +5,53 @@ set -euo pipefail ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" PATH="${ROOT}/tools/cmd:${PATH}" +resolve_rail_kubernetes_bin() { + if [[ -n "${RAILIANCE_RAIL_KUBERNETES_BIN:-}" ]]; then + if [[ -x "${RAILIANCE_RAIL_KUBERNETES_BIN}" ]]; then + printf '%s\n' "${RAILIANCE_RAIL_KUBERNETES_BIN}" + return 0 + fi + echo "ERROR: RAILIANCE_RAIL_KUBERNETES_BIN is not executable: ${RAILIANCE_RAIL_KUBERNETES_BIN}" >&2 + return 2 + fi + + local sibling="${ROOT}/../rail-kubernetes/bin/railiance" + if [[ -x "${sibling}" ]]; then + printf '%s\n' "${sibling}" + return 0 + fi + + return 1 +} + +run_compat_command() { + local cmd="$1" + shift || true + + local delegate_bin="" + local resolve_status=0 + if delegate_bin="$(resolve_rail_kubernetes_bin)"; then + exec "${delegate_bin}" "${cmd}" "$@" + else + resolve_status=$? + fi + + if [[ "${resolve_status}" -eq 2 ]]; then + exit 1 + fi + + echo "WARN: rail-kubernetes delegate not found; using compatibility implementation from railiance-cluster" >&2 + case "${cmd}" in + create-overlay) bash "$ROOT/tools/create_railiance_overlay_repo.sh" "$@" ;; + run) exec railiance-run "$@" ;; + deploy) exec railiance-stage2 deploy "$@" ;; + observe) exec railiance-stage2 observe "$@" ;; + promote) exec railiance-stage3 promote "$@" ;; + rollback) exec railiance-stage3 rollback "$@" ;; + *) echo "Unknown compatibility command: ${cmd}" >&2; exit 2 ;; + esac +} + usage() { cat <<'EOF' Usage: bin/railiance [args] @@ -16,12 +63,12 @@ Commands: gen-ssh-key Generate SSH key and show public part cloudinit Emit minimal cloud-init user-data init-repo Idempotently furnish repo housekeeping - create-overlay Scaffold a Railiance overlay repo for an upstream app - run Run Stage 1 local validation from railiance/app.toml - deploy Plan/apply Stage 2 canary deployment - observe Plan/run Stage 2 observation checks - promote Plan/apply Stage 3 stable promotion - rollback Plan/apply rollback to previous stable + create-overlay Delegate to rail-kubernetes or use local compatibility scaffold + run Delegate to rail-kubernetes or run local Stage 1 compatibility path + deploy Delegate to rail-kubernetes or run local Stage 2 compatibility path + observe Delegate to rail-kubernetes or run local Stage 2 compatibility path + promote Delegate to rail-kubernetes or run local Stage 3 compatibility path + rollback Delegate to rail-kubernetes or run local Stage 3 compatibility path deploy-triage-robustness Deploy ACTIVITY-WP-0016 and prove daily-triage validation admin-sync-smoke @@ -49,12 +96,12 @@ case "$cmd" in ;; cloudinit) cat "$ROOT/cloudinit/user-data.yaml" ;; init-repo) bash "$ROOT/tools/furnish_railiance_repo.sh" ;; - create-overlay) bash "$ROOT/tools/create_railiance_overlay_repo.sh" "$@" ;; - run) exec railiance-run "$@" ;; - deploy) exec railiance-stage2 deploy "$@" ;; - observe) exec railiance-stage2 observe "$@" ;; - promote) exec railiance-stage3 promote "$@" ;; - rollback) exec railiance-stage3 rollback "$@" ;; + create-overlay) run_compat_command create-overlay "$@" ;; + run) run_compat_command run "$@" ;; + deploy) run_compat_command deploy "$@" ;; + observe) run_compat_command observe "$@" ;; + promote) run_compat_command promote "$@" ;; + rollback) run_compat_command rollback "$@" ;; deploy-triage-robustness) exec railiance-deploy-activity-core-triage-robustness "$@" ;; admin-sync-smoke) exec railiance-admin-sync-smoke "$@" ;; build-spore) bash "$ROOT/tools/build_spore.sh" ;; diff --git a/docs/README.md b/docs/README.md index 6172bd8..0da1fb4 100644 --- a/docs/README.md +++ b/docs/README.md @@ -19,12 +19,14 @@ Use the sections below to keep those concerns separate. - [rail-kubernetes extraction map](rail-kubernetes-extraction-map.md) - [rail-kubernetes substrate profile](rail-kubernetes-substrate-profile.md) +- [rail-kubernetes compatibility shim](rail-kubernetes-compatibility-shim.md) ## Transitional Workload-Contract Docs These docs describe the generic workload-on-Kubernetes contract. They are still -hosted in this repo for compatibility, but they are targeted for extraction to -future `rail-kubernetes`. +hosted in this repo for compatibility, but canonical ownership now lives in +`rail-kubernetes` and the cluster repo should keep only temporary copies or +pointer docs during the migration window. - [Deployment lifecycle](deployment-lifecycle.md) - [Railiance app.toml contract](app-toml-contract.md) diff --git a/docs/rail-kubernetes-compatibility-shim.md b/docs/rail-kubernetes-compatibility-shim.md new file mode 100644 index 0000000..7973760 --- /dev/null +++ b/docs/rail-kubernetes-compatibility-shim.md @@ -0,0 +1,45 @@ +# rail-kubernetes Compatibility Shim + +## Purpose + +Record the migration-window behavior that keeps current +`railiance-cluster/bin/railiance` users working while canonical ownership of +the generic workload lifecycle commands moves to `rail-kubernetes`. + +## Delegated Commands + +The cluster-side shim covers only these generic rail commands: + +- `create-overlay` +- `run` +- `deploy` +- `observe` +- `promote` +- `rollback` + +For those commands, `railiance-cluster/bin/railiance` now delegates to +`rail-kubernetes/bin/railiance` when a configured or sibling checkout exists. + +Resolution order: + +1. `RAILIANCE_RAIL_KUBERNETES_BIN` +2. sibling checkout at `../rail-kubernetes/bin/railiance` +3. temporary local compatibility copy in `railiance-cluster` + +If `RAILIANCE_RAIL_KUBERNETES_BIN` is set but not executable, the shim fails +closed. + +## Commands Not Covered + +These remain outside the handoff: + +- S2 substrate commands such as `backup` and `preflight` +- 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` + +## Canonical Home + +The canonical rail-side migration contract lives in the sibling +`rail-kubernetes` repo at `docs/cluster-compatibility-handoff.md`. diff --git a/workplans/RAIL-BS-WP-0012-rail-kubernetes-extraction.md b/workplans/RAIL-BS-WP-0012-rail-kubernetes-extraction.md index 84c1fa6..ee135a2 100644 --- a/workplans/RAIL-BS-WP-0012-rail-kubernetes-extraction.md +++ b/workplans/RAIL-BS-WP-0012-rail-kubernetes-extraction.md @@ -4,11 +4,11 @@ type: workplan title: "rail-kubernetes extraction from railiance-cluster" domain: financials repo: railiance-cluster -status: active +status: finished owner: codex topic_slug: railiance created: "2026-07-25" -updated: "2026-07-25" +updated: "2026-07-26" state_hub_workstream_id: "2b01ce91-35be-4947-832b-2f462c6ba472" --- @@ -107,7 +107,7 @@ expectations, and explicit non-guarantees for wave 1. ```task id: RAIL-BS-WP-0012-T04 -status: wait +status: done priority: medium state_hub_task_id: "fdc9fa63-bee2-4774-b92f-63cf7a315603" ``` @@ -120,6 +120,13 @@ docs left behind in `railiance-cluster`. Done when the migration can proceed without a flag day for current users. +2026-07-26: Added `docs/rail-kubernetes-compatibility-shim.md` and updated the +cluster dispatcher so `create-overlay`, `run`, `deploy`, `observe`, `promote`, +and `rollback` delegate to `rail-kubernetes/bin/railiance` when a configured +or sibling checkout exists. The cluster repo keeps a temporary local fallback +for those six commands, while retained S2 commands and unrelated helper debt +stay outside the handoff. + ## Notes This workplan is intentionally repo-local. The framework-level separation plan