railiance-master/docs/rail-kubernetes-boundary.md

Wave 1 rail-kubernetes Boundary

Date: 2026-07-25

Purpose

Define the wave-1 extraction boundary between railiance-cluster and a future rail-kubernetes repo.

This document exists to make rail-kubernetes real rather than rhetorical. Today, railiance-cluster already contains the practical contract for running managed workloads on Kubernetes:

• docs/deployment-lifecycle.md
• docs/app-toml-contract.md
• docs/overlay-repo-pattern.md
• schemas/railiance-app.schema.json
• examples/railiance/app.toml
• bin/railiance
• tools/cmd/railiance-run
• tools/cmd/railiance-stage2
• tools/cmd/railiance-stage3
• tools/create_railiance_overlay_repo.sh

That is already a rail in substance. The problem is that it currently lives inside the S2 cluster-runtime repo.

Decision Summary

• rail-kubernetes is the default base rail for wave 1.
• railiance-cluster remains the S2 owner of the Kubernetes substrate.
• rail-kubernetes owns the generic workload-on-Kubernetes execution contract.
• Workload-specific helpers currently living in railiance-cluster are not part of the long-term boundary for either repo. They are migration debt that must be rehomed.

What railiance-cluster Keeps

railiance-cluster remains responsible for the Kubernetes substrate itself.

It keeps ownership of:

• k3s installation, upgrade, and baseline configuration
• cluster networking, ingress controllers, DNS, and certificate plumbing
• cluster operators and addons such as cert-manager, CloudNative PG operator, ArgoCD, admission controllers, and similar cluster-scoped services
• kubeconfig management, runtime access patterns, and cluster backup/restore posture
• cluster smoke tests that prove substrate readiness
• cluster-level runbooks for substrate recovery, upgrade, access, and failure handling
• cluster capability declarations that tell higher layers what the substrate actually supports

railiance-cluster may describe the prerequisites a rail needs from the substrate, but it should not own the workload lifecycle semantics that run on top of those prerequisites.

What rail-kubernetes Must Own

rail-kubernetes owns the generic contract for Railiance-managed workloads that run on Kubernetes.

It should own:

• the three-stage lifecycle semantics for Kubernetes-backed workloads
• the canonical railiance/app.toml contract for the Kubernetes rail
• the machine-readable schema and reference example for that contract
• the generic Stage 1, Stage 2, and Stage 3 CLI/tooling
• Kubernetes-specific check types, rollout modes, and rollback expectations
• the generic packaging pattern for Kubernetes-managed rapps
• the generic repo scaffold for Kubernetes-targeting wrappers
• compatibility guidance for how a rapp declares Kubernetes namespaces, releases, probes, ingress, routing, and rollback
• the documented compatibility path from today's overlay pattern into future rapp-* repos

In short:

• railiance-cluster answers "is the Kubernetes substrate present and healthy?"
• rail-kubernetes answers "how does a Railiance-managed workload run on that substrate?"

What Should Not Stay In Either Boundary

Some items currently inside railiance-cluster are not good long-term residents of either railiance-cluster or the future rail-kubernetes.

Examples include workload-specific helpers such as:

• deploy-triage-robustness
• admin-sync-smoke
• workload-specific runtime reconcile flows tied to activity-core or similar single-workload concerns

These belong with the owning workload or ownership repo unless they are refactored into clearly generic rail behavior.

rail-kubernetes must not become a second junk drawer after the split.

File And Artifact Migration Map

Current location in railiance-cluster	Target owner	Notes
docs/deployment-lifecycle.md	rail-kubernetes	Generic workload lifecycle, no longer S2-owned
docs/app-toml-contract.md	rail-kubernetes	Base rail contract for Kubernetes-managed workloads
schemas/railiance-app.schema.json	rail-kubernetes	Versioned workload declaration schema
examples/railiance/app.toml	rail-kubernetes	Reference contract example
docs/overlay-repo-pattern.md	rail-kubernetes	Keep as compatibility doc, evolve toward rapp-* language
tools/create_railiance_overlay_repo.sh	rail-kubernetes	Keep behavior initially, then retarget toward rapp-* scaffolding
docs/railiance-run-command.md	rail-kubernetes	Stage 1 command reference
docs/stage2-deploy-observe.md	rail-kubernetes	Stage 2 command reference
tools/cmd/railiance-run	rail-kubernetes	Generic Stage 1 tooling
tools/cmd/railiance-stage2	rail-kubernetes	Generic Stage 2 tooling
tools/cmd/railiance-stage3	rail-kubernetes	Generic Stage 3 tooling
bin/railiance generic lifecycle commands	rail-kubernetes	run, deploy, observe, promote, rollback, create-overlay
bin/railiance substrate/bootstrap commands	railiance-cluster	doctor, plan-host, cloudinit, backup, preflight, similar substrate helpers
tests/smoke_kube.sh, cluster bootstrap tests	railiance-cluster	Substrate health proof
workload-specific reconcile helpers	rehome later	Move to owner repo or rewrite as generic rail helpers

The Interface Between The Two Repos

The clean split depends on a narrow interface.

railiance-cluster should publish a Kubernetes substrate profile that rail-kubernetes can consume. At minimum, that profile should declare:

• cluster distro and supported Kubernetes version range
• ingress controller and ingress classes
• supported canary modes, such as isolated and optional weighted
• certificate management path
• default storage classes and stateful-workload constraints
• required or optional operators available to workloads
• namespace and RBAC expectations for managed workloads
• observability surfaces available for health, logs, and metrics
• approved secret-delivery patterns available on this substrate

rail-kubernetes should not assume a capability the substrate profile does not declare.

This keeps the substrate owner and the rail owner separate while still letting them compose.

Migration-Safe Path

The split should happen in six steps.

1. Create rail-kubernetes with the copied contract docs, schema, examples, and generic Stage 1-3 tooling now living in railiance-cluster.
2. Leave compatibility shims in railiance-cluster for one migration window. The cluster repo may keep a thin bin/railiance wrapper that delegates the generic lifecycle commands to rail-kubernetes.
3. Update the moved docs in railiance-cluster to become short boundary notes that point to rail-kubernetes as the owning source.
4. Keep accepting the current <app>-railiance-overlay pattern during the migration window, even though the long-term direction is toward rapp-*.
5. Rehome or delete workload-specific helpers that do not belong in either the substrate repo or the generic Kubernetes rail.
6. Only after rail-kubernetes is stable should Railiance add rail-knative.

This path avoids breaking current users while making the new boundary real.

Follow-On Path For rail-knative

rail-knative is the first expected follow-on rail, motivated by the need to run qonto-assistent.

That follow-on rail should:

• depend on the Kubernetes substrate being described cleanly first
• reuse the top-level Railiance workload and promotion model where that remains sensible
• own Knative-specific runtime semantics such as revisions, scale-to-zero, traffic splitting, activator behavior, and event-driven behavior
• avoid forcing Knative-specific design choices back into the wave-1 rail-kubernetes boundary

The test for wave 1 is not "can Railiance describe all future rails now?"

The test is "can Railiance separate the Kubernetes base rail cleanly enough that rail-knative can be added later without another taxonomy rewrite?"

Risks To Watch

• If railiance-cluster keeps generic workload lifecycle ownership, rail-kubernetes will be nominal only.
• If rail-kubernetes absorbs substrate bootstrap and operator ownership, it stops being a rail and becomes a second cluster repo.
• If workload-specific helpers are moved unchanged into rail-kubernetes, the split will preserve the current ambiguity instead of reducing it.
• If rapp-* migration is delayed too long, the old overlay naming and the new workload-package model will drift apart.

Outcome

Wave 1 should produce a base Kubernetes rail with a clean contract and a backward-compatible migration path.

That is enough to start practical repo separation without pretending the rest of the rail family already exists.