DOCSEARCHbyAlgolia
Submit Docs

SMB CSI Driver

repository·master·Indexed 20 days ago

https://github.com/kubernetes-csi/csi-driver-smb

The SMB CSI Driver enables Kubernetes clusters to mount SMB shares on Linux and Windows nodes. It supports dynamic provisioning via PVCs by creating subdirectories on pre-configured SMB servers and provides volume cloning capabilities starting from version v1.11.0. The driver can be installed and configured using Helm, with support for high-availability controller replicas and custom driver identities.

Tokens
34.7K
Snippets
101
Records
112
Agent score
70%

What's inside csi-driver-smb

  1. Overview of the SMB CSI Driver for Kubernetes

    master

    The SMB CSI Driver allows Kubernetes nodes (both Linux and Windows) to access SMB servers. It supports dynamic provisioning of Persistent Volumes (PVs) via Persistent Volume Claims (PVCs) by automatically creating new subdirectories on the existing SMB server.

    Key Details:

    • CSI plugin name: smb.csi.k8s.io
    • Project Status: GA (General Availability)
    • Requirement: An existing and already configured SMB server.

  2. Configure High-Availability (HA) for the SMB Controller

    master

    To run multiple controller replicas (controller.replicas > 1), you must ensure that replicas do not co-locate on the same node. This is because the controller uses hostNetwork: true and its liveness-probe sidecar listens on a fixed host port (controller.livenessProbe.healthPort, default 29642). If two pods attempt to bind to the same port on one node, the second pod will enter CrashLoopBackOff.

    Requirements for HA

    1. Node Count: You must have at least as many schedulable nodes as you have controller.replicas. Single-node clusters (like default k3d or kind) must keep controller.replicas=1.
    2. Anti-Affinity: You must apply a podAntiAffinity rule using the kubernetes.io/hostname topology key. The matchLabels.app value must match the controller's app label (which is derived from controller.name, defaulting to csi-smb-controller).

    Note: When running multiple candidates, you may see leader-election log noise such as "Failed to update lease optimistically, falling back to slow path". This is normal behavior and not a bug.

    HA Configuration Example

    controller:
  replicas: 2
  affinity:
    podAntiAffinity:
      requiredDuringSchedulingIgnoredDuringExecution:
        - topologyKey: kubernetes.io/hostname
          labelSelector:
            matchLabels:
              app: csi-smb-controller

  4. Avoid mounting multiple subpaths from the same SMB share on Windows

    master

    When using a single SMB server in a cluster on Windows, only use the root share as the source in your StorageClass.

    If you attempt to mount specific subpaths (e.g., \smb-server oot est1 and \smb-server oot est2) using subPath in your deployments, you may encounter errors when mounting subsequent volumes after a Windows node reboot.

    Workaround: Use the root share (e.g., \smb-server oot) as the source and manage directory separation via Kubernetes mechanisms rather than the SMB source path.

  5. Prepare SMB credentials secret

    master

    Before using the SMB CSI driver, you must create a Kubernetes secret containing the Samba server credentials. This secret is used by the driver to authenticate with the SMB share.

    Use kubectl create secret generic to store the username and password. If your environment requires domain authentication, include the domain field.

    kubectl create secret generic smbcreds --from-literal username=USERNAME --from-literal password="PASSWORD"
# For domain support:
kubectl create secret generic smbcreds --from-literal username=USERNAME --from-literal password="PASSWORD" --from-literal domain=DOMAIN-NAME

  6. Uninstall SMB CSI driver v1.19.0

    master

    To remove the SMB CSI driver version 1.19.0 from your cluster, use either the remote uninstall script or the local script from a cloned repository.

    Remote Uninstall

    Execute the uninstall script directly from GitHub using curl.

    Local Uninstall

    Clone the repository, checkout the v1.19.0 tag, and run the local uninstall script.

    # Option 1: Remote uninstall
curl -skSL https://raw.githubusercontent.com/kubernetes-csi/csi-driver-smb/v1.19.0/deploy/uninstall-driver.sh | bash -s --

# Option 2: Local uninstall
git clone https://github.com/kubernetes-csi/csi-driver-smb.git
cd csi-driver-smb
git checkout v1.19.0
./deploy/uninstall-driver.sh v1.19.0 local

  7. Install SMB CSI driver v1.4.0 via kubectl

    master

    To install version 1.4.0 of the SMB CSI driver on a Kubernetes cluster, run the installation script using curl and bash. After running the installation, verify that the controller and node pods are running correctly in the kube-system namespace.

    To monitor the status of the pods, use the following commands:

    • Check controller pods: kubectl -n kube-system get pod -o wide --watch -l app=csi-smb-controller
    • Check node pods: kubectl -n kube-system get pod -o wide --watch -l app=csi-smb-node

    Successful installation is indicated by pods having a READY status of 3/3 and a STATUS of Running.

    curl -skSL https://raw.githubusercontent.com/kubernetes-csi/csi-driver-smb/v1.4.0/deploy/install-driver.sh | bash -s v1.4.0 --

  8. Uninstall SMB CSI driver v1.10.0

    master

    To remove the SMB CSI driver version 1.10.0 from your cluster, use either the remote uninstall script or the local script from a cloned repository.

    Remote Uninstall

    Execute the uninstall script directly from GitHub using curl.

    Local Uninstall

    Clone the repository, checkout the v1.10.0 tag, and run the uninstallation script locally.

    # Option 1: Remote uninstall
curl -skSL https://raw.githubusercontent.com/kubernetes-csi/csi-driver-smb/v1.10.0/deploy/uninstall-driver.sh | bash -s --

# Option 2: Local uninstall
git clone https://github.com/kubernetes-csi/csi-driver-smb.git
cd csi-driver-smb
git checkout v1.10.0
./deploy/uninstall-driver.sh v1.10.0 local

  9. Install SMB CSI driver v1.9.0 via kubectl

    master

    You can install the SMB CSI driver version 1.9.0 using one of two methods: a remote installation via a shell script or a local installation from a cloned repository.

    Remote Install

    Use curl to fetch and execute the installation script directly from GitHub.

    Local Install

    Clone the repository, checkout the specific version tag, and run the deployment script locally.

    After installation, verify that the controller and node pods are running in the kube-system namespace.

    # Option 1: Remote install
curl -skSL https://raw.githubusercontent.com/kubernetes-csi/csi-driver-smb/v1.9.0/deploy/install-driver.sh | bash -s v1.9.0 --

# Option 2: Local install
git clone https://github.com/kubernetes-csi/csi-driver-smb.git
cd csi-driver-smb
git checkout v1.9.0
./deploy/install-driver.sh v1.9.0 local

# Verify pod status
kubectl -n kube-system get pod -o wide --watch -l app=csi-smb-controller
kubectl -n kube-system get pod -o wide --watch -l app=csi-smb-node

  10. Install SMB CSI driver v1.1.0 via kubectl

    master

    To install version 1.1.0 of the SMB CSI driver on a Kubernetes cluster, run the installation script via curl and bash. After running the installation command, verify that the controller and node pods are running in the kube-system namespace.

    To check the status of the pods, use the following commands:

    • Monitor controller pods: kubectl -n kube-system get pod -o wide --watch -l app=csi-smb-controller
    • Monitor node pods: kubectl -n kube-system get pod -o wide --watch -l app=csi-smb-node
    curl -skSL https://raw.githubusercontent.com/kubernetes-csi/csi-driver-smb/v1.1.0/deploy/install-driver.sh | bash -s v1.1.0 --

  12. Verify SMB CSI driver pod status

    master

    After installation, use the following commands to monitor the status of the driver components in the kube-system namespace. Use the --watch flag to observe the pods transitioning to a Running state.

    • Controller pods: kubectl -n kube-system get pod -o wide --watch -l app=csi-smb-controller
    • Linux node pods: kubectl -n kube-system get pod -o wide --watch -l app=csi-smb-node
    • Windows node pods: kubectl -n kube-system get pod -o wide --watch -l app=csi-smb-node-win (only if running Windows nodes)
    # Check controller pods
kubectl -n kube-system get pod -o wide --watch -l app=csi-smb-controller

# Check Linux node pods
kubectl -n kube-system get pod -o wide --watch -l app=csi-smb-node

# Check Windows node pods (if applicable)
kubectl -n kube-system get pod -o wide --watch -l app=csi-smb-node-win