使用Annotation配置负载均衡

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

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

对接ELB

表1 对接ELB注解
参数	类型	描述	支持的集群版本
kubernetes.io/elb.class	String	请根据不同的应用场景和功能需求选择合适的负载均衡器类型。取值如下： performance：独享型负载均衡。	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	表10	仅自动创建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.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:
  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.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	表13	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	表11	ELB健康检查配置选项。	v1.9及以上
kubernetes.io/elb.health-check-options	表12	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的使用方法请参见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: union                   # 负载均衡器类型
    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 主机网络注解
参数	类型	描述	支持的集群版本
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

设置超时时间

表9 设置超时时间注解
参数	类型	描述	支持的集群版本
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及以上版本

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

自动创建ELB的参数说明

**表10** 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控制台。
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" ]

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

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

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