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 地址类型。当前仅支持取值为：ipv4。ipv4

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

相关文档