113 lines
4.4 KiB
Markdown
113 lines
4.4 KiB
Markdown
# rail-kubernetes Substrate Profile
|
|
|
|
This document records the minimum cluster substrate facts that
|
|
`railiance-cluster` publishes for a future `rail-kubernetes` repo.
|
|
|
|
The intent is narrow: future rail code should depend on explicit substrate
|
|
capabilities, not on incidental implementation details scattered across this
|
|
repo.
|
|
|
|
## Runtime Base
|
|
|
|
- Kubernetes runtime: k3s installed by `ansible/bootstrap.yml`
|
|
- Current pinned k3s version in repo: `v1.35.1+k3s1`
|
|
- Current pinned Helm version in repo: `v3.17.3`
|
|
- Baseline health checks: `make smoke`
|
|
- Cluster safety gate before invasive work: `make preflight`
|
|
|
|
`rail-kubernetes` may assume a k3s-backed Kubernetes API plus Helm-based apply
|
|
paths on the current Railiance substrate. It should not assume more than that
|
|
without a declared extension.
|
|
|
|
## Access Model
|
|
|
|
- Operator access is delivered from `/etc/rancher/k3s/k3s.yaml` to
|
|
`~/.kube/config-hosteurope` as documented in `docs/kubeconfig.md`
|
|
- The raw k3s kubeconfig uses `127.0.0.1` as the server address and may require
|
|
rewrite or tunneling for remote use
|
|
- The documented operator model is cluster-admin kubeconfig access, not a
|
|
least-privilege workload service-account contract
|
|
|
|
Future `rail-kubernetes` should assume operator-driven cluster access for now.
|
|
It should not assume a published per-workload RBAC template yet.
|
|
|
|
## Routing And Canary Exposure
|
|
|
|
- The current generic tooling supports isolated canary deployment by creating a
|
|
separate Stage 2 release and namespace
|
|
- `docs/canary-helm-template.md` documents a Traefik weighted-routing example,
|
|
but `railiance-cluster` does not currently publish weighted routing as a
|
|
guaranteed substrate capability
|
|
- `tools/cmd/railiance-stage2` can inspect rollout, pods, and ingress/routing
|
|
resources for the canary release
|
|
|
|
Published guarantee for wave 1: isolated canary exposure is the safe default.
|
|
Weighted, header-based, path-based, or shadow routing must be treated as
|
|
optional future capabilities until S2 documents them explicitly.
|
|
|
|
## TLS And Cluster Operators
|
|
|
|
`SCOPE.md` currently records these cluster-level addons/operators on the active
|
|
substrate:
|
|
|
|
- nginx ingress
|
|
- cert-manager
|
|
- ArgoCD
|
|
- CloudNative PG operator
|
|
- SSO stack namespaces (`mfa`, `sso`) via Net Kingdom
|
|
|
|
Future `rail-kubernetes` should depend on capabilities such as ingress
|
|
availability or TLS readiness, not on owning these operators directly.
|
|
|
|
## Observability Expectations
|
|
|
|
- `tools/cmd/railiance-stage2` live observe checks rollout status, deployment
|
|
JSON, canary pod state, ingress/routing resources, and pod metrics
|
|
- `docs/stage2-deploy-observe.md` explicitly treats metrics-server absence as a
|
|
separate observability note rather than as proof that rollout failed
|
|
|
|
Published guarantee for wave 1: rollout, pod, and ingress inspection are part
|
|
of the substrate contract. Metrics availability is opportunistic unless the
|
|
cluster profile is later strengthened.
|
|
|
|
## Namespace And Release Behavior
|
|
|
|
- `tools/cmd/railiance-stage2` and `tools/cmd/railiance-stage3` use
|
|
`--create-namespace`
|
|
- Stage defaults derive namespace and release names from workload contract data
|
|
when the workload does not override them
|
|
|
|
Future `rail-kubernetes` may assume that namespace creation is acceptable in the
|
|
current operator flow. It should not assume namespaces or release names are
|
|
pre-provisioned by S2.
|
|
|
|
## Storage And Stateful Constraints
|
|
|
|
- `tools/cmd/railiance-backup-s2` documents that the current cluster runs k3s
|
|
in SQLite mode and backs up `/var/lib/rancher/k3s/server/db/state.db`
|
|
- This repo does not yet publish a generic storage-class, PVC, or stateful
|
|
workload placement contract for downstream workload rails
|
|
|
|
That means stateful workload assumptions remain explicit-review territory for
|
|
now. `rail-kubernetes` should not invent a storage contract on behalf of S2.
|
|
|
|
## Safety Rails Published By S2
|
|
|
|
- age-encrypted cluster backup via `make backup`
|
|
- printed restore procedure via `make restore`
|
|
- preflight gate via `make preflight`
|
|
- smoke validation via `make smoke`
|
|
|
|
These are substrate safety rails. They are not a substitute for workload-level
|
|
promotion or rollback logic.
|
|
|
|
## Not Yet Published
|
|
|
|
The future `rail-kubernetes` must currently treat these as absent or
|
|
repo-specific until S2 publishes them explicitly:
|
|
|
|
- guaranteed weighted routing on the active ingress controller
|
|
- a generic workload RBAC model
|
|
- a generic storage-class or persistent-volume contract
|
|
- a secret-delivery contract at the S2 layer
|
|
- multi-node HA assumptions beyond the active `RAIL-BS-WP-0007` work
|