Hetzner Cloud CSI Driver

The hcloud-csi-driver follows the standard Container Storage Interface (CSI) architecture, split into two distinct deployment models: a Controller and a Node Driver.

1. The Controller

Deployed as a Kubernetes Deployment, the Controller manages cluster-wide volume operations. It consists of the main hcloud-csi-driver container and several sidecar containers (csi-attacher, csi-provisioner, csi-resizer, and liveness-probe).

• Workflow: The sidecars watch the Kubernetes API for events (like PersistentVolumes or VolumeAttachments). When an event occurs, the sidecars send gRPC requests following the CSI specification to the hcloud-csi-driver container. The driver then communicates with the Hetzner Cloud API via REST to execute operations like creating, attaching, or resizing volumes.

2. The Node Driver

Deployed as a Kubernetes DaemonSet, the Node Driver manages node-specific operations. It consists of the main hcloud-csi-driver container and sidecars (csi-node-driver-registrar and liveness-probe).

• Workflow: The csi-node-driver-registrar registers the driver with the local kubelet. Once registered, the kubelet communicates directly with the hcloud-csi-driver via a Unix socket to perform node-level tasks such as mounting and unmounting volumes. Unlike the Controller, the Node Driver does not communicate with the Kubernetes API or the Hetzner API directly.

The hcloud-csi driver provides a default StorageClass named hcloud-volumes.

StorageClass Properties:

• provisioner: csi.hetzner.cloud
• volumeBindingMode: WaitForFirstConsumer: The volume is only provisioned once a Pod that uses the claim is scheduled. This ensures the volume is created in the same Hetzner Cloud location as the Pod.
• reclaimPolicy: Delete: Deleting the PersistentVolumeClaim (PVC) will automatically delete the underlying Hetzner Cloud Volume.

Usage Pattern: To use Hetzner Volumes, create a PersistentVolumeClaim specifying storageClassName: hcloud-volumes. Because Hetzner Volumes are ReadWriteOnce (RWO), they can only be attached to one node at a time. If using a Deployment, use a strategy: type: Recreate to ensure the old Pod is terminated before the new Pod attempts to attach the volume.

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: csi-pvc
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi
  storageClassName: hcloud-volumes
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-csi-app
spec:
  replicas: 1
  strategy:
    type: Recreate
  selector:
    matchLabels:
      app: my-csi-app
  template:
    metadata:
      labels:
        app: my-csi-app
    spec:
      containers:
        - name: my-frontend
          image: busybox
          command: ["sleep", "infinity"]
          volumeMounts:
            - name: my-csi-volume
              mountPath: /data
      volumes:
        - name: my-csi-volume
          persistentVolumeClaim:
            claimName: csi-pvc

The CSI controller determines the default location for all volumes during initialization using a prioritized hierarchy of four methods.

Important Exception: If your StorageClass uses volumeBindingMode: WaitForFirstConsumer, the volume's location is determined by the node where the Pod is scheduled. In this case, the default location logic described below is bypassed.

Prioritized Location Resolution Order:

1. Explicit Variable: The HCLOUD_VOLUME_DEFAULT_LOCATION environment variable is checked first.
2. Server ID: If not explicitly set, the location is derived by querying the server specified by the HCLOUD_SERVER_ID environment variable.
3. Node Name Lookup: If neither of the above is set, the driver uses the KUBE_NODE_NAME environment variable (defaulting to the node where the CSI controller is scheduled) to query the Hetzner API for a matching server and its location.
4. Metadata Service Fallback: As a final fallback, the driver queries the Hetzner metadata service to obtain the server ID, which is then used to fetch the location via the Hetzner API.

The CSI Controller manages the lifecycle of volumes. Create a file named hcloud-csi-controller.hcl with the following content. Note that for high availability, count = 2 is used with a distinct_hosts constraint. On a single-node cluster, you may need to modify or remove these stanzas.

# file: hcloud-csi-controller.hcl

job "hcloud-csi-controller" {
  datacenters = ["dc1"]
  namespace   = "default"
  type        = "service"

  group "controller" {
    count = 2

    constraint {
      distinct_hosts = true
    }

    update {
      max_parallel     = 1
      canary           = 1
      min_healthy_time = "10s"
      healthy_deadline = "1m"
      auto_revert      = true
      auto_promote     = true
    }

    task "plugin" {
      driver = "docker"

      config {
        # Get the latest version on https://hub.docker.com/r/hetznercloud/hcloud-csi-driver/tags
        image   = "hetznercloud/hcloud-csi-driver:v2.5.1"
        command = "bin/hcloud-csi-driver-controller"
      }

      env {
        CSI_ENDPOINT   = "unix://csi/csi.sock"
        ENABLE_METRICS = true
      }

      template {
        data        = <<EOH
HCLOUD_TOKEN="{{ with nomadVar "secrets/hcloud" }}{{ .hcloud_token }}{{ end }}"
EOH
        destination = "${NOMAD_SECRETS_DIR}/hcloud-token.env"
        env         = true
      }

      csi_plugin {
        id        = "csi.hetzner.cloud"
        type      = "controller"
        mount_dir = "/csi"
      }

      resources {
        cpu    = 100
        memory = 64
      }
    }
  }
}

The CSI Node job runs on every node to handle volume mounting. Create a file named hcloud-csi-node.hcl. This job uses the system type to ensure it runs on all nodes.

# file: hcloud-csi-node.hcl
job "hcloud-csi-node" {
  datacenters = ["dc1"]
  namespace   = "default"
  type        = "system"

  group "node" {
    task "plugin" {
      driver = "docker"

      config {
        # Get the latest version on https://hub.docker.com/r/hetznercloud/hcloud-csi-driver/tags
        image      = "hetznercloud/hcloud-csi-driver:v2.5.1"
        command    = "bin/hcloud-csi-driver-node"
        privileged = true
      }

      env {
        CSI_ENDPOINT   = "unix://csi/csi.sock"
        ENABLE_METRICS = true
      }

      template {
        data        = <<EOH
HCLOUD_TOKEN="{{ with nomadVar "secrets/hcloud" }}{{ .hcloud_token }}{{ end }}"
EOH
        destination = "${NOMAD_SECRETS_DIR}/hcloud-token.env"
        env         = true
      }

      csi_plugin {
        id        = "csi.hetzner.cloud"
        type      = "node"
        mount_dir = "/csi"
      }

      resources {
        cpu    = 100
        memory = 64
      }
    }
  }
}