User guide

Use TAK-OS Local CSI when your application can keep its data on one particular node. A replacement pod using the same PVC returns to that node. If the node is unavailable or cannot accept the pod, a replacement remains Pending; the driver does not move the data to another node.

Before creating a volume

Ask your administrator to install the driver and confirm the available StorageClass and its reclaim policy:

kubectl get storageclass tak-os-local -o yaml

The supplied class uses WaitForFirstConsumer, ReadWriteOnce filesystem volumes, and a Delete reclaim policy. Specify the class explicitly in PVCs even if it is the cluster default. PVCs and their consuming pods must share a namespace.

The PVC request is checked against free space when the directory is created. It is not a quota or reservation. All volumes on the backing filesystem share its free space; applications can exceed their requested size and exhaust it.

Unsupported features include raw block volumes, ReadWriteMany, ReadWriteOncePod, expansion, snapshots, cloning, and snapshot restore. The driver uses the existing host filesystem; do not request an fsType. ReadWriteOnce is a node access mode, not a guarantee that only one pod can write. Applications must coordinate any concurrent access on the owning node.

Create a PVC and pod

The example manifest creates a 64 MiB claim and a non-root BusyBox pod with /data mounted from it. Run from the repository root:

kubectl create namespace local-csi-demo
kubectl -n local-csi-demo apply -f docs/examples/workload.yaml
kubectl -n local-csi-demo wait --for=condition=Ready pod/local-csi-demo --timeout=180s
kubectl -n local-csi-demo get pvc,pod -o wide
kubectl -n local-csi-demo exec local-csi-demo -- sh -c 'echo persistent-data > /data/message'

The claim can remain Pending until the pod exists. The scheduler chooses a node for the first consumer, its local provisioner creates the directory, and the resulting PV records required node affinity. Do not set spec.nodeName on the first pod: it bypasses scheduler selection needed for delayed binding. If initial placement needs a constraint, use a nodeSelector or node affinity compatible with the storage nodes.

Verify persistence

Delete only the pod, leaving its claim in place, then recreate it:

kubectl -n local-csi-demo delete pod local-csi-demo --wait=true
kubectl -n local-csi-demo apply -f docs/examples/workload.yaml
kubectl -n local-csi-demo wait --for=condition=Ready pod/local-csi-demo --timeout=180s
kubectl -n local-csi-demo exec local-csi-demo -- cat /data/message
kubectl -n local-csi-demo get pod local-csi-demo -o wide

The output should still be persistent-data. The new pod uses the same node through the PV's affinity, even without a node selector in the pod manifest. Stateful applications should keep the same PVC across pod replacement. Creating a new PVC with the same name after deleting the old claim does not recover it.

Permissions and read-only access

New volume directories are root-owned with mode 0750. Set a pod-level securityContext.fsGroup for non-root applications, as in the example. The deployed CSIDriver uses fsGroupPolicy: File; kubelet handles group permissions. Ownership changes can take time on directories containing many files.

To consume an existing claim read-only, recreate the pod with both fields below set on its volume and mount:

# Under spec.containers[].volumeMounts:
- name: data
  mountPath: /data
  readOnly: true
# Under spec.volumes:
- name: data
  persistentVolumeClaim:
    claimName: local-csi-demo
    readOnly: true

The bind mount enforces read-only access. Keep accessModes: [ReadWriteOnce] on the PVC; ReadOnlyMany is unsupported. Every published mount has nosuid,nodev; an administrator can additionally configure noexec or ro mount options on a StorageClass. These options can prevent applications from executing stored files or writing data.

Deletion and retention

Deleting a pod alone preserves its PVC and data. With the supplied Delete policy, deleting the PVC allows Kubernetes to delete the PV and its data after use ends. Check the bound PV's policy before removing a claim:

pv=$(kubectl -n local-csi-demo get pvc local-csi-demo -o jsonpath='{.spec.volumeName}')
kubectl get pv "$pv" -o yaml

For data that must survive claim deletion, arrange a Retain policy with your administrator before deleting the claim. Retained data requires administrator handling; it is not automatically rebound to a new claim. Retention does not replace backups or protect against node or disk loss.

When you are finished with the demonstration and may discard its data:

kubectl -n local-csi-demo delete pod local-csi-demo --wait=true
kubectl -n local-csi-demo delete pvc local-csi-demo
kubectl delete namespace local-csi-demo

Troubleshooting

Start with the claim, pod, and namespace events:

kubectl -n local-csi-demo describe pvc local-csi-demo
kubectl -n local-csi-demo describe pod local-csi-demo
kubectl -n local-csi-demo get events --sort-by=.metadata.creationTimestamp

Provide your administrator the namespace, PVC and pod names, events, and bound PV name. The administrator guide covers node-level diagnostics and recovery.