SCOPE

This file helps you quickly understand what this repository is about, when it is relevant, and when it is not. It is intentionally lightweight and may be incomplete.

One-liner

Default Railiance execution rail for generic workload-on-Kubernetes semantics.

Core Idea

rail-kubernetes is the first concrete rail-* repo in Railiance. It exists to hold the generic execution contract for Railiance-managed workloads that run on Kubernetes, without keeping those semantics mixed into the S2 ownership repo.

In Scope

Kubernetes rail declaration and compatibility notes
Generic workload lifecycle semantics for Kubernetes-managed workloads
Generic workload contract surface such as railiance/app.toml
Generic rollout, observe, promote, and rollback semantics for the rail
Migration compatibility guidance while the extraction from railiance-cluster is still in progress

Out of Scope

k3s bootstrap and cluster installation
cluster-level ingress, operator, and certificate ownership
cluster backup, restore, and preflight safety rails
workload-specific wrappers and app packaging
substrate inventories and machine grouping

Relevant When

Defining how a workload targets the default Kubernetes rail
Moving generic workload lifecycle material out of railiance-cluster
Attaching a rapp-* package to its Kubernetes execution contract
Clarifying which S2 substrate facts the rail may depend on

Not Relevant When

The work is purely cluster substrate ownership
The work is workload-specific packaging
The work is substrate inventory or server grouping

Current State

Status: first-wave bootstrap complete
Implementation: declaration, generic lifecycle docs/tooling, and the cluster compatibility handoff are present
Stability: early but usable
Usage: canonical wave-1 home for the default Kubernetes rail

How It Fits

Upstream dependencies: railiance-cluster, railiance-master
Downstream consumers: future rapp-* repos and reefs that host the Kubernetes rail
Often used with: railiance-fabric, railiance-platform, railiance-infra

Terminology

Preferred terms: rail, execution contract, workload lifecycle, substrate profile
Also known as: default base rail
Potentially confusing terms: this repo defines rail semantics; it does not own the Kubernetes substrate itself

railiance-cluster — owns the Kubernetes substrate; rail-kubernetes owns the generic workload-on-Kubernetes contract
railiance-master — defines the framework architecture and boundary
future rapp-* repos — own workload packaging and scaffolding on top of this rail
future reef-* repos — own the substrate boundaries that host this rail

Getting Oriented

Start with: README.md, INTENT.md
Key files / directories: declarations/, docs/, workplans/
Entry points: declarations/rail.yaml, docs/wave-1-contract.md

Provided Capabilities

type: governance
title: Kubernetes execution rail contract
description: Defines the generic execution contract for Railiance-managed workloads that run on Kubernetes.
keywords: [railiance, rail, kubernetes, workload, execution]

Notes

Keep this repo generic. If a behavior is specific to one workload or one substrate, it belongs somewhere else.

3.4 KiB Raw Permalink Blame History