# rancher/local-path-provisioner architecture

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

- Interactive diagram: https://gitdiagram.com/rancher/local-path-provisioner
- Repository: https://github.com/rancher/local-path-provisioner

## Overview

Local Path Provisioner is a Kubernetes storage provisioner that creates hostPath- or local-backed persistent volumes using paths configured for each node or storage class. The user submits a PVC and workload; Kubernetes coordinates provisioning, after which the workload can use the bound volume. The daemon loads configuration, runs the provisioner, and uses helper pods to perform volume setup and cleanup. The README also documents shared-filesystem and custom helper-command options. Edges reflect README statements or shown source calls; where runtime dispatch is not shown, the link is marked unverified.

Main entry points: [`provisioner.go`](https://github.com/rancher/local-path-provisioner/blob/master/provisioner.go) (Volume lifecycle), [`main.go`](https://github.com/rancher/local-path-provisioner/blob/master/main.go) (Daemon startup), [`util.go`](https://github.com/rancher/local-path-provisioner/blob/master/util.go) (Helper pod validation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Storage workflow"]
  node_pvc["Storage claim"]
  node_pv["Persistent volume"]
  node_workload["Pod workload"]
end

subgraph group_daemon["Daemon runtime"]
  node_daemon_entry["Daemon startup<br/>[main.go]"]
  node_kube_client["Kubernetes client<br/>[main.go]"]
  node_configmap["ConfigMap loading<br/>[main.go]"]
  node_health["Readiness checks<br/>[main.go]"]
  node_controller["Provisioner controller<br/>[main.go]"]
end

subgraph group_config["Provisioning policy"]
  node_provisioner["Volume lifecycle<br/>[provisioner.go]"]
  node_config_policy["Path configuration<br/>[provisioner.go]"]
  node_path_resolution["Node path selection<br/>[provisioner.go]"]
end

subgraph group_execution["Node operations"]
  node_helper_template["Helper pod validation<br/>[util.go]"]
  node_helper_execution["Helper pod execution<br/>[provisioner.go]"]
  node_node_storage[("Node-local storage")]
  node_shared_storage[("Shared filesystem")]
end

node_user(("Kubernetes user"))
node_kubernetes["Kubernetes control plane"]

node_user -->|"creates claim"| node_pvc
node_user -->|"creates pod"| node_workload
node_pvc -->|"submits claim"| node_kubernetes
node_kubernetes -.->|"dispatches request"| node_controller
node_controller -.->|"runs lifecycle"| node_provisioner
node_provisioner -->|"creates volume"| node_pv
node_pv -->|"binds claim"| node_kubernetes
node_workload -->|"uses bound volume"| node_pv
node_daemon_entry -->|"creates client"| node_kube_client
node_daemon_entry -->|"loads settings"| node_configmap
node_configmap -->|"reads ConfigMap"| node_kube_client
node_daemon_entry -->|"starts checks"| node_health
node_health -->|"queries resources"| node_kube_client
node_daemon_entry -->|"runs controller"| node_controller
node_provisioner -->|"uses configuration"| node_config_policy
node_provisioner -->|"selects path"| node_path_resolution
node_provisioner -->|"creates helper pod"| node_helper_execution
node_helper_execution -->|"creates pod"| node_kube_client
node_helper_execution -->|"sets up or cleans"| node_node_storage
node_provisioner -->|"supports shared paths"| node_shared_storage
node_helper_template -.->|"validates template"| node_helper_execution

click node_daemon_entry "https://github.com/rancher/local-path-provisioner/blob/master/main.go"
click node_kube_client "https://github.com/rancher/local-path-provisioner/blob/master/main.go"
click node_configmap "https://github.com/rancher/local-path-provisioner/blob/master/main.go"
click node_health "https://github.com/rancher/local-path-provisioner/blob/master/main.go"
click node_controller "https://github.com/rancher/local-path-provisioner/blob/master/main.go"
click node_provisioner "https://github.com/rancher/local-path-provisioner/blob/master/provisioner.go"
click node_config_policy "https://github.com/rancher/local-path-provisioner/blob/master/provisioner.go"
click node_path_resolution "https://github.com/rancher/local-path-provisioner/blob/master/provisioner.go"
click node_helper_template "https://github.com/rancher/local-path-provisioner/blob/master/util.go"
click node_helper_execution "https://github.com/rancher/local-path-provisioner/blob/master/provisioner.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_pvc,node_pv,node_workload,node_user toneBlue
class node_daemon_entry,node_kube_client,node_configmap,node_health,node_controller toneAmber
class node_provisioner,node_config_policy,node_path_resolution toneMint
class node_helper_template,node_helper_execution,node_node_storage,node_shared_storage toneRose
class node_kubernetes toneIndigo
```

## Components

### Storage workflow

- **Storage claim**
- **Persistent volume**
- **Pod workload**

### Daemon runtime

- [Daemon startup](https://github.com/rancher/local-path-provisioner/blob/master/main.go): `main.go`
- [Kubernetes client](https://github.com/rancher/local-path-provisioner/blob/master/main.go): `main.go`
- [ConfigMap loading](https://github.com/rancher/local-path-provisioner/blob/master/main.go): `main.go`
- [Readiness checks](https://github.com/rancher/local-path-provisioner/blob/master/main.go): `main.go`
- [Provisioner controller](https://github.com/rancher/local-path-provisioner/blob/master/main.go): `main.go`

### Provisioning policy

- [Volume lifecycle](https://github.com/rancher/local-path-provisioner/blob/master/provisioner.go): `provisioner.go`
- [Path configuration](https://github.com/rancher/local-path-provisioner/blob/master/provisioner.go): `provisioner.go`
- [Node path selection](https://github.com/rancher/local-path-provisioner/blob/master/provisioner.go): `provisioner.go`

### Node operations

- [Helper pod validation](https://github.com/rancher/local-path-provisioner/blob/master/util.go): `util.go`
- [Helper pod execution](https://github.com/rancher/local-path-provisioner/blob/master/provisioner.go): `provisioner.go`
- **Node-local storage**
- **Shared filesystem**

### Other components

- **Kubernetes user**
- **Kubernetes control plane**

## Connections

- Kubernetes user → Storage claim: creates claim (evidence: `README.md`)
- Kubernetes user → Pod workload: creates pod (evidence: `README.md`)
- Storage claim → Kubernetes control plane: submits claim (evidence: `README.md`)
- Kubernetes control plane → Provisioner controller: dispatches request
- Provisioner controller → Volume lifecycle: runs lifecycle
- Volume lifecycle → Persistent volume: creates volume (evidence: `README.md`)
- Persistent volume → Kubernetes control plane: binds claim (evidence: `README.md`)
- Pod workload → Persistent volume: uses bound volume (evidence: `README.md`)
- Daemon startup → Kubernetes client: creates client (evidence: `main.go`)
- Daemon startup → ConfigMap loading: loads settings (evidence: `main.go`)
- ConfigMap loading → Kubernetes client: reads ConfigMap (evidence: `main.go`)
- Daemon startup → Readiness checks: starts checks (evidence: `main.go`)
- Readiness checks → Kubernetes client: queries resources (evidence: `main.go`)
- Daemon startup → Provisioner controller: runs controller (evidence: `main.go`)
- Volume lifecycle → Path configuration: uses configuration (evidence: `provisioner.go`)
- Volume lifecycle → Node path selection: selects path (evidence: `provisioner.go`)
- Volume lifecycle → Helper pod execution: creates helper pod (evidence: `provisioner.go`)
- Helper pod execution → Kubernetes client: creates pod (evidence: `provisioner.go`)
- Helper pod execution → Node-local storage: sets up or cleans (evidence: `README.md`)
- Volume lifecycle → Shared filesystem: supports shared paths (evidence: `README.md`)
- Helper pod validation → Helper pod execution: validates template
