# k3s-io/k3s architecture

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

- Interactive diagram: https://gitdiagram.com/k3s-io/k3s
- Repository: https://github.com/k3s-io/k3s
- Video tour (about a minute): https://gitdiagram.com/k3s-io/k3s/video

## Overview

K3s is a lightweight Kubernetes distribution packaged as a multicall binary. The main workflow is an operator invoking the server or agent command: configuration reaches the server runtime, which bootstraps cluster state and starts control-plane services; worker agents connect through the documented websocket tunnel. Separate branches cover datastore and etcd snapshots, certificate management, and local-manifest deployment. The source excerpts show selected startup and controller behavior; README statements preserve additional bundled capabilities whose implementation was not sampled.

Main entry points: [`pkg/server/server.go`](https://github.com/k3s-io/k3s/blob/main/pkg/server/server.go) (Server runtime), [`pkg/agent/run.go`](https://github.com/k3s-io/k3s/blob/main/pkg/agent/run.go) (Agent runtime), [`pkg/cli/server/server.go`](https://github.com/k3s-io/k3s/blob/main/pkg/cli/server/server.go) (Server configuration), [`pkg/daemons/control/server.go`](https://github.com/k3s-io/k3s/blob/main/pkg/daemons/control/server.go) (Control daemons)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Commands and operations"]
  node_binary["K3s launcher<br/>[main.go]"]
  node_command_defs["Command definitions<br/>[server.go]"]
  node_server_cli["Server configuration<br/>[server.go]"]
end

subgraph group_control["Cluster control plane"]
  node_server_runtime["Server runtime<br/>[server.go]"]
  node_control_daemons["Control daemons<br/>[server.go]"]
  node_executor["Embedded executor<br/>[embed.go]"]
  node_cluster_storage[("Cluster bootstrap storage<br/>[storage.go]")]
  node_server_handlers["Supervisor API<br/>[handlers.go]"]
end

subgraph group_node["Node runtime"]
  node_agent_runtime["Agent runtime<br/>[run.go]"]
  node_agent_tunnel["Node websocket tunnel<br/>[tunnel.go]"]
  node_containerd["Container runtime<br/>[containerd.go]"]
  node_flannel["Flannel networking<br/>[flannel.go]"]
end

subgraph group_services["Cluster services"]
  node_certs["Certificate management<br/>[certmonitor.go]"]
  node_manifest_deploy["Manifest deployment<br/>[controller.go]"]
  node_etcd_snapshots["Etcd snapshots"]
  node_service_lb["Service load balancer<br/>[servicelb.go]"]
  node_bundled_components["Bundled Kubernetes services<br/>[server.go]"]
end

node_operator(("Operator"))

node_operator -->|"invokes"| node_binary
node_binary -->|"dispatches commands"| node_command_defs
node_command_defs -->|"runs server"| node_server_cli
node_server_cli -->|"configures and starts"| node_server_runtime
node_server_runtime -->|"starts services"| node_control_daemons
node_control_daemons -->|"runs components"| node_executor
node_control_daemons -->|"bootstraps cluster"| node_cluster_storage
node_server_runtime -->|"starts API"| node_server_handlers
node_server_runtime -->|"sets up deployment"| node_manifest_deploy
node_server_cli -->|"starts agent"| node_agent_runtime
node_agent_runtime -->|"uses tunnel"| node_agent_tunnel
node_agent_runtime -->|"configures runtime"| node_containerd
node_agent_runtime -->|"monitors certificates"| node_certs
node_server_runtime -.->|"starts controllers"| node_etcd_snapshots
node_server_runtime -.->|"enables provider"| node_service_lb
node_agent_runtime -.->|"sets up networking"| node_flannel
node_server_runtime -->|"bundles services"| node_bundled_components
node_server_runtime -->|"manages certificates"| node_certs
node_server_runtime -->|"connects worker nodes"| node_agent_tunnel

click node_binary "https://github.com/k3s-io/k3s/blob/main/cmd/k3s/main.go"
click node_command_defs "https://github.com/k3s-io/k3s/blob/main/pkg/cli/cmds/server.go"
click node_server_cli "https://github.com/k3s-io/k3s/blob/main/pkg/cli/server/server.go"
click node_server_runtime "https://github.com/k3s-io/k3s/blob/main/pkg/server/server.go"
click node_control_daemons "https://github.com/k3s-io/k3s/blob/main/pkg/daemons/control/server.go"
click node_executor "https://github.com/k3s-io/k3s/blob/main/pkg/executor/embed/embed.go"
click node_cluster_storage "https://github.com/k3s-io/k3s/blob/main/pkg/cluster/storage.go"
click node_server_handlers "https://github.com/k3s-io/k3s/blob/main/pkg/server/handlers/handlers.go"
click node_agent_runtime "https://github.com/k3s-io/k3s/blob/main/pkg/agent/run.go"
click node_agent_tunnel "https://github.com/k3s-io/k3s/blob/main/pkg/agent/tunnel/tunnel.go"
click node_containerd "https://github.com/k3s-io/k3s/blob/main/pkg/agent/containerd/containerd.go"
click node_flannel "https://github.com/k3s-io/k3s/blob/main/pkg/agent/flannel/flannel.go"
click node_certs "https://github.com/k3s-io/k3s/blob/main/pkg/certmonitor/certmonitor.go"
click node_manifest_deploy "https://github.com/k3s-io/k3s/blob/main/pkg/deploy/controller.go"
click node_etcd_snapshots "https://github.com/k3s-io/k3s/blob/main/pkg/etcd/snapshot_controller.go"
click node_service_lb "https://github.com/k3s-io/k3s/blob/main/pkg/cloudprovider/servicelb.go"
click node_bundled_components "https://github.com/k3s-io/k3s/blob/main/pkg/server/server.go"

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_binary,node_command_defs,node_server_cli toneBlue
class node_server_runtime,node_control_daemons,node_executor,node_cluster_storage,node_server_handlers toneAmber
class node_agent_runtime,node_agent_tunnel,node_containerd,node_flannel toneMint
class node_certs,node_manifest_deploy,node_etcd_snapshots,node_service_lb,node_bundled_components toneRose
class node_operator toneIndigo
```

## Components

### Commands and operations

- [K3s launcher](https://github.com/k3s-io/k3s/blob/main/cmd/k3s/main.go): `cmd/k3s/main.go`
- [Command definitions](https://github.com/k3s-io/k3s/blob/main/pkg/cli/cmds/server.go): `pkg/cli/cmds/server.go`
- [Server configuration](https://github.com/k3s-io/k3s/blob/main/pkg/cli/server/server.go): `pkg/cli/server/server.go`

### Cluster control plane

- [Server runtime](https://github.com/k3s-io/k3s/blob/main/pkg/server/server.go): `pkg/server/server.go`
- [Control daemons](https://github.com/k3s-io/k3s/blob/main/pkg/daemons/control/server.go): `pkg/daemons/control/server.go`
- [Embedded executor](https://github.com/k3s-io/k3s/blob/main/pkg/executor/embed/embed.go): `pkg/executor/embed/embed.go`
- [Cluster bootstrap storage](https://github.com/k3s-io/k3s/blob/main/pkg/cluster/storage.go): `pkg/cluster/storage.go`
- [Supervisor API](https://github.com/k3s-io/k3s/blob/main/pkg/server/handlers/handlers.go): `pkg/server/handlers/handlers.go`

### Node runtime

- [Agent runtime](https://github.com/k3s-io/k3s/blob/main/pkg/agent/run.go): `pkg/agent/run.go`
- [Node websocket tunnel](https://github.com/k3s-io/k3s/blob/main/pkg/agent/tunnel/tunnel.go): `pkg/agent/tunnel/tunnel.go`
- [Container runtime](https://github.com/k3s-io/k3s/blob/main/pkg/agent/containerd/containerd.go): `pkg/agent/containerd/containerd.go`
- [Flannel networking](https://github.com/k3s-io/k3s/blob/main/pkg/agent/flannel/flannel.go): `pkg/agent/flannel/flannel.go`

### Cluster services

- [Certificate management](https://github.com/k3s-io/k3s/blob/main/pkg/certmonitor/certmonitor.go): `pkg/certmonitor/certmonitor.go`
- [Manifest deployment](https://github.com/k3s-io/k3s/blob/main/pkg/deploy/controller.go): `pkg/deploy/controller.go`
- [Etcd snapshots](https://github.com/k3s-io/k3s/blob/main/pkg/etcd/snapshot_controller.go): `pkg/etcd/snapshot_controller.go`
- [Service load balancer](https://github.com/k3s-io/k3s/blob/main/pkg/cloudprovider/servicelb.go): `pkg/cloudprovider/servicelb.go`
- [Bundled Kubernetes services](https://github.com/k3s-io/k3s/blob/main/pkg/server/server.go): `pkg/server/server.go`

### Other components

- **Operator**

## Connections

- Operator → K3s launcher: invokes (evidence: `README.md`)
- K3s launcher → Command definitions: dispatches commands (evidence: `cmd/k3s/main.go`)
- Command definitions → Server configuration: runs server
- Server configuration → Server runtime: configures and starts (evidence: `pkg/cli/server/server.go`)
- Server runtime → Control daemons: starts services (evidence: `pkg/server/server.go`)
- Control daemons → Embedded executor: runs components (evidence: `pkg/daemons/control/server.go`)
- Control daemons → Cluster bootstrap storage: bootstraps cluster (evidence: `pkg/daemons/control/server.go`)
- Server runtime → Supervisor API: starts API (evidence: `pkg/server/server.go`)
- Server runtime → Manifest deployment: sets up deployment (evidence: `pkg/server/server.go`)
- Server configuration → Agent runtime: starts agent (evidence: `pkg/cli/server/server.go`)
- Agent runtime → Node websocket tunnel: uses tunnel (evidence: `pkg/agent/run.go`)
- Agent runtime → Container runtime: configures runtime (evidence: `pkg/agent/run.go`)
- Agent runtime → Certificate management: monitors certificates (evidence: `pkg/agent/run.go`)
- Server runtime → Etcd snapshots: starts controllers
- Server runtime → Service load balancer: enables provider
- Agent runtime → Flannel networking: sets up networking
- Server runtime → Bundled Kubernetes services: bundles services (evidence: `README.md`)
- Server runtime → Certificate management: manages certificates (evidence: `README.md`)
- Server runtime → Node websocket tunnel: connects worker nodes (evidence: `README.md`)
