2026-07-25 18:57:55 +02:00
|
|
|
# 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
|
|
|
|
|
|
2026-07-26 02:20:00 +02:00
|
|
|
- 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
|
2026-07-25 18:57:55 +02:00
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## 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
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Related / Overlapping Repositories
|
|
|
|
|
|
|
|
|
|
- `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
|
|
|
|
|
|
|
|
|
|
```capability
|
|
|
|
|
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.
|
