# csi-driver-smb: SMB volumes for Kubernetes on Linux and Windows > The SMB CSI driver lets Kubernetes pods mount a share from an existing SMB server, on both Linux and Windows nodes, with dynamic provisioning that carves a new sub directory for each PersistentVolumeClaim. It is a GA driver in the Kubernetes storage SIG, and its cost is that you bring and run the file server yourself. **kubernetes-csi/csi-driver-smb** — This driver allows Kubernetes to access SMB Server on both Linux and Windows nodes. - Repository: https://github.com/kubernetes-csi/csi-driver-smb - Stars: 676 · Forks: 171 - Language: Go - License: Apache-2.0 - Published: 2026-10-21 · Updated: 2026-10-21 · Language: en - Canonical page: https://hysenlabs.com/projects/kubernetes-csi-csi-driver-smb ## A mounting layer, not a storage system The SMB CSI driver allows Kubernetes to access an SMB server on both Linux and Windows nodes. The scope is narrow and worth stating up front, because it decides who this project is for. The driver requires an existing and already configured SMB server. It does not create the file server, it does not manage the disks behind it, and it does not replicate. What it does is make an SMB share look like a Kubernetes volume, and it does that through the Container Storage Interface, so the same driver serves Linux and Windows workloads. The audience is therefore an infrastructure team that already owns a Samba or Windows file server and wants application pods to mount a share from it with the same declarative volume claim model they use for everything else. The driver name used in storage classes and node objects is smb.csi.k8s.io, and the project status is listed as GA. ## Dynamic provisioning means one directory per claim The mechanism that matters operationally is dynamic provisioning through Persistent Volume Claims, and it works by creating a new sub directory under the SMB server. That single design decision explains the driver's behaviour in practice. A claim maps to a directory rather than to a share, so isolation between claims is a directory permission rather than a storage backend feature, and deleting a claim or a volume is a matter of removing a directory. The parameters that control this are documented separately in the driver parameters file under docs/driver-parameters.md, which the README points to rather than reproducing. The example set in the repository shows the shapes this takes in practice: basic usage, a Samba server running on a Kubernetes cluster itself, a Windows example, and volume cloning. That last one is worth noting, because cloning a volume from an existing one is not something every file based driver can offer. ## Windows nodes go through the CSI proxy The compatibility table in the README is short and specific. The master branch, v1.20.3, v1.19.1 and v1.18.0 all require Kubernetes 1.21 or newer, and all require a Windows CSI Proxy at v0.2.2 or newer. The proxy is the piece that makes a Windows node work, since a container on Windows cannot call the host file system directly and the proxy mediates those calls. The dependency is visible in the module file, which requires the CSI proxy client at v1.0.1 and the v2 proxy at v2.0.0-alpha.3, along with the Azure SDK and go-autorest packages used to talk to Windows and Azure specific surfaces. The Go version declared in the module is 1.26.0, and the Kubernetes libraries are pinned at the 0.32.10 series with k8s.io/kubernetes at v1.32.10. So a driver whose published versions look like a small project is in fact a fairly heavy dependency tree, which matters when you plan upgrades rather than a single installation. ## Installing with a Helm chart or with kubectl Two installation paths are offered, and the documentation for each lives in the repository. The Helm charts are under charts/, and the kubectl route is documented in docs/install-smb-csi-driver.md. The Helm route is the one most teams will want, because the driver needs several pieces in place, the controller deployment, the node plugin and its registration, and the Windows proxy where Windows nodes are involved. The Makefile shows what a Helm driven deployment looks like from the outside, since it defines the image reference the charts are told to use through a set of image.smb.repository and image.smb.tag options, along with a controller.runOnController option. The driver image is built as smb-csi, and the default registry variable points at andyzhangx with the default image version v1.21.0, while the VERSION variable defaults to latest. For a production install those defaults are placeholders to override, not values to trust. ## How the image and the tests are built The build is driven by a Makefile that includes the shared release-tools/build.make from the Kubernetes release tooling. The binary target is a single command, smbplugin, and the package path is github.com/kubernetes-csi/csi-driver-smb. The test runner is Ginkgo, with a verbose flag and a two hour timeout set through GINKGO_FLAGS. The interesting part is the version stamping, which is the standard Kubernetes pattern of injecting build metadata into the binary through linker flags. The Makefile sets LDFLAGS to write the image version, the git commit and the build date into fields under pkg/smb, and the extension flags strip the symbol table and link statically. For continuous integration there is a specific branch: when the CI variable is set and PUBLISH is not, the image version is overridden to an e2e prefix followed by the current git commit, so a test build is never confused with a released one. Docker CLI experimental mode is enabled in the environment for the build. ## The FlexVolume driver is the older alternative The links section points to the SMB FlexVolume driver, which lives in the Azure kubernetes-volume-drivers repository, and comparing the two is the clearest way to understand why the CSI driver exists. FlexVolume is the older Kubernetes volume plugin model, in which the plugin runs as a daemon on the node and mounts through a helper binary that the kubelet invokes. CSI replaces that arrangement with a gRPC service that the kubelet talks to, and it adds the proxy concept for platforms such as Windows where the plugin cannot run with the privileges it needs. The trade-off runs the other way too. FlexVolume is simpler and was deeply integrated with kubelet behaviour, while CSI adds a specification, a proxy layer, a separate controller for provisioning, and the version pairing constraints visible in the compatibility table. If you have an existing FlexVolume deployment, the migration path and the side by side behaviour of both drivers for the same cluster are things the FlexVolume repository documents, not this one. ## Licence, tooling and the release line The driver is Apache-2.0 licensed, with the LICENSE file at the root, and it follows the Kubernetes contributor conventions, with a CONTRIBUTING.md, a code-of-conduct.md, OWNERS files for reviewer routing and SECURITY_CONTACTS for vulnerability reports. A few files tell you what the project expects of itself. known-issues.md collects the problems that are known and not yet fixed, support.md describes where to get help, RELEASE.md covers the release process, and the driver build and test flows are documented separately in docs/csi-dev.md and docs/csi-debug.md for development and troubleshooting. The release line is active: v1.20.3 was published on 2026-07-02, v1.20.2 a day earlier on 2026-07-01, and v1.20.1 on 2026-03-12, with the last push to the master branch on 2026-10-19. The repository vendors its dependencies, carries a .golangci.yml for linting and a Makefile target for the image pipeline, and continuous integration results are published on the Kubernetes TestGrid dashboards. ## Conclusion csi-driver-smb suits clusters that already have an SMB or Samba file server and want pods to consume it as a Kubernetes volume, especially mixed Linux and Windows fleets, since the driver handles both and the Windows path goes through the CSI proxy. It is the wrong choice if you need a storage system that manages the underlying media, because the driver is only the mounting layer and the server is yours to run and back up. Before deploying, read known-issues.md and the driver parameter documentation, then check the version pairing, since the branch expects Kubernetes 1.21 or newer and a Windows CSI proxy at v0.2.2 or newer. ## FAQ ### Does csi-driver-smb need an existing SMB server? Yes. The driver requires an existing and already configured SMB server, and it only handles the mounting layer. The repository does include an example that sets up a Samba server on a Kubernetes cluster if you want to try the whole path. ### How do you install the SMB CSI driver on a cluster? Either with the Helm charts under charts/ or with kubectl, following the guide in docs/install-smb-csi-driver.md. The driver registers itself under the plugin name smb.csi.k8s.io and its project status is GA. ### Which Kubernetes versions and Windows CSI proxy versions are supported? The master branch and the v1.18.0 through v1.20.3 releases require Kubernetes 1.21 or newer, and a Windows CSI Proxy at v0.2.2 or newer. The proxy is what lets the driver mount volumes on Windows nodes. ### What does dynamic provisioning do with a PersistentVolumeClaim? It creates a new sub directory under the SMB server for the claim. The parameters that control this are documented in the driver parameters file under docs/driver-parameters.md, and the repository includes examples for basic usage, Windows, a Samba server and volume cloning. ## Sources - [Issues](https://github.com/kubernetes-csi/csi-driver-smb/issues) - [kubernetes-csi/csi-driver-smb on GitHub](https://github.com/kubernetes-csi/csi-driver-smb) - [License: Apache-2.0](https://github.com/kubernetes-csi/csi-driver-smb/blob/master/LICENSE) - [README](https://github.com/kubernetes-csi/csi-driver-smb/blob/master/README.md) - [Releases](https://github.com/kubernetes-csi/csi-driver-smb/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/kubernetes-csi-csi-driver-smb