文档首页> 云容器引擎 CCE> 用户指南（巴黎区域）> 网络> 服务（Service）> 负载均衡（LoadBalancer）> 使用Annotation配置负载均衡
更新时间：2024-01-26 GMT+08:00
查看PDF

使用Annotation配置负载均衡

通过在YAML中添加注解Annotation（注解），您可以实现CCE提供的一些高级功能。本文介绍在创建LoadBalancer类型的Service时可供使用的Annotation。

对接ELB

表1 对接ELB注解

参数

类型

描述

支持的集群版本

kubernetes.io/elb.class

String

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

  • union：共享型负载均衡。
  • performance：独享型负载均衡，仅支持1.17及以上集群。

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

表9

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

示例：

  • 公网自动创建：

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

  • 私网自动创建：

    值为 '{"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算法。
说明：

当该字段的取值为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": [
         ""
      ],
      "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

会话保持

表2 会话保持注解

参数

类型

描述

支持的集群版本

kubernetes.io/elb.session-affinity-mode

String

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

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

当kubernetes.io/elb.lb-algorithm设置为“SOURCE_IP”（源IP算法）时，不支持开启会话保持。

v1.9及以上

kubernetes.io/elb.session-affinity-option

表12

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

v1.9及以上
上述注解的使用方法如下： 
apiVersion: v1 
kind: Service 
metadata: 
  name: nginx
  annotations:
    kubernetes.io/elb.id: <your_elb_id>                         # ELB ID，替换为实际值
    kubernetes.io/elb.class: union                   # 负载均衡器类型
    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

健康检查

表3 健康检查注解

参数

类型

描述

支持的集群版本

kubernetes.io/elb.health-check-flag

String

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

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

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

v1.9及以上

kubernetes.io/elb.health-check-option

表10

ELB健康检查配置选项。

v1.9及以上

kubernetes.io/elb.health-check-options

表11

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: union                   # 负载均衡器类型
    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的使用方法请参见指定多个端口配置健康检查。

使用HTTP协议

表4 使用HTTP协议注解

参数

类型

描述

支持的集群版本

kubernetes.io/elb.protocol-port

String

Service使用7层能力配置端口。

v1.19.16及以上

kubernetes.io/elb.cert-id

String

Service使用7层能力配置HTTPS证书。

v1.19.16及以上

具体使用场景和说明请参见Service使用HTTP协议。

动态调整后端云服务器权重

表5 动态调整后端云服务器权重注解

参数

类型

描述

支持的集群版本

kubernetes.io/elb.adaptive-weight

String

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

  • 开启：true
  • 关闭：false

该参数仅1.21及以上集群适用，且ELB直通Pod场景下无效。

v1.21及以上
上述注解的使用方法如下： 
apiVersion: v1 
kind: Service 
metadata: 
  name: nginx
  annotations:
    kubernetes.io/elb.id: <your_elb_id>                         # ELB ID，替换为实际值
    kubernetes.io/elb.class: union                   # 负载均衡器类型
    kubernetes.io/elb.adaptive-weight: 'true'                   # 开启动态调整后端云服务器权重功能
spec:
  selector: 
     app: nginx
  ports: 
  - name: service0 
    port: 80
    protocol: TCP 
    targetPort: 80
  type: LoadBalancer

pass-through能力

表6 pass-through注解

参数

类型

描述

支持的集群版本

kubernetes.io/elb.pass-through

String

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

v1.19及以上

具体使用场景和说明请参见LoadBalancer类型Service使用pass-through能力。

主机网络

表7 主机网络注解

参数

类型

描述

支持的集群版本

kubernetes.io/hws-hostNetwork

String

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

取值范围：

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

v1.9及以上
上述注解的使用方法如下： 
apiVersion: v1 
kind: Service 
metadata: 
  name: nginx
  annotations:
    kubernetes.io/elb.id: <your_elb_id>                         # ELB ID，替换为实际值
    kubernetes.io/elb.class: union                   # 负载均衡器类型
    kubernetes.io/hws-hostNetwork: 'true'                     # ELB会将请求转发至主机网络
spec:
  selector: 
     app: nginx
  ports: 
  - name: service0 
    port: 80
    protocol: TCP 
    targetPort: 80
  type: LoadBalancer

设置超时时间

表8 设置超时时间注解

参数

类型

描述

支持的集群版本

kubernetes.io/elb.keepalive_timeout

Integer

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

取值：

  • 若为TCP协议，取值范围为（10-4000s）默认值为300s。
  • 若为HTTP/HTTPS/TERMINATED_HTTPS监听器，取值范围为（0-4000s）默认值为60s。
  • UDP监听器不支持此字段。

v1.19.16-r30、v1.21.10-r10、v1.23.8-r10、v1.25.3-r10及以上

具体使用场景和说明请参见负载均衡类型的服务设置超时时间。

数据结构说明

表9 elb.autocreate字段数据结构说明

参数

是否必填

参数类型

描述

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

bandwidth_size

公网型负载均衡必填

Integer

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

调整带宽时的最小单位会根据带宽范围不同存在差异。
  • 小于等于300Mbit/s：默认最小单位为1Mbit/s。
  • 300Mbit/s~1000Mbit/s：默认最小单位为50Mbit/s。
  • 大于1000Mbit/s：默认最小单位为500Mbit/s。

bandwidth_sharetype

公网型负载均衡必填

String

带宽共享方式。

  • PER：独享带宽

eip_type

公网型负载均衡必填

String

弹性公网IP类型。

  • 5_bgp：全动态BGP

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

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"
 ]
表10 elb.health-check-option字段数据结构说明

参数

是否必填

参数类型

描述

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-10000字符
表11 elb.health-check-options字段数据结构说明

参数

是否必填

参数类型

描述

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-10000字符
表12 elb.session-affinity-option字段数据结构说明

参数

是否必填

参数类型

描述

persistence_timeout

是

String

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

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