# portainer/kubesolo architecture

> Architecture diagram of the GitHub repository portainer/kubesolo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/portainer/kubesolo
- Repository: https://github.com/portainer/kubesolo

## Overview

1. KubeSolo is organized as two top-level executables: `cmd/kubesolo` for the in-cluster appliance and `cmd/kubesoloctl` for lifecycle management. The former runs the Kubernetes stack; the latter installs, upgrades, resets, uninstalls, and wires kubeconfig for local clients.

2. The core architectural idea is “single-node Kubernetes in one process.” Instead of separate control-plane binaries and etcd, the repo assembles the API server, controller manager, kubelet, container runtime, DNS, storage helpers, and optional extras into one coordinated runtime with a small persistent state directory, defaulting to `/var/lib/kubesolo`.

3. State storage is replaced by Kine over SQLite. The `pkg/kine` package is the persistence boundary that substitutes for etcd, while `internal/core/pki` handles the local PKI and kubeconfig material needed for the API server and admin access. This makes the system self-contained on disk rather than depending on a cluster datastore.

4. Kubernetes control-plane components are implemented as separate packages under `pkg/kubernetes/`: `apiserver`, `controller`, `kubelet`, `kubeproxy`, and `webhook`. Each has its own flags, health checks, service definitions, and executor logic, but they are orchestrated as part of the same local appliance rather than independently deployed services.

5. A notable Kubernetes-specific boundary is the custom webhook path in `pkg/kubernetes/webhook`, which includes `NodeSetter`. The README calls this out as the replacement for the full scheduler in a single-node environment; it steers workloads without carrying multi-node scheduling machinery.

6. Container execution is handled by `pkg/runtime/containerd` plus host-level support in `internal/runtime`. This includes containerd configuration, image management, plugin setup, and lifecycle management, with `crun` and containerd called out in the README as the runtime stack. The runtime layer also includes filesystem and network helpers for mounts, IP/masquerade logic, and container health.

7. Networking and service exposure are centralized in the runtime and component layers. CoreDNS is packaged under `pkg/components/coredns`, and load-balancer behavior is handled so Services can get node-IP-based external endpoints in a single-node context. IPv6 can be disabled globally, which affects both DNS reverse zones and kubelet node-address registration.

8. Storage and workload add-ons are bundled as first-class components under `pkg/components/`: `localpath` for local persistent storage, `coredns` for cluster DNS, `portainer` for Portainer integration, and `d2k` for a Docker-compatible API endpoint. These are optional but integrated into the same deployment flow and use Kubernetes manifests, RBAC, namespaces, and services from their package boundaries.

9. Configuration and startup flow are driven by CLI flags and environment variables defined in `internal/config/flags`, then consumed by `internal/cli` and `internal/core/embedded`. The `--full`, `--container-mode`, `--offline`, `--d2k`, `--local-storage`, and related flags materially change which subsystems are activated and how much of the upstream Kubernetes default behavior is preserved.

10. `internal/cli` is the orchestration layer for install-time and lifecycle operations. It contains preflight checks, host detection, downloads, kubeconfig management, service management, process execution, reset/uninstall logic, and command handlers. This is the boundary between “user action on the host” and “cluster appliance bootstrap.”

11. Host integration is handled by `internal/system` and `internal/runtime/service`. These packages abstract OS-specific concerns such as mounts, kernel modules, monitoring, and service lifecycles across systemd, openrc, runit, s6, sysvinit, upstart, and foreground/container modes. That abstraction is what lets the same binary run as a native service or inside a container.

12. Offline vs online delivery is a major packaging boundary. `internal/core/embedded` holds embedded images and architecture-specific bundles for offline use, while the build scripts and Dockerfiles in `build/` and the release workflows produce per-architecture artifacts. The online variant fetches images from registries; the offline variant carries images and dependencies in the binary or bundle.

13. The repo also includes installation surfaces outside the binaries: `install.sh`, `install-minimal.sh`, `uninstall.sh`, and `kubesolo-service.sh`. These are thin wrappers around the same lifecycle logic, mainly for bootstrapping on managed hosts and initializing the selected init system.

14. Test and validation structure mirrors the architecture: unit tests cover config, detection, semver, process, service, and runtime helpers; e2e tests in `test/e2e` exercise actual workloads, storage, config, controllers, and DNS/load-balancer behavior. That split reflects the project’s two critical contracts: host installation correctness and local Kubernetes compatibility.

15. For an architecture diagram, the key flows are: host/installer inputs into `kubesoloctl` or `kubesolo`; flags/config into subsystem selection; embedded or downloaded artifacts into runtime startup; runtime services into the local Kubernetes control loop; and cluster state into SQLite via Kine with kubeconfig exported back to the user for external `kubectl` access.

Main entry points: [`cmd/kubesolo/main.go`](https://github.com/portainer/kubesolo/blob/develop/cmd/kubesolo/main.go) (kubesolo), [`pkg/runtime/containerd`](https://github.com/portainer/kubesolo/tree/develop/pkg/runtime/containerd) (containerd), [`pkg/kubernetes/apiserver`](https://github.com/portainer/kubesolo/tree/develop/pkg/kubernetes/apiserver) (API server), [`internal/cli`](https://github.com/portainer/kubesolo/tree/develop/internal/cli) (CLI orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_apps["Executables"]
  node_cmd_kubesolo["kubesolo<br/>appliance binary<br/>[main.go]"]
  node_cmd_kubesoloctl["kubesoloctl<br/>lifecycle CLI<br/>[main.go]"]
end

subgraph group_host["Host control"]
  node_internal_cli["CLI orchestration<br/>host workflow"]
  node_service_manager["Service mgr<br/>init abstraction"]
  node_system_host["Host system<br/>os integration"]
end

subgraph group_core["Core state"]
  node_flags_config["Flags config<br/>runtime config"]
  node_embedded_assets["Embedded assets<br/>offline bundle"]
  node_pki_state["PKI state<br/>cert and kubeconfig"]
end

subgraph group_cluster["Kubernetes stack"]
  node_kine_sqlite[("Kine store<br/>sqlite persistence")]
  node_apiserver["API server<br/>k8s control plane"]
  node_controller["Controller mgr<br/>k8s control plane"]
  node_kubelet["Kubelet<br/>node agent"]
  node_kubeproxy["Kube-proxy<br/>networking"]
  node_webhook["NodeSetter<br/>scheduler webhook"]
end

subgraph group_addons["Add-ons"]
  node_coredns["CoreDNS<br/>dns addon"]
  node_localpath["Local storage<br/>storage addon"]
  node_d2k["D2K<br/>api addon"]
  node_portainer["Portainer<br/>ui addon"]
end

subgraph group_runtime["Runtime layer"]
  node_containerd["containerd<br/>container runtime"]
  node_runtime_net["Net helpers<br/>network plumbing"]
  node_runtime_fs["FS helpers<br/>filesystem plumbing"]
end

node_cmd_kubesoloctl -->|"drives"| node_internal_cli
node_cmd_kubesolo -->|"reads"| node_flags_config
node_internal_cli -->|"starts/stops"| node_service_manager
node_internal_cli -->|"detects"| node_system_host
node_internal_cli -->|"downloads/loads"| node_embedded_assets
node_internal_cli -->|"writes"| node_pki_state
node_flags_config -->|"selects"| node_embedded_assets
node_flags_config -->|"configures"| node_apiserver
node_flags_config -->|"configures"| node_containerd
node_embedded_assets -->|"supplies"| node_containerd
node_pki_state -->|"enables"| node_apiserver
node_apiserver -->|"persists via"| node_kine_sqlite
node_controller -->|"reconciles via"| node_apiserver
node_kubelet -->|"executes on"| node_containerd
node_kubeproxy -->|"routes"| node_runtime_net
node_webhook -->|"places pods"| node_kubelet
node_containerd -->|"uses"| node_runtime_fs
node_containerd -->|"uses"| node_runtime_net
node_coredns -->|"registers with"| node_apiserver
node_localpath -->|"stores on"| node_kine_sqlite
node_d2k -->|"exposes"| node_containerd
node_portainer -->|"manages via"| node_apiserver
node_cmd_kubesolo -->|"orchestrates"| node_containerd
node_cmd_kubesolo -->|"starts"| node_apiserver
node_cmd_kubesolo -->|"starts"| node_controller
node_cmd_kubesolo -->|"starts"| node_kubelet
node_cmd_kubesolo -->|"starts"| node_webhook
node_cmd_kubesolo -->|"starts"| node_coredns
node_cmd_kubesolo -->|"starts"| node_localpath

click node_cmd_kubesolo "https://github.com/portainer/kubesolo/blob/develop/cmd/kubesolo/main.go"
click node_cmd_kubesoloctl "https://github.com/portainer/kubesolo/blob/develop/cmd/kubesoloctl/main.go"
click node_internal_cli "https://github.com/portainer/kubesolo/tree/develop/internal/cli"
click node_service_manager "https://github.com/portainer/kubesolo/tree/develop/internal/cli/service"
click node_system_host "https://github.com/portainer/kubesolo/tree/develop/internal/system"
click node_flags_config "https://github.com/portainer/kubesolo/tree/develop/internal/config/flags"
click node_embedded_assets "https://github.com/portainer/kubesolo/tree/develop/internal/core/embedded"
click node_pki_state "https://github.com/portainer/kubesolo/tree/develop/internal/core/pki"
click node_kine_sqlite "https://github.com/portainer/kubesolo/tree/develop/pkg/kine"
click node_apiserver "https://github.com/portainer/kubesolo/tree/develop/pkg/kubernetes/apiserver"
click node_controller "https://github.com/portainer/kubesolo/tree/develop/pkg/kubernetes/controller"
click node_kubelet "https://github.com/portainer/kubesolo/tree/develop/pkg/kubernetes/kubelet"
click node_kubeproxy "https://github.com/portainer/kubesolo/tree/develop/pkg/kubernetes/kubeproxy"
click node_webhook "https://github.com/portainer/kubesolo/tree/develop/pkg/kubernetes/webhook"
click node_containerd "https://github.com/portainer/kubesolo/tree/develop/pkg/runtime/containerd"
click node_runtime_net "https://github.com/portainer/kubesolo/tree/develop/internal/runtime/network"
click node_runtime_fs "https://github.com/portainer/kubesolo/tree/develop/internal/runtime/filesystem"
click node_coredns "https://github.com/portainer/kubesolo/tree/develop/pkg/components/coredns"
click node_localpath "https://github.com/portainer/kubesolo/tree/develop/pkg/components/localpath"
click node_d2k "https://github.com/portainer/kubesolo/tree/develop/pkg/components/d2k"
click node_portainer "https://github.com/portainer/kubesolo/tree/develop/pkg/components/portainer"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cmd_kubesolo,node_cmd_kubesoloctl toneBlue
class node_internal_cli,node_service_manager,node_system_host toneAmber
class node_flags_config,node_embedded_assets,node_pki_state toneMint
class node_kine_sqlite,node_apiserver,node_controller,node_kubelet,node_kubeproxy,node_webhook toneRose
class node_coredns,node_localpath,node_d2k,node_portainer toneIndigo
class node_containerd,node_runtime_net,node_runtime_fs toneTeal
```

## Components

### Executables

Top-level entrypoints for appliance and host lifecycle management.

- [kubesolo](https://github.com/portainer/kubesolo/blob/develop/cmd/kubesolo/main.go): appliance binary · Main in-cluster executable that starts the single-node Kubernetes appliance. · `cmd/kubesolo/main.go`
- [kubesoloctl](https://github.com/portainer/kubesolo/blob/develop/cmd/kubesoloctl/main.go): lifecycle CLI · Host-facing executable for install, upgrade, reset, uninstall, and kubeconfig wiring. · `cmd/kubesoloctl/main.go`

### Host control

Installation, detection, service management, and environment integration on the host.

- [CLI orchestration](https://github.com/portainer/kubesolo/tree/develop/internal/cli): host workflow · Command handlers and lifecycle orchestration for install-time and maintenance operations. · `internal/cli`
- [Service mgr](https://github.com/portainer/kubesolo/tree/develop/internal/cli/service): init abstraction · Abstracts systemd, openrc, runit, s6, sysvinit, upstart, foreground, and container modes. · `internal/cli/service`
- [Host system](https://github.com/portainer/kubesolo/tree/develop/internal/system): os integration · Host detection, modules, monitoring, and mount integration across operating environments. · `internal/system`

### Core state

Embedded assets, configuration selection, and local PKI/state boundaries.

- [Flags config](https://github.com/portainer/kubesolo/tree/develop/internal/config/flags): runtime config · Flag and environment-driven startup selection that controls which subsystems are enabled. · `internal/config/flags`
- [Embedded assets](https://github.com/portainer/kubesolo/tree/develop/internal/core/embedded): offline bundle · Offline images, architecture bundles, and embedded delivery content for startup. · `internal/core/embedded`
- [PKI state](https://github.com/portainer/kubesolo/tree/develop/internal/core/pki): cert and kubeconfig · Local PKI, certificates, and kubeconfig material for API server and admin access. · `internal/core/pki`

### Kubernetes stack

In-cluster control-plane and node services run as one appliance.

- [Kine store](https://github.com/portainer/kubesolo/tree/develop/pkg/kine): sqlite persistence · Persistence boundary that replaces etcd using Kine over SQLite. · `pkg/kine`
- [API server](https://github.com/portainer/kubesolo/tree/develop/pkg/kubernetes/apiserver): k8s control plane · Kubernetes API server package with flags, RBAC, health, and service wiring. · `pkg/kubernetes/apiserver`
- [Controller mgr](https://github.com/portainer/kubesolo/tree/develop/pkg/kubernetes/controller): k8s control plane · Controller manager package with execution, validation, health, and service definitions. · `pkg/kubernetes/controller`
- [Kubelet](https://github.com/portainer/kubesolo/tree/develop/pkg/kubernetes/kubelet): node agent · Local node agent with config, kubeconfig, validation, health, and service wiring. · `pkg/kubernetes/kubelet`
- [Kube-proxy](https://github.com/portainer/kubesolo/tree/develop/pkg/kubernetes/kubeproxy): networking · Service networking component for local cluster traffic handling. · `pkg/kubernetes/kubeproxy`
- [NodeSetter](https://github.com/portainer/kubesolo/tree/develop/pkg/kubernetes/webhook): scheduler webhook · Custom webhook that replaces full scheduling with single-node placement logic. · `pkg/kubernetes/webhook`

### Add-ons

Optional but integrated cluster components and service extensions.

- [CoreDNS](https://github.com/portainer/kubesolo/tree/develop/pkg/components/coredns): dns addon · Cluster DNS component packaged as an integrated manifest-driven add-on. · `pkg/components/coredns`
- [Local storage](https://github.com/portainer/kubesolo/tree/develop/pkg/components/localpath): storage addon · Local persistent volume provider and storage class for single-node workloads. · `pkg/components/localpath`
- [D2K](https://github.com/portainer/kubesolo/tree/develop/pkg/components/d2k): api addon · Docker-compatible API endpoint integrated as an optional component. · `pkg/components/d2k`
- [Portainer](https://github.com/portainer/kubesolo/tree/develop/pkg/components/portainer): ui addon · Optional Portainer integration packaged with Kubernetes manifests and RBAC. · `pkg/components/portainer`

### Runtime layer

Container runtime, networking, filesystem, and persistence plumbing.

- [containerd](https://github.com/portainer/kubesolo/tree/develop/pkg/runtime/containerd): container runtime · Runtime executor for container configuration, images, plugins, namespace, and health. · `pkg/runtime/containerd`
- [Net helpers](https://github.com/portainer/kubesolo/tree/develop/internal/runtime/network): network plumbing · IP, masquerade, IPv6, and network health helpers for cluster connectivity. · `internal/runtime/network`
- [FS helpers](https://github.com/portainer/kubesolo/tree/develop/internal/runtime/filesystem): filesystem plumbing · Binary and file helpers used by the runtime layer for mounts and artifacts. · `internal/runtime/filesystem`

## Connections

- kubesoloctl → CLI orchestration: drives · Lifecycle command entrypoint delegates into CLI orchestration.
- kubesolo → Flags config: reads · Main appliance process consumes startup flags and environment configuration.
- CLI orchestration → Service mgr: starts/stops · Install and maintenance actions manage services through the abstraction layer.
- CLI orchestration → Host system: detects · CLI uses host detection and OS integration before bootstrap.
- CLI orchestration → Embedded assets: downloads/loads · Installer selects embedded or fetched artifacts for offline and online modes.
- CLI orchestration → PKI state: writes · CLI prepares kubeconfig and local certificate material for users and services.
- Flags config → Embedded assets: selects · Flags determine offline, container-mode, and feature bundle selection.
- Flags config → API server: configures · Configuration controls control-plane startup and preserved upstream behavior.
- Flags config → containerd: configures · Startup flags influence runtime mode and image behavior.
- Embedded assets → containerd: supplies · Embedded binaries and images feed runtime startup.
- PKI state → API server: enables · Certificates and kubeconfig material secure API server access.
- API server → Kine store: persists via · API server state is stored through Kine rather than etcd.
- Controller mgr → API server: reconciles via · Controllers operate against the local API server.
- Kubelet → containerd: executes on · Kubelet launches and manages workloads through the container runtime.
- Kube-proxy → Net helpers: routes · Service networking relies on host and cluster network helpers.
- NodeSetter → Kubelet: places pods · NodeSetter webhook steers workloads in lieu of a full scheduler.
- containerd → FS helpers: uses · Runtime uses filesystem helpers for artifacts and mounts.
- containerd → Net helpers: uses · Runtime uses networking helpers for IP and masquerade behavior.
- CoreDNS → API server: registers with · DNS add-on integrates as a cluster service.
- Local storage → Kine store: stores on · Local storage add-on supports persistent volumes on the node.
- D2K → containerd: exposes · Docker-compatible endpoint fronts the container runtime.
- Portainer → API server: manages via · Portainer add-on connects to the cluster control plane.
- kubesolo → containerd: orchestrates · Appliance binary assembles runtime, control plane, and addons into one process boundary.
- kubesolo → API server: starts · Main appliance process brings up the Kubernetes API server.
- kubesolo → Controller mgr: starts · Main appliance process brings up the controller manager.
- kubesolo → Kubelet: starts · Main appliance process brings up the node agent.
- kubesolo → NodeSetter: starts · Main appliance process brings up the single-node placement webhook.
- kubesolo → CoreDNS: starts · Core cluster DNS is part of the appliance runtime.
- kubesolo → Local storage: starts · Local persistent storage is part of the appliance runtime.
