Configuration

This page describes how to configure the CSI Hostpath Driver for your Kubernetes environment. It covers the environment variables, container entrypoint behavior, and runtime options that control how the driver provisions local hostpath volumes on a node. Understanding these settings lets you tune the driver to match your development or testing workflow before you deploy workloads that depend on CSI-based persistent storage.

Before configuring the CSI Hostpath Driver, ensure you have the following in place:

• A running Kubernetes cluster accessible via kubectl
• The hostpathplugin binary built or the container image pulled (the image is based on Alpine Linux and packages util-linux for losetup support)
• Sufficient permissions to create and manage CSI driver objects, DaemonSets, and related RBAC resources in your cluster
• Familiarity with Kubernetes PersistentVolumes and the CSI specification

Follow these steps to build and deploy the CSI Hostpath Driver.

1. Clone the repository and navigate to the project root:

git clone https://github.com/kubernetes-csi/csi-driver-host-path.git
cd csi-driver-host-path

2. Build the hostpathplugin binary using the project Makefile:

make

This compiles the hostpathplugin binary into the ./bin/ directory.

3. Build the container image (optional, if you need a custom image):

docker build -t your-registry/hostpathplugin:latest .

The Dockerfile copies ./bin/hostpathplugin into an Alpine-based image and sets it as the container entrypoint. The image also installs util-linux to provide an up-to-date version of losetup.

4. Push the image to your container registry if deploying a custom build:

docker push your-registry/hostpathplugin:latest

5. Deploy the driver to your cluster using the provided deployment manifests (located in the deploy/ directory of the repository):

kubectl apply -f deploy/

The CSI Hostpath Driver is configured primarily through command-line flags passed to the hostpathplugin entrypoint inside the container. These flags are specified in your Kubernetes pod or DaemonSet spec under args.

General guidance:

• Flags are passed via the args field of the container spec in your DaemonSet or Deployment manifest.
• Environment variables set in the pod spec (under env) can supplement flag-based configuration depending on driver version.
• The driver does not use an external config file by default; all runtime behavior is controlled at startup via flags.

Because the driver runs as a container with /hostpathplugin as its ENTRYPOINT, any flags you specify in the pod's args array are appended directly to the binary invocation, for example:

containers:
  - name: hostpath
    image: your-registry/hostpathplugin:latest
    args:
      - "--flag-name=value"

Once the driver is deployed, you interact with it through standard Kubernetes storage primitives — you do not call the driver binary directly. The driver exposes its CSI interface over a Unix domain socket that Kubernetes node and controller components communicate with on your behalf.

Create a StorageClass that references the CSI Hostpath Driver:

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: csi-hostpath-sc
provisioner: hostpath.csi.k8s.io
reclaimPolicy: Delete
volumeBindingMode: Immediate

Apply it to your cluster:

kubectl apply -f storageclass.yaml

Create a PersistentVolumeClaim backed by the StorageClass:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: my-hostpath-pvc
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 1Gi
  storageClassName: csi-hostpath-sc

kubectl apply -f pvc.yaml

Mount the volume in a pod:

apiVersion: v1
kind: Pod
metadata:
  name: my-app
spec:
  containers:
    - name: app
      image: busybox
      command: ["sleep", "3600"]
      volumeMounts:
        - mountPath: /data
          name: storage
  volumes:
    - name: storage
      persistentVolumeClaim:
        claimName: my-hostpath-pvc

kubectl apply -f pod.yaml

After the pod starts, data written to /data inside the container is stored in the hostpath directory on the node where the pod is scheduled.

Example 1 — Verify the StorageClass is registered

After deploying the driver and creating the StorageClass, confirm it is visible to Kubernetes:

kubectl get storageclass csi-hostpath-sc

Expected output:

NAME             PROVISIONER              RECLAIMPOLICY   VOLUMEBINDINGMODE   ALLOWVOLUMEEXPANSION   AGE
csi-hostpath-sc  hostpath.csi.k8s.io      Delete          Immediate           false                  30s

Example 2 — Confirm the PVC is bound

After applying the PVC manifest, check that Kubernetes successfully provisioned a volume:

kubectl get pvc my-hostpath-pvc

Expected output:

NAME               STATUS   VOLUME                                     CAPACITY   ACCESS MODES   STORAGECLASS      AGE
my-hostpath-pvc    Bound    pvc-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx   1Gi        RWO            csi-hostpath-sc   10s

If the STATUS remains Pending, the driver may not be running or may be unable to schedule the volume — see the Troubleshooting section.

Example 3 — Write and read data through the mounted volume

Exec into the running pod and verify read/write access:

kubectl exec -it my-app -- sh -c "echo 'hello hostpath' > /data/test.txt && cat /data/test.txt"

Expected output:

hello hostpath

Example 4 — Inspect driver logs

If you need to observe provisioning events, stream the driver pod logs:

kubectl logs -l app=csi-hostpathplugin -n kube-system --follow

Expected output: A stream of gRPC calls corresponding to CreateVolume, NodeStageVolume, and NodePublishVolume as Kubernetes interacts with the driver.

Use the following reference to diagnose common problems with the CSI Hostpath Driver.

Issue: PVC stays in Pending state

• Symptom: kubectl get pvc shows STATUS: Pending indefinitely after applying the PVC manifest.
• Likely cause: The driver pod is not running, the CSIDriver object is missing, or the StorageClass provisioner field does not match the driver's registered name.
• Fix:
  1. Check that the driver pod is running: kubectl get pods -n kube-system -l app=csi-hostpathplugin
  2. Confirm the CSIDriver object exists: kubectl get csidriver hostpath.csi.k8s.io
  3. Verify the provisioner value in your StorageClass exactly matches the driver's registered identity.

Issue: Pod fails to start with a volume mount error

• Symptom: Pod events show FailedMount or FailedAttach.
• Likely cause: The driver's node plugin is not running on the node where the pod was scheduled, or the Unix socket path is misconfigured.
• Fix:
  1. Confirm the DaemonSet has a running pod on the target node: kubectl get pods -n kube-system -o wide
  2. Check driver logs for socket or permission errors: kubectl logs <driver-pod> -n kube-system

Issue: losetup errors in driver logs

• Symptom: Driver logs contain errors referencing losetup or loop devices.
• Likely cause: The node kernel does not support loop devices, or the driver container is running without the necessary privileges.
• Fix:
  1. Ensure the driver container is running in privileged mode in your DaemonSet spec.
  2. Confirm loop device support is enabled on the node: lsmod | grep loop
  3. The base image includes util-linux specifically for an up-to-date losetup; if you are using a custom image, ensure this package is present.

Issue: make fails during build

• Symptom: Running make exits with a compilation error.
• Likely cause: Missing Go toolchain or incorrect Go version.
• Fix:
  1. Ensure Go is installed and available in your PATH: go version
  2. Confirm the version meets the project's requirements (see go.mod in the repository root).