--- title: Deployment Guide product: csi-driver-host-path doc_type: guide version: master source: git2docs (code-derived, validation-filtered) canonical: https://git2docs.com/xing-yang/docs/csi-driver-host-path/csi-hostpath-driver/deployment-guide --- # Deployment Guide _Deploying to production (Docker, Kubernetes, serverless)_ ## Overview This guide walks you through deploying the CSI Hostpath Driver to a Kubernetes cluster so you can provision local hostpath volumes and test CSI-based persistent storage workflows. The driver runs as a lightweight plugin built on Alpine Linux, exposing a CSI-compatible API that Kubernetes uses to create, attach, and manage volumes on a node. By the end of this guide, your cluster will have a functioning CSI driver ready to serve `PersistentVolumeClaim` requests. This is the recommended starting point before integrating the driver into any application-level storage workflow. ## Prerequisites Before you begin, make sure you have the following in place: - **A running Kubernetes cluster** — The CSI Hostpath Driver is deployed as a Kubernetes workload; you need `kubectl` access to your cluster. - **`kubectl` CLI** — Configured to communicate with your target cluster (`kubectl version` should return both client and server versions). - **Docker or a compatible container runtime** — Required if you intend to build the driver image locally from the `Dockerfile`. - **Sufficient node permissions** — The driver mounts paths on the host node, so your cluster nodes must allow hostpath volume access. In most managed clusters this requires a permissive `PodSecurityPolicy` or equivalent admission configuration. - **`make` and a Go toolchain** — Only required if you are building the `hostpathplugin` binary from source using the provided `Makefile`. Pre-built images do not require this. > **Note for reviewer:** Specific minimum Kubernetes version, Go version, and Docker version requirements are not present in the source material. Please supply exact version constraints before publishing. ## Installation ### Step 1 — Build the driver binary (source builds only) If you are using a pre-built container image, skip to Step 2. From the root of the repository, run: ```bash make all ``` This compiles the `hostpathplugin` binary and places it in the `./bin/` directory. --- ### Step 2 — Build the container image The `Dockerfile` copies the compiled binary into an Alpine-based image and sets it as the container entrypoint. ```bash docker build -t csi-hostpathplugin:latest . ``` Verify the image was created: ```bash docker images | grep csi-hostpathplugin ``` Expected output: ``` csi-hostpathplugin latest ``` --- ### Step 3 — Push the image to a registry accessible by your cluster Tag the image for your registry and push it: ```bash docker tag csi-hostpathplugin:latest /csi-hostpathplugin:latest docker push /csi-hostpathplugin:latest ``` Replace `` with your actual container registry host (for example, `registry.example.com/myproject`). --- ### Step 4 — Deploy the driver to Kubernetes Apply the Kubernetes manifests that define the CSI driver `DaemonSet`, `ServiceAccount`, RBAC rules, and `CSIDriver` object. If you are using the manifests bundled with the repository: ```bash kubectl apply -f deploy/kubernetes/ ``` > **Note for reviewer:** The source material does not include Kubernetes manifest files. The exact manifest directory path, manifest contents, and any Helm chart details should be added here before publishing. --- ### Step 5 — Confirm the driver pods are running ```bash kubectl get pods -n kube-system -l app=csi-hostpathplugin ``` All pods should show `Running` status before you proceed. ## Configuration The `hostpathplugin` binary is launched via the container `ENTRYPOINT` defined in the `Dockerfile`. You pass configuration to the driver through command-line flags or environment variables when you define the container spec in your Kubernetes manifests. > **Note for reviewer:** The source material (Dockerfile and Makefile) does not enumerate the specific flags, environment variables, or configuration file options accepted by `hostpathplugin`. The table below is a structural placeholder. Please supply the actual flag names, defaults, valid values, and behavioral descriptions from the driver's Go source or help output (`/hostpathplugin --help`) before publishing. | Flag / Environment Variable | Default | Valid Values | Effect | |---|---|---|---| | *(flag name)* | *(default)* | *(accepted values)* | *(what it controls)* | **General guidance:** - **Node ID** — Typically required so the driver can register itself with the Kubernetes CSI node registrar. Set this to a value that uniquely identifies the node. - **Endpoint** — The Unix domain socket path over which Kubernetes communicates with the CSI driver. This is passed in the container spec and must match the socket path used by the node-driver-registrar sidecar. - **Root directory** — The host path under which the driver creates volume directories. Changing this affects where data is physically stored on the node. ## Usage Once the driver is deployed and its pods are running, you interact with it through the standard Kubernetes storage API — you do not call the driver's CSI gRPC endpoints directly. The common workflow is: 1. **Create a `StorageClass`** that references the CSI Hostpath Driver as the provisioner. This tells Kubernetes to route `PersistentVolumeClaim` requests to the driver. 2. **Submit a `PersistentVolumeClaim` (PVC)** referencing that `StorageClass`. Kubernetes calls the driver's `CreateVolume` CSI endpoint internally, and the driver provisions a directory on the node. 3. **Mount the PVC in a `Pod`**. When the pod is scheduled, Kubernetes calls the driver's `NodePublishVolume` endpoint, which bind-mounts the provisioned directory into the container. 4. **Verify the volume** by writing and reading data inside the running container. All of these steps use standard `kubectl` commands and Kubernetes manifest files — no driver-specific CLI tooling is required after deployment. > **Note for reviewer:** If the driver exposes any HTTP-based management or status API endpoints, those details are not present in the source material and should be documented here, including base URL, authentication method, and example requests/responses. ## Examples ### Example 1 — Create a StorageClass backed by the CSI Hostpath Driver Save the following as `storageclass.yaml` and apply it: ```yaml apiVersion: storage.k8s.io/v1 kind: StorageClass metadata: name: csi-hostpath-sc provisioner: hostpath.csi.k8s.io reclaimPolicy: Delete volumeBindingMode: Immediate ``` ```bash kubectl apply -f storageclass.yaml ``` Expected output: ``` storageclass.storage.k8s.io/csi-hostpath-sc created ``` --- ### Example 2 — Provision a PersistentVolumeClaim Save the following as `pvc.yaml`: ```yaml apiVersion: v1 kind: PersistentVolumeClaim metadata: name: csi-hostpath-pvc spec: accessModes: - ReadWriteOnce storageClassName: csi-hostpath-sc resources: requests: storage: 1Gi ``` ```bash kubectl apply -f pvc.yaml ``` Confirm the PVC is bound: ```bash kubectl get pvc csi-hostpath-pvc ``` Expected output: ``` NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE csi-hostpath-pvc Bound pvc- 1Gi RWO csi-hostpath-sc 10s ``` --- ### Example 3 — Mount the volume in a Pod and verify it Save the following as `pod.yaml`: ```yaml apiVersion: v1 kind: Pod metadata: name: csi-hostpath-demo spec: containers: - name: demo image: busybox command: ["sh", "-c", "echo 'CSI Hostpath works!' > /data/test.txt && sleep 3600"] volumeMounts: - mountPath: /data name: hostpath-vol volumes: - name: hostpath-vol persistentVolumeClaim: claimName: csi-hostpath-pvc ``` ```bash kubectl apply -f pod.yaml kubectl wait --for=condition=Ready pod/csi-hostpath-demo --timeout=60s kubectl exec csi-hostpath-demo -- cat /data/test.txt ``` Expected output: ``` CSI Hostpath works! ``` > **Note for reviewer:** The provisioner name `hostpath.csi.k8s.io` used in these examples is a common convention for this driver but is not explicitly confirmed in the provided source material. Please verify the exact provisioner string from the driver's identity response or deployment manifests. ## Troubleshooting Use the consistent format below: **Symptom → Likely cause → Fix**. --- **PVC stays in `Pending` state indefinitely** - *Symptom:* `kubectl get pvc` shows `STATUS: Pending` after several minutes. - *Likely cause:* The CSI driver pods are not running, or the `StorageClass` provisioner name does not match the driver's registered identity. - *Fix:* Run `kubectl get pods -n kube-system -l app=csi-hostpathplugin` and check for crash loops or scheduling failures. Confirm the `provisioner` field in your `StorageClass` exactly matches the name the driver registers with Kubernetes. --- **Driver pod is in `CrashLoopBackOff`** - *Symptom:* `kubectl get pods` shows the `csi-hostpathplugin` pod repeatedly restarting. - *Likely cause:* A required command-line flag is missing, the socket path is incorrect, or the container image is inaccessible from the node. - *Fix:* Inspect logs with `kubectl logs -n kube-system`. Verify the image reference in your `DaemonSet` manifest matches the image you pushed, and that nodes can pull from your registry. --- **Pod using the PVC fails to start with a `MountVolume` error** - *Symptom:* `kubectl describe pod ` shows an event like `MountVolume.SetUp failed`. - *Likely cause:* The hostpath directory on the node does not exist, or the driver does not have permission to create it. - *Fix:* Confirm the node's root directory used by the driver exists and is writable by the driver process. Check whether a `PodSecurityPolicy`, `PodSecurityAdmission`, or SELinux/AppArmor policy is blocking hostpath mounts on the node. --- **`docker build` fails with `no such file or directory: ./bin/hostpathplugin`** - *Symptom:* Building the Docker image fails because the binary is missing. - *Likely cause:* The `make all` step was skipped or failed silently. - *Fix:* Run `make all` from the repository root before running `docker build`. Ensure your Go toolchain is installed and that `$GOPATH` is configured correctly. --- **`kubectl apply -f deploy/kubernetes/` reports `no objects passed to apply`** - *Symptom:* The deploy command produces no output or an error about missing objects. - *Likely cause:* The manifest directory path is incorrect for your local checkout. - *Fix:* Verify the path to the manifest files with `ls deploy/kubernetes/` and adjust the path in the `kubectl apply` command accordingly. > **Note for reviewer:** Additional failure modes specific to the driver's flags, CSI node registration, and the node-driver-registrar sidecar should be added here once those configuration details are available.