--- title: Key Concepts product: csi-driver-host-path doc_type: concept version: master source: git2docs (code-derived, validation-filtered) canonical: https://git2docs.com/xing-yang/docs/csi-driver-host-path/csi-hostpath-driver/key-concepts --- # Key Concepts _Domain concepts and API design patterns_ ## Overview 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. ## Content ## What the CSI Hostpath Driver is The CSI Hostpath Driver is a lightweight implementation of the [Container Storage Interface (CSI)](https://github.com/container-storage-interface/spec) 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: | Object | Role | |---|---| | `VolumeSnapshotClass` | Declares the snapshotter (`csi-hostpath`) and the deletion policy for snapshots taken with this class. | | `VolumeSnapshot` | A user-facing request for a point-in-time copy of a PVC. You reference a `VolumeSnapshotClass` and a source PVC. | | `VolumeSnapshotContent` | The driver-side record of the actual snapshot. Kubernetes creates this automatically when a `VolumeSnapshot` is fulfilled. | 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. ## Examples ### 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: ```shell 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 ``` ```shell 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: ```shell kubectl describe volumeattachment ``` Expected output: ``` Name: csi-a7515d53b30a1193fd70b822b18181cff1d16422fd922692bce5ea234cb191e9 Namespace: Labels: Annotations: 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:** ```shell kubectl exec -it my-csi-app /bin/sh ``` ```shell / # touch /data/hello-world / # exit ``` **Step 2 — Locate the file inside the hostpath plugin container:** ```shell kubectl exec -it $(kubectl get pods --selector app=csi-hostpathplugin -o jsonpath='{.items[*].metadata.name}') -c hostpath /bin/sh ``` ```shell / # find / -name hello-world /tmp/057485ab-c714-11e8-bb16-000c2967769a/hello-world / # exit ``` The file path `/tmp//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. ```shell 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. ## Related concepts - **[Container Storage Interface (CSI) specification](https://github.com/container-storage-interface/spec)** — 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](https://kubernetes.io/docs/concepts/storage/persistent-volumes/)** — The Kubernetes documentation on PersistentVolumes and PersistentVolumeClaims, including access modes, reclaim policies, and the PV/PVC binding lifecycle. - **[Kubernetes Storage Classes](https://kubernetes.io/docs/concepts/storage/storage-classes/)** — How StorageClass objects configure dynamic provisioning and which parameters are passed to the underlying CSI driver. - **[Volume Snapshots](https://kubernetes.io/docs/concepts/storage/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](https://github.com/kubernetes-csi/external-provisioner)** — The sidecar that watches for PVCs and triggers `CreateVolume` calls on behalf of the driver. - **[CSI external-attacher](https://github.com/kubernetes-csi/external-attacher)** — The sidecar responsible for managing VolumeAttachment objects and calling `ControllerPublishVolume`. - **[CSI liveness probe](https://github.com/kubernetes-csi/livenessprobe)** — The sidecar that monitors driver health and triggers pod restarts when a CSI endpoint becomes unresponsive.