hetznercloud/csi-driver puts Hetzner Cloud Volumes behind the Kubernetes storage API

What ReadWriteOnce volumes mean on Hetzner Cloud

Hetzner Cloud Volumes are block storage that attaches to a Hetzner Cloud server. The hetznercloud/csi-driver exists so a Kubernetes cluster can ask for one of them through the Container Storage Interface spec and then treat it as a ReadWriteOnce volume. The README states that the driver enables ReadWriteOnce volumes inside Kubernetes and other container orchestrators, and it sets a hard floor of Kubernetes 1.19 or newer. That floor is the first thing most teams will hit, because clusters older than that need some other route to persistent storage. The audience is narrow and well defined: operators running Kubernetes on Hetzner Cloud who want the control plane to provision and attach storage rather than creating volumes by hand and wiring them into pods with node affinity rules. Note that only ReadWriteOnce is named in the README. ReadWriteMany and ReadOnlyMany are not mentioned, so treat them as unsupported rather than as working but undocumented.

One binary, two roles, and why the wrappers exist

The container image is built from alpine:3.24 and receives the compiled driver as a single executable copied to /bin/hcloud-csi-driver. The container entrypoint is that one binary, and the role is chosen with a flag rather than with a separate image per component. The Dockerfile also writes two small shell wrappers, one that runs the driver with -node and one with -controller. The stated reason is backward compatibility: installations that rely on separate entrypoints keep working, which means an upgrade only needs the image tag to change rather than a rewrite of the deployment. The base image also carries a set of filesystem and block tools, namely blkid, btrfs-progs, e2fsprogs, xfsprogs and cryptsetup. The README does not spell out which of these serves which purpose, so read that list as the preparation the image makes rather than as a documented support matrix.

Bringing up a development cluster with make -C dev up

The README documents a full developer loop that runs on real Hetzner Cloud servers. You need tofu, k3sup, docker and skaffold installed, and you need an API token in the environment, set through the HCLOUD_TOKEN variable in your shell session.

The README warns that the development environment runs on Hetzner Cloud servers and therefore induces costs. Create the cluster with:

make -C dev up

Then load the generated configuration so the cluster context is reachable:

source dev/files/env.sh

Confirm the nodes came up before touching the driver:

kubectl get nodes -o wide

Start the driver in that cluster with skaffold dev, which rebuilds the image on code change, redeploys it and streams the logs from the csi components. When the work is done, tear the environment down, since it is still billable:

make -C dev down

Two e2e suites, one of them borrowed from Kubernetes upstream

The driver is tested twice, and the two suites answer different questions. The docker level suite exercises the integration tests against containers, and it needs nothing but docker:

go test -v -tags integration ./test/integration

The kubernetes level suite is the interesting one, because the README says the driver is tested against the official Kubernetes e2e tests. That gives the project a compatibility signal that a bespoke test harness would not provide, since the upstream suite is the same set of cases Kubernetes applies to every storage implementation. It does assume the development cluster from the previous step already exists. The dependency list backs this up: the module requires github.com/kubernetes-csi/csi-test/v5 at v5.6.0, the official test driver package, alongside github.com/container-storage-interface/spec at v1.13.0 and github.com/kubernetes-csi/csi-lib-utils at v0.25.0. The dependency set also includes github.com/hashicorp/nomad/api, which is a hint that the same binary is meant to be driven by Nomad's CSI support rather than by Kubernetes alone.

Where the driver's support stops, and what the README leaves unsaid

Several limits are stated plainly. Kubernetes must be 1.19 or newer. Only ReadWriteOnce is described. Docker Swarm and HashiCorp Nomad are listed under other container orchestrators, and the README marks those environments as not officially supported, offering quick start guides for them only because they are compatible with the CSI spec and through community contributions. The guide paths are docs/docker-swarm/README.md and docs/nomad/README.md. Other gaps are silent rather than documented. The README does not describe a rollback procedure for a failed volume attach, does not enumerate a backup or snapshot workflow, and does not give a step by step upgrade path for an existing installation. Anyone planning a production rollout should treat those as unknown and confirm them separately. One more practical cost sits in the developer loop itself: standing up the environment spends money on Hetzner Cloud servers, so an idle cluster is a running invoice.

The Go module, the release history and the MIT licence

The module is github.com/hetznercloud/csi-driver, built against go 1.26.8 with a toolchain line of go1.27.2. The cloud API client is pinned to github.com/hetznercloud/hcloud-go/v2 v2.52.0, and the gRPC stack to google.golang.org/grpc v1.84.0, which is what carries the CSI spec RPCs. Prometheus client_golang v1.25.0 and the grpc prometheus middleware show that metrics are a first class part of the deployment. On the release side, v2.22.2 was published on 2026-08-31, v2.23.0 on 2026-09-03 and v2.24.0 on 2026-10-12, and the last push was on 2026-10-22. The project is published under the MIT licence, which is a permissive grant with short attribution requirements and no copyleft obligation on anything that links to it. The repository layout supports several delivery routes: a chart/ directory, a deploy/ directory, a top-level kustomization.yaml and a nomad/ directory, alongside internal/, cmd/ and test/.

How a standalone CSI driver differs from a bundled cloud plugin

The alternative approach to the same job is the in-tree volume plugin, which ships compiled into the Kubernetes distribution and is wired directly to the cloud API by the controller manager and the cloud controller. The difference in approach matters for an operator. An in-tree plugin needs no separate deployment and no sidecar containers, but it is tied to a specific Kubernetes release and to the vendor support window of the Kubernetes project. An external CSI driver runs in the cluster as its own workload and talks to the control plane over gRPC, implementing the spec calls such as create, publish and stage through the spec module version pinned here at v1.13.0. That indirection buys versioning independence and lets the same binary target a second orchestrator, which is exactly what the Nomad dependency and the nomad/ directory point to. It also costs an extra set of components to operate and to keep upgraded. The project points to its own architecture notes for the component breakdown.

Editorial conclusion

Adopt the hetznercloud/csi-driver when your cluster already runs on Hetzner Cloud and you want block volumes managed by the control plane rather than by hand. Skip it if you need storage modes beyond ReadWriteOnce, if you are on a Kubernetes release older than 1.19, or if your orchestrator is anything other than Kubernetes and you do not want to rely on community guides. Before installing, verify that the packaged chart and deploy manifests match your cluster version, and confirm that the Hetzner API token you supply can create and attach volumes in the target project.

Frequently asked questions

Official sources

1. hetznercloud/csi-driver on GitHub
2. Issues
3. License: MIT
4. README
5. Releases