You need to enable JavaScript to run this app.
导航

通过 Annotation 配置四层负载均衡

最近更新时间2023.11.08 19:44:05

首次发布时间2022.02.08 17:53:49

通过配置服务(Service)YAML 文件中特定的注解(Annotation)内容,实现更丰富的四层负载均衡(CLB)能力。

背景信息

当您在容器服务集群中配置 Service 时,允许通过配置 YAML 文件中特定的注解,新建或复用四层负载均衡实例。

新建和复用四层负载均衡实例的主要区别如下表所示。

资源对象新建 CLB复用 CLB

CLB

  • 控制器会根据 Annotation 配置,自动创建 CLB、监听器和后端服务器组。
  • 删除 Service 时,控制器会删除自动创建的 CLB。
  • 在 Annotation 配置service.beta.kubernetes.io/volcengine-loadbalancer-id中指定复用 CLB 实例的 ID。
  • 控制器会根据 Annotation 中的其他配置,为 CLB 创建监听器和后端服务器组。
  • 删除 Service 时,控制器会删除为复用 CLB 创建的监听器和后端服务器组,不会删除 CLB 实例。

说明

  • 仅支持复用通过负载均衡控制台创建的 CLB,不支持复用通过容器服务 LoadBalancer 类型的 Service 自动创建的 CLB。
  • CLB 在 VPC 内提供负载均衡,复用的 CLB 需要和集群处于同一个 VPC。

监听器

  • 控制器会根据 Annotation 的配置,自动创建监听器和后端服务器组。
  • 删除 Service 时,控制器会删除创建的监听器和后端服务器组。
  • 控制器会根据 Annotation 的配置,自动创建监听器和后端服务器组。
  • 控制器无法在指定复用 CLB 上已经存在的端口上创建监听器。

LoadBalancer 类型的 Service 会在如下场景触发调谐:

  • 创建/删除/修改 Service 时,后端的变化(例如:Pod IP 改变,新增/下线 Pod)。
  • 控制器的 Pod 重启。

因此,需要注意以下事项:

  • 在负载均衡控制台手动修改 CLB 实例配置时,控制器无法感知。因此,控制器无法将负载均衡控制台中的修改写入 Service 的 Annotation 中。当 Service 触发调谐时,在负载均衡控制台上修改的配置可能会被控制器根据 Annotation 中的配置刷新。
  • CLB 配置项的处理逻辑如下:
    • 如果在 Annotation 中有相关配置(例如开启 ACL 访问控制),则 CLB 的配置和 Annotation 保持一致。在负载均衡控制台手动修改 CLB 的配置后,CLB 的配置直到 Service 下次调谐前,都与负载均衡控制台所做的修改保持一致。但在 Service 再次调谐时,将会被 Annotation 中的设置刷新。
    • 如果在 Annotation 中没有相关配置,CLB 的配置和负载均衡控制台上的配置一致,Service 的调谐不会修改负载均衡控制台上的设置。
    • 如果 Annotation 中有相关配置(例如开启 ACL 访问控制),接着删除了相关的 Annotation,则 CLB 的相关功能维持现状(例如 ACL 依然处于开启状态)。如果希望通过 Annotation 关闭相关功能,需要在 Annotation 中将相关功能的配置设置为关闭状态,而不是直接删除对应的 Annotation。

使用限制

暂不支持通过 Annotation 修改 CLB 实例的规格和类型。

Annotation 使用说明

注解的内容需要严格区分大小写。

Annotation 典型使用方式

注意

  • 在 VKE 中创建负载均衡服务时,如果通过 Annotation:service.beta.kubernetes.io/volcengine-loadbalancer-acl-status,为负载均衡服务关联的 CLB 实例监听器配置了访问控制策略,则 VKE 侧的配置,会覆盖负载均衡控制台上的配置(只要触发 VKE 侧的配置,就会覆盖 CLB 侧的配置),请谨慎操作。
  • 各个 Annotation 对应的详细说明及 Value 的取值范围,请参见本文下方 常用 Annotation 集合

使用方式一

通过新建的负载均衡器,创建负载均衡服务。YAML 配置示例如下所示,示例中的 Annotation 详细说明,请参见本文下方 常用 Annotation 集合

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/volcengine-loadbalancer-name: "test-svc"
    #必填,要创建的负载均衡实例名称。
    service.beta.kubernetes.io/volcengine-loadbalancer-subnet-id: "subnet-mizw4xqzpssg5smt1b******"   
    #必填,[CLB 实例配置]负载均衡实例所属的子网 ID。
    service.beta.kubernetes.io/volcengine-loadbalancer-address-type: "PUBLIC"
    #非必填,[CLB 实例配置]负载均衡实例的网络类型。不设置时,默认网络类型为 PUBLIC。
    service.beta.kubernetes.io/volcengine-loadbalancer-isp-type: "BGP"
    #address-type 为 PUBLIC 时必填,[CLB 实例配置]负载均衡实例的线路类型。
    service.beta.kubernetes.io/volcengine-loadbalancer-eip-billing-type: "2"
    #address-type 为 PUBLIC 时必填,[CLB 实例配置]公网 IP(EIP)计费类型。
    service.beta.kubernetes.io/volcengine-loadbalancer-bandwidth: "25" 
    #address-type 为 PUBLIC 时必填,[CLB 实例配置]公网类型负载均衡实例需要指定公网 IP(EIP)带宽峰值。   
    service.beta.kubernetes.io/volcengine-loadbalancer-ip-version: "ipv4"
    #非必填,[CLB 实例配置]负载均衡实例的 IP 地址类型。CLB 目前仅支持 IPv4。
    service.beta.kubernetes.io/volcengine-loadbalancer-spec: "small_1"
    #必填,[CLB 实例配置]负载均衡实例的规格。
    service.beta.kubernetes.io/volcengine-loadbalancer-pass-through: "false"
    #非必填,[监听器配置]是否开启负载均衡器直通 Pod 模式。
    service.beta.kubernetes.io/volcengine-loadbalancer-scheduler: "wrr"
    #非必填,[监听器配置]监听器的调度算法。
    service.beta.kubernetes.io/volcengine-loadbalancer-acl-status: "on"
    #非必填,[监听器配置]是否开启监听器的访问控制。
    service.beta.kubernetes.io/volcengine-loadbalancer-acl-type: "white"
    #acl-status 为 on 时必填,[监听器配置]开启访问控制的方式(白名单、黑名单)。
    service.beta.kubernetes.io/volcengine-loadbalancer-acl-id: "acl-3cj44nv0jhhxc6c6rrtet****,acl-2febxt4pu0zy85oxruw0t****"
    #acl-status 为 on 时必填,[监听器配置]监听器绑定的访问控制策略组 ID。
    service.beta.kubernetes.io/volcengine-loadbalancer-health-check-flag: "on" 
    #非必填,[监听器配置]是否开启健康检查。
    service.beta.kubernetes.io/volcengine-loadbalancer-health-check-connect-timeout: "2" 
    #health-check-flag 为 on 时必填,[监听器配置]等待健康检查的响应时间。
    service.beta.kubernetes.io/volcengine-loadbalancer-health-check-interval: "2" 
    #health-check-flag 为 on 时必填,[监听器配置]健康检查的时间间隔。
    service.beta.kubernetes.io/volcengine-loadbalancer-healthy-threshold: "3" 
    #health-check-flag 为 on 时必填,[监听器配置]后端服务器正常的健康检查次数。
    service.beta.kubernetes.io/volcengine-loadbalancer-unhealthy-threshold: "3" 
    #health-check-flag 为 on 时必填,[监听器配置]后端服务器异常的健康检查次数。
    
  name: test-service          #服务的名称。
  namespace: default        #服务所属的命名空间。
spec:
  externalTrafficPolicy: Cluster
  ports:
  - name: test              #端口映射策略命名。
    port: 80                #服务端口。
    protocol: TCP           #端口通信协议,支持 TCP/UDP。
    targetPort: 80          #容器端口。
  type: LoadBalancer        #服务的类型。

使用方式二

使用已有的负载均衡器,创建负载均衡服务。YAML 配置示例如下所示,示例中的 Annotation 详细说明,请参见本文下方 常用 Annotation 集合

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/volcengine-loadbalancer-id: "clb-mim02n8g5kw05smt1b******"
    #必填,[CLB 实例配置]已有负载均衡实例的 ID。
    service.beta.kubernetes.io/volcengine-loadbalancer-pass-through: "false"
    #非必填,[监听器配置]是否开启负载均衡器直通 Pod 模式。
    service.beta.kubernetes.io/volcengine-loadbalancer-scheduler: "wrr"
    #非必填,[监听器配置]监听器的调度算法。
    service.beta.kubernetes.io/volcengine-loadbalancer-acl-status: "on"
    #非必填,[监听器配置]是否开启监听器的访问控制。
    service.beta.kubernetes.io/volcengine-loadbalancer-acl-type: "white"
    #acl-status 为 on 时必填,[监听器配置]开启访问控制的方式(白名单、黑名单)。
    service.beta.kubernetes.io/volcengine-loadbalancer-acl-id: "acl-3cj44nv0jhhxc6c6rrtet****,acl-2febxt4pu0zy85oxruw0t****"
    #acl-status 为 on 时必填,[监听器配置]监听器绑定的访问控制策略组 ID。
    service.beta.kubernetes.io/volcengine-loadbalancer-health-check-flag: "on" 
    #非必填,[监听器配置]是否开启健康检查。
    service.beta.kubernetes.io/volcengine-loadbalancer-health-check-connect-timeout: "2" 
    #health-check-flag 为 on 时必填,[监听器配置]等待健康检查的响应时间。
    service.beta.kubernetes.io/volcengine-loadbalancer-health-check-interval: "2" 
    #health-check-flag 为 on 时必填,[监听器配置]健康检查的时间间隔。
    service.beta.kubernetes.io/volcengine-loadbalancer-healthy-threshold: "3" 
    #health-check-flag 为 on 时必填,[监听器配置]后端服务器正常的健康检查次数。
    service.beta.kubernetes.io/volcengine-loadbalancer-unhealthy-threshold: "3" 
    #health-check-flag 为 on 时必填,[监听器配置]后端服务器异常的健康检查次数。

  name: test-service                   #服务的名称。
  namespace: default                 #服务所属的命名空间。
spec:
  externalTrafficPolicy: Cluster
  ports:
  - name: test                       #端口映射策略命名。
    port: 80                         #服务端口。
    protocol: TCP                    #端口通信协议 TCP/UDP
    targetPort: 80                   #容器端口。
  type: LoadBalancer                 #服务的类型。

使用方式三

创建一个新的负载均衡服务并关联以弹性容器实例(VCI)方式部署的工作负载。YAML 配置示例如下所示,示例中的 Annotation 详细说明,请参见本文下方 常用 Annotation 集合

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/volcengine-loadbalancer-name: "test-svc"
    #必填,要创建的负载均衡实例名称。
    service.beta.kubernetes.io/volcengine-loadbalancer-subnet-id: "subnet-mizw4xqzpssg5smt1b******"   
    #必填,[CLB 实例配置]负载均衡实例所属的子网 ID。
    service.beta.kubernetes.io/volcengine-loadbalancer-address-type: "PUBLIC"
    #非必填,[CLB 实例配置]负载均衡实例的网络类型。不设置时,默认网络类型为 PUBLIC。
    service.beta.kubernetes.io/volcengine-loadbalancer-isp-type: "BGP"
    #address-type 为 PUBLIC 时必填,[CLB 实例配置]负载均衡实例的线路类型。
    service.beta.kubernetes.io/volcengine-loadbalancer-eip-billing-type: "2"
    #address-type 为 PUBLIC 时必填,[CLB 实例配置]公网 IP(EIP)计费类型。
    service.beta.kubernetes.io/volcengine-loadbalancer-bandwidth: "25" 
    #address-type 为 PUBLIC 时必填,[CLB 实例配置]公网类型负载均衡实例需要指定公网 IP(EIP)带宽峰值。   
    service.beta.kubernetes.io/volcengine-loadbalancer-ip-version: "ipv4"
    #非必填,[CLB 实例配置]负载均衡实例的 IP 地址类型。CLB 目前仅支持 IPv4。
    service.beta.kubernetes.io/volcengine-loadbalancer-spec: "small_1"
    #必填,[CLB 实例配置]负载均衡实例的规格。
    service.beta.kubernetes.io/volcengine-loadbalancer-pass-through: "true"
    #必填,[监听器配置]是否开启负载均衡器直通 Pod 模式。关联 VCI 工作负载时必须开启。
    service.beta.kubernetes.io/volcengine-loadbalancer-scheduler: "wrr"
    #非必填,[监听器配置]监听器的调度算法。
    service.beta.kubernetes.io/volcengine-loadbalancer-health-check-flag: "on" 
    #非必填,[监听器配置]是否开启健康检查。
    service.beta.kubernetes.io/volcengine-loadbalancer-health-check-connect-timeout: "2" 
    #health-check-flag 为 on 时必填,[监听器配置]等待健康检查的响应时间。
    service.beta.kubernetes.io/volcengine-loadbalancer-health-check-interval: "2" 
    #health-check-flag 为 on 时必填,[监听器配置]健康检查的时间间隔。
    service.beta.kubernetes.io/volcengine-loadbalancer-healthy-threshold: "3" 
    #health-check-flag 为 on 时必填,[监听器配置]后端服务器正常的健康检查次数。
    service.beta.kubernetes.io/volcengine-loadbalancer-unhealthy-threshold: "3" 
    #health-check-flag 为 on 时必填,[监听器配置]后端服务器异常的健康检查次数。
    
  name: test-service          #服务的名称。
  namespace: default        #服务所属的命名空间。
spec:
  externalTrafficPolicy: Cluster
  ports:
  - name: test              #端口映射策略命名。
    port: 80                #服务端口。
    protocol: TCP           #端口通信协议,支持 TCP/UDP。
    targetPort: 80          #容器端口。
  selector:                 #标签选择器,将 Service 与后端容器组实例(Pod)绑定。
    app: vci-deployment     #具体标签。本示例选择以 VCI 方式部署的工作负载标签。
  type: LoadBalancer        #服务的类型。

常用 Annotation 集合

负载均衡 CLB 常用注解如下所示。

Key类型是否必须描述默认值

service.beta.kubernetes.io/volcengine-loadbalancer-id

String

使用已有 CLB 时,必须

使用已有的负载均衡实例 ID,设置后无法修改。
不指定则新创建负载均衡实例。

service.beta.kubernetes.io/volcengine-loadbalancer-name

String

要创建的负载均衡实例名称。
不指定则自动生成名称。

service.beta.kubernetes.io/volcengine-loadbalancer-subnet-idString自动创建 CLB 时,必须负载均衡实例所属的子网 ID。

service.beta.kubernetes.io/volcengine-loadbalancer-address-type

String

负载均衡实例的网络访问类型。取值如下:

  • PUBLIC:公网类型的负载均衡实例。
  • PRIVATE:私网类型的负载均衡实例。

PUBLIC

service.beta.kubernetes.io/volcengine-loadbalancer-isp-type

String

address-type 为 PUBLIC 时,必须

负载均衡实例的线路类型。取值如下:
BGP:BGP(多线)线路。

BGP

service.beta.kubernetes.io/volcengine-loadbalancer-eip-BandwidthPackageId

String

共享带宽资源包 ID。

注意

  • 仅在service.beta.kubernetes.io/volcengine-loadbalancer-address-type=PUBLIC时生效。
  • 生效后原先的付费方式(按流量计费或按固定带宽计费)会被覆盖。

service.beta.kubernetes.io/volcengine-loadbalancer-eip-billing-type

Integer

address-type 为 PUBLIC 时,必须

公网 IP(EIP)计费类型。取值如下:

  • 2:按量计费-按带宽上限,指定带宽上限后,将按照使用时长计费,与实际流量无关。
  • 3:按量计费-按实际流量,指定带宽上限后,将按照实际使用的出公网流量计费,与使用时长无关。

3

service.beta.kubernetes.io/volcengine-loadbalancer-bandwidth

Integer

address-type 为 PUBLIC 时,必须

负载均衡实例的公网带宽峰值。

  • 取值范围:
    • eip-billing-type 为 2(按带宽上限)时:[1, 500]。
    • eip-billing-type 为 3(按实际流量)时:[1, 200]。
  • 单位:Mbps。

10

service.beta.kubernetes.io/volcengine-loadbalancer-ip-versionString负载均衡实例的 IP 地址类型。当前仅支持取值为:ipv4ipv4

service.beta.kubernetes.io/volcengine-loadbalancer-spec

String

负载均衡实例的规格类型。详细说明,请参见 产品类型与规格
取值:

  • small_1:小型I
  • small_2:小型II
  • medium_1:中型I
  • medium_2:中型II
  • large_1:大型I
  • large_2:大型II

small_1

service.beta.kubernetes.io/volcengine-loadbalancer-pass-through

Boolean

是否开启负载均衡器直通 Pod 模式。取值如下:

  • true:开启,直接关联 Pod 作为负载均衡器的后端。
  • false:不开启。

注意

LoadBlancer 类型 Service 关联弹性容器实例(VCI)方式部署的工作负载时,必须配置该 Annotation 且取值必须为 true,否则会导致 Service 不可用。

false

service.beta.kubernetes.io/volcengine-loadbalancer-scheduler

String

负载均衡实例的监听器调度算法。取值如下:

  • wrr:权重值越高的后端服务器,被轮询到的次数(概率)越高。
  • wlc:将请求分发给“当前连接/权重”比值最小的后端服务器
  • sh:基于源 IP 地址的一致性哈希,相同的源地址会调度到相同的后端服务器。

wrr

service.beta.kubernetes.io/volcengine-loadbalancer-acl-status

String

负载均衡实例的监听器是否开启访问控制。取值如下:

  • off:不开启。
  • on:开启。

off

service.beta.kubernetes.io/volcengine-loadbalancer-acl-type

String

acl-status 为 on 时,必须

负载均衡实例的监听器开启访问控制的方式。取值如下:

  • black:黑名单方式。表示仅拒绝来自所选访问控制策略组中设置的 IP 地址或地址段的请求。

    说明

    如果所选策略组中没有添加 IP,则监听器会转发所有请求。

  • white:白名单方式。表示监听器仅转发来自所选访问控制策略组中设置的 IP 地址或地址段的请求。

    说明

    如果所选策略组中没有添加 IP,则监听器不会转发任何请求。

black

service.beta.kubernetes.io/volcengine-loadbalancer-acl-id

String

acl-status 为 on 时,必须

负载均衡实例的监听器所绑定的访问控制策略组(ACL)ID。策略组相关信息,请参见 管理访问控制策略组
最多支持传入 5 个策略组 ID,多个策略组 ID 间使用英文逗号(,)分隔。

service.beta.kubernetes.io/volcengine-loadbalancer-health-check-flag

String

是否开启健康检查。取值如下:

  • on:开启健康检查,您还需要配置下方其余的健康检查相关 Annotation。
  • off:不开启健康检查,无需配置其余健康检查相关 Annotation。

off

service.beta.kubernetes.io/volcengine-loadbalancer-health-check-interval

Integer

健康检查的时间间隔。

  • 取值范围:[1, 300]
  • 单位:秒

2

service.beta.kubernetes.io/volcengine-loadbalancer-health-check-connect-timeout

Integer

健康检查的超时时间。

  • 取值范围:[1, 60]
  • 单位:秒

2

service.beta.kubernetes.io/volcengine-loadbalancer-healthy-threshold

Integer

健康检查连续成功多少次后,将后端服务器的健康检查状态由 Fail 判定为 Success。

  • 取值范围 :[3, 10]
  • 单位:次

3

service.beta.kubernetes.io/volcengine-loadbalancer-unhealthy-threshold

Integer

健康检查连续失败多少次后,将后端服务器的健康检查状态由 Success 判定为 Fail。

  • 取值范围:[3, 10]
  • 单位:次

3

service.beta.kubernetes.io/volcengine-loadbalancer-proxy-protocol

String

是否开启 Proxy Protocal 源 IP 透传,取值如下:

  • standard:开启 proxy protocal 源 IP 透传。

  • off:关闭 proxy protocal 源 IP 透传。

注意

目前,CLB 的配置最终会与 LB Service 中的设置保持一致。若此前已经手动在负载均衡控制台修改了 CLB 的配置,请在 LB service 中配置相应的内容,防止手动修改的内容失效。

off

相关文档