使用注解（Annotations）配置负载均衡的高级功能

ELB配置

• 对接ELB
• 会话保持
• 健康检查
• pass-through能力
• 添加资源标签
• 修改自定义EIP

端口/协议配置

• 使用HTTP/HTTPS协议
• 配置服务器名称指示（SNI）
• 使用HTTP/2

ELB监听器高级配置

• 动态调整后端云服务器权重
• 黑名单/白名单设置
• 主机网络
• 设置超时时间
• 配置HTTP/HTTPS头字段
• 开启gzip压缩
• 配置ELB后端优雅退出
• 配置获取客户端IP
• 配置区间端口监听
• 配置IP类型的后端

kubernetes.io/elb.class

String

请根据不同的应用场景和功能需求选择合适的负载均衡器类型。

取值如下：

• union：共享型负载均衡。
• performance：独享型负载均衡，仅支持1.17及以上集群，详情请参见共享型弹性负载均衡与独享型负载均衡的功能区别。

默认取值为union。

v1.9及以上

kubernetes.io/elb.id

String

仅关联已有ELB的场景需填写。

为负载均衡实例的ID。

获取方法：

登录ELB控制台，单击ELB的名称，在ELB详情页的“基本信息”页签下找到“ID”字段复制即可。

v1.9及以上

kubernetes.io/elb.autocreate

表20

仅自动创建ELB的场景：必填。

示例：

• 自动创建公网独享型ELB：

  值为'{"type":"public","bandwidth_name":"cce-bandwidth-1741230802502","bandwidth_chargemode":"bandwidth","bandwidth_size":5,"bandwidth_sharetype":"PER","eip_type":"5_bgp","available_zone":["*****"],"elb_virsubnet_ids":["*****"],"l7_flavor_name":"","l4_flavor_name":"L4_flavor.elb.pro.max","vip_subnet_cidr_id":"*****"}'

• 自动创建私网独享型ELB：

  值为'{"type":"inner","available_zone":["*****"],"elb_virsubnet_ids":["*****"],"l7_flavor_name":"","l4_flavor_name":"L4_flavor.elb.pro.max","vip_subnet_cidr_id":"*****"}'

• 自动创建公网共享型ELB：

  值为 '{"type":"public","bandwidth_name":"cce-bandwidth-1551163379627","bandwidth_chargemode":"bandwidth","bandwidth_size":5,"bandwidth_sharetype":"PER","eip_type":"5_bgp","name":"james"}'

• 自动创建私网共享型ELB：

  值为 '{"type":"inner", "name": "A-location-d-test"}'

v1.9及以上

kubernetes.io/elb.enterpriseID

String

仅自动创建ELB的场景：选填。

v1.15及以上版本的集群支持此字段，v1.15以下版本默认创建到default项目下。

为ELB企业项目ID，选择后可以直接创建在具体的ELB企业项目下。

该字段不传（或传为字符串'0'），则将资源绑定给默认企业项目。

获取方法：

登录企业项目管理控制台，在企业项目列表中单击要加入的企业项目名称，进入企业项目详情页，找到“ID”字段复制即可。

v1.15及以上

kubernetes.io/elb.subnet-id

String

仅自动创建ELB的场景：选填。

为集群所在子网的ID，取值范围：1-100字符。

• Kubernetes v1.11.7-r0及以下版本的集群自动创建时：必填
• Kubernetes v1.11.7-r0以上版本的集群：可不填。

v1.11.7-r0以下必填

v1.11.7-r0以上该字段废弃

kubernetes.io/elb.lb-algorithm

String

后端云服务器组的负载均衡算法，默认值为“ROUND_ROBIN”。

取值范围：

• ROUND_ROBIN：加权轮询算法。
• LEAST_CONNECTIONS：加权最少连接算法。
• SOURCE_IP：源IP算法。

v1.9及以上

kubernetes.io/elb.session-affinity-mode

String

支持基于源IP地址的简单会话保持，即来自同一IP地址的访问请求转发到同一台后端服务器上。

• 不启用：不填写该参数。
• 开启会话保持：需增加该参数，取值“SOURCE_IP”，表示基于源IP地址。

v1.9及以上

kubernetes.io/elb.session-affinity-option

表23

ELB会话保持配置选项，可设置会话保持的超时时间。

v1.9及以上

kubernetes.io/elb.health-check-flag

String

是否开启ELB健康检查功能。

• 开启：“（空值）”或“on”
• 关闭：“off”

开启时需同时填写kubernetes.io/elb.health-check-option或kubernetes.io/elb.health-check-options字段。

v1.9及以上

kubernetes.io/elb.health-check-option

表21

ELB健康检查配置选项。

v1.9及以上

kubernetes.io/elb.health-check-options

表22

ELB健康检查配置选项。支持Service每个端口单独配置，且可以只配置部分端口。

v1.19.16-r5及以上

v1.21.8-r0及以上

v1.23.6-r0及以上

v1.25.2-r0及以上

kubernetes.io/elb.protocol-port

String

Service使用HTTP/HTTPS时，需设置协议及端口号，格式为protocol:port。

其中，

• protocol：为监听器端口对应的协议，取值为http或https。
• ports：为Service的服务端口，即spec.ports[].port指定的端口。

v1.19.16及以上

kubernetes.io/elb.cert-id

String

ELB服务中的证书ID，作为HTTPS服务器证书。

获取方法：登录ELB控制台，选择“证书管理”。在列表中复制对应证书名称下的ID即可。

v1.19.16及以上

kubernetes.io/elb.tls-certificate-ids

String

ELB服务中的SNI证书ID列表（SNI证书中必须带有域名），不同ID间使用英文逗号隔开。

获取方法：登录ELB控制台，选择“证书管理”。在列表中复制对应证书名称下的ID即可。

v1.23.13-r0、v1.25.8-r0、v1.27.5-r0、v1.28.3-r0及以上版本

kubernetes.io/elb.adaptive-weight

String

根据节点上的Pod数量动态调整ELB后端云服务器的权重。每个Pod收到的负载请求更加均衡。

• 开启：true
• 关闭：false

v1.21及以上

kubernetes.io/elb.pass-through

String

集群内访问Service是否经过ELB。

v1.19及以上

kubernetes.io/elb.acl-id

String

• 不填写该参数时：表示CCE不对ELB侧访问控制进行修改。
• 参数值填写为空值时：表示允许所有IP访问。
• 参数值填写为ELB的IP地址组ID时：表示开启访问控制，为ELB设置IP地址黑名单或白名单。此时需同时填写kubernetes.io/elb.acl-status和kubernetes.io/elb.acl-type参数。
  说明：

  v1.25.16-r10、v1.27.16-r10、v1.28.15-r0、v1.29.10-r0、v1.30.6-r0、v1.31.1-r0及以上版本的集群中，使用独享型ELB时可同时填写多个IP地址组，最多同时填写5个，用英文逗号分隔。

  获取方法：

  登录ELB控制台，单击“弹性负载均衡 > IP地址组”，复制目标IP地址组的“ID”即可。详情请参见IP地址组。

v1.23.12-r0、v1.25.7-r0、v1.27.4-r0、v1.28.2-r0及以上

kubernetes.io/elb.acl-status

String

为ELB设置IP地址黑名单或白名单时需填写，取值如下：

• on或true：表示开启访问控制。
• off或false：表示不开启访问控制。

v1.23.12-r0、v1.25.7-r0、v1.27.4-r0、v1.28.2-r0及以上

kubernetes.io/elb.acl-type

String

为ELB设置IP地址黑名单或白名单时需填写，取值如下：

• black：表示黑名单，所选IP地址组无法访问ELB地址。
• white：表示白名单，仅所选IP地址组可以访问ELB地址。

v1.23.12-r0、v1.25.7-r0、v1.27.4-r0、v1.28.2-r0及以上

kubernetes.io/hws-hostNetwork

String

如果Pod使用hostNetwork主机网络，使用该注解后ELB会将请求转发至主机网络。

取值范围：

• 开启：true
• 关闭：false，默认为false

v1.9及以上

kubernetes.io/elb.keepalive_timeout

String

客户端连接空闲超时时间，在超过keepalive_timeout时长一直没有请求， 负载均衡会暂时中断当前连接，直到下一次请求时重新建立新的连接。

取值：

• 若为TCP协议，取值范围为10-4000s，默认值为300s。
• 若为HTTP/HTTPS/TERMINATED_HTTPS监听器，取值范围为0-4000s，默认值为60s。
• 若为UDP协议（仅独享型ELB支持），取值范围为10-4000s，默认值为300s。

独享型ELB：v1.19.16-r30、v1.21.10-r10、v1.23.8-r10、v1.25.3-r10及以上

共享型ELB：v1.23.13-r0、v1.25.8-r0、v1.27.5-r0、v1.28.3-r0及以上版本

kubernetes.io/elb.client_timeout

String

等待客户端请求超时时间，包括两种情况：

• 读取整个客户端请求头的超时时长：如果客户端未在超时时长内发送完整个请求头，则请求将被中断。
• 两个连续body体的数据包到达LB的时间间隔，超出client_timeout将会断开连接。

取值范围为1-300s，默认值为60s。

v1.23.13-r0、v1.25.8-r0、v1.27.5-r0、v1.28.3-r0及以上版本

kubernetes.io/elb.member_timeout

String

等待后端服务器响应超时时间。请求转发后端服务器后，等待超过member_timeout时长没有响应，负载均衡将终止等待，并返回 HTTP504错误码。

取值范围为1-300s，默认值为60s。

v1.23.13-r0、v1.25.8-r0、v1.27.5-r0、v1.28.3-r0及以上版本

kubernetes.io/elb.tags

String

为ELB添加资源标签，仅自动创建ELB时支持设置。

格式为key=value，同时添加多个标签时以英文逗号（,）隔开。

v1.23.11-r0、v1.25.6-r0、v1.27.3-r0及以上

kubernetes.io/elb.http2-enable

String

表示HTTP/2功能的开启状态。开启后，可提升客户端与ELB间的访问性能，但ELB与后端服务器间仍采用HTTP1.X协议。

取值范围：

• true：开启HTTP/2功能；
• false：关闭HTTP/2功能（默认为关闭状态）。

注意：只有当监听器的协议为HTTPS时，才支持开启或关闭HTTP/2功能。当监听器的协议为HTTP时，该字段无效，默认将其设置为false。

v1.23.13-r0、v1.25.8-r0、v1.27.5-r0、v1.28.3-r0及以上版本

kubernetes.io/elb.x-forwarded-port

String

ELB可通过X-Forwarded-Port头字段获取监听器的端口号，传输到后端服务器的报文中。

• true：开启获取监听器端口号开关。
• false：关闭获取监听器端口号开关。

v1.23.13-r0、v1.25.8-r0、v1.27.5-r0、v1.28.3-r0及以上版本

kubernetes.io/elb.x-forwarded-for-port

String

ELB可通过X-Forwarded-For-Port头字段获取客户端请求的端口号，传输到后端服务器的报文中。

• true：开启获取客户端请求端口号开关。
• false：关闭获取客户端请求端口号开关。

kubernetes.io/elb.x-forwarded-host

String

• true：开启重写X-Forwarded-Host开关，ELB以客户端请求头的Host重写X-Forwarded-Host传递到后端服务器。
• false：关闭重写X-Forwarded-Host开关，ELB透传客户端的X-Forwarded-Host到后端服务器。

kubernetes.io/elb.x-real-ip

String

• true：开启重写X-Real-IP开关，ELB以客户端的源IP地址重写X-Real-IP传递到后端服务器
• false：关闭重写X-Real-IP开关，ELB透传客户端的X-Real-IP到后端服务器。

v1.25.16-r30、v1.27.16-r30、v1.28.15-r20、v1.29.13-r0、v1.30.10-r0、v1.31.6-r0、v1.32.1-r0及以上版本

kubernetes.io/elb.gzip-enabled

String

ELB支持开启数据压缩，通过数据压缩可缩小传输文件大小，提升文件传输效率减少带宽消耗。

开启将对特定文件类型进行压缩，关闭则不会对任何文件类型进行压缩。在默认情况下数据压缩为关闭。

支持的压缩类型如下：

• Brotli支持压缩所有类型。
• Gzip支持压缩的类型包括：text/xml text/plain text/css application/javascript application/x-javascript application/rss+xml application/atom+xml application/xml application/json。

仅独享型ELB的HTTP/HTTPS类型监听器支持配置。删除开启数据压缩高级配置或对应的annotation，将不会对ELB侧配置进行修改。

v1.23.14-r0、v1.25.9-r0、v1.27.6-r0、v1.28.4-r0及以上版本

kubernetes.io/elb.connection-drain-enable

String

是否开启ELB后端优雅退出。

• true：开启ELB后端优雅退出。
• false：关闭ELB后端优雅退出。

v1.23.13-r0、v1.25.8-r0、v1.27.5-r0、v1.28.3-r0及以上版本

kubernetes.io/elb.connection-drain-timeout

String

ELB后端优雅退出时间，取值范围为10-4000秒，默认为300秒。

kubernetes.io/elb.transparent-client-ip

String

仅使用共享型ELB创建LoadBalancer类型的服务，且使用TCP/UDP协议时支持配置。

• true：表示开启客户端源IP能力。
• false：表示关闭客户端源IP能力。

v1.23.17-r0、v1.25.12-r0、v1.27.9-r0、v1.28.7-r0、v1.29.3-r0及以上版本

kubernetes.io/elb.custom-eip-id

String

自定义EIP的ID，您可以前往EIP控制台查看。该EIP必须是处于可绑定状态。

v1.23.18-r0、v1.25.13-r0、v1.27.10-r0、v1.28.8-r0、v1.29.4-r0、v1.30.1-r0及以上版本

kubernetes.io/elb.port-ranges

String

使用独享型ELB且选择TCP/UDP/TLS协议时，支持创建某个端口范围的监听器，端口范围1~65535，您最多可为每个监听器添加10个互不重叠的监听端口段。

参数值格式如下，ports_name和port均不允许重复：

 '{"<ports_name_1>":["<port_1>,<port_2>","<port_3>,<port_4>"], "<ports_name_2>":["<port_5>,<port_6>","<port_7>,<port_8>"]}'

例如以下示例表示，端口配置名称为cce-service-0，其监听端口范围为100~200和300~400；端口配置名称为cce-service-1，其监听端口范围为500~600和700~800。

'{"cce-service-0":["100,200", "300,400"], "cce-service-1":["500,600", "700,800"]}'

v1.23.18-r0、v1.25.13-r0、v1.27.10-r0、v1.28.8-r0、v1.29.4-r0、v1.30.1-r0及以上版本

kubernetes.io/elb.ip-target-enabled

String

v1.25.16-r30、v1.27.16-r30、v1.28.15-r20、v1.29.13-r0、v1.30.10-r0、v1.31.6-r0、v1.32.1-r0及以上版本

name

否

String

自动创建的负载均衡的名称。

取值范围：只能由中文、英文字母、数字、下划线、中划线、点组成，且长度范围为1-64个字符。

默认名称：cce-lb+service.UID

type

否

String

负载均衡实例网络类型，公网或者私网。

• public：公网型负载均衡
• inner：私网型负载均衡

默认类型：inner

bandwidth_name

公网型负载均衡必填

String

带宽的名称，默认值为：cce-bandwidth-******。

取值范围：只能由中文、英文字母、数字、下划线、中划线、点组成，且长度范围为1-64个字符。

bandwidth_chargemode

公网型负载均衡必填

String

带宽付费模式。

• bandwidth：按带宽
• traffic：按流量

bandwidth_size

公网型负载均衡必填

Integer

带宽大小，默认1Mbit/s~2000Mbit/s，请根据Region带宽支持范围设置。

bandwidth_sharetype

公网型负载均衡必填

String

带宽共享方式。

• PER：独享带宽

eip_type

公网型负载均衡必填

String

弹性公网IP类型。

• 5_telcom：电信
• 5_union：联通
• 5_bgp：全动态BGP
• 5_sbgp：静态BGP

具体类型以各区域配置为准，详情请参见弹性公网IP控制台。

vip_subnet_cidr_id

否

String

填写子网的IPv4子网ID，指定ELB所在的子网，用于分配ELB实例对外服务的IP地址，该子网必须属于集群所在的VPC。

如不指定，则默认与集群在同一个子网。

仅v1.21及以上版本的集群支持指定该字段。

获取方式：

登录VPC控制台，在左侧导航栏选择“子网”，根据集群所在的VPC名称筛选子网，单击子网名称，在“基本信息”页签下找到“IPv4子网ID”字段复制即可。

ipv6_vip_virsubnet_id

否

String

双栈类型负载均衡器所在IPv6子网的网络ID，需要对应的子网开启IPv6。

独享型负载均衡器独有字段。

获取方式：

登录VPC控制台，在左侧导航栏选择“子网”，根据集群所在的VPC名称筛选子网，单击子网名称，在“基本信息”页签下找到“网络ID”字段复制即可。

elb_virsubnet_ids

否

Array of strings

填写子网的网络ID，指定负载均衡后端所在子网，用于分配与后端服务建立连接的IP地址，不填默认为vip_subnet_cidr_id参数所选的子网。不同实例规格将占用不同数量子网IP，不建议使用其他资源（如集群，节点等）的子网网段。

独享型负载均衡器独有字段。

示例：

"elb_virsubnet_ids": [
   "14567f27-8ae4-42b8-ae47-9f847a4690dd"
 ]

获取方式：

登录VPC控制台，在左侧导航栏选择“子网”，根据集群所在的VPC名称筛选子网，单击子网名称，在“基本信息”页签下找到“网络ID”字段复制即可。

vip_address

否

String

负载均衡器的内网IP。仅支持指定IPv4地址，不支持指定IPv6地址。

该IP必须为ELB所在子网网段中的IP。若不指定，自动从ELB所在子网网段中生成一个IP地址。

仅v1.23.11-r0、v1.25.6-r0、v1.27.3-r0及以上版本集群支持指定该字段。

available_zone

是

Array of strings

负载均衡所在可用区。

可以通过查询可用区列表获取所有支持的可用区。

独享型负载均衡器独有字段。

l4_flavor_name

否

String

四层负载均衡实例规格名称。需要使用TCP、UDP、TLS协议时必填。

可以通过查询规格列表获取所有支持的类型。

独享型负载均衡器独有字段。

l7_flavor_name

否

String

七层负载均衡实例规格名称。使用HTTP协议时必填。

可以通过查询规格列表获取所有支持的类型。

独享型负载均衡器独有字段，必须与l4_flavor_name对应规格的类型一致，即都为弹性规格或都为固定规格。

delay

否

String

健康检查间隔（秒）。

默认值：5，取值范围：1-50

timeout

否

String

健康检查的超时时间（秒）。

默认值：10，取值范围1-50

max_retries

否

String

健康检查的最大重试次数。

默认值：3，取值范围1-10

protocol

否

String

健康检查的协议。

取值范围：“TCP”、“UDP”或者“HTTP”

path

否

String

健康检查的URL，协议是“HTTP”时配置。

默认值：“/”

取值范围：1-80字符

target_service_port

是

String

spec.ports添加健康检查的目标端口，由协议、端口号组成，如：TCP:80

monitor_port

否

String

重新指定的健康检查端口，不指定时默认使用业务端口。

delay

否

String

健康检查间隔（秒）

默认值：5，取值范围：1-50

timeout

否

String

健康检查的超时时间（秒）

默认值：10，取值范围1-50

max_retries

否

String

健康检查的最大重试次数

默认值：3，取值范围1-10

protocol

否

String

健康检查的协议

默认值：取关联服务的协议

取值范围：“TCP”、“UDP”或者“HTTP”

path

否

String

健康检查的URL，协议是“HTTP”时需要配置

默认值：“/”

取值范围：1-80字符

expected_codes

否

String

期望响应状态码，仅v1.19.16-r50、v1.21.11-r10、v1.23.9-r10、v1.25.4-r10、v1.27.1-r10及以上版本的集群支持。

取值：

• 单值：单个返回码，例如"200"。
• 列表：多个特定返回码，例如"200,202"。
• 区间：一个返回码区间，例如"200-204"。

默认值：200，取值范围1-64个字符

仅支持HTTP设置该字段，其他协议设置不会生效。

persistence_timeout

是

String

当elb.session-affinity-mode是“SOURCE_IP”时生效，设置会话保持的超时时间（分钟）。

默认值为："60"，取值范围：1-60。