You need to enable JavaScript to run this app.
文档中心
容器服务

容器服务

请输入
  • 文档首页
    • 容器服务容器服务 VKE用户指南网络服务（Service）负载均衡（LoadBalancer）CLB 负载均衡使用 Annotation 配置 CLB 负载均衡服务
复制全文
下载 pdf
我的收藏
CLB 负载均衡
使用 Annotation 配置 CLB 负载均衡服务
复制全文
下载 pdf
我的收藏
使用 Annotation 配置 CLB 负载均衡服务
服务（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​
ports:​
- name: test​
port: 80​
protocol: TCP​
targetPort: 80​
type: LoadBalancer​
​
Annotation 说明如下表所示。​
​
字段​
类型​
是否必须​
描述​
默认值​
是否支持修改​
service.beta.kubernetes.io/volcengine-loadbalancer-id​
String​
是​
已存在的负载均衡实例 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-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​
ipFamilyPolicy: PreferDualStack # 通信协议类型。SingleStack 表示单栈，PreferDualStack 表示双栈​
ipFamilies: # 具体使用的通信协议。单栈场景支持 IPv4；双栈场景支持 IPv4&IPv6、IPv6&IPv4​
- IPv6​
- IPv4​
selector:​
app: nginx​
ports:​
- name: test​
port: 80​
protocol: TCP​
targetPort: 8​
type: LoadBalancer​
​
Annotation 说明如下表所示。​
​
字段​
类型​
是否必须​
描述​
默认值​
是否支持修改​
service.beta.kubernetes.io/volcengine-loadbalancer-name​
String​
否​
创建的负载均衡实例名称，不指定则自动生成名称。​
无​
否​
service.beta.kubernetes.io/volcengine-loadbalancer-subnet-id​
String​
是​
负载均衡实例所属的子网 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​
String​
否​
负载均衡实例的计费类型。取值：​
  • 2：按量计费-按规格计费。指定实例规格，并按照实例的使用时长计费。​
  • 3：按量计费-按使用量计费。无需指定实例规格，按照实例实际消耗的性能容量计费。​
注意​
  • 按量计费-按使用量计费 为负载均衡产品的邀测功能，如需使用，请联系客户经理申请。​
  • 当负载均衡选择 按量计费-按使用量计费 类型时，无需配置实例规格类型，即loadbalancer-spec参数。​
2​
是​
service.beta.kubernetes.io/volcengine-loadbalancer-eip-billing-type​
String​
否​
公网 IP（EIP）计费类型。取值：​
  • 2：按量计费-按带宽上限，指定带宽上限后，将按照使用时长计费，与实际流量无关。​
  • 3：按量计费-按实际流量，指定带宽上限后，将按照实际使用的出公网流量计费，与使用时长无关。​
3​
否​
service.beta.kubernetes.io/volcengine-loadbalancer-bandwidth​
String​
否​
负载均衡实例的公网带宽峰值，单位为 Mbps，取值：​
  • 当eip-billing-type为 2 时，取值范围为 1～500。​
  • 当eip-billing-type为 3 时，取值范围为 1～200。​
1​
否​
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​
ports:​
- name: test​
port: 80​
protocol: TCP​
targetPort: 80​
type: LoadBalancer​
​
Annotation 说明如下表所示。​
​
字段​
类型​
是否必须​
描述​
默认值​
是否支持修改​
service.beta.kubernetes.io/volcengine-loadbalancer-name​
String​
否​
创建的负载均衡实例名称，不指定则自动生成名称。​
无​
否​
service.beta.kubernetes.io/volcengine-loadbalancer-subnet-id​
String​
是​
负载均衡实例所属的子网 ID。​
无​
否​
service.beta.kubernetes.io/volcengine-loadbalancer-pass-through​
String​
是​
是否开启负载均衡器直通 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​
ports:​
- name: test​
port: 80​
protocol: UDP # 端口通信协议，本例中取值为 UDP，表示创建 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​
ports:​
- name: test ​
port: 80​
protocol: TCP # 端口通信协议，本例中取值为 TCP，表示创建 TCP 协议的监听器​
targetPort: 80​
type: LoadBalancer​
​
创建 HTTP 协议监听器​
注意​
  • 如需配置 HTTP 协议监听器，需升级 cloud-controller-manager 组件至 v1.42.3 及以上版本，详情请参见 升级组件。​
  • 如需配置 HTTP 协议监听器的超时时间：​
  • 需升级 cloud-controller-manager 组件至 v1.50.0 及以上版本，详情请参见 升级组件。​
  • 如果 Service 中同时包含 HTTP 和 TCP 端口，则监听器超时时间的相关配置，只更新 HTTP 监听器。​
  • 删除监听器超时时间相关 Annotation 时，监听器会保留删除前的配置。例如某 Annotation 的默认值为 20 ，用户将其修改为 60 后删除了该 Annotation，系统会保持 60 不变。​
负载均衡服务支持通过 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）和端口号​
service.beta.kubernetes.io/volcengine-loadbalancer-keepalive-timeout: "75" # 非必填，客户端连接空闲超时时间，整数形式，取值范围为 0～900，默认值为 75，单位为秒。取值为 0 时表示禁用客户端长连接​
service.beta.kubernetes.io/volcengine-loadbalancer-client-header-timeout: "60" # 非必填，客户端请求头超时时间，整数形式，取值范围为 30～120，默认值为 60，单位为秒​
service.beta.kubernetes.io/volcengine-loadbalancer-client-body-timeout: "30" # 非必填，客户端请求正文超时时间，整数形式，取值范围为 30～120，默认值为 60，单位为秒​
service.beta.kubernetes.io/volcengine-loadbalancer-send-timeout: "60" # 非必填，客户端转发响应超时时间，整数形式，取值范围为 1～1300，默认值为 60，单位为秒​
service.beta.kubernetes.io/volcengine-loadbalancer-proxy-read-timeout: "60" # 非必填，后端响应超时时间，整数形式，取值范围为 30～3600，默认值为 60，单位为秒​
service.beta.kubernetes.io/volcengine-loadbalancer-proxy-send-timeout: "60" # 非必填，后端转发请求超时时间，整数形式，取值范围为 30～3600，默认值为 60，单位为秒​
service.beta.kubernetes.io/volcengine-loadbalancer-proxy-connect-timeout: "4" # 非必填，后端建连超时时间，整数形式，取值范围为 4～120，默认值为 4，单位为秒​
name: clb-service​
namespace: default​
spec:​
externalTrafficPolicy: Cluster​
selector:​
app: nginx​
ports:​
- name: test​
port: 80​
protocol: TCP​
targetPort: 80​
type: LoadBalancer​
​
Annotation 说明如下表所示。​
​
字段​
类型​
是否必须​
描述​
默认值​
是否支持修改​
service.beta.kubernetes.io/volcengine-loadbalancer-protocol-port​
String​
是​
配置监听器的七层协议和端口号。允许配置多个值，多个值之间用英文半角逗号,分隔，例如https:443,http:80。​
警告​
配置完成后，允许在 YAML 中更新或删除该 Annotation 配置。更新 Annotation 时，系统会删除原监听器，并基于更新后的配置重建监听器。此过程会导致业务中断，请谨慎配置。​
无​
是​
service.beta.kubernetes.io/volcengine-loadbalancer-keepalive-timeout​
String​
否​
客户端与 CLB 之间的长连接超时时间。若在超时时间内一直没有访问请求，CLB 会中断当前连接，直到下一次请求到来时重新建立新的连接。​
  • 整数形式，取值范围为 0～900。​
  • 单位为秒。​
  • 取值为 0 时，表示禁用长连接。​
75​
是​
service.beta.kubernetes.io/volcengine-loadbalancer-client-header-timeout​
String​
否​
读取客户端请求头的超时时间。客户端向 CLB 发起请求，若在超时时间内客户端没有传输整个报头，则 CLB 将返回 408 错误码给客户端，表示请求超时。​
  • 整数形式，取值范围为 30～120。​
  • 单位为秒。​
60​
是​
service.beta.kubernetes.io/volcengine-loadbalancer-client-body-timeout​
String​
否​
读取客户端请求正文的超时时间。客户端向 CLB 发起请求，若在超时时间内客户端没有发送任何请求体，则 CLB 将返回 408 错误码给客户端，表示请求超时。​
  • 整数形式，取值范围为 30～120。​
  • 单位为秒。​
  • 此超时仅针对两个连续的写操作之间设置，而非整响应的传输过程。​
60​
是​
service.beta.kubernetes.io/volcengine-loadbalancer-send-timeout​
String​
否​
CLB 向客户端发送响应的超时时间。CLB 向客户端发送响应，若客户端在超时时间内未收到任何内容，则连接会被关闭。​
  • 整数形式，取值范围为 1～3600。​
  • 单位为秒。​
  • 此超时仅针对两个连续的写操作之间设置，而非整响应的传输过程。​
60​
是​
service.beta.kubernetes.io/volcengine-loadbalancer-proxy-read-timeout​
String​
否​
CLB 从后端服务器读取响应的超时时间。CLB 向后端服务器发起请求，若超时时间内接收请求的后端服务器无响应，则会关闭此连接。​
  • 整数形式，取值范围为 30～3600。​
  • 单位为秒。​
  • 此超时仅针对两个连续的写操作之间设置，而非整响应的传输过程。​
60​
是​
service.beta.kubernetes.io/volcengine-loadbalancer-proxy-send-timeout​
String​
否​
CLB 将请求传输到后端服务器的超时时间。CLB 向后端服务器发起请求，若后端服务器在超时时间内未收到任何内容，则会关闭此连接。​
  • 整数形式，取值范围为 30～3600。​
  • 单位为秒。​
  • 此超时仅针对两个连续的写操作之间设置，而非整响应的传输过程。​
60​
是​
service.beta.kubernetes.io/volcengine-loadbalancer-proxy-connect-timeout​
String​
否​
CLB 与后端服务器之间的连接建立超时时间。若超时时间内 CLB 与后端服务器连接未建立，则终止建立连接操作。​
  • 整数形式，取值范围为 4～120。​
  • 单位为秒。​
  • 建议大于健康检查超时时间。​
4​
是​
​
创建 HTTPS 协议监听器​
注意​
  • 如需配置 HTTPS 协议监听器，需升级 cloud-controller-manager 组件至 v1.42.3 及以上版本，详情请参见 升级组件。​
  • 如需配置 HTTP 协议监听器的超时时间：​
  • 需升级 cloud-controller-manager 组件至 v1.50.0 及以上版本，详情请参见 升级组件。​
  • 如果 Service 中同时包含 HTTPS 和 TCP 端口，则超时时间的相关配置，只更新 HTTPS 监听器。​
  • 删除监听器超时时间相关 Annotation 时，监听器会保留删除前的配置。例如某 Annotation 的默认值为 20 ，用户将其修改为 60 后删除了该 Annotation，系统会保持 60 不变。​
  • 创建 HTTPS 协议监听器前，请首先登录您的火山引擎账号，然后单击 服务授权，并在弹出的页面中单击 立即授权，完成跨服务授权。​
  • 当您配置 HTTPS 监听器时，需要注意：​
  • 使用loadbalancer-protocol-port配置的端口号（本例中为443），必须在spec.ports字段中声明，同时配置对应端口的spec.ports.protocol字段为TCP。​
  • 如果配置的端口号（本例中为443），未在spec.ports字段中声明，则 Annotation 中指定的HTTP：443会被忽视。​
  • 如果声明了配置的端口号，但spec.ports.protocol字段为UDP，则 Annotation 中指定的HTTPS：443会被忽视。​
负载均衡服务支持通过 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​
service.beta.kubernetes.io/volcengine-loadbalancer-keepalive-timeout: "75" # 非必填，客户端连接空闲超时时间，整数形式，取值范围为 0～900，默认值为 75，单位为秒。取值为 0 时表示禁用客户端长连接​
service.beta.kubernetes.io/volcengine-loadbalancer-client-header-timeout: "60" # 非必填，客户端请求头超时时间，整数形式，取值范围为 30～120，默认值为 60，单位为秒​
service.beta.kubernetes.io/volcengine-loadbalancer-client-body-timeout: "30" # 非必填，客户端请求正文超时时间，整数形式，取值范围为 30～120，默认值为 60，单位为秒​
service.beta.kubernetes.io/volcengine-loadbalancer-send-timeout: "60" # 非必填，客户端转发响应超时时间，整数形式，取值范围为 1～1300，默认值为 60，单位为秒​
service.beta.kubernetes.io/volcengine-loadbalancer-proxy-read-timeout: "60" # 非必填，后端响应超时时间，整数形式，取值范围为 30～3600，默认值为 60，单位为秒​
service.beta.kubernetes.io/volcengine-loadbalancer-proxy-send-timeout: "60" # 非必填，后端转发请求超时时间，整数形式，取值范围为 30～3600，默认值为 60，单位为秒​
service.beta.kubernetes.io/volcengine-loadbalancer-proxy-connect-timeout: "4" # 非必填，后端建连超时时间，整数形式，取值范围为 4～120，默认值为 4，单位为秒​
name: clb-service​
namespace: default​
spec:​
externalTrafficPolicy: Cluster​
selector:​
app: nginx​
ports:​
- name: test​
port: 443​
protocol: TCP​
targetPort: 443​
type: LoadBalancer​
​
Annotation 说明如下表所示。​
​
字段​
类型​
是否必须​
描述​
默认值​
是否支持修改​
service.beta.kubernetes.io/volcengine-loadbalancer-protocol-port​
String​
是​
配置监听器的七层协议和端口号。允许配置多个值，多个值之间用英文半角逗号,分隔，例如https:443,http:80。​
警告​
配置完成后，允许在 YAML 中更新或删除该 Annotation 配置。更新 Annotation 时，系统会删除原监听器，并基于更新后的配置重建监听器。此过程会导致业务中断，请谨慎配置。​
无​
是​
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 不合法，会导致创建监听器失败。​
无​
是​
service.beta.kubernetes.io/volcengine-loadbalancer-keepalive-timeout​
String​
否​
客户端与 CLB 之间的长连接超时时间。若在超时时间内一直没有访问请求，CLB 会中断当前连接，直到下一次请求到来时重新建立新的连接。​
  • 整数形式，取值范围为 0～900。​
  • 单位为秒。​
  • 取值为 0 时，表示禁用长连接。​
75​
是​
service.beta.kubernetes.io/volcengine-loadbalancer-client-header-timeout​
String​
否​
读取客户端请求头的超时时间。客户端向 CLB 发起请求，若在超时时间内客户端没有传输整个报头，则 CLB 将返回 408 错误码给客户端，表示请求超时。​
  • 整数形式，取值范围为 30～120。​
  • 单位为秒。​
60​
是​
service.beta.kubernetes.io/volcengine-loadbalancer-client-body-timeout​
String​
否​
读取客户端请求正文的超时时间。客户端向 CLB 发起请求，若在超时时间内客户端没有发送任何请求体，则 CLB 将返回 408 错误码给客户端，表示请求超时。​
  • 整数形式，取值范围为 30～120。​
  • 单位为秒。​
  • 此超时仅针对两个连续的写操作之间设置，而非整响应的传输过程。​
60​
是​
service.beta.kubernetes.io/volcengine-loadbalancer-send-timeout​
String​
否​
CLB 向客户端发送响应的超时时间。CLB 向客户端发送响应，若客户端在超时时间内未收到任何内容，则连接会被关闭。​
  • 整数形式，取值范围为 1～3600。​
  • 单位为秒。​
  • 此超时仅针对两个连续的写操作之间设置，而非整响应的传输过程。​
60​
是​
service.beta.kubernetes.io/volcengine-loadbalancer-proxy-read-timeout​
String​
否​
CLB 从后端服务器读取响应的超时时间。CLB 向后端服务器发起请求，若超时时间内接收请求的后端服务器无响应，则会关闭此连接。​
  • 整数形式，取值范围为 30～3600。​
  • 单位为秒。​
  • 此超时仅针对两个连续的写操作之间设置，而非整响应的传输过程。​
60​
是​
service.beta.kubernetes.io/volcengine-loadbalancer-proxy-send-timeout​
String​
否​
CLB 将请求传输到后端服务器的超时时间。CLB 向后端服务器发起请求，若后端服务器在超时时间内未收到任何内容，则会关闭此连接。​
  • 整数形式，取值范围为 30～3600。​
  • 单位为秒。​
  • 此超时仅针对两个连续的写操作之间设置，而非整响应的传输过程。​
60​
是​
service.beta.kubernetes.io/volcengine-loadbalancer-proxy-connect-timeout​
String​
否​
CLB 与后端服务器之间的连接建立超时时间。若超时时间内 CLB 与后端服务器连接未建立，则终止建立连接操作。​
  • 整数形式，取值范围为 4～120。​
  • 单位为秒。​
  • 建议大于健康检查超时时间。​
4​
是​
​
配置调度算法​
负载均衡服务支持通过 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​
ports:​
- name: test​
port: 80​
protocol: TCP ​
targetPort: 80​
type: LoadBalancer​
​
Annotation 说明如下表所示。​
​
字段​
类型​
是否必须​
描述​
默认值​
是否支持修改​
service.beta.kubernetes.io/volcengine-loadbalancer-scheduler​
String​
是​
配置监听器的调度算法。取值：​
  • wrr：加权轮询。权重值越高的后端服务器，被轮询到的次数（概率）越高。​
  • wlc：加权最小连接数。将请求分发给当前连接/权重比值最小的后端服务器。​
  • sh：源地址哈希。基于源 IP 地址的一致性哈希，相同的源地址会调度到相同的后端服务器。​
无​
是​
​
配置超时时间​
说明​
仅 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​
ports:​
- name: test​
port: 80​
protocol: TCP​
targetPort: 80​
type: LoadBalancer​
​
Annotation 说明如下表所示。​
​
字段​
类型​
是否必须​
描述​
默认值​
是否支持修改​
service.beta.kubernetes.io/volcengine-loadbalancer-established-timeout​
String​
是​
配置监听器的连接超时时间，当前仅针对 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​
ports:​
- name: test​
port: 80​
protocol: TCP​
targetPort: 80​
type: LoadBalancer​
​
Annotation 说明如下表所示。​
​
字段​
类型​
是否必须​
描述​
默认值​
是否支持修改​
service.beta.kubernetes.io/volcengine-loadbalancer-listener-bandwidth​
String​
是​
配置监听器的带宽峰值，单位为 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​
ports:​
- name: test​
port: 80​
protocol: TCP​
targetPort: 80​
type: LoadBalancer​
​
Annotation 说明如下表所示。​
​
字段​
类型​
是否必须​
描述​
默认值​
是否支持修改​
service.beta.kubernetes.io/volcengine-loadbalancer-persistence-timeout​
String​
是​
配置监听器的会话保持功能和超时时间。开启后，将支持基于源 IP 的会话保持能力。取值范围为 0～3600，单位为秒。其中：​
  • 取值为 0 时，表示关闭监听器的会话保持功能。​
  • 取值为 1～3600 时，表示开启监听器的会话保持功能，并配置超时时间。​
无​
是​
​
配置健康检查​
配置 TCP 健康检查​
负载均衡服务支持通过 Annotation 配置 TCP 协议监听器的健康检查功能，示例和说明如下：​
​
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-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" # 非必填，后端服务器异常的健康检查次数​
name: clb-service​
namespace: default​
spec:​
externalTrafficPolicy: Cluster​
selector:​
app: nginx​
ports:​
- name: test​
port: 80​
protocol: TCP # 端口通信协议，本例中取值为 TCP，表示创建 TCP 协议的监听器​
targetPort: 80​
type: LoadBalancer​
​
Annotation 说明如下表所示。​
​
字段​
类型​
是否必须​
描述​
默认值​
是否支持修改​
service.beta.kubernetes.io/volcengine-loadbalancer-health-check-flag​
String​
是​
是否开启健康检查。取值：​
  • on：开启。​
  • off：关闭。​
无​
是​
service.beta.kubernetes.io/volcengine-loadbalancer-health-check-interval​
String​
否​
健康检查的时间间隔。​
  • 取值范围：1～300​
  • 单位：秒​
2​
是​
service.beta.kubernetes.io/volcengine-loadbalancer-health-check-connect-timeout​
String​
否​
健康检查的超时时间。​
  • 取值范围：1～60​
  • 单位：秒​
2​
是​
service.beta.kubernetes.io/volcengine-loadbalancer-healthy-threshold​
String​
否​
健康检查连续成功多少次后，将后端服务器的健康检查状态由 Fail 判定为 Success。​
  • 取值范围：3～10​
  • 单位：次​
3​
是​
service.beta.kubernetes.io/volcengine-loadbalancer-unhealthy-threshold​
String​
否​
健康检查连续失败多少次后，将后端服务器的健康检查状态由 Success 判定为 Fail。​
  • 取值范围：3～10​
  • 单位：次​
3​
是​
​
配置 UDP 健康检查​
负载均衡服务支持通过 Annotation 配置 UDP 协议监听器的健康检查功能，示例和说明如下：​
​
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-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​
ports:​
- name: test​
port: 80​
protocol: UDP # 端口通信协议，本例中取值为 UDP，表示创建 UDP 协议的监听器​
targetPort: 80​
type: LoadBalancer​
​
Annotation 说明如下表所示。​
​
字段​
类型​
是否必须​
描述​
默认值​
是否支持修改​
service.beta.kubernetes.io/volcengine-loadbalancer-health-check-flag​
String​
是​
是否开启健康检查。取值：​
  • on：开启。​
  • off：关闭。​
无​
是​
service.beta.kubernetes.io/volcengine-loadbalancer-health-check-interval​
String​
否​
健康检查的时间间隔。​
  • 取值范围：1～300​
  • 单位：秒​
2​
是​
service.beta.kubernetes.io/volcengine-loadbalancer-health-check-connect-timeout​
String​
否​
健康检查的超时时间。​
  • 取值范围：1～60​
  • 单位：秒​
2​
是​
service.beta.kubernetes.io/volcengine-loadbalancer-healthy-threshold​
String​
否​
健康检查连续成功多少次后，将后端服务器的健康检查状态由 Fail 判定为 Success。​
  • 取值范围：3～10​
  • 单位：次​
3​
是​
service.beta.kubernetes.io/volcengine-loadbalancer-unhealthy-threshold​
String​
否​
健康检查连续失败多少次后，将后端服务器的健康检查状态由 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 个字符。​
无​
是​
​
配置 HTTP 健康检查​
注意​
需升级 cloud-controller-manager 组件至 v1.42.3 及以上版本，详情请参见 升级组件。​
负载均衡服务支持通过 Annotation 配置 HTTP 协议监听器的健康检查功能，示例和说明如下：​
​
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-protocol-port: "HTTP:80" # 必填，配置七层协议监听器，包括协议（HTTP、HTTPS）和端口号​
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" # 非必填，后端服务器异常的健康检查次数​
name: clb-service​
namespace: default​
spec:​
externalTrafficPolicy: Cluster​
selector:​
app: nginx​
ports:​
- name: test​
port: 80​
protocol: TCP # 端口通信协议，配置 HTTP 健康检查时，该配置必须为 TCP​
targetPort: 80​
type: LoadBalancer​
​
Annotation 说明如下表所示。​
​
字段​
类型​
是否必须​
描述​
默认值​
是否支持修改​
service.beta.kubernetes.io/volcengine-loadbalancer-health-check-flag​
String​
是​
是否开启健康检查。取值：​
  • on：开启。​
  • off：关闭。​
无​
是​
service.beta.kubernetes.io/volcengine-loadbalancer-protocol-port​
String​
是​
配置监听器的七层协议和端口号。允许配置多个值，多个值之间用英文半角逗号,分隔，例如http:80,http:8080。​
无​
是​
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-uri​
String​
否​
健康检查的路径，仅监听器协议为 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​
String​
否​
健康检查的时间间隔。​
  • 取值范围：1～300​
  • 单位：秒​
2​
是​
service.beta.kubernetes.io/volcengine-loadbalancer-health-check-connect-timeout​
String​
否​
健康检查的超时时间。​
  • 取值范围：1～60​
  • 单位：秒​
2​
是​
service.beta.kubernetes.io/volcengine-loadbalancer-healthy-threshold​
String​
否​
健康检查连续成功多少次后，将后端服务器的健康检查状态由 Fail 判定为 Success。​
  • 取值范围：3～10​
  • 单位：次​
3​
是​
service.beta.kubernetes.io/volcengine-loadbalancer-unhealthy-threshold​
String​
否​
健康检查连续失败多少次后，将后端服务器的健康检查状态由 Success 判定为 Fail。​
  • 取值范围：3～10​
  • 单位：次​
3​
是​
​
配置 HTTPS 健康检查​
注意​
  • 需升级 cloud-controller-manager 组件至 v1.42.3 及以上版本，详情请参见 升级组件。​
  • 创建 HTTPS 协议监听器前，请首先登录您的火山引擎账号，然后单击 服务授权，并在弹出的页面中单击 立即授权，完成跨服务授权。​
  • 当您配置 HTTPS 监听器时，需要注意：​
  • 使用loadbalancer-protocol-port配置的端口号（本例中为443），必须在spec.ports字段中声明，同时配置对应端口的spec.ports.protocol字段为TCP。​
  • 如果配置的端口号（本例中为443），未在spec.ports字段中声明，则 Annotation 中指定的HTTP：443会被忽视。​
  • 如果声明了配置的端口号，但spec.ports.protocol字段为UDP，则 Annotation 中指定的HTTPS：443会被忽视。​
负载均衡服务支持通过 Annotation 配置 HTTPS 协议监听器的健康检查功能，示例和说明如下：​
​
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-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-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" # 非必填，后端服务器异常的健康检查次数​
name: clb-service​
namespace: default​
spec:​
externalTrafficPolicy: Cluster​
selector:​
app: nginx​
ports:​
- name: test​
port: 443​
protocol: TCP # 端口通信协议，配置 HTTP 健康检查时，该配置必须为 TCP​
targetPort: 443​
type: LoadBalancer​
​
Annotation 说明如下表所示。​
​
字段​
类型​
是否必须​
描述​
默认值​
是否支持修改​
service.beta.kubernetes.io/volcengine-loadbalancer-health-check-flag​
String​
是​
是否开启健康检查。取值：​
  • on：开启。​
  • off：关闭。​
无​
是​
service.beta.kubernetes.io/volcengine-loadbalancer-protocol-port​
String​
是​
配置监听器的七层协议和端口号。允许配置多个值，多个值之间用英文半角逗号,分隔，例如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-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-uri​
String​
否​
健康检查的路径，仅监听器协议为 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​
String​
否​
健康检查的时间间隔。​
  • 取值范围：1～300​
  • 单位：秒​
2​
是​
service.beta.kubernetes.io/volcengine-loadbalancer-health-check-connect-timeout​
String​
否​
健康检查的超时时间。​
  • 取值范围：1～60​
  • 单位：秒​
2​
是​
service.beta.kubernetes.io/volcengine-loadbalancer-healthy-threshold​
String​
否​
健康检查连续成功多少次后，将后端服务器的健康检查状态由 Fail 判定为 Success。​
  • 取值范围：3～10​
  • 单位：次​
3​
是​
service.beta.kubernetes.io/volcengine-loadbalancer-unhealthy-threshold​
String​
否​
健康检查连续失败多少次后，将后端服务器的健康检查状态由 Success 判定为 Fail。​
  • 取值范围：3～10​
  • 单位：次​
3​
是​
​
配置访问控制​
负载均衡服务支持通过 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" # 必填，访问控制方式，取值：white（白名单）、black（黑名单）​
service.beta.kubernetes.io/volcengine-loadbalancer-acl-id: "acl-3cj44nv0jhhxc6c6rrtet****,acl-2febxt4pu0zy85oxruw0t****" # 必填，监听器绑定的访问控制策略组 ID​
name: clb-service​
namespace: default​
spec:​
externalTrafficPolicy: Cluster​
selector:​
app: nginx​
ports:​
- name: test​
port: 80​
protocol: TCP​
targetPort: 80​
type: LoadBalancer​
​
Annotation 说明如下表所示。​
​
字段​
类型​
是否必须​
描述​
默认值​
是否支持修改​
service.beta.kubernetes.io/volcengine-loadbalancer-acl-status​
String​
是​
监听器是否开启访问控制。取值：​
  • on：开启。​
  • off：关闭。​
无​
是​
service.beta.kubernetes.io/volcengine-loadbalancer-acl-type​
String​
是​
监听器开启访问控制的方式。取值：​
  • black：黑名单方式。表示仅拒绝来自所选访问控制策略组中设置的 IP 地址或地址段的请求。​
说明​
如果所选策略组中没有添加 IP，则监听器会转发所有请求。​
  • white：白名单方式。表示监听器仅转发来自所选访问控制策略组中设置的 IP 地址或地址段的请求。​
说明​
如果所选策略组中没有添加 IP，则监听器不会转发任何请求。​
无​
是​
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​
ports:​
- name: test​
port: 80​
protocol: TCP​
targetPort: 80​
type: LoadBalancer​
​
Annotation 说明如下表所示。​
​
字段​
类型​
是否必须​
描述​
默认值​
是否支持修改​
service.beta.kubernetes.io/volcengine-loadbalancer-proxy-protocol​
String​
是​
是否开启 Proxy Protocol 源 IP 透传，取值：​
  • standard：开启。​
  • off：关闭。​
无​
是​
​
配置连接优雅中断​
说明​
需升级 cloud-controller-manager 组件至 v1.43.0 及以上版本。详情请参见 升级组件。​
负载均衡服务支持通过 Annotation 配置监听器的连接优雅中断功能。开启该功能后，当后端服务器被删除、健康检查异常时，现有连接在优雅中断的超时时间内依然能够正常传输。示例和说明如下：​
​
apiVersion: v1​
kind: Service​
metadata:​
annotations:​
service.beta.kubernetes.io/volcengine-loadbalancer-id: "clb-mim02n8g5kw05smt1b******" # 必填，已有负载均衡实例的 ID​
service.beta.kubernetes.io/volcengine-loadbalancer-connection-drain: "on" # 必填，是否开启连接优雅中断，取值：on、off​
service.beta.kubernetes.io/volcengine-loadbalancer-connection-drain-timeout: "100" # 开启连接优雅中断时必填，配置优雅中断的超时时间​
name: clb-service​
namespace: default​
spec:​
externalTrafficPolicy: Cluster​
selector:​
app: nginx​
ports:​
- name: test​
port: 80​
protocol: TCP​
targetPort: 80​
type: LoadBalancer​
​
Annotation 说明如下表所示。​
​
字段​
类型​
是否必须​
描述​
默认值​
是否支持修改​
service.beta.kubernetes.io/volcengine-loadbalancer-connection-drain​
String​
是​
是否开启连接优雅中断。取值：​
  • on：开启。​
  • off：关闭。​
无​
是​
service.beta.kubernetes.io/volcengine-loadbalancer-connection-drain-timeout​
String​
否​
连接优雅中断超时时间。整数形式，取值范围为 0～900，单位为秒。​
取值为 0 时，表示后端服务器被删除、健康检查异常时，立刻发送 Reset 报文，终止连接。​
说明​
当开启连接优雅中断时，该参数必填。​
无​
是​
​
其他配置​
直通 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​
ports:​
- name: test​
port: 80​
protocol: TCP​
targetPort: 80​
type: LoadBalancer​
​
Annotation 说明如下表所示。​
​
Key​
类型​
是否必须​
描述​
默认值​
是否支持修改​
service.beta.kubernetes.io/volcengine-loadbalancer-pass-through​
String​
是​
是否开启负载均衡器直通 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​
ports:​
- name: test​
port: 80​
protocol: TCP​
targetPort: 80​
type: LoadBalancer # 服务的类型​
​
Annotation 说明如下表所示。​
​
Key​
类型​
是否必须​
描述​
默认值​
是否支持修改​
service.beta.kubernetes.io/volcengine-loadbalancer-display-internal-ip​
String​
是​
是否展示公网 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-tags​
String​
是​
为负载均衡添加额外标签。值为key=value形式，支持配置多个标签，多个标签之间用英文半角逗号,分隔。​
无​
否​
​
配置完成后，您可以登录负载均衡控制台，查看新创建 CLB 实例中的额外标签。​
相关文档​
​
最近更新时间：2026.08.18 18:00:54
这个页面对您有帮助吗？
有用
有用
无用
无用