Docs/CSI Hostpath Driver/Getting Started
Tutorial

Getting Started

Making your first API request

Overview
Getting Started: Making Your First API Request CSI HOSTPATH DRIVER — WORKFLOW 1. Verify Prerequisites Kubernetes ≥ 1.13 + kubectl installed Cluster running? kubectl cluster-info No Start / provision a Kubernetes cluster Yes 2. Access Deploy Script deploy/kubernetes-1.13/deploy-hostpath.sh 3. Run Deployment Script $ ./deploy-hostpath.sh Deployment OK? Check pod status No Check logs & review RBAC/images Yes 4. Create StorageClass & PVC Apply StorageClass, then PVC manifest 5. Verify Volume Bound kubectl get pvc — STATUS: Bound ✓ ✓ First volume provisioned! SETUP DEPLOY USE

This tutorial walks you through deploying the CSI Hostpath Driver on a Kubernetes cluster and making your first API request to provision a persistent volume. The CSI Hostpath Driver is a lightweight driver that provisions local hostpath volumes on a node, making it ideal for quickly testing and evaluating CSI-based persistent storage workflows. By the end of this page, you will have a running driver, a provisioned volume mounted to an application pod, and confirmation that the driver is functioning correctly.

Prerequisites

Before you begin, make sure you have the following:

  • A running Kubernetes cluster at version 1.13 or later
  • kubectl installed and configured to communicate with your cluster
  • Terminal access to execute shell commands
  • Sufficient permissions to apply RBAC rules and create cluster-level resources
  • (Optional) The VolumeSnapshotDataSource feature gate enabled on your cluster if you intend to use volume snapshot functionality (alpha in Kubernetes v1.12+)
Quick start

The steps below get you from zero to a running CSI Hostpath Driver with a provisioned volume as fast as possible.

  1. Run the deployment script for your Kubernetes version:
$ deploy/kubernetes-1.13/deploy-hostpath.sh
  1. Confirm all driver pods are running:
$ kubectl get pods
  1. Deploy the example application, storage class, and PVC:
$ kubectl create -f ./examples
  1. Verify the PVC is bound:
$ kubectl get pvc

Once the csi-pvc PVC shows a Bound status, your driver is deployed and serving storage requests.

Steps

Follow these steps to fully deploy the driver, provision a volume, and validate the setup.

Step 1: Deploy the CSI Hostpath Driver

Run the deployment script that matches your Kubernetes version. For Kubernetes 1.13:

$ deploy/kubernetes-1.13/deploy-hostpath.sh

This script applies RBAC rules and deploys four components: the hostpath plugin, external provisioner, external attacher, and snapshotter. It also deploys a liveness probe side-container to monitor CSI service health. Wait for the script to complete — it will print the deployment status of each component to your terminal.

Step 2: Verify all driver pods are running

Confirm that all expected pods have started and are in the Running state:

$ kubectl get pods

You should see four pods: csi-hostpath-attacher-0, csi-hostpath-provisioner-0, csi-hostpath-snapshotter-0, and csi-hostpathplugin-0. The plugin pod should show 2/2 ready containers (the driver and the liveness probe). Do not proceed until all pods show Running.

Step 3: Deploy the example application

From the repository root, apply the example manifests. This creates a StorageClass, a PersistentVolumeClaim (PVC), and an application pod that mounts a volume provisioned by the driver:

$ kubectl create -f ./examples

The driver will dynamically provision a PersistentVolume (PV) in response to the PVC request.

Step 4: Confirm the PV and PVC are bound

Check that the PVC has been satisfied and a PV has been created:

$ kubectl get pv
$ kubectl get pvc

The csi-pvc PVC should show Bound status and reference the dynamically provisioned PV.

Step 5: Inspect the application pod

Verify that the application pod my-csi-app is running and has the volume mounted at /data:

$ kubectl describe pods/my-csi-app

Look for Status: Running and confirm that the Volumes section lists my-csi-volume with ClaimName: csi-pvc.

Step 6: Confirm the driver works end-to-end

Write a file from inside the application pod:

$ kubectl exec -it my-csi-app /bin/sh
/ # touch /data/hello-world
/ # exit

Then exec into the hostpath plugin container and verify the file exists under /tmp:

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

Locating hello-world under a /tmp/<volume-id>/ path confirms that the volume is properly mounted and the driver is working.

Step 7: Inspect the VolumeAttachment object

As a final check, inspect the VolumeAttachment object that Kubernetes created when it attached the volume to the node:

$ kubectl describe volumeattachment

Confirm that Status.Attached is true. This proves the CSI attacher component successfully communicated with the driver.

Examples

Example 1: Successful driver deployment output

When you run the deployment script, you should see output similar to the following, confirming that RBAC rules were applied and all components were created:

$ deploy/kubernetes-1.13/deploy-hostpath.sh
applying RBAC rules
kubectl apply -f https://raw.githubusercontent.com/kubernetes-csi/external-provisioner/v1.0.1/deploy/kubernetes/rbac.yaml
serviceaccount/csi-provisioner created
clusterrole.rbac.authorization.k8s.io/external-provisioner-runner created
clusterrolebinding.rbac.authorization.k8s.io/csi-provisioner-role created
...
deploying hostpath components
service/csi-hostpath-attacher created
statefulset.apps/csi-hostpath-attacher created
service/csi-hostpathplugin created
statefulset.apps/csi-hostpathplugin created
service/csi-hostpath-provisioner created
statefulset.apps/csi-hostpath-provisioner created
service/csi-hostpath-snapshotter created
statefulset.apps/csi-hostpath-snapshotter created
deploying snapshotclass
voluesnapshotclass.snapshot.storage.k8s.io/csi-hostpath-snapclass created

Example 2: All driver pods in Running state

After deployment, kubectl get pods should return four pods all showing Running:

$ kubectl get pods
NAME                         READY   STATUS    RESTARTS   AGE
csi-hostpath-attacher-0      1/1     Running   0          5m47s
csi-hostpath-provisioner-0   1/1     Running   0          5m47s
csi-hostpath-snapshotter-0   1/1     Running   0          5m47s
csi-hostpathplugin-0         2/2     Running   0          5m45s

Note that csi-hostpathplugin-0 shows 2/2 because it runs both the driver container and the liveness probe side-container.

Example 3: PV and PVC bound after applying examples

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

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

A Bound status for the PVC confirms the driver received the storage request and provisioned a volume.

Example 4: File written to the volume appears in the hostpath container

Write the file from the application pod:

$ kubectl exec -it my-csi-app /bin/sh
/ # touch /data/hello-world
/ # exit

Locate the file in 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 appearing under /tmp/<volume-id>/hello-world confirms the volume is correctly backed by the hostpath container's filesystem.

Example 5: VolumeAttachment confirming the volume is attached

$ kubectl describe volumeattachment
Name:         csi-a7515d53b30a1193fd70b822b18181cff1d16422fd922692bce5ea234cb191e9
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 confirms the CSI attacher sidecar successfully communicated the attach operation to the driver.

Troubleshooting

Use the following reference to diagnose common issues.

Issue: One or more driver pods are stuck in Pending or CrashLoopBackOff

  • Symptom: kubectl get pods shows a driver pod not in Running state.
  • Likely cause: Insufficient cluster resources, a failed image pull, or a missing RBAC permission.
  • Fix: Run kubectl describe pod <pod-name> to read the Events section. Look for FailedScheduling (resource constraints), ErrImagePull (network or registry issue), or Error exit codes. Correct the underlying issue — for RBAC errors, re-run the deployment script to reapply the rules.

Issue: PVC remains in Pending state after applying examples

  • Symptom: kubectl get pvc shows csi-pvc with status Pending for more than a minute.
  • Likely cause: The csi-hostpath-provisioner-0 pod is not running, or the StorageClass was not created correctly.
  • Fix: Verify the provisioner pod is Running with kubectl get pods. Check provisioner logs with kubectl logs csi-hostpath-provisioner-0. Also confirm the storage class exists: kubectl get storageclass csi-hostpath-sc.

Issue: The hello-world file is not found in the hostpath container

  • Symptom: find / -name hello-world inside the hostpath container returns no results.
  • Likely cause: The volume was not mounted correctly in the application pod, or you are exec-ing into the wrong container.
  • Fix: Confirm the application pod has the volume mounted by running kubectl describe pods/my-csi-app and checking the Mounts section for /data. Ensure you are targeting the hostpath container specifically with -c hostpath in your kubectl exec command. Also verify the pod is on the same node as the hostpath plugin.

Issue: VolumeAttachment shows Attached: false or does not exist

  • Symptom: kubectl describe volumeattachment shows Attached: false or the command returns no resources.
  • Likely cause: The csi-hostpath-attacher sidecar is not running or encountered an error communicating with the driver.
  • Fix: Check the attacher pod status with kubectl get pods and inspect its logs: kubectl logs csi-hostpath-attacher-0. Ensure the csi-hostpathplugin-0 pod is healthy, as the attacher depends on the plugin's gRPC endpoint.

Issue: Snapshot-related resources are not available

  • Symptom: Commands like kubectl get volumesnapshotclass return errors about unknown resource types.
  • Likely cause: The VolumeSnapshotDataSource feature gate is not enabled on your cluster, or your Kubernetes version is below 1.12.
  • Fix: Enable the VolumeSnapshotDataSource feature gate on the API server and controller manager. This feature is alpha and must be explicitly opted into. Refer to your cluster provider's documentation for enabling feature gates.