cbeneke/hcloud-fip-controller

hcloud-fip-controller

项目状态

注意：此项目目前处于开发中（WIP），可能无法正常工作且文档可能不完整。使用时请谨慎，如有问题欢迎提交bug报告和拉取请求。

镜像概述和主要用途

hcloud-fip-controller是一个小型控制器，旨在运行于Hetzner Cloud虚拟机上的Kubernetes集群中。其核心功能是定期检查Hetzner Cloud API，确保配置的浮动IP（或IPv6子网）分配给当前调度了该控制器Pod的节点。需注意，控制器不会处理节点的网络配置，因此必须确保所有节点上已预先配置这些IP地址，以保证故障转移正常工作。

核心功能和特性

• 定期检查与更新：每30秒通过Hetzner Cloud API检查浮动IP分配状态，如未分配给当前节点则自动更新
• 多配置方式：支持环境变量和配置文件两种配置方式，环境变量优先级高于配置文件
• 多IP支持：通过配置文件可管理多个浮动IP
• 节点地址类型配置：可指定节点地址类型（外部或内部），适应不同网络环境

使用场景和适用范围

适用于部署在Hetzner Cloud上的Kubernetes集群，需要实现浮动IP自动故障转移的场景。例如：

• 高可用集群中控制平面或负载均衡器的浮动IP管理
• 需要固定入口IP的应用服务，确保节点故障时IP自动漂移

配置说明

环境变量

环境变量优先级高于配置文件，支持以下参数：

配置文件（config.json）

配置文件支持与环境变量对应的字段，格式如下：

json
{
  "hcloudFloatingIPs": [
    "<HCLOUD_FLOATING_IP>"  // 浮动IP列表，支持多个
  ],
  "hcloudApiToken": "<HCLOUD_API_TOKEN>",  // Hetzner Cloud API令牌
  "nodeAddressType": "<NODE_ADDRESS_TYPE>",  // 节点地址类型（"external"或"internal"）
  "nodeName": "<NODE_NAME>"  // 当前节点名称
}

Kubernetes部署指南

前提条件

• 已部署Kubernetes集群（运行在Hetzner Cloud虚拟机上）
• 拥有Hetzner Cloud API令牌（需具备管理浮动IP的权限）
• 所有节点已配置需管理的浮动IP地址

部署步骤

1. 创建命名空间

bash
kubectl create namespace fip-controller

2. 应用RBAC配置（权限设置）

bash
kubectl apply -f deploy/rbac.yaml

3. 部署控制器

bash
kubectl apply -f deploy/deployment.yaml

4. 创建配置和密钥

bash
cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: ConfigMap
metadata:
  name: fip-controller-config
  namespace: fip-controller
data:
  config.json: |
    {
      "hcloudFloatingIPs": [
        "<hcloud-floating-ip-1>",  // 替换为实际浮动IP
        "<hcloud-floating-ip-2>"   // 可添加多个IP
      ]
    }
---
apiVersion: v1
kind: Secret
metadata:
  name: fip-controller-secrets
  namespace: fip-controller
stringData:
  HCLOUD_API_TOKEN: <hcloud_api_token>  // 替换为实际API令牌
EOF

注意事项

• 确保所有节点已手动配置浮动IP地址，控制器仅负责API层面的分配，不处理节点网络配置
• 多IP管理需通过配置文件实现，环境变量仅支持单个IP
• 节点名称（NODE_NAME）建议通过Pod spec中的fieldRef自动获取，例如在deployment.yaml中配置：

  yaml
  env:
  - name: NODE_NAME
    valueFrom:
      fieldRef:
        fieldPath: spec.nodeName