📁 Linode File Storage CSI Driver

Table of Contents

• Overview
  • What the driver does
  • Current limitations
• Before you begin
• Quickstart
• Disclaimers
• Architecture
  • Component layout
  • Volume and snapshot identity
  • Provisioning lifecycle
  • Mount lifecycle
• Installation
  • Requirements
  • Secure a Linode API access token
  • Install with Helm
  • Install with kubectl
  • Upgrade and uninstall
• Usage
  • Create a StorageClass
  • Create a PersistentVolumeClaim
  • Consume it from a pod
  • Share one volume between pods
  • StorageClass parameters
• Access and Networking
  • VPC requirement
  • Access-policy modes
  • Squash policy
• Reference
  • Environment variables
  • Helm values
  • Volume context keys
• Troubleshooting
• Development
  • Prerequisites
  • Local toolchain
  • Development cluster
  • Testing
  • Contributing
• License
• Community

📚 Overview

This is the Container Storage Interface (CSI) driver for Linode managed NFS file storage. It lets Kubernetes provision, share, and mount NFSv4 filesystems from a Linode NFS Storage Space as PersistentVolumes.

The volumes are network filesystems rather than block devices, so a single volume can be mounted read-write by pods on many nodes at the same time. That makes it suitable for shared caches, shared media, CI artifacts, and any workload that needs ReadWriteMany.

For background on Kubernetes CSI, see the Kubernetes CSI documentation and the CSI specification.

What the driver does

• Provisions filesystems. A PersistentVolumeClaim becomes a Linode NFS filesystem inside an NFS Storage Space that you pre-create and name in the StorageClass.
• Leaves Space access to you. The Storage Space access policy must be enabled and admit the cluster VPC. The Space owner maintains it; the driver neither validates nor changes it, so a misconfigured policy surfaces as mount failures. accessPolicy.mode=node enables per-filesystem Linode ACL management, but is not currently recommended because every publish and unpublish waits for an asynchronous policy update and scales poorly.
• Mounts over NFSv4. The node plugin mounts filesystem DNS name at the kubelet staging path, then bind-mounts it into each pod.
• Reports usage. NodeGetVolumeStats reports byte and inode usage read from the mounted filesystem.
• Volume expansion supports capacity increases through the NFS filesystem’s root quota.

Current Limitations:

• Volume cloning is planned, through snapshots, but not available yet.
• Snapshots and restores are planned, but not available yet.

🧭 Before you begin

• The driver is in alpha. See the disclaimers.
• Every node must be attached to a VPC with IPv6 connectivity, and all nodes must be in one region. See Access and Networking.
• The Linode Cloud Controller Manager must be installed and running, because the driver reads each node’s providerID and region label.
• You create the NFS Storage Space yourself. See Create an NFS Storage Space.
• The Space access policy must be enabled and list your cluster’s VPC to ensure proper access. Incorrect customer ACLs surface as mount failures. See Admit the cluster VPC.
• You need a Linode API token. See Secure a Linode API access token.

⚡ Quickstart

First create the NFS Storage Space and admit your cluster VPC on its access policy. You can do both in Cloud Manager or directly against the API with curl. The steps are in Create an NFS Storage Space and Admit the cluster VPC.

Then install the driver and create a StorageClass and a claim:

helm repo add linode-nfs-csi https://linode.github.io/linode-filestorage-csi-driver/
helm install linode-nfs-csi-driver -n kube-system --set apiToken="${LINODE_API_TOKEN}" linode-nfs-csi/linode-nfs-csi-driver
kubectl apply -f - <<EOF
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: linode-nfs
provisioner: linodenfs.csi.linode.com
parameters:
  linodenfs.csi.linode.com/space-id: "${SPACE_ID}"
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: nfs-pvc
spec:
  accessModes:
    - ReadWriteMany
  storageClassName: linode-nfs
  resources:
    requests:
      storage: 10Gi
EOF

Check that the claim binds:

kubectl get pvc nfs-pvc

NAME      STATUS   VOLUME                                     CAPACITY   ACCESS MODES   STORAGECLASS   AGE
nfs-pvc   Bound    pvc-a1b2c3d4-5e6f-7890-abcd-ef1234567890   10Gi       RWX            linode-nfs     35s

Then mount nfs-pvc from a pod as shown in Consume it from a pod. The first volume in a region can be slow because backend resources are provisioned on first use. See Installation and Usage for the full steps.

🚧 Disclaimers

• The driver is in alpha. Behavior and the interfaces it exposes may change between releases.
• VPC-backed IPv6 connectivity is required for mounts. The driver does not discover the cluster VPC or gate provisioning on it. Network and customer ACL problems surface as mount failures. See Access and Networking.
• Storage Spaces are not created by the driver. You must create the NFS Storage Space yourself and reference it from every StorageClass. The driver creates and deletes filesystems inside that space, never the space itself.
• Capacity increases are quota-backed. The driver increases the NFS filesystem’s root quota for PVC expansion and rejects reductions. The Linode API enforces the maximum customer-manageable capacity; rejected requests and the API’s error are returned to Kubernetes.

💬 Join Us on Slack

• General Help/Discussion: Kubernetes Slack - #linode
• Development/Debugging: Gopher’s Slack - #linodego

License

This project is licensed under the Apache License, Version 2.0.