Local Kubernetes development

Stackie’s Kubernetes plugin provisions and operates a real upstream K3s distribution for local development. Kubernetes remains Kubernetes: Stackie does not reimplement the API server, scheduler, controllers, kubelet, or kubectl contract.

What each plugin owns

The Kubernetes and CRI packages are separately buildable first-party plugins. The Kubernetes plugin owns verified K3s artifacts, cluster processes, lifecycle, CNI setup, and persistent-data safety. The CRI plugin owns the CRI v1 endpoint used by kubelet. Mocker compatibility alone decides whether an image maps to a Stackie block; Stackied admits and supervises the resulting workload.

Stackie flowchart: #stackie-mermaid-0{font-family:Inter Variable,Inter,ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,Segoe UI,sans-serif;font-size:16px;fill:#f8fafc;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#stackie-mermaid-0 .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#stackie-mermaid-0 .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#stackie-mermaid-0 .error-icon{fill:#111827;}#stackie-mermaid-0 .error-text{fill:#f8fafc;stroke:#f8fafc;}#stackie-mermaid-0 .edge-thickness-normal{stroke-width:1px;}#stackie-mermaid-0 .edge-thickness-thick{stroke-width:3.5px;}#stackie-mermaid-0 .edge-pattern-solid{stroke-dasharray:0;}#stackie-mermaid-0 .edge-thickness-invisible{stroke-width:0;fill:none;}#stackie-mermaid-0 .edge-pattern-dashed{stroke-dasharray:3;}#stackie-mermaid-0 .edge-pattern-dotted{stroke-dasharray:2;}#stackie-mermaid-0 .marker{fill:#facc15;stroke:#facc15;}#stackie-mermaid-0 .marker.cross{stroke:#facc15;}#stackie-mermaid-0 svg{font-family:Inter Variable,Inter,ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,Segoe UI,sans-serif;font-size:16px;}#stackie-mermaid-0 p{margin:0;}#stackie-mermaid-0 .label{font-family:Inter Variable,Inter,ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,Segoe UI,sans-serif;color:#f8fafc;}#stackie-mermaid-0 .cluster-label text{fill:#f8fafc;}#stackie-mermaid-0 .cluster-label span{color:#f8fafc;}#stackie-mermaid-0 .cluster-label span p{background-color:transparent;}#stackie-mermaid-0 .label text,#stackie-mermaid-0 span{fill:#f8fafc;color:#f8fafc;}#stackie-mermaid-0 .node rect,#stackie-mermaid-0 .node circle,#stackie-mermaid-0 .node ellipse,#stackie-mermaid-0 .node polygon,#stackie-mermaid-0 .node path{fill:#1f2937;stroke:#facc15;stroke-width:1px;}#stackie-mermaid-0 .rough-node .label text,#stackie-mermaid-0 .node .label text,#stackie-mermaid-0 .image-shape .label,#stackie-mermaid-0 .icon-shape .label{text-anchor:middle;}#stackie-mermaid-0 .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#stackie-mermaid-0 .rough-node .label,#stackie-mermaid-0 .node .label,#stackie-mermaid-0 .image-shape .label,#stackie-mermaid-0 .icon-shape .label{text-align:center;}#stackie-mermaid-0 .node.clickable{cursor:pointer;}#stackie-mermaid-0 .root .anchor path{fill:#facc15!important;stroke-width:0;stroke:#facc15;}#stackie-mermaid-0 .arrowheadPath{fill:rgba(255, 255, 255, 0);}#stackie-mermaid-0 .edgePath .path{stroke:#facc15;stroke-width:1px;}#stackie-mermaid-0 .flowchart-link{stroke:#facc15;fill:none;}#stackie-mermaid-0 .edgeLabel{background-color:#171717;text-align:center;}#stackie-mermaid-0 .edgeLabel p{background-color:#171717;}#stackie-mermaid-0 .edgeLabel rect{opacity:0.5;background-color:#171717;fill:#171717;}#stackie-mermaid-0 .labelBkg{background-color:rgba(23, 23, 23, 0.5);}#stackie-mermaid-0 .cluster rect{fill:#111827;stroke:#2dd4bf;stroke-width:1px;}#stackie-mermaid-0 .cluster text{fill:#f8fafc;}#stackie-mermaid-0 .cluster span{color:#f8fafc;}#stackie-mermaid-0 div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:Inter Variable,Inter,ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,Segoe UI,sans-serif;font-size:12px;background:#111827;border:1px solid #2dd4bf;border-radius:2px;pointer-events:none;z-index:100;}#stackie-mermaid-0 .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#f8fafc;}#stackie-mermaid-0 rect.text{fill:none;stroke-width:0;}#stackie-mermaid-0 .icon-shape,#stackie-mermaid-0 .image-shape{background-color:#171717;text-align:center;}#stackie-mermaid-0 .icon-shape p,#stackie-mermaid-0 .image-shape p{background-color:#171717;padding:2px;}#stackie-mermaid-0 .icon-shape .label rect,#stackie-mermaid-0 .image-shape .label rect{opacity:0.5;background-color:#171717;fill:#171717;}#stackie-mermaid-0 .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#stackie-mermaid-0 .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#stackie-mermaid-0 .node .neo-node{stroke:#facc15;}#stackie-mermaid-0 [data-look="neo"].node rect,#stackie-mermaid-0 [data-look="neo"].cluster rect,#stackie-mermaid-0 [data-look="neo"].node polygon{stroke:url(#stackie-mermaid-0-gradient);filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}#stackie-mermaid-0 [data-look="neo"].swimlane.cluster rect{filter:none;}#stackie-mermaid-0 [data-look="neo"].node path{stroke:url(#stackie-mermaid-0-gradient);stroke-width:1px;}#stackie-mermaid-0 [data-look="neo"].node .outer-path{filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}#stackie-mermaid-0 [data-look="neo"].node .neo-line path{stroke:#facc15;filter:none;}#stackie-mermaid-0 [data-look="neo"].node circle{stroke:url(#stackie-mermaid-0-gradient);filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}#stackie-mermaid-0 [data-look="neo"].node circle .state-start{fill:#000000;}#stackie-mermaid-0 [data-look="neo"].icon-shape .icon{fill:url(#stackie-mermaid-0-gradient);filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}#stackie-mermaid-0 [data-look="neo"].icon-shape .icon-neo path{stroke:url(#stackie-mermaid-0-gradient);filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}#stackie-mermaid-0 :root{--mermaid-font-family:Inter Variable,Inter,ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,Segoe UI,sans-serif;}, CRI, kubectl and Kubernetes clients, Upstream K3s API, controllers, scheduler, Upstream kubelet. Use horizontal scrolling when the full diagram is wider than the visible frame. Generated from Stackie public documentation source.

In text: Kubernetes clients talk to upstream K3s. K3s’s kubelet calls the separate CRI v1 plugin, which asks Mocker compatibility to classify images before Stackied admits workloads. K3s uses the verified upstream CNI plugin bundle for pod networking.

This dependency direction is deliberate. In a later sprint a future Mocker plugin can provide the same compatibility capability to the Kubernetes and CRI plugins; Docker-to-Stackie translation will not move into either plugin or into Bridge.

Supported profile

Component	Pinned/supported value
Host	Linux `amd64` or Linux `arm64`
Kubernetes distribution	K3s `v1.36.2+k3s1`
Kubernetes API version	`v1.36.2`
CRI API	`k8s.io/cri-api v0.36.2`, CRI v1
CRI validation	Unmodified upstream `critest v1.36.0`
OCI runtime	Upstream `runc v1.4.2`
Networking	Upstream CNI plugins `v1.9.1`

Stackie verifies every downloaded artifact against the repository’s pinned HTTPS URL, size ceiling, and SHA-256 digest before it can become executable. Unsupported hosts can display package availability, but start returns an explicit unsupported result; Stackie never substitutes a simulated Kubernetes or another container runtime.

Package, administration, and subscription are separate

Build inclusion and runtime entitlement are independent generic host facts. Including the package does not grant a subscription, and a subscription cannot materialise a package omitted from a build. Kubernetes and CRI currently declare the same canonical kubernetes_development product module, so one Kubernetes Development entitlement gates the pair. The plugin architecture also supports assigning distinct catalog modules—and therefore distinct paid tiers—to either package without adding host-side product checks.

Package	Administrator state	Subscription	Platform	Result
Absent	Any	Any	Any	Kubernetes is unavailable; no plugin service starts
Present	Disabled	Any	Supported	Installed but administrator-disabled and inactive; cluster data is preserved
Present	Enabled	Missing	Supported	Subscription-required state; processes stop and data is preserved
Present	Enabled	Granted	Unsupported	Explicit unsupported-platform state; no fallback starts
Present	Enabled	Granted	Supported	K3s server and agent may start after artifact and health checks pass

The dashboard, API, and CLI report these facts separately so “not included,” “disabled,” “subscription required,” “unsupported,” and “failed” are not collapsed into a misleading generic error.

Lifecycle and recovery

Cluster operations are durable. Stackie records the intended generation before starting or stopping K3s, validates the exact executable and process start identity it owns, and resumes or repairs interrupted operations after restart. A stale process, executable mismatch, or superseded operation is rejected instead of being adopted or terminated by name alone.

Action	Processes and disposable state	Persistent volumes
Stop	Stops the owned K3s server and agent	Preserved
Subscription loss	Stops local Kubernetes and marks entitlement absent	Preserved
Reset	Stops processes and removes disposable sockets, runtime state, artifact caches, and CNI state	Preserved
Uninstall	Removes package/disposable state	Preserved and still registered
Purge	Requires a fresh confirmation matching the current cluster generation and persistent-volume count	Permanently deleted only after that confirmation

Reset and uninstall are therefore safe recovery actions, not aliases for deleting data. Permanent deletion is always the distinct, explicit purge operation. If the cluster changes after confirmation is shown, the purge is refused and must be confirmed again.

Operational boundary

Use ordinary Kubernetes clients and manifests against the provisioned K3s endpoint. Kubernetes API behavior, scheduling, controllers, and kubelet conformance come from the pinned upstream distribution. Stackie owns local provisioning and workload integration only; managed-cloud Kubernetes such as EKS, GKE, and AKS remains a separate Spaceport follow-up.