README
¶
Stratum Kubernetes Engine (SKE)
A new Kubernetes distribution: one self-extracting binary that carries its component binaries AND container images (no airgap variant — the artifact is airgap-complete), pins every version in one file, builds hermetically from unmodified upstream tags (with one exception: the dashboard's npm dependencies resolve from the public registry), and runs the control plane as kubelet-managed static pods with a full product layer on top — declarative cluster config, token joins, managed etcd with scheduled/S3 snapshots, a manifest deployer with pruning, a HelmChart operator, and rolling upgrades. The CIS hardening profile and its auditor are part of Stratum PRO; the engine keeps the profile mechanism they are built on.
What is in the box
| Component | How it ships | Role |
|---|---|---|
| kubernetes 1.35.9 | kubelet and kubectl built from source; control plane from upstream OCI images | kubelet and kubectl on the host; apiserver, controller-manager, scheduler as static pods |
| containerd 2.2.10 + runc 1.5.2 | built from source | container runtime, cgroup v2 only |
| etcd 3.6.6 | OCI image; etcdctl and etcdutl built from source | the only datastore, TLS, managed (join/snapshot/restore), runs as a static pod |
| kube-vip 1.3.1 | OCI image | API server VIP, a static pod on controllers |
| cilium 1.20.3 | OCI images, manifest stack | CNI, network policy, kube-proxy replacement |
| coredns 1.13.2 | OCI image, manifest stack | cluster DNS |
| local-path 0.0.37 | OCI images, manifest stack | default StorageClass |
| dashboard | React + Vite SPA, embedded in the binary | stratum dash: cluster views, pod exec, optional node shell |
Naming
The product is Stratum Kubernetes Engine, SKE for short. Every code
identifier uses the standalone name stratum — the binary, the module path,
/var/lib/stratum/bin, the version suffix, the patch prefix.
That split is deliberate, not an inconsistency to tidy up. "Kubernetes"
in a product name is a Linux Foundation mark usable only after CNCF conformance
certification, so the combination name cannot be load-bearing in code that ships
before certification. stratum works standalone at every stage.
Quick start
Host tools come from mise.toml: install
mise, then mise install. It does
not provide Go (that pin lives in build/versions.mk), nor docker and ssh,
which make inttest and the ostests backends need. It does provide node and
pnpm, which make build needs: the dashboard SPA is embedded in the binary, so
building it is part of building stratum (TAGS=noui skips it).
make help # targets, current version, target platform
make components # build the host components (Kubernetes takes ~25 min)
make dash # build the dashboard SPA into dash/dist
make images # pull and stage the pinned OCI images
make package # the release artifact: dist/stratum (~610 MB, airgap-complete)
make smoke # run it in a clean container
make inttest # real clusters in containers: Ready node, network, day-2
# then, on a node:
stratum up # a single schedulable node to Ready, no registry
make lint # pin and patch governance
make test # go vet + go test
make verify-payload # embedded image set == build/images.txt, by name and digest
make fences-check # version fences still match upstream compatibility data
make days-behind # how far behind upstream each branch is
make verify-reproducible COMPONENT=runc
Layout
| Path | What |
|---|---|
build/versions.mk |
The pin file. Every version and build flag. Nothing else may pin a version. |
build/images.txt |
Runtime OCI images, digest-pinned. Staged into the binary's payload. |
build/components/<name>/Dockerfile |
Hermetic per-component build. All versions arrive as build args. |
build/components/<name>/patches/ |
Ordered git am queue. Ships empty. |
tools/ |
Governance: version lint, patch lint, droppable-patch detection, version derivation, build-info. |
tools/inttest/ |
Integration checks. The CI matrix is generated from this directory. |
cmd/stratum, pkg/cli |
The binary's entry point and its command-line interface. |
internal/assets |
Runtime staging of the appended ZIP payload (binaries + images). |
dash/ |
The dashboard SPA (React + Vite) and the //go:embed that carries it into the binary. |
internal/dashboard |
The stratum dash server: apiserver proxy, session layer, node-shell gate. |
internal/ |
The control plane and product layer: PKI, static pods, host-process supervision, etcd, upgrades, hardening. |
renovate.json5 |
Bump grouping and per-branch version fences (generated). |
docs/ |
The public documentation site (MkDocs Material). Published, not read in-repo. |
How the pieces fit
build/versions.mk ──┐
├─→ per-component build containers ─→ staging/<os>-<arch>/bin/
build/components/ ───┘ │
build/images.txt ─────→ docker pull @digest + save ─────→ staging/<os>-<arch>/images/
│
├─→ embedded-bins.zip
│ │
cmd/stratum ──────┴────────┴─→ dist/stratum
(cat zip >> binary)
The last step is the interesting one. A ZIP reader locates the central directory
by scanning backwards from EOF, and an ELF loader ignores trailing bytes, so
dist/stratum is simultaneously a working executable and a working archive of its
own payload. At runtime it opens itself, extracts bin/ and images/ under
/var/lib/stratum, and skips extraction entirely when size and mtime already
match — which matters when the payload is a third of a gigabyte of images.
Carrying the images in the same archive is what removes the separate airgap
bundle.
Documentation
- Cutting a release — who may, the RC and hotfix and batch rules, and the whole procedure end to end
- Public documentation — the user-facing MkDocs site, and how to build it locally
- Contributing — building, testing, and the commit and pull request conventions
- Security — reporting a vulnerability, supported versions,
and how
stratum dashhandles credentials and the node shell
What is not here
These are deferred, and nothing blocks them: an SSH installer that builds a fleet from zero, channel-polling autopilot CRs, konnectivity, SLSA attestations, and a nightly rebuild-and-compare.
License
Stratum is licensed under the Apache License, Version 2.0. Third-party material checked into this repository keeps its own license; see THIRD_PARTY_NOTICES.md. LICENSING.md holds the policy for the licenses of the code Stratum ships.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
stratum
command
Command stratum is the single self-extracting artifact for Stratum Kubernetes Engine.
|
Command stratum is the single self-extracting artifact for Stratum Kubernetes Engine. |
|
stratum-dash
command
Command stratum-dash is the dashboard server alone, built into the image the cluster runs it from.
|
Command stratum-dash is the dashboard server alone, built into the image the cluster runs it from. |
|
Package dash carries the built dashboard SPA into the stratum binary.
|
Package dash carries the built dashboard SPA into the stratum binary. |
|
internal
|
|
|
addons
Package addons carries the cluster add-on manifests (CoreDNS, local-path storage, Cilium CNI) embedded in the stratum binary, and renders each one for the cluster it is about to be installed into — substituting the mirrored image registry, the pinned versions, and the per-cluster apiserver endpoint.
|
Package addons carries the cluster add-on manifests (CoreDNS, local-path storage, Cilium CNI) embedded in the stratum binary, and renders each one for the cluster it is about to be installed into — substituting the mirrored image registry, the pinned versions, and the per-cluster apiserver endpoint. |
|
assets
Package assets stages the payload embedded in the stratum executable onto disk at runtime.
|
Package assets stages the payload embedded in the stratum executable onto disk at runtime. |
|
atomicfile
Package atomicfile is stratum's one durable single-file writer: a file is written to a unique hidden temp file in its own directory, labelled for its destination, fsynced at its final mode, renamed into place, and the directory is fsynced so the rename survives a power loss.
|
Package atomicfile is stratum's one durable single-file writer: a file is written to a unique hidden temp file in its own directory, labelled for its destination, fsynced at its final mode, renamed into place, and the directory is fsynced so the rename survives a power loss. |
|
bootstrap
Package bootstrap owns cluster-info transport for every consumer of the kube-public cluster-info ConfigMap, under two distinct trust models.
|
Package bootstrap owns cluster-info transport for every consumer of the kube-public cluster-info ConfigMap, under two distinct trust models. |
|
bootstrap/clusterinfo
Package clusterinfo authenticates the kube-public cluster-info ConfigMap and turns the authenticated payload into a CA trust bundle.
|
Package clusterinfo authenticates the kube-public cluster-info ConfigMap and turns the authenticated payload into a CA trust bundle. |
|
certinputs
Package certinputs defines the certificate inputs every control-plane lifecycle issues leaves from — the host, the node's address, and the named SAN purposes the cluster's network facts call for — and builds them through one constructor.
|
Package certinputs defines the certificate inputs every control-plane lifecycle issues leaves from — the host, the node's address, and the named SAN purposes the cluster's network facts call for — and builds them through one constructor. |
|
certs
Cross-node orchestration for `stratum certs rotate-ca --cluster`.
|
Cross-node orchestration for `stratum certs rotate-ca --cluster`. |
|
cluster
Package cluster assembles a SKE node: the declarative cluster config, the persisted per-node state, the component processes the supervisor runs, and the bring-up/join flows around them.
|
Package cluster assembles a SKE node: the declarative cluster config, the persisted per-node state, the component processes the supervisor runs, and the bring-up/join flows around them. |
|
comps
Package comps speaks systemctl-shaped verbs (restart, stop, is-active) to the stratum supervisor's control socket, for the components that are still supervised HOST processes: containerd, kubelet, and the operator.
|
Package comps speaks systemctl-shaped verbs (restart, stop, is-active) to the stratum supervisor's control socket, for the components that are still supervised HOST processes: containerd, kubelet, and the operator. |
|
dashboard
Package dashboard serves the Stratum dashboard from the stratum binary: the embedded SPA, a reverse proxy to this cluster's own apiserver, and a session layer that authenticates users by ServiceAccount bearer-token passthrough.
|
Package dashboard serves the Stratum dashboard from the stratum binary: the embedded SPA, a reverse proxy to this cluster's own apiserver, and a session layer that authenticates users by ServiceAccount bearer-token passthrough. |
|
enginesettings
Package enginesettings holds the apiserver flags and kubelet lines the engine renders on every node whatever its profile: the apiserver verifies kubelet serving certificates against the cluster's trust bundle, and the kubelet either bootstraps its serving certificate through the CSR flow or serves the static leaf pair a control plane holds.
|
Package enginesettings holds the apiserver flags and kubelet lines the engine renders on every node whatever its profile: the apiserver verifies kubelet serving certificates against the cluster's trust bundle, and the kubelet either bootstraps its serving certificate through the CSR flow or serves the static leaf pair a control plane holds. |
|
etcddata
Package etcddata coordinates Stratum operations that create, replace, or restore the local etcd data directory.
|
Package etcddata coordinates Stratum operations that create, replace, or restore the local etcd data directory. |
|
etcdsnap
Package etcdsnap wraps the host-staged etcdctl for etcd snapshot save (the pre-upgrade data-safety floor), over the same mTLS endpoint/flags as `stratum etcdctl`, and the host-staged etcdutl for an offline single-member snapshot restore (the heavy rollback path).
|
Package etcdsnap wraps the host-staged etcdctl for etcd snapshot save (the pre-upgrade data-safety floor), over the same mTLS endpoint/flags as `stratum etcdctl`, and the host-staged etcdutl for an offline single-member snapshot restore (the heavy rollback path). |
|
ha
Package ha implements HA control-plane join (`stratum server --server --token --certificate-key`): it securely distributes the shared CP certs, adds a live etcd member, brings up an additional apiserver, and fronts them with a per-node HAProxy.
|
Package ha implements HA control-plane join (`stratum server --server --token --certificate-key`): it securely distributes the shared CP certs, adds a live etcd member, brings up an additional apiserver, and fronts them with a per-node HAProxy. |
|
host
Package host performs node prerequisites: directories, kernel modules, sysctls, swapoff, and node-IP/hostname detection.
|
Package host performs node prerequisites: directories, kernel modules, sysctls, swapoff, and node-IP/hostname detection. |
|
interrupt
Package interrupt owns the one signal set every stratum command stops under, so no two handlers can drift apart: SIGINT, SIGTERM and SIGHUP.
|
Package interrupt owns the one signal set every stratum command stops under, so no two handlers can drift apart: SIGINT, SIGTERM and SIGHUP. |
|
k8sutil
Package k8sutil holds small host-side helpers shared across the stratum subcommands: running the embedded kubectl against admin.conf, the apiserver health gate, node-registration wait, the progress "step" printer, the admin-clientset constructor, the etcdctl mTLS env, the node label/stamp the upgrade orchestrator relies on, and the cluster maintenance fence the command-level seams take.
|
Package k8sutil holds small host-side helpers shared across the stratum subcommands: running the embedded kubectl against admin.conf, the apiserver health gate, node-registration wait, the progress "step" printer, the admin-clientset constructor, the etcdctl mTLS env, the node label/stamp the upgrade orchestrator relies on, and the cluster maintenance fence the command-level seams take. |
|
k8sver
Package k8sver parses, validates and orders Kubernetes version strings.
|
Package k8sver parses, validates and orders Kubernetes version strings. |
|
kubeconfig
Package kubeconfig writes the control-plane kubeconfigs in Go using client-go's clientcmd/api.
|
Package kubeconfig writes the control-plane kubeconfigs in Go using client-go's clientcmd/api. |
|
maintlease
Package maintlease holds self-renewing cluster maintenance Leases.
|
Package maintlease holds self-renewing cluster maintenance Leases. |
|
mcp
Package mcp serves Stratum's Model Context Protocol tools.
|
Package mcp serves Stratum's Model Context Protocol tools. |
|
mcp/kube
Package kube is Stratum's Kubernetes access layer: config resolution, clients, and resource addressing.
|
Package kube is Stratum's Kubernetes access layer: config resolution, clients, and resource addressing. |
|
mcp/kube/kubetest
Package kubetest starts a real Kubernetes control plane for tests.
|
Package kubetest starts a real Kubernetes control plane for tests. |
|
netcfg
Package netcfg is the single place that understands the cluster's pod/service CIDRs and their address families, so every consumer (systemd unit flags, PKI SANs, Cilium, node-IP detection) agrees on single- vs dual-stack.
|
Package netcfg is the single place that understands the cluster's pod/service CIDRs and their address families, so every consumer (systemd unit flags, PKI SANs, Cilium, node-IP detection) agrees on single- vs dual-stack. |
|
netcfg/netdefault
Package netdefault holds the cluster network's built-in defaults: the pod and service ranges, the addresses on the default service range, and the DNS domain a cluster gets when the user names none.
|
Package netdefault holds the cluster network's built-in defaults: the pod and service ranges, the addresses on the default service range, and the DNS domain a cluster gets when the user names none. |
|
nodejob
Package nodejob runs a privileged, node-pinned Job that nsenters PID 1 and execs the on-host stratum binary, then gates on the Job result.
|
Package nodejob runs a privileged, node-pinned Job that nsenters PID 1 and execs the on-host stratum binary, then gates on the Job result. |
|
nodelock
Package nodelock excludes concurrent node-maintenance operations — upgrade, rollback, certificate rotation, etcd CA migration, snapshot restore, rejoin, uninstall — on one host: while one such operation holds the lock, the next refuses instead of waiting.
|
Package nodelock excludes concurrent node-maintenance operations — upgrade, rollback, certificate rotation, etcd CA migration, snapshot restore, rejoin, uninstall — on one host: while one such operation holds the lock, the next refuses instead of waiting. |
|
nodestate
Package nodestate persists what a node IS — written at bring-up/join, read on every controller start, patched by rejoin/restore.
|
Package nodestate persists what a node IS — written at bring-up/join, read on every controller start, patched by rejoin/restore. |
|
objstore
Package objstore is a thin S3 client (AWS SDK for Go v2) for offloading etcd snapshots to an S3-compatible object store — AWS S3, MinIO, Ceph RGW, etc.
|
Package objstore is a thin S3 client (AWS SDK for Go v2) for offloading etcd snapshots to an S3-compatible object store — AWS S3, MinIO, Ceph RGW, etc. |
|
operator
corednsspread.go — move a CoreDNS replica off a node that holds all of them.
|
corednsspread.go — move a CoreDNS replica off a node that holds all of them. |
|
pki
etcd CA migration — splitting etcd out of the Kubernetes trust domain.
|
etcd CA migration — splitting etcd out of the Kubernetes trust domain. |
|
procid
Package procid answers one question for every /proc scanner in the tree: which live process is Stratum's, and which component does it belong to?
|
Package procid answers one question for every /proc scanner in the tree: which live process is Stratum's, and which component does it belong to? |
|
profile
Package profile is the engine's notion of a node profile: a named set of hardened settings an importer registers through pkg/cli.WithProfiles and a node selects by name.
|
Package profile is the engine's notion of a node profile: a named set of hardened settings an importer registers through pkg/cli.WithProfiles and a node selects by name. |
|
profile/profiletest
Package profiletest gives tests a hardened node profile shaped like the cis profile a Stratum PRO binary registers: an audit policy and an admission configuration as config files, an at-rest encryption config as a shared secret, kernel sysctls, and every property set.
|
Package profiletest gives tests a hardened node profile shaped like the cis profile a Stratum PRO binary registers: an audit policy and an admission configuration as config files, an at-rest encryption config as a shared secret, kernel sysctls, and every property set. |
|
profilefiles
Package profilefiles writes a node profile's config files where the renderers read them.
|
Package profilefiles writes a node profile's config files where the renderers read them. |
|
registry
Package registry translates an RKE2/k3s-compatible /etc/stratum/registries.yaml into containerd's certs.d configuration so image pulls can be redirected to a mirror (the air-gap / sovereign-registry case).
|
Package registry translates an RKE2/k3s-compatible /etc/stratum/registries.yaml into containerd's certs.d configuration so image pulls can be redirected to a mirror (the air-gap / sovereign-registry case). |
|
rollout
Package rollout restarts the in-cluster workloads Stratum owns, so that every command that has to do it (snapshot restore, and rotate-ca) rolls one list.
|
Package rollout restarts the in-cluster workloads Stratum owns, so that every command that has to do it (snapshot restore, and rotate-ca) rolls one list. |
|
rtcheck
Package rtcheck compares what is installed on disk with what is actually serving: a node can run a different containerd than the one on disk when an orphan from an earlier run holds the CRI socket.
|
Package rtcheck compares what is installed on disk with what is actually serving: a node can run a different containerd than the one on disk when an orphan from an earlier run holds the CRI socket. |
|
runtime
Package runtime configures containerd from the staged payload: config.toml with the host-matched cgroup driver, the stratum CRI socket, and registry mirrors.
|
Package runtime configures containerd from the staged payload: config.toml with the host-matched cgroup driver, the stratum CRI socket, and registry mirrors. |
|
selinux
Package selinux keeps the files Stratum writes labelled the way the host's SELinux policy says they should be, and registers the file contexts that make the policy treat Stratum's paths the way container-selinux treats the standard container runtime's.
|
Package selinux keeps the files Stratum writes labelled the way the host's SELinux policy says they should be, and registers the file contexts that make the policy treat Stratum's paths the way container-selinux treats the standard container runtime's. |
|
staticpod
Package staticpod renders and manages the control-plane static pod manifests (the control plane runs as kubelet-managed static pods).
|
Package staticpod renders and manages the control-plane static pod manifests (the control plane runs as kubelet-managed static pods). |
|
supervisor
Package supervisor runs and restarts the host processes that make up a SKE node: containerd, kubelet, and the operator.
|
Package supervisor runs and restarts the host processes that make up a SKE node: containerd, kubelet, and the operator. |
|
token
Package token implements `stratum token create`: it mints a bootstrap token, stores the bootstrap-token Secret, wires the node-bootstrap and node-renewal RBAC with upstream bootstrap auto-approval reserved and empty (the operator approves joins), publishes the cluster-info ConfigMap (so agents can discover the CA), and prints the join command.
|
Package token implements `stratum token create`: it mints a bootstrap token, stores the bootstrap-token Secret, wires the node-bootstrap and node-renewal RBAC with upstream bootstrap auto-approval reserved and empty (the operator approves joins), publishes the cluster-info ConfigMap (so agents can discover the CA), and prints the join command. |
|
toolenv
Package toolenv is how host tools are found and run when Stratum runs them as root: iptables and tc load code from XTABLES_LIBDIR and TC_LIB_DIR, and a shim of any tool can sit first on the caller's PATH, so neither the caller's environment nor its PATH is used.
|
Package toolenv is how host tools are found and run when Stratum runs them as root: iptables and tc load code from XTABLES_LIBDIR and TC_LIB_DIR, and a shim of any tool can sit first on the caller's PATH, so neither the caller's environment nor its PATH is used. |
|
trustaudit
Package trustaudit evaluates this node's etcd and kubelet client trust against the live components.
|
Package trustaudit evaluates this node's etcd and kubelet client trust against the live components. |
|
uninstall
Package uninstall removes a stratum node's footprint: it stops the supervised components (via the controller's control socket, when one is running) and deletes the on-disk layout created by `stratum up`.
|
Package uninstall removes a stratum node's footprint: it stops the supervised components (via the controller's control socket, when one is running) and deletes the on-disk layout created by `stratum up`. |
|
upgrade
Package upgrade implements `stratum upgrade` / `stratum rollback`: a per-node binary-swap primitive and a `--cluster` orchestrator that rolls an HA cluster (serial control planes, then workers) natively, version-stamped and self-contained (the binary embeds the new component binaries).
|
Package upgrade implements `stratum upgrade` / `stratum rollback`: a per-node binary-swap primitive and a `--cluster` orchestrator that rolls an HA cluster (serial control planes, then workers) natively, version-stamped and self-contained (the binary embeds the new component binaries). |
|
version
Package version carries the ldflags-stamped release versions, the ports and fixed component settings every node shares, and the filesystem layout every other package derives paths from.
|
Package version carries the ldflags-stamped release versions, the ports and fixed component settings every node shares, and the filesystem layout every other package derives paths from. |
|
pkg
|
|
|
cli
Package cli builds the stratum command tree as a *cobra.Command.
|
Package cli builds the stratum command tree as a *cobra.Command. |
|
tools
|
|
|
apiboundary
command
Command apiboundary asserts that a package's exported API (exported func, type, var, and const declarations) never references a type from one of this module's own internal/...
|
Command apiboundary asserts that a package's exported API (exported func, type, var, and const declarations) never references a type from one of this module's own internal/... |
|
depotrelease
command
|
|
|
gatelist
Package gatelist holds the pin guards that keep the repository's two gate lists from drifting apart.
|
Package gatelist holds the pin guards that keep the repository's two gate lists from drifting apart. |
|
importlayers
command
Command importlayers is the internal import-layering rule's lint guard, run by make lint over the whole repository.
|
Command importlayers is the internal import-layering rule's lint guard, run by make lint over the whole repository. |
|
inttest/apipoller
command
Command apipoller is the in-cluster API client check-ha-rotate-ca.sh runs through a CA rotation.
|
Command apipoller is the in-cluster API client check-ha-rotate-ca.sh runs through a CA rotation. |
|
nodefilewrites
command
Command nodefilewrites is the node-file write rule's lint guard, run by make lint over the whole repository.
|
Command nodefilewrites is the node-file write rule's lint guard, run by make lint over the whole repository. |
|
ociimage
command
Command ociimage writes a single-binary OCI image archive for `ctr images import`: one layer holding the binary at its root, no base image, and byte-identical output for the same input.
|
Command ociimage writes a single-binary OCI image archive for `ctr images import`: one layer holding the binary at its root, no base image, and byte-identical output for the same input. |
Click to show internal directories.
Click to hide internal directories.