文档首页> 云容器引擎 CCE> 用户指南> Standard和Turbo集群用户指南> 网络> 服务（Service）> 负载均衡（LoadBalancer）> 使用Annotation配置负载均衡

更新时间：2024-04-11 GMT+08:00

使用Annotation配置负载均衡

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

对接ELB
会话保持
健康检查
使用HTTP/HTTPS协议
配置服务器名称指示（SNI）
动态调整后端云服务器权重
pass-through能力
黑名单/白名单设置
主机网络
设置超时时间
添加资源标签
使用HTTP/2

对接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	表13	仅自动创建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": [
         "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

会话保持

表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	表16	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

健康检查

表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	表14	ELB健康检查配置选项。	v1.9及以上
kubernetes.io/elb.health-check-options	表15	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协议

表4 使用HTTP/HTTPS协议注解
参数	类型	描述	支持的集群版本
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服务器证书。获取方法：在CCE控制台，单击顶部的“服务列表 > 网络 > 弹性负载均衡”，并选择“证书管理”。在列表中复制对应证书名称下的ID即可。	v1.19.16及以上

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

配置服务器名称指示（SNI）

表5 配置服务器名称指示（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）。

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

表6 动态调整后端云服务器权重注解
参数	类型	描述	支持的集群版本
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: performance                   # 负载均衡器类型
    kubernetes.io/elb.adaptive-weight: 'true'                   # 开启动态调整后端云服务器权重功能
spec:
  selector: 
     app: nginx
  ports: 
  - name: service0 
    port: 80
    protocol: TCP 
    targetPort: 80
  type: LoadBalancer

pass-through能力

表7 pass-through注解
参数	类型	描述	支持的集群版本
kubernetes.io/elb.pass-through	String	集群内访问Service是否经过ELB。	v1.19及以上

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

黑名单/白名单设置

表8 ELB访问控制注解
参数	类型	描述	支持的集群版本
kubernetes.io/elb.acl-id	String	不填写该参数时：表示CCE不对ELB侧访问控制进行修改。参数值填写为空值时：表示允许所有IP访问。参数值填写为ELB的IP地址组ID时：表示开启访问控制，为ELB设置IP地址黑名单或白名单。此时需同时填写kubernetes.io/elb.acl-status和kubernetes.io/elb.acl-type参数。获取方法：登录控制台后，单击顶部菜单右侧的“网络 > 弹性负载均衡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：表示开启访问控制。 off：表示不开启访问控制。	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及以上

上述注解的使用方法如下：

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

主机网络

表9 主机网络注解
参数	类型	描述	支持的集群版本
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: performance                   # 负载均衡器类型
    kubernetes.io/hws-hostNetwork: 'true'                     # ELB会将请求转发至主机网络
spec:
  selector: 
     app: nginx
  ports: 
  - name: service0 
    port: 80
    protocol: TCP 
    targetPort: 80
  type: LoadBalancer

设置超时时间

**表10** 设置超时时间注解
参数	类型	描述	支持的集群版本
kubernetes.io/elb.keepalive_timeout	String	客户端连接空闲超时时间，在超过keepalive_timeout时长一直没有请求，负载均衡会暂时中断当前连接，直到下一次请求时重新建立新的连接。取值：若为TCP协议，取值范围为（10-4000s）默认值为300s。若为HTTP/HTTPS/TERMINATED_HTTPS监听器，取值范围为（0-4000s）默认值为60s。 UDP监听器不支持此字段。	独享型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及以上版本

具体使用场景和说明请参见Service配置超时时间。

添加资源标签

**表11** 添加资源标签注解
参数	类型	描述	支持的集群版本
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

**表12** 使用HTTP/2注解
参数	类型	描述	支持的集群版本
kubernetes.io/elb.http2-enable	String	表示HTTP/2功能的开启状态。开启后，可提升客户端与LB间的访问性能，但LB与后端服务器间仍采用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及以上版本

具体使用场景和说明请参见Service配置HTTP/2。

自动创建ELB的参数说明

**表13** 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_telcom：电信 5_union：联通 5_bgp：全动态BGP 5_sbgp：静态BGP 具体类型以各区域配置为准，详情请参见弹性公网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	四层负载均衡实例规格名称。可以通过查询规格列表获取所有支持的类型。弹性规格：适用于业务用量波动较大的场景，按实际使用量收取每小时使用的容量费用。v1.21.10-r10、v1.23.8-r10、v1.25.3-r10及以上版本集群支持使用弹性规格。固定规格：适用于业务用量较为稳定的场景，按固定规格折算收取每小时使用的容量费用。独享型负载均衡器独有字段。
l7_flavor_name	否	String	七层负载均衡实例规格名称。可以通过查询规格列表获取所有支持的类型。弹性规格：适用于业务用量波动较大的场景，按实际使用量收取每小时使用的容量费用。v1.21.10-r10、v1.23.8-r10、v1.25.3-r10及以上版本集群支持使用弹性规格。固定规格：适用于业务用量较为稳定的场景，按固定规格折算收取每小时使用的容量费用。独享型负载均衡器独有字段，必须与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，仅使用双栈集群时需填写。独享型负载均衡器独有字段。

**表14** 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-80字符

**表15** 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-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设置该字段，其他协议设置不会生效。

**表16** elb.session-affinity-option字段数据结构说明
参数	是否必填	参数类型	描述
persistence_timeout	是	String	当elb.session-affinity-mode是“SOURCE_IP”时生效，设置会话保持的超时时间（分钟）。默认值为："60"，取值范围：1-60。

父主题： 负载均衡（LoadBalancer）

上一篇：创建负载均衡类型的服务

下一篇：Service配置HTTP/HTTPS协议

意见反馈

文档内容是否对您有帮助？

有帮助没帮助

提供反馈

提交成功！非常感谢您的反馈，我们会继续努力做到更好！您可在我的云声建议查看反馈及问题处理状态。

系统繁忙，请稍后重试

在使用文档中是否遇到以下问题

内容与产品页面不一致

内容不易理解

缺失示例代码

步骤不可操作

搜不到想要的内容

缺少最佳实践

意见反馈（选填）

0/500

请至少选择一项反馈信息并填写问题反馈

字符长度不能超过500

直接提交取消

如您有其它疑问，您也可以通过华为云社区问答频道来与我们联系探讨

智能客服提问云社区提问

使用Annotation配置负载均衡

对接ELB

会话保持

健康检查

使用HTTP/HTTPS协议

配置服务器名称指示（SNI）

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

pass-through能力

黑名单/白名单设置

主机网络

设置超时时间

添加资源标签

使用HTTP/2

自动创建ELB的参数说明

相关文档

相关产品

意见反馈

文档内容是否对您有帮助？

7*24

备案

专业服务

退订

建议反馈

售前咨询热线