4.5 KiB
INTENT
This file captures why this repository exists, the direction it is moving toward, and the kind of system it is meant to become. It is intentionally aspirational and stable, not a description of current implementation.
One-liner
The application workload layer - turning platform capabilities into reliable, user-facing Railiance services with repeatable release operations.
Why This Exists
A converged platform is not yet a useful experience for users. Someone must take shared runtime, data, identity, registry, and enablement capabilities and turn them into deployed workloads with clear release configuration, operator runbooks, and app-level verification.
Without a disciplined application layer:
- deployment concerns scatter across source repos and live clusters,
- lower-layer boundaries blur when apps need "just one" platform tweak,
- operators rediscover the same ingress, secret, probe, and registry traps,
- and user-facing services become difficult to promote, debug, and recover.
This layer exists to make application releases repeatable, bounded, and operable, so Railiance can add services without turning every deployment into a new archaeology exercise.
The Mission
Where we are going.
To become the canonical home for Railiance application workload releases - the Helm values, Kubernetes manifests, app-level runbooks, smoke checks, and operator recipes that make user-facing services safe to ship on top of the platform.
This means:
- Application deployments have source-controlled release contracts
- Operators can deploy, verify, and recover apps through repeatable runbooks
- Apps consume lower-layer capabilities through stable handoff points
- Source application repos remain responsible for their code, packages, and build artifacts
- The first-app lessons become reusable patterns for the next app
Core Principles
1. Workloads, Not Runtime
Own the application releases that run on the platform. Do not own the infrastructure, cluster runtime, or shared platform services beneath them.
2. Release Contracts over Source Internals
This repo should describe how an application is released and operated on Railiance, not become the application's source-code repository.
3. Repeatable Operations
Deploys, upgrades, smoke tests, migrations, and emergency checks should be codified as scripts, Make targets, and runbooks rather than remembered by operators.
4. Clear Lower-Layer Handoffs
Applications consume databases, secrets, storage, identity, and runtime capabilities through explicit contracts with S1-S4. This layer does not reach down and mutate those layers to make an app work.
5. Evidence Before Confidence
An app release is healthy when probes, status checks, smoke tests, and operator evidence say it is healthy, not merely because manifests applied successfully.
6. App Workloads, Forge Consumers
Applications consume forge artifacts without owning forge runtime state. Early application releases should leave behind reusable deployment patterns that survive future forge and app migrations.
What This Is (Conceptually)
This layer is:
- an application workload release layer
- a home for Helm release configuration and app-level manifests
- an operator runbook and deployment guardrail surface
- a bridge from shared platform capabilities to user-facing services
- a place where app deployment lessons become reusable S5 patterns
What This Is Not
This layer is not:
- the infrastructure substrate beneath Railiance
- the Kubernetes runtime or cluster addon layer
- the shared platform-services layer for databases, secrets, cache, or storage
- the CI/CD and developer enablement layer
- the source-code home for deployed applications
- a secret custody authority
It is the last-mile release and operations surface for services users actually touch.
Direction of Evolution
This layer is expected to evolve toward:
- A reusable new S5 app release checklist
- Stronger image and package promotion patterns
- Clearer backup, restore, and data ownership handoffs with S3
- More complete smoke, migration, rollback, and observability recipes
- Cleaner consumption of forge-owned artifacts and evidence from app release runbooks
- Self-evidencing, reviewable application readiness before promotion
Guiding Question
How can each Railiance application become easy to release, verify, operate, and recover without weakening the boundaries of the layers beneath it?