Key Concepts

This page explains the core concepts behind the CSI Hostpath Driver: how it models storage, what Kubernetes API objects it creates and manages, and how the driver's components interact with each other. Understanding these concepts will help you reason about what happens when you provision a volume, attach it to a pod, or take a snapshot — and why the driver behaves the way it does in each case.

What the CSI Hostpath Driver is

The CSI Hostpath Driver is a lightweight implementation of the Container Storage Interface (CSI) specification for Kubernetes. Rather than provisioning storage on an external system, it carves out directories on the node's local filesystem — by default under /tmp inside the hostpath plugin container — and presents them as persistent volumes to your workloads.

Because volumes live on the node, the driver is best suited for testing and evaluating CSI-based storage workflows. It lets you exercise the full CSI lifecycle (provision → attach → mount → snapshot → restore) without requiring a cloud provider or dedicated storage backend.

Core API objects

The driver works by creating and managing several Kubernetes API objects. Understanding what each object represents will help you trace the state of your storage at any point.

StorageClass

A StorageClass named csi-hostpath-sc tells Kubernetes to use the Hostpath driver as the provisioner for any PersistentVolumeClaim that references it. When you submit a PVC bound to this class, the external provisioner component watches for that event and instructs the driver to allocate a new directory on the node.

PersistentVolumeClaim (PVC) and PersistentVolume (PV)

A PersistentVolumeClaim is your application's request for storage — you declare how much capacity you need and which access modes you require (for example, ReadWriteOnce). The driver fulfils that claim by dynamically creating a PersistentVolume backed by a directory under /tmp in the plugin container. The PV and PVC are then bound to each other.

The reclaim policy is set to Delete by default: when you delete the PVC, the driver removes the underlying directory as well.

VolumeAttachment

After a PV is created, Kubernetes must attach it to the specific node where your pod is scheduled before the kubelet can mount it into the container. The VolumeAttachment object records this attachment. It captures:

• Attacher — the driver name (csi-hostpath) responsible for the attachment.
• Node name — the target node.
• Persistent volume name — the PV being attached.
• Status.Attached — a boolean that the external attacher sets to true once the operation succeeds.

You can inspect a VolumeAttachment to confirm that the driver successfully completed the attach phase.

VolumeSnapshotClass, VolumeSnapshot, and VolumeSnapshotContent

The driver supports the alpha volume snapshot API introduced in Kubernetes v1.12. Three objects are involved:

Once a snapshot exists, you can restore it by creating a new PVC that references the snapshot as its data source. The driver provisions a new volume pre-populated with the snapshot's contents.

Driver components and how they interact

The deployment ships as a set of stateful pods. Each component has a focused responsibility:

hostpathplugin

The core driver container. It implements the CSI gRPC endpoints for identity, controller (create/delete volumes and snapshots, attach/detach), and node (mount/unmount) operations. This is the only component that physically creates directories under /tmp.

A liveness probe sidecar continuously checks the CSI endpoints and reports health back to Kubernetes so that the pod is restarted automatically if the driver becomes unresponsive.

A node-driver-registrar sidecar registers the driver with the kubelet on the node so that Kubernetes knows which socket to use when it needs to call node-level CSI operations.

external-provisioner

Watches for new PersistentVolumeClaim objects that reference the csi-hostpath-sc StorageClass. When it detects one, it calls the driver's CreateVolume endpoint and then creates the corresponding PersistentVolume object in the Kubernetes API.

external-attacher

Watches for VolumeAttachment objects and calls the driver's ControllerPublishVolume endpoint to perform the attach operation. It then updates the VolumeAttachment status to signal that the volume is ready for the kubelet to mount.

external-snapshotter

Watches for VolumeSnapshot objects and calls the driver's CreateSnapshot endpoint. It creates the VolumeSnapshotContent object to record the result and keeps snapshot status up to date.

Volume lifecycle

The following sequence describes what happens from the moment you submit a PVC to the moment your pod can write data:

1. Provision — You create a PVC referencing csi-hostpath-sc. The external-provisioner detects this and calls CreateVolume on the driver. A new directory is created under /tmp in the plugin container, and a PV is registered in the Kubernetes API.
2. Bind — Kubernetes binds the PVC to the new PV.
3. Attach — When your pod is scheduled, Kubernetes creates a VolumeAttachment object. The external-attacher calls ControllerPublishVolume; the driver confirms the volume is available on the target node and sets Status.Attached: true.
4. Mount — The kubelet calls the driver's node-level NodeStageVolume and NodePublishVolume endpoints to bind-mount the directory into your pod's filesystem at the path you specify (for example, /data).
5. Use — Your application reads and writes files. Those files are physically stored in the directory under /tmp inside the hostpath plugin container.
6. Unmount and detach — When the pod is deleted, the kubelet calls NodeUnpublishVolume and NodeUnstageVolume, then Kubernetes removes the VolumeAttachment.
7. Delete — When the PVC is deleted, the external-provisioner calls DeleteVolume and removes both the PV object and the underlying directory.

Where volumes are stored

All volumes are stored as subdirectories under /tmp inside the csi-hostpathplugin StatefulSet pod. Directory names correspond to the volume's unique ID (for example, /tmp/057485ab-c714-11e8-bb16-000c2967769a). This storage persists only as long as the plugin pod is running — if the pod is deleted or the node is rebooted, the volume data is lost. This reinforces why the driver is intended for development and testing rather than production use.

Inspect a bound PersistentVolume and PersistentVolumeClaim

After deploying the example application, confirm that the driver provisioned a PV and that it is bound to the PVC:

kubectl get pv

Expected output:

NAME                                       CAPACITY   ACCESS MODES   RECLAIM POLICY   STATUS   CLAIM             STORAGECLASS      REASON   AGE
pvc-58d5ec38-03e5-11e9-be51-000c29e88ff1   1Gi        RWO            Delete           Bound    default/csi-pvc   csi-hostpath-sc            80s

kubectl get pvc

Expected output:

NAME      STATUS   VOLUME                                     CAPACITY   ACCESS MODES   STORAGECLASS      AGE
csi-pvc   Bound    pvc-58d5ec38-03e5-11e9-be51-000c29e88ff1   1Gi        RWO            csi-hostpath-sc   93s

The STATUS: Bound field on both objects confirms that the provisioner created the PV and that Kubernetes paired it with the PVC.

Inspect the VolumeAttachment object

To verify that the external-attacher successfully completed the attach phase, describe the VolumeAttachment resource:

kubectl describe volumeattachment

Expected output:

Name:         csi-a7515d53b30a1193fd70b822b18181cff1d16422fd922692bce5ea234cb191e9
Namespace:
Labels:       <none>
Annotations:  <none>
API Version:  storage.k8s.io/v1
Kind:         VolumeAttachment
Spec:
  Attacher:   csi-hostpath
  Node Name:  127.0.0.1
  Source:
    Persistent Volume Name:  pvc-58d5ec38-03e5-11e9-be51-000c29e88ff1
Status:
  Attached:  true

Status.Attached: true means the driver confirmed the volume is attached to the node and the kubelet can proceed with mounting it into your pod.

Verify that a file written inside the pod is visible in the hostpath container

This example demonstrates the full round-trip: a file written by your application appears in the underlying hostpath directory, confirming that the volume mount is working correctly.

Step 1 — Create a file from inside the application pod:

kubectl exec -it my-csi-app /bin/sh

/ # touch /data/hello-world
/ # exit

Step 2 — Locate the file inside the hostpath plugin container:

kubectl exec -it $(kubectl get pods --selector app=csi-hostpathplugin -o jsonpath='{.items[*].metadata.name}') -c hostpath /bin/sh

/ # find / -name hello-world
/tmp/057485ab-c714-11e8-bb16-000c2967769a/hello-world
/ # exit

The file path /tmp/<volume-id>/hello-world shows you exactly where the driver stored the volume data on the node.

Inspect a VolumeSnapshot and its backing VolumeSnapshotContent

After creating a snapshot, you can examine both sides of the snapshot relationship.

kubectl describe volumesnapshot

Expected output (abbreviated):

Name:         new-snapshot-demo
Namespace:    default
API Version:  snapshot.storage.k8s.io/v1alpha1
Kind:         VolumeSnapshot
Spec:
  Snapshot Class Name:    csi-hostpath-snapclass
  Snapshot Content Name:  snapcontent-f55db632-c716-11e8-8911-000c2967769a
  Source:
    Kind:  PersistentVolumeClaim
    Name:  csi-pvc
Status:
  Ready:          true
  Restore Size:   1Gi

The Status.Ready: true field confirms the snapshot was taken successfully and is available for restore.

• Container Storage Interface (CSI) specification — The vendor-neutral API that the Hostpath Driver implements. Reading the spec helps you understand the gRPC operations (CreateVolume, ControllerPublishVolume, NodePublishVolume, and so on) that each driver component calls.
• Kubernetes Persistent Volumes — The Kubernetes documentation on PersistentVolumes and PersistentVolumeClaims, including access modes, reclaim policies, and the PV/PVC binding lifecycle.
• Kubernetes Storage Classes — How StorageClass objects configure dynamic provisioning and which parameters are passed to the underlying CSI driver.
• Volume Snapshots — The Kubernetes documentation on the VolumeSnapshot API, including how to enable the VolumeSnapshotDataSource feature gate required by the Hostpath Driver's snapshot support.
• CSI external-provisioner — The sidecar that watches for PVCs and triggers CreateVolume calls on behalf of the driver.
• CSI external-attacher — The sidecar responsible for managing VolumeAttachment objects and calling ControllerPublishVolume.
• CSI liveness probe — The sidecar that monitors driver health and triggers pod restarts when a CSI endpoint becomes unresponsive.