hetznercloud/hcloud-csi-driver

Hetzner Cloud CSI Driver 镜像文档

镜像概述

本镜像为Hetzner Cloud提供容器存储接口(CSI)驱动实现，旨在将Hetzner Cloud的块存储服务集成到容器化环境（如Kubernetes）中，实现存储资源的动态管理。通过标准CSI接口，容器编排平台可直接调用Hetzner Cloud存储API，完成存储卷的创建、绑定、扩展、快照及删除等操作，满足容器应用的持久化存储需求。

核心功能与特性

标准CSI功能

• 动态存储卷供应：根据PVC(PersistentVolumeClaim)自动创建Hetzner Cloud块存储卷
• 卷绑定：支持立即绑定(Immediate)和延迟绑定(WaitForFirstConsumer)两种模式
• 卷扩展：支持在线扩展已挂载卷的容量（需存储类启用扩展功能）
• 快照与恢复：支持创建卷快照及从快照恢复新卷
• 卷删除：PVC删除时自动清理关联的Hetzner Cloud存储卷（依赖回收策略）

Hetzner Cloud增强功能

• 原生API集成：直接调用Hetzner Cloud Block Storage API，确保操作高效性
• 多区域支持：适配Hetzner Cloud全球数据中心区域（如fsn1、nbg1、hel1等）
• 存储类型选择：支持指定卷类型（SSD或HDD）及IOPS性能等级
• 标签管理：自动为创建的存储卷添加元数据标签，便于Hetzner Cloud控制台识别

使用场景与适用范围

典型应用场景

• Kubernetes集群部署在Hetzner Cloud时的持久化存储解决方案
• 需要动态管理存储资源的微服务架构，如数据库（MySQL、PostgreSQL）、消息队列（Kafka、RabbitMQ）等有状态应用
• 要求支持存储快照备份的业务系统
• 需弹性调整存储容量的动态负载场景

环境要求

• 容器编排平台：Kubernetes 1.20+（CSI 1.4+兼容）
• Hetzner Cloud账号：需具备API访问权限及块存储服务使用权限
• 网络环境：驱动容器需能访问Hetzner Cloud API端点（[***]

使用方法与配置说明

部署方式

1. Kubernetes集成（推荐）

通过容器化部署在Kubernetes集群中，通常以DaemonSet（节点插件）+ Deployment（控制器插件）形式运行：

yaml
# 示例：Kubernetes部署清单核心片段
apiVersion: apps/v1
kind: Deployment
metadata:
  name: hcloud-csi-controller
  namespace: kube-system
spec:
  replicas: 1
  template:
    spec:
      containers:
      - name: csi-driver
        image: hetznercloud/hcloud-csi-driver:latest
        env:
        - name: HCLOUD_TOKEN
          valueFrom:
            secretKeyRef:
              name: hcloud-csi-token
              key: token
        - name: HCLOUD_REGION
          value: fsn1
        args:
        - --endpoint=unix:///csi/csi.sock
        - --log-level=info

2. 独立Docker运行（测试环境）

bash
docker run -d \
  --name hcloud-csi-driver \
  --privileged \
  --network host \
  -e HCLOUD_TOKEN="your_hetzner_api_token" \
  -e HCLOUD_REGION="fsn1" \
  -v /var/lib/kubelet/plugins/csi.hetzner.cloud:/var/lib/kubelet/plugins/csi.hetzner.cloud \
  -v /var/lib/kubelet/pods:/var/lib/kubelet/pods:shared \
  hetznercloud/hcloud-csi-driver:latest \
  --endpoint=unix:///csi/csi.sock --log-level=debug

核心配置参数

环境变量

存储类参数（Kubernetes）

在StorageClass中通过parameters字段配置卷属性：

yaml
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: hcloud-ssd
provisioner: csi.hetzner.cloud
parameters:
  type: "ssd"  # 存储类型，可选"ssd"或"hdd"
  # size: "20Gi"  # 默认卷大小（可被PVC的storage字段覆盖）
  # labels: "env=prod,app=database"  # 附加到Hetzner卷的标签
reclaimPolicy: Delete  # 回收策略：Delete/Retain
allowVolumeExpansion: true  # 启用卷扩展
volumeBindingMode: WaitForFirstConsumer  # 延迟绑定模式

部署验证

1. 检查CSI驱动组件运行状态：

bash
kubectl get pods -n kube-system | grep hcloud-csi

2. 创建测试PVC验证动态供应：

yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: test-pvc
spec:
  accessModes: ["ReadWriteOnce"]
  storageClassName: "hcloud-ssd"
  resources:
    requests:
      storage: 10Gi

3. 验证PVC状态（应为Bound）：

bash
kubectl get pvc test-pvc

注意事项

• API令牌安全：建议通过Kubernetes Secret管理HCLOUD_TOKEN，避免明文配置
• 权限控制：API令牌需最小权限集，推荐仅授予"volumes"相关操作权限
• 区域一致性：驱动部署区域需与Kubernetes节点所在Hetzner Cloud区域一致
• 存储限制：Hetzner Cloud块存储单卷最大容量为10TB，快照数量上限受账号配额限制
• 版本兼容性：确保驱动版本与Kubernetes版本匹配（参考https://github.com/hetznercloud/csi-driver#compatibility%EF%BC%89

参考链接

• https://github.com/hetznercloud/csi-driver
• Hetzner Cloud Block Storage文档
• https://github.com/container-storage-interface/spec