coulomb/railiance-cluster
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
railiance-cluster/docs/rail-kubernetes-substrate-profile.md
codex be3b8ff31e
All checks were successful
CI Smoke / host-smoke (push) Successful in 0s
Details
CI Smoke / container-smoke (push) Successful in 6s
Details
Clarify cluster boundary for rail-kubernetes
2026-07-25 11:17:51 +02:00

4.4 KiB
Raw Permalink Blame History

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