Skip to content


Repository files navigation

Container Storage Interface driver for Hetzner Cloud

GitHub Actions status codecov

This is a Container Storage Interface driver for Hetzner Cloud enabling you to use ReadWriteOnce Volumes within Kubernetes & other Container Orchestrators. Please note that this driver requires Kubernetes 1.19 or newer.

Getting Started

Depending on your Container Orchestrator you need to follow different steps to get started with the Hetzner Cloud csi-driver. You can also find other docs relevant to that Container Orchestrator behind the link:

Docker Swarm⚠ Not officially supported

HashiCorp Nomad⚠ Not officially supported


Integration Tests

Requirements: Docker

The core operations like publishing and resizing can be tested locally with Docker.

go test $(go list ./... | grep integration) -v

E2E Tests

⚠️ Kubernetes E2E Tests were recently refactored and the docs are now outdated. See the GitHub Actions workflow for an up-to-date script to run the e2e tests.

The Hetzner Cloud CSI Driver was tested against the official k8s e2e tests for a specific version. You can run the tests with the following commands. Keep in mind, that these tests run on real cloud servers and will create volumes that will be billed.

Test Server Setup:

1x CPX21 (Ubuntu 18.04)

Requirements: Docker and Go 1.17

  1. Configure your environment correctly
    export HCLOUD_TOKEN=<specify a project token>
    export K8S_VERSION=1.21.0 # The specific (latest) version is needed here
    export USE_SSH_KEYS=key1,key2 # Name or IDs of your SSH Keys within the Hetzner Cloud, the servers will be accessible with that keys
  2. Run the tests
    go test $(go list ./... | grep e2e) -v -timeout 60m

The tests will now run, this will take a while (~30 min).

If the tests fail, make sure to clean up the project with the Hetzner Cloud Console or the hcloud cli.

Local test setup

⚠️ Local Kubernetes Dev Setup was recently refactored and the docs are now outdated. Check out the scripts & for an automatic dev setup.

This repository provides skaffold to easily deploy / debug this driver on demand


  1. Install hcloud-cli
  2. Install k3sup
  3. Install cilium
  4. Install docker

You will also need to set a HCLOUD_TOKEN in your shell session

Manual Installation guide

  1. Create an SSH key

Assuming you already have created an ssh key via ssh-keygen

hcloud ssh-key create --name ssh-key-csi-test --public-key-from-file ~/.ssh/ 
  1. Create a server
hcloud server create --name csi-test-server --image ubuntu-20.04 --ssh-key ssh-key-csi-test --type cx11 
  1. Setup k3s on this server
k3sup install --ip $(hcloud server ip csi-test-server) --local-path=/tmp/kubeconfig --cluster --k3s-channel=v1.23 --k3s-extra-args='--no-flannel --no-deploy=servicelb --no-deploy=traefik --disable-cloud-controller --disable-network-policy --kubelet-arg=cloud-provider=external'
  • The kubeconfig will be created under /tmp/kubeconfig
  • Kubernetes version can be configured via --k3s-channel
  1. Switch your kubeconfig to the test cluster
export KUBECONFIG=/tmp/kubeconfig
  1. Install cilium + test your cluster
cilium install
  1. Add your secret to the cluster
kubectl -n kube-system create secret generic hcloud --from-literal="token=$HCLOUD_TOKEN"
  1. Install hcloud-cloud-controller-manager + test your cluster
kubectl apply -f
kubectl config set-context default
kubectl get node -o wide
  1. Deploy your CSI driver
SKAFFOLD_DEFAULT_REPO=naokiii skaffold dev
  • docker login required
  • Skaffold is using your own dockerhub repo to push the CSI image.

On code change, skaffold will repack the image & deploy it to your test cluster again. Also, it is printing all logs from csi components.


MIT license