You need to enable JavaScript to run this app.
导航
容器服务
  • 文档首页
    • /容器服务/容器服务 VKE/用户指南/网络/服务（Service）/负载均衡（LoadBalancer）/使用 Annotation 配置负载均衡服务
使用 Annotation 配置负载均衡服务
最近更新时间：2025.03.20 10:59:31首次发布时间：2022.02.08 17:53:49
我的收藏
有用
有用
无用
无用

服务（Serivce）支持通过注解（Annotation）实现更加丰富的四层负载均衡（CLB）能力。本文主要介绍使用 Annotation 配置负载均衡服务的配置方法。

注意

创建服务

对接已有 CLB 实例

使用如下 YAML 配置，创建服务并对接已有的负载均衡实例。

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/volcengine-loadbalancer-id: "clb-mim02n8g5kw05smt1b******"
    # 必填，已有负载均衡实例的 ID
  name: clb-service # 服务的名称
  namespace: default # 服务所属的命名空间
spec:
  externalTrafficPolicy: Cluster
  selector:
    app: nginx # 通过标签选择器将服务与后端容器组（Pod）绑定
  ports:
  - name: test # 端口映射策略命名
    port: 80 # 服务端口
    protocol: TCP  # 端口通信协议 TCP/UDP
    targetPort: 80 # 容器端口
  type: LoadBalancer # 服务的类型

Annotation 说明如下表所示。

Key类型是否必须描述默认值是否支持修改
service.beta.kubernetes.io/volcengine-loadbalancer-idString是已存在的负载均衡实例 ID。无否

新建 CLB 实例

使用如下 YAML 配置，创建服务并同时创建新的负载均衡实例。

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/volcengine-loadbalancer-name: "clb-demo"
    # 非必填，新创建的负载均衡实例名称
    service.beta.kubernetes.io/volcengine-loadbalancer-subnet-id: "subnet-mizw4xqzpssg5smt1b******"
    # 必填，负载均衡实例所属的子网 ID
    service.beta.kubernetes.io/volcengine-loadbalancer-address-type: "PUBLIC"
    # 非必填，负载均衡实例的网络类型。不设置时，默认网络类型为 PUBLIC
    service.beta.kubernetes.io/volcengine-loadbalancer-isp-type: "BGP"
    # 非必填，负载均衡实例的线路类型
    service.beta.kubernetes.io/volcengine-loadbalancer-billing-type: "2"
    # 非必填，负载均衡实例计费类型
    service.beta.kubernetes.io/volcengine-loadbalancer-eip-billing-type: "3"
    # 非必填，公网 IP（EIP）计费类型
    service.beta.kubernetes.io/volcengine-loadbalancer-bandwidth: "25" 
    # 非必填，公网类型负载均衡实例需要指定公网 IP（EIP）带宽峰值。  
    service.beta.kubernetes.io/volcengine-loadbalancer-ip-version: "ipv4"
    # 非必填，负载均衡实例的 IP 地址类型，目前仅支持 IPv4
    service.beta.kubernetes.io/volcengine-loadbalancer-spec: "small_1"
    # 非必填，负载均衡实例的规格
    service.beta.kubernetes.io/volcengine-loadbalancer-sync-fields: "spec"
    # 更新 CLB 实例规格时必填，填写该字段为 spec 时，会根据 loadbalancer-spec 字段更新 CLB 的实例规格
    service.beta.kubernetes.io/volcengine-loadbalancer-master-zone-id: "cn-beijing-a"
    # 非必填，负载均衡实例的主可用区 ID
    service.beta.kubernetes.io/volcengine-loadbalancer-slave-zone-id: "cn-beijing-b"
    # 非必填，负载均衡实例的备可用区 ID
    service.beta.kubernetes.io/volcengine-loadbalancer-modification-protection-status: "ConsoleProtection"
    # 非必填，负载均衡实例的修改保护功能
    service.beta.kubernetes.io/volcengine-loadbalancer-eip-BandwidthPackageId: "bwp-2d63yyj3ki4u858oz***" 
    # 非必填，共享带宽资源包 ID
    service.beta.kubernetes.io/volcengine-loadbalancer-eni-address-number: "2"
    # 非必填，配置负载均衡实例的私网 IPv4 地址数量
    service.beta.kubernetes.io/volcengine-loadbalancer-eni-address: "192.168.0.1" 
    # 非必填，配置负载均衡实例的私网 IPv4 地址，该地址必须包含在所选子网的 IPv4 网段中，且未被占用
  name: clb-service # 服务的名称
  namespace: default # 服务所属的命名空间
spec:
  externalTrafficPolicy: Cluster
  selector:
    app: nginx # 通过标签选择器将服务与后端容器组（Pod）绑定
  ports:
  - name: test # 端口映射策略命名
    port: 80 # 服务端口
    protocol: TCP # 端口通信协议 TCP/UDP
    targetPort: 80 # 容器端口
  type: LoadBalancer # 服务的类型

Annotation 说明如下表所示。

Key类型是否必须描述默认值是否支持修改
service.beta.kubernetes.io/volcengine-loadbalancer-nameString否创建的负载均衡实例名称，不指定则自动生成名称。无否
service.beta.kubernetes.io/volcengine-loadbalancer-subnet-idString是负载均衡实例所属的子网 ID。无否

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

String

否

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

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

PUBLIC

否

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

String

否

负载均衡实例的线路类型。包括：BGP、SingleLine_BGP、Static_BGP、Fusion_BGP、ChinaMobile、ChinaTelecom、ChinaUnicom、ChinaMobile_Value、ChinaUnicom_Value 和 ChinaTelecom_Value。详细参数解释，请参见 EIP 产品文档。

注意

除 BGP 外，其他线路类型均为 EIP 产品的邀测功能，如需使用，请联系客户经理申请。

BGP

否

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

Integer

否

负载均衡实例的计费类型。取值：

  • 2：按量计费-按规格计费。指定实例规格，并按照实例的使用时长计费。
  • 3：按量计费-按使用量计费。无需指定实例规格，按照实例实际消耗的性能容量计费。

注意

  • 按量计费-按使用量计费 为负载均衡产品的邀测功能，如需使用，请联系客户经理申请。
  • 当负载均衡选择 按量计费-按使用量计费 类型时，无需配置实例规格类型，即loadbalancer-spec参数。

2

是

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

Integer

否

公网 IP（EIP）计费类型。取值：

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

3

否

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

Integer

否

负载均衡实例的公网带宽峰值，单位为 Mbps，取值：

  • 当eip-billing-type为 2 时，取值范围为 1～500。
  • 当eip-billing-type为 3 时，取值范围为 1～200。

1

否

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

注意

  • 负载均衡实例规格类型的详细说明，请参见 产品类型与规格。
  • 当loadbalancer-billing-type配置为3，即负载均衡实例采用 按量计费-按使用量计费 类型时，不支持配置本参数。
  • 当您使用本参数修改 CLB 实例的规格时，必须同时配置loadbalancer-sync-fields为spec。

small_1

是

service.beta.kubernetes.io/volcengine-loadbalancer-sync-fields

String

需要更新 CLB 实例的规格时，必选

更新 YAML 时，是否感知 loadbalancer-spec字段的变更，并更新 CLB 实例。取值：

  • spec：感知loadbalancer-spec字段的变更，并更新 CLB 实例的规格。

无

否

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

String

否

负载均衡实例的主可用区 ID。

  • 取值不能与slave-zone-id参数取值相同。
  • 不配置该参数或该参数为空时，默认分配子网所在可用区为主可用区。

说明

负载均衡在各地域支持的可用区情况以及可用区 ID，请参见 地域与可用区。

无

否

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

String

否

负载均衡实例的备可用区 ID。

  • 取值不能与master-zone-id参数取值相同。
  • 如果配置该参数，则参数master-zone-id必须一并配置，否则会报错。
  • 不配置该参数或该参数为空时，根据地域可用区部署情况按照如下逻辑处理：
    • 指定地域为单可用区部署时，该参数默认为空，创建单可用区负载均衡实例。
    • 指定地域为多可用区部署时，默认根据指定地域支持的可用区随机分配备可用区。

无

否

service.beta.kubernetes.io/volcengine-loadbalancer-modification-protection-status

String

否

负载均衡实例的修改保护功能，取值：

  • NonProtection：不开启控制台修改保护功能，表示允许通过控制台修改实例或删除实例。
  • ConsoleProtection：开启控制台修改保护功能，表示禁止通过控制台修改实例或删除实例。
  • 不配置该参数或该参数为空时，默认为空，表示开启控制台修改保护功能。

无

是

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-eni-address-number

String

否

配置负载均衡实例的私网 IPv4 地址数量。

说明

  • 仅私网实例支持使用此参数。
  • 与volcengine-loadbalancer-eni-address参数不能同时配置。

无

否

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

String

否

配置负载均衡实例的私网 IPv4 地址，该地址必须包含在所选子网的 IPv4 网段中，且未被占用。

说明

与volcengine-loadbalancer-eni-address-number参数不能同时配置。

无

否

新建 CLB 实例并对接 VCI 工作负载

使用如下 YAML 配置，创建一个新的负载均衡服务并关联以弹性容器实例（VCI）方式部署的工作负载。

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/volcengine-loadbalancer-name: "clb-demo"
    # 非必填，新创建的负载均衡实例名称
    service.beta.kubernetes.io/volcengine-loadbalancer-subnet-id: "subnet-mizw4xqzpssg5smt1b******"   
    # 必填，负载均衡实例所属的子网 ID
    service.beta.kubernetes.io/volcengine-loadbalancer-pass-through: "true"
    # 必填，开启负载均衡器直通 Pod 模式。关联 VCI 工作负载时必须开启
  name: clb-service # 服务的名称
  namespace: default # 服务所属的命名空间
spec:
  externalTrafficPolicy: Cluster
  selector:
    app: nginx # 通过标签选择器将服务与后端容器组（Pod）绑定
  ports:
  - name: test # 端口映射策略命名
    port: 80 # 服务端口
    protocol: TCP # 端口通信协议 TCP/UDP
    targetPort: 80 # 容器端口
  type: LoadBalancer # 服务的类型

Annotation 说明如下表所示。

Key类型是否必须描述默认值是否支持修改
service.beta.kubernetes.io/volcengine-loadbalancer-nameString否创建的负载均衡实例名称，不指定则自动生成名称。无否
service.beta.kubernetes.io/volcengine-loadbalancer-subnet-idString是负载均衡实例所属的子网 ID。无否

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

Boolean

是

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

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

false

是

注意

  • 仅在 VPC-CNI 网络模型的集群中支持配置为true。修改该字段会导致流量断流，请谨慎操作。
  • 负载均衡服务关联基于弹性容器实例（VCI）方式部署的工作负载时，必须开启直通 Pod 模式，否则会导致服务不可用。

监听器配置

说明

监听器支持在对接已有 CLB 实例时配置，也支持在创建新的 CLB 实例时配置。下文以对接已有 CLB 实例为例。

创建 UDP 协议监听器

当您未使用service.beta.kubernetes.io/volcengine-loadbalancer-protocol-port字段配置监听器的负载均衡协议时，系统会根据 YAML 配置中的spec.ports字段配置监听器协议，例如：当spec.ports字段中的protocol配置为 UDP 时，则系统创建 UDP 类型的监听器。示例如下：

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/volcengine-loadbalancer-id: "clb-mim02n8g5kw05smt1b******"
    # 必填，已有负载均衡实例的 ID
  name: clb-service # 服务的名称
  namespace: default # 服务所属的命名空间
spec:
  externalTrafficPolicy: Cluster
  selector:
    app: nginx # 通过标签选择器将服务与后端容器组（Pod）绑定
  ports:
  - name: test # 端口映射策略命名
    port: 80 # 服务端口
    protocol: UDP  # 端口通信协议 TCP/UDP
    targetPort: 80 # 容器端口
  type: LoadBalancer # 服务的类型

创建 TCP 协议监听器

当您未使用service.beta.kubernetes.io/volcengine-loadbalancer-protocol-port字段配置监听器的负载均衡协议时，系统会根据 YAML 配置中的spec.ports字段配置监听器协议，例如：当spec.ports字段中的protocol配置为 TCP 时，则系统创建 TCP 类型的监听器。示例如下：

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/volcengine-loadbalancer-id: "clb-mim02n8g5kw05smt1b******"
    # 必填，已有负载均衡实例的 ID
  name: clb-service # 服务的名称
  namespace: default # 服务所属的命名空间
spec:
  externalTrafficPolicy: Cluster
  selector:
    app: nginx # 通过标签选择器将服务与后端容器组（Pod）绑定
  ports:
  - name: test # 端口映射策略命名
    port: 80 # 服务端口
    protocol: TCP  # 端口通信协议 TCP/UDP
    targetPort: 80 # 容器端口
  type: LoadBalancer # 服务的类型

创建 HTTP 协议监听器

负载均衡服务支持通过 Annotation 配置 CLB 实例中 HTTP 协议类型的监听器，示例和说明如下：

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/volcengine-loadbalancer-id: "clb-mim02n8g5kw05smt1b******"
    # 必填，已有负载均衡实例的 ID
    service.beta.kubernetes.io/volcengine-loadbalancer-protocol-port: "HTTP: 80"
    # 必填，配置七层协议监听器，包括协议（HTTP、HTTPS）和端口号
  name: clb-service # 服务的名称
  namespace: default # 服务所属的命名空间
spec:
  externalTrafficPolicy: Cluster
  selector:
    app: nginx # 通过标签选择器将服务与后端容器组（Pod）绑定
  ports:
  - name: test # 端口映射策略命名
    port: 80 # 服务端口
    protocol: TCP  # 端口通信协议 TCP/UDP
    targetPort: 80 # 容器端口
  type: LoadBalancer # 服务的类型

Annotation 说明如下表所示。

Key类型是否必须描述默认值是否支持修改
service.beta.kubernetes.io/volcengine-loadbalancer-protocol-portString是配置监听器的七层协议和端口号。允许配置多个值，多个值之间用英文半角逗号,分隔，例如https:443,http:80。无是

警告

配置完成后，允许在 YAML 中更新或删除该 Annotation 配置。更新 Annotation 时，系统会删除原监听器，并基于更新后的配置重建监听器。此过程会导致业务中断，请谨慎配置。

创建 HTTPS 协议监听器

说明

创建 HTTPS 协议监听器前，需要首先在 CLB 控制台或证书中心上传 CA 证书和服务器证书。详情请参见 证书管理、创建 SSL 证书、上传SSL证书。

负载均衡服务支持通过 Annotation 配置 CLB 实例中 HTTPS 协议类型的监听器，示例和说明如下：

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/volcengine-loadbalancer-id: "clb-mim02n8g5kw05smt1b******"
    # 必填，已有负载均衡实例的 ID
    service.beta.kubernetes.io/volcengine-loadbalancer-protocol-port: "HTTPS: 443"
    # 必填，配置七层协议监听器，包括协议（HTTP、HTTPS）和端口号
    service.beta.kubernetes.io/volcengine-loadbalancer-cert-source: "clb"
    # 必填，HTTPS 协议使用的证书来源。取值：clb 和 cert_center（证书中心）
    service.beta.kubernetes.io/volcengine-loadbalancer-cert-id: "cert-22jti***"
    # 必填，HTTPS 协议使用的服务器证书 ID
    service.beta.kubernetes.io/volcengine-loadbalancer-security-policy-id: "default_policy"
    # 非必填，加密套件选择策略
    service.beta.kubernetes.io/volcengine-loadbalancer-ca-enabled: "on"
    # 非必填，是否开启双向认证，取值：on（开启）、off（关闭）
    service.beta.kubernetes.io/volcengine-loadbalancer-ca-cert-id: "cert-22jti***"
    # 当开启双向认证时必填，双向认证使用的 CA 证书 ID
  name: clb-service # 服务的名称
  namespace: default # 服务所属的命名空间
spec:
  externalTrafficPolicy: Cluster
  selector:
    app: nginx # 通过标签选择器将服务与后端容器组（Pod）绑定
  ports:
  - name: test # 端口映射策略命名
    port: 80 # 服务端口
    protocol: TCP  # 端口通信协议 TCP/UDP
    targetPort: 80 # 容器端口
  type: LoadBalancer # 服务的类型

Annotation 说明如下表所示。

Key类型是否必须描述默认值是否支持修改
service.beta.kubernetes.io/volcengine-loadbalancer-protocol-portString是配置监听器的七层协议和端口号。允许配置多个值，多个值之间用英文半角逗号,分隔，例如https:443,http:80。无是

service.beta.kubernetes.io/volcengine-loadbalancer-cert-source

String

是

配置证书来源，取值：

  • clb：CLB 控制台中管理的证书。
  • cert_center：证书中心管理的证书。

无

是

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

String

是

服务器证书 ID。

说明

CCM 不主动校验证书 ID 的合法性。如果证书 ID 不合法，会导致创建监听器失败。

无

是

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

String

否

开启 TLS 安全策略，并选择加密策略。取值：

  • default_policy：支持 SSL v3、TLS v1.0、TLS v1.1、TLS v1.2。
  • tls_cipher_policy_1_0：支持 TLS v1.0、TLS v1.1、TLS v1.2。
  • tls_cipher_policy_1_1：支持 TLS v1.1、TLS v1.2。
  • tls_cipher_policy_1_2：支持 TLS v1.2。
  • tls_cipher_policy_1_2_strict：支持 TLS v1.2。

default_policy

是

service.beta.kubernetes.io/volcengine-loadbalancer-ca-enabled

String

否

是否开启双向认证，取值：

  • on：开启双向认证。
  • off：关闭双向认证。

无

是

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

Srting

开启双向认证时必填

双向认证使用的 CA 证书 ID。

说明

CCM 不主动校验证书 ID 的合法性。如果证书 ID 不合法，会导致创建监听器失败。

无

是

警告

配置完成后，允许在 YAML 中更新或删除该 Annotation 配置。更新 Annotation 时，系统会删除原监听器，并基于更新后的配置重建监听器。此过程会导致业务中断，请谨慎配置。

配置调度算法

负载均衡服务支持通过 Annotation 配置 CLB 实例的调度算法，示例和说明如下：

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/volcengine-loadbalancer-id: "clb-mim02n8g5kw05smt1b******"
    # 必填，已有负载均衡实例的 ID
    service.beta.kubernetes.io/volcengine-loadbalancer-scheduler: "wrr"
    # 必填，监听器的调度算法，取值：wrr、wlc 和 sh
  name: clb-service # 服务的名称
  namespace: default # 服务所属的命名空间
spec:
  externalTrafficPolicy: Cluster
  selector:
    app: nginx # 通过标签选择器将服务与后端容器组（Pod）绑定
  ports:
  - name: test # 端口映射策略命名
    port: 80 # 服务端口
    protocol: TCP  # 端口通信协议 TCP/UDP
    targetPort: 80 # 容器端口
  type: LoadBalancer # 服务的类型

Annotation 说明如下表所示。

Key类型是否必须描述默认值是否支持修改

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

String

是

配置监听器的调度算法。取值：

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

wrr

是

配置超时时间

说明

仅 TCP 和 UDP 协议的监听器支持配置超时时间。

负载均衡服务支持通过 Annotation 配置 CLB 实例的超时时间，示例和说明如下：

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/volcengine-loadbalancer-id: "clb-mim02n8g5kw05smt1b******"
    # 必填，已有负载均衡实例的 ID
    service.beta.kubernetes.io/volcengine-loadbalancer-established-timeout: 100
    # 必填，监听器的超时时间
  name: clb-service # 服务的名称
  namespace: default # 服务所属的命名空间
spec:
  externalTrafficPolicy: Cluster
  selector:
    app: nginx # 通过标签选择器将服务与后端容器组（Pod）绑定
  ports:
  - name: test # 端口映射策略命名
    port: 80 # 服务端口
    protocol: TCP  # 端口通信协议 TCP/UDP
    targetPort: 80 # 容器端口
  type: LoadBalancer # 服务的类型

Annotation 说明如下表所示。

Key类型是否必须描述默认值是否支持修改

service.beta.kubernetes.io/volcengine-loadbalancer-established-timeout

Integer

是

配置监听器的连接超时时间，当前仅针对 TCP 和 UDP 监听器生效。取值范围：

  • TCP 协议：10～900 秒，默认为 900 秒。
  • UDP 协议：1～300 秒，默认为 90 秒。

无

是

配置带宽峰值

负载均衡服务支持通过 Annotation 配置 CLB 实例的带宽峰值，示例和说明如下：

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/volcengine-loadbalancer-id: "clb-mim02n8g5kw05smt1b******"
    # 必填，已有负载均衡实例的 ID
    service.beta.kubernetes.io/volcengine-loadbalancer-listener-bandwidth: 10
    # 必填，监听器的带宽峰值
  name: clb-service # 服务的名称
  namespace: default # 服务所属的命名空间
spec:
  externalTrafficPolicy: Cluster
  selector:
    app: nginx # 通过标签选择器将服务与后端容器组（Pod）绑定
  ports:
  - name: test # 端口映射策略命名
    port: 80 # 服务端口
    protocol: TCP  # 端口通信协议 TCP/UDP
    targetPort: 80 # 容器端口
  type: LoadBalancer # 服务的类型

Annotation 说明如下表所示。

Key类型是否必须描述默认值是否支持修改

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

Integer

是

配置监听器的带宽峰值，单位为 Mbps。

  • -1：（默认值）此监听器不独占 CLB 的带宽，与其他监听器共享 CLB 实例未被独占的带宽
  • 取值范围：1～CLB 实例未被独占的带宽。 CLB 实例的规格带宽请参见 产品规格。

无

是

配置会话保持

负载均衡服务支持通过 Annotation 配置 CLB 实例的会话保持，示例和说明如下：

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/volcengine-loadbalancer-id: "clb-mim02n8g5kw05smt1b******"
    # 必填，已有负载均衡实例的 ID
    service.beta.kubernetes.io/volcengine-loadbalancer-persistence-timeout: 3600
    # 必填，监听器的会话保持功能
  name: clb-service # 服务的名称
  namespace: default # 服务所属的命名空间
spec:
  externalTrafficPolicy: Cluster
  selector:
    app: nginx # 通过标签选择器将服务与后端容器组（Pod）绑定
  ports:
  - name: test # 端口映射策略命名
    port: 80 # 服务端口
    protocol: TCP  # 端口通信协议 TCP/UDP
    targetPort: 80 # 容器端口
  type: LoadBalancer # 服务的类型

Annotation 说明如下表所示。

Key类型是否必须描述默认值是否支持修改

service.beta.kubernetes.io/volcengine-loadbalancer-persistence-timeout

Integer

是

配置监听器的会话保持功能和超时时间。开启后，将支持基于源 IP 的会话保持能力。取值范围为 0～3600，单位为秒。其中：

  • 取值为 0 时，表示关闭监听器的会话保持功能。
  • 取值为 1～3600 时，表示开启监听器的会话保持功能，并配置超时时间。

无

是

配置健康检查

负载均衡服务支持通过 Annotation 配置监听器的健康检查功能，示例和说明如下：

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/volcengine-loadbalancer-id: "clb-mim02n8g5kw05smt1b******"
    # 必填，已有负载均衡实例的 ID
    service.beta.kubernetes.io/volcengine-loadbalancer-health-check-flag: "on" 
    # 必填，是否开启健康检查
    service.beta.kubernetes.io/volcengine-loadbalancer-health-check-method: "GET"
    # 非必填，健康检查的方法，支持 GET（默认值）、HEAD，仅监听器协议为 HTTP/HTTPS 时支持
    service.beta.kubernetes.io/volcengine-loadbalancer-health-check-domain: "example.com"
    # 非必填，健康检查的域名，支持为空，仅监听器协议为 HTTP/HTTPS 时支持
    service.beta.kubernetes.io/volcengine-loadbalancer-health-check-uri: "/"
    # 非必填，健康检查的路径，仅监听器协议为 HTTP/HTTPS 时支持
    service.beta.kubernetes.io/volcengine-loadbalancer-health-check-http-code: "http_2xx"
    # 非必填，健康检查正常的状态码，仅监听器协议为 HTTP/HTTPS 时支持
    service.beta.kubernetes.io/volcengine-loadbalancer-health-check-connect-timeout: "2" 
    # 非必填，等待健康检查的响应时间
    service.beta.kubernetes.io/volcengine-loadbalancer-health-check-interval: "2" 
    # 非必填，健康检查的时间间隔
    service.beta.kubernetes.io/volcengine-loadbalancer-healthy-threshold: "3" 
    # 非必填，后端服务器正常的健康检查次数
    service.beta.kubernetes.io/volcengine-loadbalancer-unhealthy-threshold: "3" 
    # 非必填，后端服务器异常的健康检查次数
    service.beta.kubernetes.io/volcengine-loadbalancer-health-check-udp-request: "healthcheckrequest"
    # 非必填，配置健康检查的请求字符串，仅监听器协议为 UDP 时支持
    service.beta.kubernetes.io/volcengine-loadbalancer-health-check-udp-expect: "ok"
    # 非必填，配置健康检查的响应字符串，仅监听器协议为 UDP 时支持
  name: clb-service # 服务的名称
  namespace: default # 服务所属的命名空间
spec:
  externalTrafficPolicy: Cluster
  selector:
    app: nginx # 通过标签选择器将服务与后端容器组（Pod）绑定
  ports:
  - name: test # 端口映射策略命名
    port: 80 # 服务端口
    protocol: TCP  # 端口通信协议 TCP/UDP
    targetPort: 80 # 容器端口
  type: LoadBalancer # 服务的类型

Annotation 说明如下表所示。

Key类型是否必须描述默认值是否支持修改

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

String

是

是否开启健康检查。取值：

  • on：开启健康检查。
  • off：不开启健康检查。

off

是

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

String

否

健康检查的方法，仅监听器协议为 HTTP/HTTPS 时支持。取值：

  • GET（默认值）
  • HEAD

GET

是

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

String

否

健康检查的域名，仅监听器协议为 HTTP/HTTPS 时支持。

  • 支持配置为空。配置为空时，系统默认检查后端服务器组内网 IP 地址。
  • 配置不为空时，需输入域名格式的参数，例如example.com。

无

是

service.beta.kubernetes.io/volcengine-loadbalancer-health-check-uriString否健康检查的路径，仅监听器协议为 HTTP/HTTPS 时支持。/是

service.beta.kubernetes.io/volcengine-loadbalancer-health-check-http-code

String

否

健康检查正常的状态码，支持配置多个 HTTP 状态码，多个状态码间用半角逗号,分隔。仅监听器协议为 HTTP/HTTPS 时支持。取值：

  • http_2xx
  • http_3xx
  • http_4xx
  • http_5xx

http_2xx

是

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-health-check-udp-request

String

否

健康检查的请求字符串，仅监听器协议为 UDP 时支持。

  • 必须与volcengine-loadbalancer-health-check-udp-expect同时配置。
  • 只允许包含字母和数字，最大长度限制为 64 个字符。

无

是

service.beta.kubernetes.io/volcengine-loadbalancer-health-check-udp-expect

String

否

健康检查的响应字符串，仅监听器协议为 UDP 时支持。

  • 必须与volcengine-loadbalancer-health-check-udp-request同时配置。
  • 只允许包含字母和数字，最大长度限制为 64 个字符。

无

是

配置访问控制

负载均衡服务支持通过 Annotation 配置监听器的访问控制功能，示例和说明如下：

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/volcengine-loadbalancer-id: "clb-mim02n8g5kw05smt1b******"
    # 必填，已有负载均衡实例的 ID
    service.beta.kubernetes.io/volcengine-loadbalancer-acl-status: "on"
    # 必填，是否开启监听器的访问控制
    service.beta.kubernetes.io/volcengine-loadbalancer-acl-type: "white"
    # 必填，开启访问控制的方式（白名单、黑名单）
    service.beta.kubernetes.io/volcengine-loadbalancer-acl-id: "acl-3cj44nv0jhhxc6c6rrtet****,acl-2febxt4pu0zy85oxruw0t****"
    # 必填，监听器绑定的访问控制策略组 ID
  name: clb-service # 服务的名称
  namespace: default # 服务所属的命名空间
spec:
  externalTrafficPolicy: Cluster
  selector:
    app: nginx # 通过标签选择器将服务与后端容器组（Pod）绑定
  ports:
  - name: test # 端口映射策略命名
    port: 80 # 服务端口
    protocol: TCP  # 端口通信协议 TCP/UDP
    targetPort: 80 # 容器端口
  type: LoadBalancer # 服务的类型

Annotation 说明如下表所示。

Key类型是否必须描述默认值是否支持修改

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

String

是

监听器是否开启访问控制。取值：

  • off：不开启。
  • on：开启。

off

是

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

String

是

监听器开启访问控制的方式。取值：

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

    说明

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

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

    说明

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

black

是

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

String

是

监听器绑定的访问控制策略组（ACL）ID。策略组相关信息，请参见 管理访问控制策略组。
最多支持传入 5 个策略组 ID，多个策略组 ID 间使用英文逗号（,）分隔。

无

是

配置 Proxy Protocol 源 IP 透传

负载均衡服务支持通过 Annotation 配置监听器的 Proxy Protocol 源 IP 透传功能，示例和说明如下：

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/volcengine-loadbalancer-id: "clb-mim02n8g5kw05smt1b******"
    # 必填，已有负载均衡实例的 ID
    service.beta.kubernetes.io/volcengine-loadbalancer-proxy-protocol: "standard"
    # 必填，开启 Proxy Protocol 源 IP 透传
  name: clb-service # 服务的名称
  namespace: default # 服务所属的命名空间
spec:
  externalTrafficPolicy: Cluster
  selector:
    app: nginx # 通过标签选择器将服务与后端容器组（Pod）绑定
  ports:
  - name: test # 端口映射策略命名
    port: 80 # 服务端口
    protocol: TCP  # 端口通信协议 TCP/UDP
    targetPort: 80 # 容器端口
  type: LoadBalancer # 服务的类型

Annotation 说明如下表所示。

Key类型是否必须描述默认值是否支持修改

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

String

是

是否开启 Proxy Protocol 源 IP 透传，取值：

  • standard：开启 proxy protocol 源 IP 透传。
  • off：关闭 proxy protocol 源 IP 透传。

off

是

其他配置

直通 Pod 模式

注意

  • 该配置支持在对接已有 CLB 实例时配置，也支持在创建新的 CLB 实例时配置。本例以对接已有 CLB 实例为例。
  • 仅在 VPC-CNI 网络模型的集群中支持配置为true。修改该字段会导致流量断流，请谨慎操作。
  • 负载均衡服务关联基于弹性容器实例（VCI）方式部署的工作负载时，必须开启直通 Pod 模式，否则会导致服务不可用。

负载均衡服务支持通过 Annotation 配置直通 Pod 模式，示例和说明如下：

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/volcengine-loadbalancer-id: "clb-mim02n8g5kw05smt1b******"
    # 必填，已有负载均衡实例的 ID
    service.beta.kubernetes.io/volcengine-loadbalancer-pass-through: "true"
    # 必填，是否开启负载均衡器直通 Pod 模式
  name: clb-service # 服务的名称
  namespace: default # 服务所属的命名空间
spec:
  externalTrafficPolicy: Cluster
  selector:
    app: nginx # 通过标签选择器将服务与后端容器组（Pod）绑定
  ports:
  - name: test # 端口映射策略命名
    port: 80 # 服务端口
    protocol: TCP  # 端口通信协议 TCP/UDP
    targetPort: 80 # 容器端口
  type: LoadBalancer # 服务的类型

Annotation 说明如下表所示。

Key类型是否必须描述默认值是否支持修改

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

Boolean

是

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

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

false

是

展示公网 CLB 的私网 IP 地址

注意

  • 该配置支持在对接已有 CLB 实例时配置，也支持在创建新的 CLB 实例时配置。本例以对接已有 CLB 实例为例。
  • 该配置仅在 CLB 为公网类型时生效。对于私网类型的 CLB 实例，无论是否配置该参数，均仅允许查看 CLB 实例的私网 IP 地址。
  • 该配置仅支持单栈集群，不支持双栈集群。

负载均衡服务支持通过 Annotation 配置是否展示公网 CLB 的私网 IP 地址，示例和说明如下：

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/volcengine-loadbalancer-id: "clb-mim02n8g5kw05smt1b******"
    # 必填，已有负载均衡实例的 ID
    service.beta.kubernetes.io/volcengine-loadbalancer-display-internal-ip: "true"
    # 必填，是否展示公网 CLB 的私网 IP 地址
  name: clb-service # 服务的名称
  namespace: default # 服务所属的命名空间
spec:
  externalTrafficPolicy: Cluster
  selector:
    app: nginx # 通过标签选择器将服务与后端容器组（Pod）绑定
  ports:
  - name: test # 端口映射策略命名
    port: 80 # 服务端口
    protocol: TCP  # 端口通信协议 TCP/UDP
    targetPort: 80 # 容器端口
  type: LoadBalancer # 服务的类型

Annotation 说明如下表所示。

Key类型是否必须描述默认值是否支持修改

service.beta.kubernetes.io/volcengine-loadbalancer-display-internal-ip

Boolean

是

是否展示公网 CLB 的私网 IP 地址。取值：

  • true：开启。即当 CLB 为公网类型时，展示 CLB 的公网和内网 IP 地址。
  • false：不开启。即当 CLB 为公网类型时，仅展示 CLB 的公网 IP 地址。
  • 未配置该参数时，默认为不开启。即当 CLB 为公网类型时，仅展示 CLB 的公网 IP 地址。

false

是

配置完成后，支持通过控制台或 YAML 配置，查看 CLB 实例的公网和私网 IP 地址。
alt
alt

为负载均衡添加额外标签

注意

  • 该功能支持在新建 CLB 实例时生效，对接已有 CLB 实例时系统会报错。
  • 创建服务时配置该 Annotation，但值为空字符串时，表示清理用户的标签。
  • 创建 CLB 实例时配置的额外标签，不支持通过 Annotation 更新。

负载均衡服务支持通过 Annotation 为负载均衡添加额外标签，示例和说明如下：

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/volcengine-loadbalancer-name: "clb-demo"
    # 非必填，新创建的负载均衡实例名称
    service.beta.kubernetes.io/volcengine-loadbalancer-subnet-id: "subnet-mizw4xqzpssg5smt1b******"
    # 必填，负载均衡实例所属的子网 ID
    service.beta.kubernetes.io/volcengine-loadbalancer-additional-resource-tags: "key1=value1,key2=value2"
    # 必填，为负载均衡添加额外标签
  name: clb-service # 服务的名称
  namespace: default # 服务所属的命名空间
spec:
  externalTrafficPolicy: Cluster
  selector:
    app: nginx # 通过标签选择器将服务与后端容器组（Pod）绑定
  ports:
  - name: test # 端口映射策略命名
    port: 80 # 服务端口
    protocol: TCP  # 端口通信协议 TCP/UDP
    targetPort: 80 # 容器端口
  type: LoadBalancer # 服务的类型

Annotation 说明如下表所示。

Key类型是否必须描述默认值是否支持修改
service.beta.kubernetes.io/volcengine-loadbalancer-additional-resource-tagsString是为负载均衡添加额外标签。值为key=value形式，支持配置多个标签，多个标签之间用英文半角逗号,分隔。无否

配置完成后，您可以登录负载均衡控制台，查看新创建 CLB 实例中的额外标签。

相关文档