# chazapis/hpktainer architecture

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

- Interactive diagram: https://gitdiagram.com/chazapis/hpktainer
- Repository: https://github.com/chazapis/hpktainer

## Overview

HPK provides HPC users with a private Kubernetes cluster whose nodes run in rootless “bubbles.” The principal workflow starts with Slurm launching bubbles, then Kubernetes schedules Pods to HPK’s kubelet provider, which prepares pod state and submits jobs that run a pause container and user containers. Separate runtime capabilities cover image handling, volumes, logs/exec, and pod networking. The README documents the overall deployment and networking design; source excerpts show key runtime actions, but do not expose every provider-to-handler call, so those links are documented at subsystem level.

Main entry points: [`internal/compute/podhandler/podhandler.go`](https://github.com/chazapis/hpktainer/blob/main/internal/compute/podhandler/podhandler.go) (Pod lifecycle), [`internal/provider/provider.go`](https://github.com/chazapis/hpktainer/blob/main/internal/provider/provider.go) (Virtual kubelet provider), [`cmd/hpk-pause/main.go`](https://github.com/chazapis/hpktainer/blob/main/cmd/hpk-pause/main.go) (Pod pause process), [`cmd/hpktainer/main.go`](https://github.com/chazapis/hpktainer/blob/main/cmd/hpktainer/main.go) (Container launcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cluster["Cluster control"]
  node_k3s["K3s cluster"]
  node_hpk_kubelet["HPK kubelet<br/>[root.go]"]
  node_provider["Virtual kubelet provider<br/>[provider.go]"]
  node_node["Node management<br/>[node.go]"]
end

subgraph group_podruntime["Pod runtime"]
  node_pod_handler["Pod lifecycle<br/>[podhandler.go]"]
  node_image_pull["Image handling<br/>[pull.go]"]
  node_runtime_submit["Job submission<br/>[submit.go]"]
  node_pause["Pod pause process<br/>[main.go]"]
  node_hpktainer["Container launcher<br/>[main.go]"]
  node_volumes["Pod volumes"]
  node_projected_volume["Projected volumes<br/>[projected.go]"]
end

subgraph group_networking["Pod networking"]
  node_network_cni["CNI address allocation<br/>[cni.go]"]
  node_calico["Calico networking<br/>[calico.go]"]
  node_net_daemon["TAP forwarder<br/>[main.go]"]
  node_netutil["TAP/socket copying<br/>[copy.go]"]
end

subgraph group_support["Runtime support"]
  node_atomic_writer["Atomic volume writes<br/>[atomic_writer.go]"]
  node_endpoint["Pod file paths<br/>[paths.go]"]
  node_events["Pod event listener<br/>[listener.go]"]
  node_file_watch["Filesystem watching<br/>[poller.go]"]
  node_logs["Container logs<br/>[logs.go]"]
  node_host_subpath["Safe volume subpaths<br/>[subpath.go]"]
end

node_hpc_user(("HPC user"))
node_slurm["Slurm job"]
node_kubectl(("kubectl"))
node_app_container["Application container"]
node_bgp_peers["Bubble BGP peers"]
node_external_network["External network"]

node_hpc_user -->|"submits job"| node_slurm
node_slurm -->|"launches bubbles"| node_k3s
node_kubectl -->|"issues commands"| node_k3s
node_k3s -->|"hosts kubelet"| node_hpk_kubelet
node_hpk_kubelet -.->|"configures provider"| node_provider
node_provider -.->|"manages nodes"| node_node
node_provider -.->|"updates pods"| node_pod_handler
node_pod_handler -.->|"handles images"| node_image_pull
node_pod_handler -.->|"prepares volumes"| node_volumes
node_pod_handler -.->|"submits jobs"| node_runtime_submit
node_runtime_submit -->|"runs pod process"| node_pause
node_pause -->|"spawns containers"| node_hpktainer
node_hpktainer -->|"allocates address"| node_network_cni
node_hpktainer -->|"starts forwarder"| node_net_daemon
node_net_daemon -->|"forwards TAP traffic"| node_netutil
node_net_daemon -->|"connects socket pair"| node_net_daemon
node_hpktainer -->|"executes container"| node_app_container
node_pause -->|"hosts applications"| node_app_container
node_calico -->|"routes between bubbles"| node_bgp_peers
node_bgp_peers -->|"routes traffic outward"| node_external_network
node_volumes -.->|"supports projected data"| node_projected_volume
node_projected_volume -.->|"writes volume files"| node_atomic_writer
node_pod_handler -->|"uses pod paths"| node_endpoint
node_provider -->|"watches pod state"| node_file_watch
node_pod_handler -->|"registers watches"| node_file_watch
node_pause -->|"queries pod API"| node_k3s
node_provider -.->|"serves container logs"| node_logs
node_volumes -.->|"secures subpaths"| node_host_subpath
node_pod_handler -.->|"reports pod events"| node_events

click node_hpk_kubelet "https://github.com/chazapis/hpktainer/blob/main/cmd/hpk-kubelet/commands/root/root.go"
click node_provider "https://github.com/chazapis/hpktainer/blob/main/internal/provider/provider.go"
click node_node "https://github.com/chazapis/hpktainer/blob/main/internal/provider/node.go"
click node_pod_handler "https://github.com/chazapis/hpktainer/blob/main/internal/compute/podhandler/podhandler.go"
click node_image_pull "https://github.com/chazapis/hpktainer/blob/main/internal/compute/image/pull.go"
click node_runtime_submit "https://github.com/chazapis/hpktainer/blob/main/internal/compute/runtime/submit.go"
click node_pause "https://github.com/chazapis/hpktainer/blob/main/cmd/hpk-pause/main.go"
click node_hpktainer "https://github.com/chazapis/hpktainer/blob/main/cmd/hpktainer/main.go"
click node_volumes "https://github.com/chazapis/hpktainer/tree/main/internal/compute/volume"
click node_projected_volume "https://github.com/chazapis/hpktainer/blob/main/internal/compute/volume/projected/projected.go"
click node_atomic_writer "https://github.com/chazapis/hpktainer/blob/main/internal/compute/volume/util/atomic_writer.go"
click node_network_cni "https://github.com/chazapis/hpktainer/blob/main/internal/network/cni.go"
click node_calico "https://github.com/chazapis/hpktainer/blob/main/internal/network/calico.go"
click node_net_daemon "https://github.com/chazapis/hpktainer/blob/main/cmd/hpk-net-daemon/main.go"
click node_netutil "https://github.com/chazapis/hpktainer/blob/main/internal/netutil/copy.go"
click node_endpoint "https://github.com/chazapis/hpktainer/blob/main/internal/compute/endpoint/paths.go"
click node_events "https://github.com/chazapis/hpktainer/blob/main/internal/compute/events/listener.go"
click node_file_watch "https://github.com/chazapis/hpktainer/blob/main/pkg/filenotify/poller.go"
click node_logs "https://github.com/chazapis/hpktainer/blob/main/pkg/container/logs.go"
click node_host_subpath "https://github.com/chazapis/hpktainer/blob/main/pkg/hostutil/subpath.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_k3s,node_hpk_kubelet,node_provider,node_node,node_hpc_user toneBlue
class node_pod_handler,node_image_pull,node_runtime_submit,node_pause,node_hpktainer,node_volumes,node_projected_volume toneAmber
class node_network_cni,node_calico,node_net_daemon,node_netutil toneMint
class node_atomic_writer,node_endpoint,node_events,node_file_watch,node_logs,node_host_subpath toneRose
class node_slurm,node_kubectl,node_app_container,node_bgp_peers,node_external_network toneIndigo
```

## Components

### Cluster control

- **K3s cluster**
- [HPK kubelet](https://github.com/chazapis/hpktainer/blob/main/cmd/hpk-kubelet/commands/root/root.go): `cmd/hpk-kubelet/commands/root/root.go`
- [Virtual kubelet provider](https://github.com/chazapis/hpktainer/blob/main/internal/provider/provider.go): `internal/provider/provider.go`
- [Node management](https://github.com/chazapis/hpktainer/blob/main/internal/provider/node.go): `internal/provider/node.go`

### Pod runtime

- [Pod lifecycle](https://github.com/chazapis/hpktainer/blob/main/internal/compute/podhandler/podhandler.go): `internal/compute/podhandler/podhandler.go`
- [Image handling](https://github.com/chazapis/hpktainer/blob/main/internal/compute/image/pull.go): `internal/compute/image/pull.go`
- [Job submission](https://github.com/chazapis/hpktainer/blob/main/internal/compute/runtime/submit.go): `internal/compute/runtime/submit.go`
- [Pod pause process](https://github.com/chazapis/hpktainer/blob/main/cmd/hpk-pause/main.go): `cmd/hpk-pause/main.go`
- [Container launcher](https://github.com/chazapis/hpktainer/blob/main/cmd/hpktainer/main.go): `cmd/hpktainer/main.go`
- [Pod volumes](https://github.com/chazapis/hpktainer/tree/main/internal/compute/volume): `internal/compute/volume`
- [Projected volumes](https://github.com/chazapis/hpktainer/blob/main/internal/compute/volume/projected/projected.go): `internal/compute/volume/projected/projected.go`

### Pod networking

- [CNI address allocation](https://github.com/chazapis/hpktainer/blob/main/internal/network/cni.go): `internal/network/cni.go`
- [Calico networking](https://github.com/chazapis/hpktainer/blob/main/internal/network/calico.go): `internal/network/calico.go`
- [TAP forwarder](https://github.com/chazapis/hpktainer/blob/main/cmd/hpk-net-daemon/main.go): `cmd/hpk-net-daemon/main.go`
- [TAP/socket copying](https://github.com/chazapis/hpktainer/blob/main/internal/netutil/copy.go): `internal/netutil/copy.go`

### Runtime support

- [Atomic volume writes](https://github.com/chazapis/hpktainer/blob/main/internal/compute/volume/util/atomic_writer.go): `internal/compute/volume/util/atomic_writer.go`
- [Pod file paths](https://github.com/chazapis/hpktainer/blob/main/internal/compute/endpoint/paths.go): `internal/compute/endpoint/paths.go`
- [Pod event listener](https://github.com/chazapis/hpktainer/blob/main/internal/compute/events/listener.go): `internal/compute/events/listener.go`
- [Filesystem watching](https://github.com/chazapis/hpktainer/blob/main/pkg/filenotify/poller.go): `pkg/filenotify/poller.go`
- [Container logs](https://github.com/chazapis/hpktainer/blob/main/pkg/container/logs.go): `pkg/container/logs.go`
- [Safe volume subpaths](https://github.com/chazapis/hpktainer/blob/main/pkg/hostutil/subpath.go): `pkg/hostutil/subpath.go`

### Other components

- **HPC user**
- **Slurm job**
- **kubectl**
- **Application container**
- **Bubble BGP peers**
- **External network**

## Connections

- HPC user → Slurm job: submits job (evidence: `README.md`)
- Slurm job → K3s cluster: launches bubbles (evidence: `README.md`)
- kubectl → K3s cluster: issues commands (evidence: `README.md`)
- K3s cluster → HPK kubelet: hosts kubelet (evidence: `README.md`)
- HPK kubelet → Virtual kubelet provider: configures provider
- Virtual kubelet provider → Node management: manages nodes
- Virtual kubelet provider → Pod lifecycle: updates pods
- Pod lifecycle → Image handling: handles images
- Pod lifecycle → Pod volumes: prepares volumes
- Pod lifecycle → Job submission: submits jobs
- Job submission → Pod pause process: runs pod process (evidence: `README.md`)
- Pod pause process → Container launcher: spawns containers (evidence: `README.md`)
- Container launcher → CNI address allocation: allocates address (evidence: `cmd/hpktainer/main.go`)
- Container launcher → TAP forwarder: starts forwarder (evidence: `cmd/hpktainer/main.go`)
- TAP forwarder → TAP/socket copying: forwards TAP traffic (evidence: `cmd/hpk-net-daemon/main.go`)
- TAP forwarder → TAP forwarder: connects socket pair (evidence: `README.md`)
- Container launcher → Application container: executes container (evidence: `cmd/hpktainer/main.go`)
- Pod pause process → Application container: hosts applications (evidence: `README.md`)
- Calico networking → Bubble BGP peers: routes between bubbles (evidence: `README.md`)
- Bubble BGP peers → External network: routes traffic outward (evidence: `README.md`)
- Pod volumes → Projected volumes: supports projected data
- Projected volumes → Atomic volume writes: writes volume files
- Pod lifecycle → Pod file paths: uses pod paths (evidence: `internal/compute/podhandler/podhandler.go`)
- Virtual kubelet provider → Filesystem watching: watches pod state (evidence: `internal/provider/provider.go`)
- Pod lifecycle → Filesystem watching: registers watches (evidence: `internal/compute/podhandler/podhandler.go`)
- Pod pause process → K3s cluster: queries pod API (evidence: `cmd/hpk-pause/main.go`)
- Virtual kubelet provider → Container logs: serves container logs
- Pod volumes → Safe volume subpaths: secures subpaths
- Pod lifecycle → Pod event listener: reports pod events
