rail-kubernetes/INTENT.md

INTENT

Why This Repo Exists

rail-kubernetes exists so Railiance has a first-class home for the default execution rail used by platform services and managed workloads.

Before this repo, generic workload lifecycle semantics, workload declarations, and Kubernetes rollout helpers were mixed into railiance-cluster. That was pragmatic while Railiance had only one runtime path, but it is the wrong steady state once Railiance starts introducing multiple rails.

This repo establishes the durable answer to:

• how a Railiance-managed workload targets Kubernetes as a rail
• which workload lifecycle semantics are generic to Kubernetes-managed workloads
• which substrate guarantees the rail expects from S2
• where future packages such as rapp-openbao attach when they run on the default rail

What This Repo Must Protect

This repo must keep the wave-1 Kubernetes rail narrow and reusable.

That means:

• protect the distinction between rail semantics and cluster ownership
• protect the distinction between rail semantics and workload packaging
• keep the compatibility path from railiance-cluster explicit while the extraction is incomplete
• avoid encoding assumptions that only work for one workload or one substrate

What This Repo Is Not

This repo is not:

• the ownership home for the Kubernetes substrate
• the ownership home for OpenBao, Forgejo, or any other single workload
• the ownership home for one specific server or cluster substrate
• the place to normalize workload-specific operator commands

Initial Operating Context

Wave 1 is intentionally centered on Kubernetes.

Railiance should treat this repo as the default rail path until a later workload presents a strong enough reason to justify a different rail such as rail-knative.

The first version of this repo therefore prioritizes:

• a clean boundary with railiance-cluster
• a stable attachment point for future rapp-* repos
• compatibility with the currently published S2 substrate profile