使用Annotation配置负载均衡类型的服务
通过在YAML中添加注解Annotation(注解),您可以实现CCE提供的一些高级功能。本文介绍在创建LoadBalancer类型的Service时可供使用的Annotation。
- 对接ELB
- 会话保持
- 健康检查
- 使用HTTP/HTTPS协议
- 配置服务器名称指示(SNI)
- 动态调整后端云服务器权重
- 跨集群访问
- pass-through能力
- 黑名单/白名单设置
- 主机网络
- 设置超时时间
- 添加资源标签
- 使用HTTP/2
- 开启gzip压缩
- 配置ELB后端优雅退出
- 配置获取客户端IP
- 配置自定义EIP
- 配置区间端口监听
对接ELB
参数 |
类型 |
描述 |
支持的集群版本 |
---|---|---|---|
kubernetes.io/elb.class |
String |
请根据不同的应用场景和功能需求选择合适的负载均衡器类型。 取值如下:
|
v1.9及以上 |
kubernetes.io/elb.id |
String |
仅关联已有ELB的场景:必填。 为负载均衡实例的ID。 获取方法: 在控制台的“服务列表”中,单击“网络 > 弹性负载均衡 ELB”,单击ELB的名称,在ELB详情页的“基本信息”页签下找到“ID”字段复制即可。
说明:
系统优先根据kubernetes.io/elb.id注解对接ELB,若此字段未指定,则会根据spec.loadBalancerIP字段(非必填,且仅1.23及以前版本可用)对接ELB。 请尽量不要使用spec.loadBalancerIP字段对接ELB,该字段在将来的集群版本中会被Kubernetes官方废弃,详情请参见Deprecation。 |
v1.9及以上 |
kubernetes.io/elb.autocreate |
仅自动创建ELB的场景:必填。 示例: |
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字符。
|
v1.11.7-r0以下必填 v1.11.7-r0以上该字段废弃 |
kubernetes.io/elb.lb-algorithm |
String |
后端云服务器组的负载均衡算法,默认值为“ROUND_ROBIN”。 取值范围:
说明:
当该字段的取值为SOURCE_IP时,后端云服务器组绑定的后端云服务器的权重设置(weight字段)无效,且不支持开启会话保持。 |
v1.9及以上 |
上述注解的使用方法如下:
- 关联已有ELB场景:详情请参见通过kubectl命令行创建-使用已有ELB
apiVersion: v1 kind: Service metadata: name: nginx annotations: kubernetes.io/elb.id: <your_elb_id> # ELB ID,替换为实际值 kubernetes.io/elb.class: performance # 负载均衡器类型 kubernetes.io/elb.lb-algorithm: ROUND_ROBIN # 负载均衡器算法 spec: selector: app: nginx ports: - name: service0 port: 80 protocol: TCP targetPort: 80 type: LoadBalancer
- 自动创建ELB场景:详情请参见通过kubectl命令行创建-自动创建ELB
共享型负载均衡:
apiVersion: v1 kind: Service metadata: annotations: kubernetes.io/elb.class: union kubernetes.io/elb.autocreate: '{ "type": "public", "bandwidth_name": "cce-bandwidth-1551163379627", "bandwidth_chargemode": "bandwidth", "bandwidth_size": 5, "bandwidth_sharetype": "PER", "eip_type": "5_bgp" }' kubernetes.io/elb.enterpriseID: '0' # 负载均衡所属企业项目ID kubernetes.io/elb.lb-algorithm: ROUND_ROBIN # 负载均衡器算法 labels: app: nginx name: nginx spec: ports: - name: service0 port: 80 protocol: TCP targetPort: 80 selector: app: nginx type: LoadBalancer
独享型负载均衡:apiVersion: v1 kind: Service metadata: name: nginx labels: app: nginx namespace: default annotations: kubernetes.io/elb.class: performance kubernetes.io/elb.autocreate: '{ "type": "public", "bandwidth_name": "cce-bandwidth-1626694478577", "bandwidth_chargemode": "bandwidth", "bandwidth_size": 5, "bandwidth_sharetype": "PER", "eip_type": "5_bgp", "available_zone": [ "cn-north-4b" ], "l4_flavor_name": "L4_flavor.elb.s1.small" }' kubernetes.io/elb.enterpriseID: '0' # 负载均衡所属企业项目ID kubernetes.io/elb.lb-algorithm: ROUND_ROBIN # 负载均衡器算法 spec: selector: app: nginx ports: - name: cce-service-0 targetPort: 80 nodePort: 0 port: 80 protocol: TCP type: LoadBalancer
会话保持
参数 |
类型 |
描述 |
支持的集群版本 |
---|---|---|---|
kubernetes.io/elb.session-affinity-mode |
String |
支持基于源IP地址的简单会话保持,即来自同一IP地址的访问请求转发到同一台后端服务器上。
说明:
当kubernetes.io/elb.lb-algorithm设置为“SOURCE_IP”(源IP算法)时,不支持开启会话保持。 |
v1.9及以上 |
kubernetes.io/elb.session-affinity-option |
ELB会话保持配置选项,可设置会话保持的超时时间。 |
v1.9及以上 |
apiVersion: v1 kind: Service metadata: name: nginx annotations: kubernetes.io/elb.id: <your_elb_id> # ELB ID,替换为实际值 kubernetes.io/elb.class: performance # 负载均衡器类型 kubernetes.io/elb.session-affinity-mode: SOURCE_IP # 会话保持类型为源IP kubernetes.io/elb.session-affinity-option: '{"persistence_timeout": "30"}' # 会话保持时间(分钟) spec: selector: app: nginx ports: - name: service0 port: 80 protocol: TCP targetPort: 80 type: LoadBalancer
健康检查
参数 |
类型 |
描述 |
支持的集群版本 |
---|---|---|---|
kubernetes.io/elb.health-check-flag |
String |
是否开启ELB健康检查功能。
开启时需同时填写kubernetes.io/elb.health-check-option字段。 |
v1.9及以上 |
kubernetes.io/elb.health-check-option |
ELB健康检查配置选项。 |
v1.9及以上 |
|
kubernetes.io/elb.health-check-options |
ELB健康检查配置选项。支持Service每个端口单独配置,且可以只配置部分端口。
说明:
不允许同时配置 "kubernetes.io/elb.health-check-option" 和 "kubernetes.io/elb.health-check-options"。 |
v1.19.16-r5及以上 v1.21.8-r0及以上 v1.23.6-r0及以上 v1.25.2-r0及以上 |
- kubernetes.io/elb.health-check-option的使用方法如下:
apiVersion: v1 kind: Service metadata: name: nginx annotations: kubernetes.io/elb.id: <your_elb_id> # ELB ID,替换为实际值 kubernetes.io/elb.class: performance # 负载均衡器类型 kubernetes.io/elb.health-check-flag: 'on' # 开启ELB健康检查功能 kubernetes.io/elb.health-check-option: '{ "protocol":"TCP", "delay":"5", "timeout":"10", "max_retries":"3" }' spec: selector: app: nginx ports: - name: service0 port: 80 protocol: TCP targetPort: 80 type: LoadBalancer
- kubernetes.io/elb.health-check-options的使用方法请参见为负载均衡类型的Service指定多个端口配置健康检查。
使用HTTP/HTTPS协议
参数 |
类型 |
描述 |
支持的集群版本 |
---|---|---|---|
kubernetes.io/elb.protocol-port |
String |
Service使用HTTP/HTTPS时,需设置协议及端口号,格式为protocol:port。 其中,
|
v1.19.16及以上 |
kubernetes.io/elb.cert-id |
String |
ELB服务中的证书ID,作为HTTPS服务器证书。 获取方法:在CCE控制台,单击顶部的“服务列表 > 网络 > 弹性负载均衡”,并选择“证书管理”。在列表中复制对应证书名称下的ID即可。 |
v1.19.16及以上 |
具体使用场景和说明请参见为负载均衡类型的Service配置HTTP/HTTPS协议。
配置服务器名称指示(SNI)
参数 |
类型 |
描述 |
支持的集群版本 |
---|---|---|---|
kubernetes.io/elb.tls-certificate-ids |
String |
ELB服务中的SNI证书ID列表(SNI证书中必须带有域名),不同ID间使用英文逗号隔开。 获取方法:在CCE控制台,单击顶部的“服务列表 > 网络 > 弹性负载均衡”,并选择“证书管理”。在列表中复制对应证书名称下的ID即可。 |
v1.23.13-r0、v1.25.8-r0、v1.27.5-r0、v1.28.3-r0及以上版本 |
需要开启HTTPS协议配合使用,具体使用场景和说明请参见为负载均衡类型的Service配置服务器名称指示(SNI)。
动态调整后端云服务器权重
参数 |
类型 |
描述 |
支持的集群版本 |
---|---|---|---|
kubernetes.io/elb.adaptive-weight |
String |
根据节点上的Pod数量动态调整ELB后端云服务器的权重。每个Pod收到的负载请求更加均衡。
|
v1.21及以上 |
该参数在ELB直通Pod场景(即CCE Turbo集群中使用独享型ELB实例的场景)中无效。
该参数在配置ELB跨集群访问时无效。
apiVersion: v1 kind: Service metadata: name: nginx annotations: kubernetes.io/elb.id: <your_elb_id> # ELB ID,替换为实际值 kubernetes.io/elb.class: performance # 负载均衡器类型 kubernetes.io/elb.adaptive-weight: 'true' # 开启动态调整后端云服务器权重功能 spec: selector: app: nginx ports: - name: service0 port: 80 protocol: TCP targetPort: 80 type: LoadBalancer
跨集群访问
参数 |
类型 |
描述 |
支持的集群版本 |
---|---|---|---|
kubernetes.io/elb.multicluster |
String |
取值为true,表示开启Service跨集群访问。 |
v1.19.16-r0、v1.21.4-r0、v1.23.1-r0及以上 |
kubernetes.io/elb.multivpc |
String |
取值为true,表示开启不同VPC间跨集群访问,需要在kubernetes.io/elb.multicluster开关为true的情况下启用。 仅支持独享型ELB。 |
v1.19.16-r4、v1.21.7-r0、v1.23.5-r0及以上 |
kubernetes.io/elb.multicluster-loadbalancer-weight |
String |
集群Service接收流量的权重,权重可填0-100,数值越大被分发的流量越多。 |
v1.19.16-r0、v1.21.4-r0、v1.23.1-r0及以上 |
kubernetes.io/elb.multicluster-resource-recycle-policy |
String |
ELB资源的删除策略,默认为member-only。
|
v1.19.16-r0、v1.21.4-r0、v1.23.1-r0及以上 |
具体使用场景和说明请参见为负载均衡类型的Service配置跨集群的后端。
pass-through能力
参数 |
类型 |
描述 |
支持的集群版本 |
---|---|---|---|
kubernetes.io/elb.pass-through |
String |
集群内访问Service是否经过ELB。 |
v1.19及以上 |
具体使用场景和说明请参见为负载均衡类型的Service配置pass-through能力。
黑名单/白名单设置
参数 |
类型 |
描述 |
支持的集群版本 |
---|---|---|---|
kubernetes.io/elb.acl-id |
String |
|
v1.23.12-r0、v1.25.7-r0、v1.27.4-r0、v1.28.2-r0及以上 |
kubernetes.io/elb.acl-status |
String |
为ELB设置IP地址黑名单或白名单时需填写,取值如下:
|
v1.23.12-r0、v1.25.7-r0、v1.27.4-r0、v1.28.2-r0及以上 |
kubernetes.io/elb.acl-type |
String |
为ELB设置IP地址黑名单或白名单时需填写,取值如下:
|
v1.23.12-r0、v1.25.7-r0、v1.27.4-r0、v1.28.2-r0及以上 |
apiVersion: v1 kind: Service metadata: name: nginx annotations: kubernetes.io/elb.id: <your_elb_id> # ELB ID,替换为实际值 kubernetes.io/elb.class: performance # 负载均衡器类型 kubernetes.io/elb.acl-id: <your_acl_id> # ELB的IP地址组ID kubernetes.io/elb.acl-status: 'on' # 开启访问控制 kubernetes.io/elb.acl-type: 'white' # 白名单控制 spec: selector: app: nginx ports: - name: service0 port: 80 protocol: TCP targetPort: 80 type: LoadBalancer
主机网络
参数 |
类型 |
描述 |
支持的集群版本 |
---|---|---|---|
kubernetes.io/hws-hostNetwork |
String |
如果Pod使用hostNetwork主机网络,使用该注解后ELB会将请求转发至主机网络。 取值范围:
|
v1.9及以上 |
apiVersion: v1 kind: Service metadata: name: nginx annotations: kubernetes.io/elb.id: <your_elb_id> # ELB ID,替换为实际值 kubernetes.io/elb.class: performance # 负载均衡器类型 kubernetes.io/hws-hostNetwork: 'true' # ELB会将请求转发至主机网络 spec: selector: app: nginx ports: - name: service0 port: 80 protocol: TCP targetPort: 80 type: LoadBalancer
设置超时时间
参数 |
类型 |
描述 |
支持的集群版本 |
---|---|---|---|
kubernetes.io/elb.keepalive_timeout |
String |
客户端连接空闲超时时间,在超过keepalive_timeout时长一直没有请求, 负载均衡会暂时中断当前连接,直到下一次请求时重新建立新的连接。 取值:
|
独享型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 |
等待客户端请求超时时间,包括两种情况:
取值范围为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及以上版本 |
具体使用场景和说明请参见为负载均衡类型的Service配置超时时间。
添加资源标签
参数 |
类型 |
描述 |
支持的集群版本 |
---|---|---|---|
kubernetes.io/elb.tags |
String |
为ELB添加资源标签,仅自动创建ELB时支持设置。 格式为key=value,同时添加多个标签时以英文逗号(,)隔开。 |
v1.23.11-r0、v1.25.6-r0、v1.27.3-r0及以上 |
具体使用场景和说明请参见通过kubectl命令行创建-自动创建ELB。
使用HTTP/2
参数 |
类型 |
描述 |
支持的集群版本 |
---|---|---|---|
kubernetes.io/elb.http2-enable |
String |
表示HTTP/2功能的开启状态。开启后,可提升客户端与ELB间的访问性能,但ELB与后端服务器间仍采用HTTP1.X协议。 取值范围:
注意:只有当监听器的协议为HTTPS时,才支持开启或关闭HTTP/2功能。当监听器的协议为HTTP时,该字段无效,默认将其设置为false。 |
v1.23.13-r0、v1.25.8-r0、v1.27.5-r0、v1.28.3-r0及以上版本 |
具体使用场景和说明请参见为负载均衡类型的Service配置HTTP/2。
开启gzip压缩
参数 |
类型 |
描述 |
支持的集群版本 |
---|---|---|---|
kubernetes.io/elb.gzip-enabled |
String |
ELB支持开启数据压缩,通过数据压缩可缩小传输文件大小,提升文件传输效率减少带宽消耗。 开启将对特定文件类型进行压缩,关闭则不会对任何文件类型进行压缩。在默认情况下数据压缩为关闭。 支持的压缩类型如下:
仅独享型ELB的HTTP/HTTPS类型监听器支持配置。删除开启数据压缩高级配置或对应的annotation,将不会对ELB侧配置进行修改。 |
v1.23.14-r0、v1.25.9-r0、v1.27.6-r0、v1.28.4-r0及以上版本 |
具体使用场景和说明请参见为负载均衡类型的Service配置gzip数据压缩。
配置ELB后端优雅退出
当前支持Service 4层场景配置ELB后端优雅退出时间,默认为开启,优雅退出时间默认为300s。
该特性由ELB受限开放,使用前请提交工单给ELB服务进行申请。
参数 |
类型 |
描述 |
支持的集群版本 |
---|---|---|---|
kubernetes.io/elb.connection-drain-enable |
String |
是否开启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,单位为秒。 |
配置获取客户端IP
参数 |
参数类型 |
描述 |
支持的集群版本 |
---|---|---|---|
kubernetes.io/elb.transparent-client-ip |
String |
仅使用共享型ELB创建LoadBalancer类型的服务,且使用TCP/UDP协议时支持配置。
|
v1.23.17-r0、v1.25.12-r0、v1.27.9-r0、v1.28.7-r0、v1.29.3-r0及以上版本 |
具体使用场景和说明请参见为负载均衡类型的Service配置获取客户端IP。
配置自定义EIP
参数 |
参数类型 |
描述 |
支持的集群版本 |
---|---|---|---|
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及以上版本 |
具体使用场景和说明请参见为负载均衡类型的Service配置自定义EIP。
配置区间端口监听
参数 |
参数类型 |
描述 |
支持的集群版本 |
---|---|---|---|
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"]}'
说明:
该功能依赖ELB能力,使用该功能前请确认当前区域是否支持。ELB已发布区域请参见四层协议全端口监听和转发。 |
v1.23.18-r0、v1.25.13-r0、v1.27.10-r0、v1.28.8-r0、v1.29.4-r0、v1.30.1-r0及以上版本 |
具体使用场景和说明请参见为负载均衡类型的Service配置区间端口监听。
自动创建ELB的参数说明
参数 |
是否必填 |
参数类型 |
描述 |
---|---|---|---|
name |
否 |
String |
自动创建的负载均衡的名称。 取值范围:只能由中文、英文字母、数字、下划线、中划线、点组成,且长度范围为1-64个字符。 默认名称:cce-lb+service.UID |
type |
否 |
String |
负载均衡实例网络类型,公网或者私网。
默认类型:inner |
bandwidth_name |
公网型负载均衡必填 |
String |
带宽的名称,默认值为:cce-bandwidth-******。 取值范围:只能由中文、英文字母、数字、下划线、中划线、点组成,且长度范围为1-64个字符。 |
bandwidth_chargemode |
否 |
String |
带宽付费模式。
默认类型:bandwidth |
bandwidth_size |
公网型负载均衡必填 |
Integer |
带宽大小,默认1Mbit/s~2000Mbit/s,请根据Region带宽支持范围设置。
调整带宽时的最小单位会根据带宽范围不同存在差异。
|
bandwidth_sharetype |
公网型负载均衡必填 |
String |
带宽共享方式。
|
eip_type |
公网型负载均衡必填 |
String |
弹性公网IP类型。
具体类型以各区域配置为准,详情请参见弹性公网IP控制台。 |
vip_subnet_cidr_id |
否 |
String |
指定ELB所在的子网,该子网必须属于集群所在的VPC。 如不指定,则ELB与集群在同一个子网。 仅v1.21及以上版本的集群支持指定该字段。 |
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 |
四层负载均衡实例规格名称。 可以通过查询规格列表获取所有支持的类型。
独享型负载均衡器独有字段。 |
l7_flavor_name |
否 |
String |
七层负载均衡实例规格名称。 可以通过查询规格列表获取所有支持的类型。
独享型负载均衡器独有字段,必须与l4_flavor_name对应规格的类型一致,即都为弹性规格或都为固定规格。 |
elb_virsubnet_ids |
否 |
Array of strings |
负载均衡后端所在子网,不填默认为集群子网。不同实例规格将占用不同数量子网IP,不建议使用其他资源(如集群,节点等)的子网网段。 独享型负载均衡器独有字段。 示例: "elb_virsubnet_ids": [ "14567f27-8ae4-42b8-ae47-9f847a4690dd" ] |
ipv6_vip_virsubnet_id |
否 |
String |
双栈类型负载均衡器所在子网的IPv6网络ID,需要对应的子网开启IPv6,仅使用双栈集群时需填写。 独享型负载均衡器独有字段。 |
参数 |
是否必填 |
参数类型 |
描述 |
---|---|---|---|
delay |
否 |
String |
健康检查间隔(秒)。 默认值:5,取值范围:1-50 |
timeout |
否 |
String |
健康检查的超时时间(秒)。 默认值:10,取值范围1-50 |
max_retries |
否 |
String |
健康检查的最大重试次数。 默认值:3,取值范围1-10 |
protocol |
否 |
String |
健康检查的协议。 取值范围:“TCP”或者“HTTP” |
path |
否 |
String |
健康检查的URL,协议是“HTTP”时配置。 默认值:“/” 取值范围:1-80字符 |
参数 |
是否必填 |
参数类型 |
描述 |
---|---|---|---|
target_service_port |
是 |
String |
spec.ports添加健康检查的目标端口,由协议、端口号组成,如:TCP:80 |
monitor_port |
否 |
String |
重新指定的健康检查端口,不指定时默认使用业务端口。
说明:
请确保该端口在Pod所在节点已被监听,否则会影响健康检查结果。 |
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,取值范围1-64个字符 仅支持HTTP设置该字段,其他协议设置不会生效。 |