138 lines
4.5 KiB
Markdown
138 lines
4.5 KiB
Markdown
# 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?**
|