147 lines
5.5 KiB
Markdown
147 lines
5.5 KiB
Markdown
# 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
|
|
|
|
S2 Cluster Runtime layer of the Railiance OAS Stack - owns k3s installation,
|
|
Helm, ingress, CNI, admission controllers, operators, kubeconfig management,
|
|
and the substrate facts published to downstream workload rails.
|
|
|
|
---
|
|
|
|
## Core Idea
|
|
|
|
Railiance is structured as five independent repos per OAS Stack layer. This repo
|
|
is S2. It installs and configures the Kubernetes cluster runtime: k3s, Helm,
|
|
ingress controller, CNI plugin, cluster addons and operators. S1 (OS) must be
|
|
converged before S2 can run. S2 explicitly does not own platform services
|
|
(PostgreSQL, caches) - those are S3.
|
|
|
|
Some generic workload lifecycle docs and commands still live here as a temporary
|
|
compatibility layer. That material is transition debt pending extraction to a
|
|
future `rail-kubernetes` repo and must not be treated as long-term S2 scope.
|
|
|
|
---
|
|
|
|
## In Scope
|
|
|
|
- k3s installation and baseline configuration
|
|
- Helm chart management
|
|
- Ingress controller, CNI plugin
|
|
- Admission controllers and cluster operators
|
|
- Cluster addons (cert-manager, etc.)
|
|
- kubeconfig management and access
|
|
- Smoke tests to validate cluster health
|
|
- Published substrate facts and safety expectations for downstream workload rails
|
|
|
|
---
|
|
|
|
## Out of Scope
|
|
|
|
- OS security hardening, SSH, firewall -> railiance-infra (S1)
|
|
- Platform services (PostgreSQL HA, Valkey, object storage) -> railiance-platform (S3)
|
|
- CI/CD and developer tooling -> railiance-enablement (S4)
|
|
- Application deployments -> railiance-apps (S5)
|
|
- Generic workload lifecycle semantics, `railiance/app.toml`, and wrapper scaffolding as long-term ownership concerns -> future `rail-kubernetes` / `rapp-*`
|
|
- No re-configuration of S1 concerns from this repo
|
|
|
|
---
|
|
|
|
## Relevant When
|
|
|
|
- Setting up or maintaining the Kubernetes cluster runtime
|
|
- Installing or updating cluster-level operators and addons
|
|
- Diagnosing cluster health (smoke tests)
|
|
- k3s upgrades or kubeconfig rotation
|
|
- Defining what the current Kubernetes substrate guarantees to downstream workload rails
|
|
|
|
---
|
|
|
|
## Not Relevant When
|
|
|
|
- OS-level work (use railiance-infra)
|
|
- Platform service configuration (use railiance-platform)
|
|
- Application deployments (use railiance-apps)
|
|
|
|
---
|
|
|
|
## Current State
|
|
|
|
- Status: active / stable
|
|
- Implementation: k3s baseline, age-encrypted backup, kubeconfig delivery, and cluster operator/addon management are established; generic workload lifecycle docs/tooling remain here as transition debt pending `rail-kubernetes` extraction
|
|
- Open work: RAIL-BS-WP-0007 ThreePhoenix HA cluster (active, 0/7); RAIL-BS-WP-0008 activity-core WP-0016 deploy (ready); RAIL-BS-WP-0009 admin-sync smoke (ready); RAIL-BS-WP-0012 rail-kubernetes extraction (active)
|
|
- Usage: core Kubernetes runtime for all Railiance deployments; runs on COULOMBCORE (92.205.130.254)
|
|
- Also deployed at cluster level: cert-manager, ArgoCD, CloudNative PG operator (cnpg), nginx ingress, SSO stack (mfa + sso namespaces via net-kingdom)
|
|
|
|
---
|
|
|
|
## How It Fits
|
|
|
|
- Upstream dependencies: railiance-infra (S1) - OS must be converged and verified
|
|
- Downstream consumers: railiance-platform (S3), railiance-enablement (S4), railiance-apps (S5)
|
|
- Often used with: railiance-platform (next layer to configure after cluster is up)
|
|
|
|
---
|
|
|
|
## Terminology
|
|
|
|
- Preferred terms: OAS Stack Level S2, smoke test, pre-condition chain, boundary rule
|
|
- Potentially confusing terms: cluster runtime != platform services; cluster runtime != generic workload rail; Gitea and databases are not S2 concerns
|
|
|
|
---
|
|
|
|
## Related / Overlapping
|
|
|
|
- `railiance-infra` (S1) - must be converged before this layer runs
|
|
- `railiance-platform` (S3) - consumes the cluster runtime provided by S2
|
|
|
|
---
|
|
|
|
## Getting Oriented
|
|
|
|
- Start with: `CLAUDE.md`, `README.md`
|
|
- Key files / directories: `workplans/`, `.sops.yaml`, `docs/rail-kubernetes-extraction-map.md`, `docs/rail-kubernetes-substrate-profile.md`
|
|
- Entry points: `Makefile` targets; remote work requires SSH tunnel to State Hub
|
|
|
|
---
|
|
|
|
## Provided Capabilities
|
|
|
|
```capability
|
|
type: infrastructure
|
|
title: Kubernetes cluster provisioning (k3s)
|
|
description: Install and configure a production k3s cluster including Helm, ingress controller, CNI plugin, and kubeconfig management on Railiance servers.
|
|
keywords: [kubernetes, k3s, cluster, helm, ingress, cni, k8s, provisioning]
|
|
```
|
|
|
|
```capability
|
|
type: infrastructure
|
|
title: Cluster operators and addon management
|
|
description: Deploy and manage cluster-wide operators and addons (cert-manager, CloudNative PG operator, ArgoCD, nginx ingress) on the running Railiance Kubernetes cluster.
|
|
keywords: [operator, addon, cert-manager, cnpg, argocd, admission, kubernetes, cluster]
|
|
```
|
|
|
|
```capability
|
|
type: operations
|
|
title: Kubernetes runtime backup (age-encrypted)
|
|
description: Daily encrypted backup of k3s cluster state (SQLite hot copy), Helm release values, and kubeconfig to /opt/backup/railiance/cluster/ using age encryption. Run via sudo make backup.
|
|
keywords: [backup, restore, age, encryption, k3s, state, helm, kubeconfig, disaster-recovery]
|
|
```
|
|
|
|
---
|
|
|
|
## Notes
|
|
|
|
Runs on COULOMBCORE (92.205.130.254). State Hub access via ops-bridge reverse
|
|
tunnel - `bridge up state-hub-coulombcore` from the workstation (see ADR-004).
|
|
Gitea Helm values were migrated to S5 (railiance-apps) in RAIL-HO-WP-0004-T06 -
|
|
boundary violation resolved.
|
|
|
|
`bin/railiance` lifecycle subcommands, `railiance/app.toml`, and overlay/wrapper
|
|
scaffolding stay in this repo only as a migration bridge. They are not the
|
|
steady-state S2 identity.
|