--- title: Getting Started product: csi-driver-host-path doc_type: tutorial version: master source: git2docs (code-derived, validation-filtered) canonical: https://git2docs.com/xing-yang/docs/csi-driver-host-path/csi-hostpath-driver/getting-started --- # Getting Started _Making your first API request_ ## Overview 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: ```shell $ deploy/kubernetes-1.13/deploy-hostpath.sh ``` 2. Confirm all driver pods are running: ```shell $ kubectl get pods ``` 3. Deploy the example application, storage class, and PVC: ```shell $ kubectl create -f ./examples ``` 4. Verify the PVC is bound: ```shell $ 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: ```shell $ 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: ```shell $ 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: ```shell $ 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: ```shell $ 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`: ```shell $ 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: ```shell $ 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`: ```shell $ 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//` 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: ```shell $ 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: ```shell $ 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`: ```shell $ 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** ```shell $ 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: ```shell $ kubectl exec -it my-csi-app /bin/sh / # touch /data/hello-world / # exit ``` Locate the file in the hostpath plugin container: ```shell $ 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//hello-world` confirms the volume is correctly backed by the hostpath container's filesystem. --- **Example 5: VolumeAttachment confirming the volume is attached** ```shell $ 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 ` 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.