Hetzner CSI Driver Setup Instructions¶

1. Get your Hetzner Cloud API Token¶

1. Go to the Hetzner Cloud Console: https://console.hetzner.cloud/
2. Navigate to your project
3. Go to "Security" → "API Tokens"
4. Create a new API Token with Read & Write permissions
5. Copy the token (it will only be shown once)

2. Deploy via Terraform¶

The Hetzner Cloud token secret is automatically managed via Terraform. Simply deploy the updated Terraform configuration:

cd terraform/environments/hetzner-mgmt-cluster/2-components
terraform plan
terraform apply

The Terraform configuration will: - Create the hcloud-token secret in the kube-system namespace - Use the same Hetzner Cloud token that's already configured for your infrastructure

3. Deploy the CSI Driver¶

The CSI driver will be automatically deployed via Flux once you:

1. Create the secret (step 2)
2. Commit and push the changes to your repository
3. Flux will automatically sync and deploy the CSI driver

4. Verify the Installation¶

# Check if the CSI driver pods are running
kubectl get pods -n kube-system -l app=hcloud-csi

# Check if the storage class was created
kubectl get storageclass

# Check CSI driver registration
kubectl get csinodes

5. Test with a Persistent Volume¶

Create a test PVC to verify the CSI driver works:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: test-pvc
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi
  storageClassName: hcloud-volumes

Storage Classes Created¶

The following storage class will be available: - hcloud-volumes (default) - Standard Hetzner Cloud volumes with ext4 filesystem

Features¶

• Dynamic provisioning: Volumes are created automatically when PVCs are created
• Volume expansion: Volumes can be resized online
• Snapshots: Volume snapshots are supported (if snapshot controller is installed)
• Multi-attach: ReadOnlyMany access mode is supported

Troubleshooting¶

If the CSI driver fails to start, check: 1. The hcloud-token secret exists and has the correct token 2. The token has Read & Write permissions 3. The token is for the correct Hetzner Cloud project 4. Check the controller and node pod logs:

kubectl logs -n kube-system -l app=hcloud-csi-controller
kubectl logs -n kube-system -l app=hcloud-csi-node