hetznercloud/hcloud-cloud-controller-manager

Kubernetes Cloud Controller Manager for Hetzner Cloud 镜像文档

镜像概述

本Docker镜像包含用于Hetzner Cloud的Kubernetes cloud-controller-manager实现，遵循Kubernetes云控制器管理器接口规范。它作为Kubernetes集群与Hetzner Cloud之间的桥梁，负责协调Kubernetes集群与Hetzner Cloud基础设施的交互，自动管理云资源以满足Kubernetes集群需求。

主要用途

• 实现Kubernetes集群与Hetzner Cloud的深度集成
• 自动化管理与Kubernetes资源关联的Hetzner Cloud资源
• 提供云原生的节点生命周期、负载均衡器及网络路由管理能力

核心功能和特性

节点管理

• 节点注册：自动将Hetzner Cloud服务器节点注册到Kubernetes集群
• 健康检查：监控节点健康状态，基于Hetzner Cloud API检查服务器状态
• 节点驱逐：当Hetzner Cloud服务器被删除或不可用时，触发Kubernetes节点驱逐

负载均衡器管理

• 自动创建：为Kubernetes Service（类型为Load***）自动创建Hetzner Cloud负载均衡器
• 配置同步：同步Service规格变更到负载均衡器（如端口映射、协议配置）
• 自动删除：当Service删除时清理关联的负载均衡器资源
• 注解支持：通过Service注解自定义负载均衡器配置（如名称、类型、健康检查路径等）

路由管理

• 配置Kubernetes节点与Hetzner Cloud网络之间的路由规则
• 维护节点网络可达性，确保Pod跨节点通信

其他特性

• 领导者选举：支持多实例部署时的领导者选举，确保高可用性
• 日志增强：详细日志记录资源操作过程，便于问题排查
• 版本兼容：适配主流Kubernetes版本（参考官方支持矩阵）

使用场景和适用范围

适用场景

• 运行在Hetzner Cloud上的自管理Kubernetes集群（非托管K8s服务）
• 需要自动管理Hetzner Cloud负载均衡器的Kubernetes集群
• 需实现节点自动注册与生命周期管理的Hetzner Cloud K8s环境
• 希望通过Kubernetes原生接口管理云资源的场景

不适用场景

• 托管Kubernetes服务（如Hetzner Cloud Kubernetes Service），通常已内置云控制器功能
• 非Hetzner Cloud环境的Kubernetes集群
• 仅需基础网络功能、无需云资源管理的极简集群

使用方法和配置说明

前置条件

1. 运行中的Kubernetes集群（版本需与镜像支持版本匹配，通常≥v1.21）
2. Hetzner Cloud API令牌（需具备适当权限，如read、write权限）
3. 集群节点已配置与Hetzner Cloud网络通信的网络策略
4. 已创建RBAC权限配置（为cloud-controller-manager提供必要的Kubernetes API权限）

部署方式

环境变量配置

核心环境变量说明：

Docker Run示例（仅测试用，生产环境建议通过Kubernetes部署）

bash
docker run -d \
  --name hcloud-ccm \
  -e HCLOUD_TOKEN="your-hetzner-cloud-api-token" \
  -e CLUSTER_NAME="my-k8s-cluster" \
  -v /var/run/kubernetes/kubelet.sock:/var/run/kubernetes/kubelet.sock \
  --network host \
  hetznercloud/hcloud-cloud-controller-manager:latest

Kubernetes部署示例（Deployment）

创建hcloud-ccm-deployment.yaml：

yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: hcloud-cloud-controller-manager
  namespace: kube-system
spec:
  replicas: 1
  selector:
    matchLabels:
      app: hcloud-cloud-controller-manager
  template:
    metadata:
      labels:
        app: hcloud-cloud-controller-manager
    spec:
      containers:
      - name: hcloud-cloud-controller-manager
        image: hetznercloud/hcloud-cloud-controller-manager:latest
        command:
        - /hcloud-cloud-controller-manager
        - --cloud-provider=hcloud
        - --leader-elect=true
        - --cluster-name=my-k8s-cluster
        env:
        - name: HCLOUD_TOKEN
          valueFrom:
            secretKeyRef:
              name: hcloud-api-token
              key: token
        resources:
          requests:
            cpu: 100m
            memory: 50Mi
          limits:
            cpu: 500m
            memory: 256Mi
      serviceAccountName: cloud-controller-manager
      tolerations:
      - key: node-role.kubernetes.io/master
        effect: NoSchedule
      - key: node-role.kubernetes.io/control-plane
        effect: NoSchedule

RBAC权限配置示例

创建hcloud-ccm-rbac.yaml：

yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  name: cloud-controller-manager
  namespace: kube-system
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: system:cloud-controller-manager
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: cluster-admin
subjects:
- kind: ServiceAccount
  name: cloud-controller-manager
  namespace: kube-system

服务注解配置

通过Service注解自定义负载均衡器配置示例：

yaml
apiVersion: v1
kind: Service
metadata:
  name: my-service
  annotations:
    load-balancer.hetzner.cloud/name: "my-service-lb"  # 负载均衡器名称
    load-balancer.hetzner.cloud/type: "lb11"            # 负载均衡器类型
    load-balancer.hetzner.cloud/location: "nbg1"        # 部署位置
    load-balancer.hetzner.cloud/use-private-ip: "true"  # 是否使用私有IP
spec:
  type: LoadBalancer
  ports:
  - port: 80
    targetPort: 8080
  selector:
    app: my-app

验证部署

部署完成后，可通过以下方式验证：

1. 检查Pod状态：kubectl get pods -n kube-system | grep hcloud-cloud-controller-manager
2. 查看日志：kubectl logs -n kube-system <pod-name>
3. 创建测试Service（类型Load***），验证Hetzner Cloud控制台是否自动创建负载均衡器

注意事项

1. 权限控制：确保RBAC配置提供足够权限，避免因权限不足导致资源管理失败
2. 版本兼容性：镜像版本需与Kubernetes集群版本匹配，参考官方兼容性矩阵
3. API令牌安全：建议通过Kubernetes Secret管理API令牌，避免明文配置
4. 高可用性：生产环境建议部署多个实例（启用领导者选举），确保服务可用性