apache/cloudstack-kubernetes-provider

Apache CloudStack Kubernetes Provider

1. 镜像概述和主要用途

Apache CloudStack Kubernetes Provider 是一个云控制器管理器（Cloud Controller Manager），用于在 CloudStack 平台上简化 Kubernetes 集群的部署和管理。该项目基于旧版 Kubernetes 中已移除的 CloudStack 提供程序开发，旨在为 CloudStack 环境中的 Kubernetes 集群提供云资源集成能力。

2. 核心功能和特性

• 云资源集成：作为 Cloud Controller Manager，实现 Kubernetes 与 CloudStack 计算、网络资源的对接
• 自动部署：在 CloudStack 4.16+ 环境中创建 Kubernetes 集群时自动部署
• 负载均衡支持：支持 TCP、UDP 及 TCP-Proxy（基于 HAProxy Proxy Protocol）类型的 Load*** 服务部署
• 节点标签管理：自动从 CloudStack 获取元数据并为 Kubernetes 节点添加标签（如实例类型、可用区等）
• 灵活的 API 配置：通过 cloud-config 支持 CloudStack API 访问参数配置，包括项目、可用区、SSL 验证等选项

3. 使用场景和适用范围

• 在 CloudStack 云平台上部署和管理 Kubernetes 集群的场景
• 需要将 Kubernetes 集群与 CloudStack 网络（负载均衡、安全组）和计算资源（实例类型、可用区）深度集成的环境
• 需在 Kubernetes 中使用 TCP、UDP 或 TCP-Proxy 协议负载均衡服务的场景
• 从旧版 Kubernetes CloudStack 提供程序迁移至独立控制器的集群

4. 使用方法和配置说明

4.1 前提条件

• CloudStack 版本要求：
  • 基础功能：CloudStack 4.16+（自动部署场景）
  • UDP 和 TCP-Proxy 支持：CloudStack 4.6+
• Kubernetes 集群：需配置为使用外部云控制器管理器（CCM）
• 网络访问：确保 Kubernetes 集群可访问 CloudStack API 服务端

4.2 配置 CloudStack API 访问

4.2.1 创建 cloud-config 文件

需创建 cloud-config 配置文件，提供 CloudStack API 访问参数。文件格式如下：

ini
[Global]
api-url = <CloudStack API URL>          # CloudStack API 地址（必填）
api-key = <CloudStack API Key>          # CloudStack API 密钥（必填）
secret-key = <CloudStack API Secret>    # CloudStack API 密钥（必填）
project-id = <CloudStack Project UUID>  # CloudStack 项目 UUID（可选）
zone = <CloudStack Zone Name>           # CloudStack 可用区名称（可选）
ssl-no-verify = <true|false>            # 禁用 SSL 证书验证（可选，默认 false）

注意：配置的 API 密钥需具备以下权限：获取 VM 信息、在节点所在项目/域中部署负载均衡器。

4.2.2 创建 Kubernetes Secret

使用 kubectl 创建包含 cloud-config 的 Secret，存储于 kube-system 命名空间：

bash
kubectl -n kube-system create secret generic cloudstack-secret --from-file=cloud-config

4.3 部署控制器

通过官方提供的 deployment.yaml 部署 CloudStack Kubernetes Provider 控制器：

bash
# 下载部署文件（或从项目仓库获取）
kubectl apply -f deployment.yaml

部署文件地址：https://github.com/apache/cloudstack-kubernetes-provider/blob/main/deployment.yaml

4.4 协议支持配置

4.4.1 支持的协议类型

• TCP：默认支持，无特殊版本要求
• UDP：需 CloudStack 4.6+
• TCP-Proxy（基于 HAProxy Proxy Protocol）：需 CloudStack 4.6+，且后端服务需支持 Proxy Protocol

4.4.2 协议配置注意事项

• kube-proxy 限制：kube-proxy 不支持 UDP 和 Proxy Protocol，需将服务直接连接至 Pod（例如通过 DaemonSet 部署并设置 hostPort: <TCP port>）
• 服务协议兼容性：确保 Pod 中运行的服务支持所选协议（例如，启用 TCP-Proxy 时，服务需兼容 Proxy Protocol）

4.4.3 Ingress 控制器示例

• Traefik Ingress 控制器：项目提供基础部署示例，支持 Proxy Protocol：

  bash
  kubectl apply -f traefik-ingress-controller.yml
  

  （文件地址：https://github.com/apache/cloudstack-kubernetes-provider/blob/main/traefik-ingress-controller.yml%EF%BC%89

• Nginx Ingress 控制器：

  1. 参考官方部署文档：https://kubernetes.github.io/ingress-nginx/deploy/
  2. 应用 Proxy Protocol 支持补丁：

     bash
     kubectl apply -f nginx-ingress-controller-patch.yml
     

4.5 节点标签配置

4.5.1 节点名称要求

⚠️ 节点名称必须与主机名一致，控制器需通过节点名称从 CloudStack 获取并分配元数据标签。

4.5.2 kubelet 初始化配置

建议启动 kubelet 时添加以下参数，将节点标记为“未初始化”，触发控制器自动应用 CloudStack 元数据标签：

bash
--register-with-taints=node.cloudprovider.kubernetes.io/uninitialized=true:NoSchedule

4.5.3 支持的节点标签

• Kubernetes ≤ 1.16：

  • kubernetes.io/hostname: 实例名称
  • beta.kubernetes.io/instance-type: 计算规格
  • failure-domain.beta.kubernetes.io/zone: 可用区
  • failure-domain.beta.kubernetes.io/region: 可用区（与 zone 一致）

• Kubernetes ≥ 1.17：

  • kubernetes.io/hostname: 实例名称
  • node.kubernetes.io/instance-type: 计算规格
  • topology.kubernetes.io/zone: 可用区
  • topology.kubernetes.io/region: 可用区（与 zone 一致）

4.5.4 手动触发标签同步

若需手动触发节点标签同步，可通过以下命令为节点添加 taint：

bash
kubectl taint nodes <my-node-without-labels> node.cloudprovider.kubernetes.io/uninitialized=true:NoSchedule

5. 迁移指南

从旧版 Kubernetes CloudStack 提供程序迁移至本独立控制器时，需注意以下差异：

5.1 负载均衡规则变更

负载均衡规则名称现在包含协议、LB 名称及服务端口，以区分同一端口上的 TCP、UDP 和 TCP-Proxy 服务（例如，支持同一端口同时运行 TCP 和 UDP 服务）。

⚠️ 迁移前需删除现有规则，迁移后重新创建，否则会导致同一服务出现重复规则，引发功能异常。

5.2 元数据获取方式变更

旧版提供程序运行在节点上，通过虚拟路由器的 DHCP 服务器获取元数据；本控制器运行在 Pod 内，通过以下流程获取元数据：

1. 从 Kubernetes 获取节点名称
2. 通过 CloudStack API 查询节点对应的 CloudStack 实例信息

6. 版权信息

Copyright 2019 The Apache Software Foundation

本产品包含由 Apache Software Foundation 开发的软件（[***]