ghcr.io/kube-vip/kube-vip-cloud-provider:v0.0.3

kube-vip-cloud-provider

Kube-Vip 云提供商是一个通用的云提供商，适用于本地裸机或虚拟化环境。它设计用于与 kube-vip 项目配合使用，但如果负载均衡器解决方案遵循 Kubernetes 约定，则此云提供商将提供可由其他解决方案宣告的 IP 地址。

Architecture

kube-vip-cloud-provider 仅实现树外云提供商功能中的 load*** 功能。其设计旨在完全独立于 Kubernetes API 以外的任何其他技术，这意味着唯一的契约是 kube-vip-cloud-provider 与 Kubernetes 服务模式之间的契约。云提供商不会生成任何其他格式的配置信息，其唯一目的是确保类型为 load*** 的新服务已从地址池分配到地址。它通过使用来自其 IPAM 的地址更新 .annotations.kube-vip.io/loadbalancerIPs 和 .spec.loadBalancerIP 来实现此目的，而宣告该地址并更新 .status.loadBalancer.ingress.ip 的责任则由实际的负载均衡器（如 kube-vip.io）承担。

在 k8s 1.24 中，.spec.loadBalancerIP 已被弃用，未来 kube-vip-cloud-provider 将仅更新 .annotations.kube-vip.io/loadbalancerIPs 注解。

IP address functionality

• 按 CIDR 划分的 IP 地址池
• IP 范围 [起始地址 - 结束地址]
• 每个命名空间多个 CIDR 池
• 每个命名空间多个 IP 范围（处理重叠范围）
• 指定多个池或范围时支持混合 IP 家族
• 通过 --load-balancer-ip=x.x.x.x 或注解 kube-vip.io/loadbalancerIPs: x.x.x.x 设置静态地址
• 设置特殊 IP 0.0.0.0 用于 DHCP 工作流
• 支持单栈 IPv6 或 IPv4
• 通过注解支持双栈：kube-vip.io/loadbalancerIPs: 192.168.10.10,2001:db8::1
• 通过设置 search-order=desc，在从池或范围分配 IP 时支持升序和降序搜索顺序
• 支持 load***Class kube-vip.io/kube-vip-class
• 支持在单个 VIP 上分配多个服务（仅 IPv4，可选）
• 支持按命名空间或全局级别指定服务接口
• 支持从 CIDR 中排除第一个和最后一个 IP
• 支持自定义 load***Class 名称

Installing the kube-vip-cloud-provider

我们可以直接从该仓库应用控制器清单以获取最新版本：

$ kubectl apply -f https://raw.githubusercontent.com/kube-vip/kube-vip-cloud-provider/main/manifest/kube-vip-cloud-controller.yaml

它使用 Deployment，可通过以下命令查看：

kubectl describe deployment/kube-vip-cloud-provider -n kube-system
POD_NAME=$(kubectl get po -n kube-system | grep kube-vip-cloud-provider | cut -d' ' -f1)
kubectl describe pod/$POD_NAME -n kube-system

Global and namespace pools

Global pool

任何命名空间中的任何服务都将从全局池 cidr/range-global 获取地址。

Namespace pool

服务将根据其命名空间池 cidr/range-namespace 获取地址。示例如下：

$ kubectl get configmap -n kube-system kubevip -o yaml

apiVersion: v1
kind: ConfigMap
metadata:
  name: kubevip
  namespace: kube-system
data:
  cidr-default: 192.168.0.200/29
  cidr-development: 192.168.0.210/29
  cidr-finance: 192.168.0.220/29
  cidr-testing: 192.168.0.230/29
  cidr-ipv6: 2001::10/127

Create an IP pool using a CIDR

kubectl create configmap --namespace kube-system kubevip --from-literal cidr-global=192.168.0.220/29

Create an IP pool using a CIDR and descending search order

kubectl create configmap --namespace kube-system kubevip --from-literal cidr-global=192.168.0.220/29 --from-literal search-order=desc

Create an IP range

kubectl create configmap --namespace kube-system kubevip --from-literal range-global=192.168.0.200-192.168.0.202

Create an IP range and descending search order

kubectl create configmap --namespace kube-system kubevip --from-literal range-global=192.168.0.200-192.168.0.202 --from-literal search-order=desc

Multiple pools or ranges

我们可以通过逗号分隔来应用多个池或范围。例如：192.168.0.200/30,192.168.0.200/29 或 2001::12/127,2001::10/127 或 192.168.0.10-192.168.0.11,192.168.0.10-192.168.0.13 或 2001::10-2001::14,2001::20-2001::24 或 192.168.0.200/30,2001::10/127

Dualstack Services

假设配置映射中的池如下：range-default: 192.168.0.10-192.168.0.11,2001::10-2001::11，且当前没有 IP 在使用。

然后通过创建具有以下规范的服务（在 ipFamilies 中首先指定 IPv6）：

apiVersion: v1
kind: Service
metadata:
  name: my-service
  labels:
    app.kubernetes.io/name: MyApp
spec:
  ipFamilyPolicy: PreferDualStack
  ipFamilies:
    - IPv6
    - IPv4
  selector:
    app.kubernetes.io/name: MyApp
  ports:
    - protocol: TCP
      port: 80

该服务将收到注解 kube-vip.io/loadbalancerIPs: 2001::10,192.168.0.10，遵循优先 IPv6 的意图。相反，如果首先指定 IPv4，则 IPv4 地址将在注解中首先出现。

使用 PreferDualStack IP 家族策略时，只要池中任何 IP 家族有可用地址，kube-vip-cloud-provider 将尽最大努力在 loadBalancerIPs 中提供至少一个 IP。

如果指定了 RequireDualStack，则如果 kube-vip-cloud-provider 无法在池的两个 IP 家族中均找到可用地址，将无法设置 kube-vip.io/loadbalancerIPs 注解。

Special DHCP CIDR

将 CIDR 设置为 0.0.0.0/32，这将使控制器为所有 Load***s 分配 IP 0.0.0.0。

Load***Class support

如果用户仅希望 kube-vip-cloud-provider 为特定服务集分配 IP，可将环境变量 KUBEVIP_ENABLE_LOADBALANCERCLASS: true 传递给 kube-vip-cloud-provider。kube-vip-cloud-provider 将仅为 spec.loadBalancerClass: kube-vip.io/kube-vip-class 的服务分配 IP。

允许多个 IPv4 服务共享一个 VIP

启用后，如果服务的端口不重叠，kube-vip-cloud-provider 会尝试将服务分配到已使用的 VIP。如果希望启用服务间的 VIP 共享，可以将 allow-share-namespace 设置为 true。它遵循与全局池和命名空间池配置相同的规则。

为 development 命名空间启用共享的示例对象：

$ kubectl get configmap -n kube-system kubevip -o yaml

apiVersion: v1
kind: ConfigMap
metadata:
name: kubevip
namespace: kube-system
data:
cidr-default: 192.168.0.200/29
cidr-development: 192.168.0.210/29
allow-share-development: true

指定命名空间范围的服务接口

Kube-vip 0.8.0 支持在 LB 类型的服务上使用 kube-vip.io/serviceInterface 注解。现在用户可以在命名空间级别指定 IP 范围/CIDR，我们假设同一命名空间内的这些 IP 应共享相同的接口，因此支持通过以下方式在命名空间级别指定接口：

示例对象：

$ kubectl get configmap -n kube-system kubevip -o yaml

apiVersion: v1
kind: ConfigMap
metadata:
name: kubevip
namespace: kube-system
data:
cidr-default: 192.168.0.200/29
interface-default: eth3
cidr-development: 172.16.0.0/29
interface-default: eth5

interface-global 可用于指定所有命名空间下的所有服务使用此 IP 接口。如果某个命名空间未指定接口，将回退到 interface-global。但通常不需要这样做，因为 kube-vip 提供了 vip_servicesinterface 供用户为 LB 类型的服务定义默认接口。

从 CIDR 中排除首尾 IP

默认情况下，指定 cidr- 时，该 CIDR 内的所有 IP 都将分配给 LB 类型的服务。但在某些情况下，第一个 IP 可能用作网络 IP，最后一个 IP 可能用作广播 IP，用户可能不希望将这些 IP 分配给 LB 类型的服务。此时，用户可以在 configmap 中指定 skip-end-ips-in-cidr: true，以跳过 CIDR 中的第一个和最后一个 IP。

示例对象：

$ kubectl get configmap -n kube-system kubevip -o yaml

apiVersion: v1
kind: ConfigMap
metadata:
name: kubevip
namespace: kube-system
data:
cidr-default: 192.168.0.200/29
skip-end-ips-in-cidr: true

在这种情况下，只有 IP 192.168.0.201-192.168.0.206 会分配给服务，192.168.0.200 和 192.168.0.207 会被排除。

调试

可以使用以下命令查看 cloud-provider 控制器的日志：

kubectl logs -n kube-system kube-vip-cloud-provider-0 -f

创建IP范围和降序搜索顺序

kubectl create configmap --namespace kube-system kubevip --from-literal range-global=192.168.0.200-192.168.0.202 --from-literal search-order=desc

多个池或范围

我们可以通过逗号分隔来应用多个池或范围。例如：192.168.0.200/30,192.168.0.200/29 或 2001::12/127,2001::10/127 或 192.168.0.10-192.168.0.11,192.168.0.10-192.168.0.13 或 2001::10-2001::14,2001::20-2001::24 或 192.168.0.200/30,2001::10/127

双栈服务

假设配置映射中的池如下：range-default: 192.168.0.10-192.168.0.11,2001::10-2001::11，且当前没有IP在使用。

然后，通过创建具有以下规范的服务（在 ipFamilies 中首先指定 IPv6）：

apiVersion: v1
kind: Service
metadata:
  name: my-service
  labels:
    app.kubernetes.io/name: MyApp
spec:
  ipFamilyPolicy: PreferDualStack
  ipFamilies:
    - IPv6
    - IPv4
  selector:
    app.kubernetes.io/name: MyApp
  ports:
    - protocol: TCP
      port: 80

该服务将收到注解 kube-vip.io/loadbalancerIPs: 2001::10,192.168.0.10，遵循优先使用IPv6的意图。相反，如果首先指定 IPv4，则IPv4地址将在注解中首先出现。

使用 PreferDualStack IP家族策略时，只要池中任何IP家族有可用地址，kube-vip-cloud-provider将尽最大努力在 loadBalancerIPs 中提供至少一个IP。

如果指定 RequireDualStack，则如果无法在池的两个IP家族中均找到可用地址，kube-vip-cloud-provider将无法设置 kube-vip.io/loadbalancerIPs 注解。

特殊DHCP CIDR

将CIDR设置为 0.0.0.0/32，这将使控制器为所有 Load***s 分配IP 0.0.0.0。

Load***Class支持

如果用户仅希望kube-vip-cloud-provider为特定服务集分配IP，可将 KUBEVIP_ENABLE_LOADBALANCERCLASS: true 作为环境变量传递给kube-vip-cloud-provider。kube-vip-cloud-provider将仅为设置了 spec.loadBalancerClass: kube-vip.io/kube-vip-class 的服务分配IP。

如果用户希望使用自定义load***Class名称，可在设置 KUBEVIP_ENABLE_LOADBALANCERCLASS: true 的同时，传递环境变量 KUBEVIP_CUSTOM_LOADBALANCERCLASS_NAME: <自定义名称>。并在服务上设置 spec.loadBalancerClass: <自定义名称>。

允许多个IPv4服务共享一个VIP

启用后，如果服务的端口不重叠，kube-vip-cloud-provider会尝试将服务分配到已使用的VIP。 若要启用服务间的VIP共享，可将 allow-share-<namespace> 设置为true。其遵循与全局池和命名空间池配置相同的规则。

为命名空间 development 启用共享的示例对象：

$ kubectl get configmap -n kube-system kubevip -o yaml

apiVersion: v1
kind: ConfigMap
metadata:
  name: kubevip
  namespace: kube-system
data:
  cidr-default: 192.168.0.200/29
  cidr-development: 192.168.0.210/29
  allow-share-development: true

指定命名空间作用域的服务接口

Kube-vip 0.8.0支持在LB类型服务上使用 kube-vip.io/serviceInterface 注解。现在用户可以在命名空间级别指定IP范围/CIDR，我们假设命名空间内的这些IP应共享同一接口，因此支持按命名空间级别指定接口：

$ kubectl get configmap -n kube-system kubevip -o yaml

apiVersion: v1
kind: ConfigMap
metadata:
  name: kubevip
  namespace: kube-system
data:
  cidr-default: 192.168.0.200/29
  interface-default: eth3
  cidr-development: 172.16.0.0/29
  interface-default: eth5

interface-global 可用于指定所有命名空间下的所有服务使用此IP接口。如果某个命名空间未指定接口，将回退到 interface-global。但通常不需要此配置，因为kube-vip已通过 vip_servicesinterface 允许用户定义LB类型服务的默认接口。

从CIDR中排除第一个和最后一个IP

默认情况下，指定 cidr-<namespace> 时，该CIDR内的所有IP都将分配给LB类型服务。但在某些情况下，第一个IP可能用作网络IP，最后一个IP可能用作广播IP，用户可能不希望将这些IP分配给LB类型服务。在此情况下，用户可在配置映射中指定 skip-end-ips-in-cidr: true 以跳过CIDR中的第一个和最后一个IP。

示例对象：

$ kubectl get configmap -n kube-system kubevip -o yaml

apiVersion: v1
kind: ConfigMap
metadata:
  name: kubevip
  namespace: kube-system
data:
  cidr-default: 192.168.0.200/29
  skip-end-ips-in-cidr: true

在此情况下，只有IP 192.168.0.201-192.168.0.206 会分配给服务，192.168.0.200 和 192.168.0.207 被排除。

调试

可通过以下命令查看cloud-provider控制器的日志：

kubectl logs -n kube-system kube-vip-cloud-provider-0 -f