更新时间:2025-05-16 GMT+08:00

用于配置ELB Ingress的注解(Annotations)

通过在YAML中添加注解(Annotations),您可以实现更多的Ingress高级功能。本文介绍在创建ELB类型的Ingress时可供使用的Annotation。

索引

在同一个集群中,多个Ingress可以使用同一个监听器(即使用同一个负载均衡器的同一个端口)。如果两个Ingress设置了不同的监听器配置,则实际生效的监听器配置将以最早创建的Ingress(简称为“首路由”)配置为准。

涉及以下场景:

如果不同的Ingress设置了不同的监听器配置,建议同步每个Ingress中的监听器配置。

对接ELB的基本配置

具体使用场景和示例如下:
表1 对接ELB注解

参数

类型

描述

支持的集群版本

kubernetes.io/elb.class

String

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

  • performance:独享型负载均衡,仅支持1.17及以上集群。

v1.9及以上

kubernetes.io/ingress.class

String

  • cce:表示使用自研ELB Ingress。
  • nginx:表示使用Nginx Ingress,未安装NGINX Ingress控制器插件时无法使用,详情请参见通过Kubectl命令行创建Nginx Ingress

    NGINX Ingress控制器插件为2.5.4及以上时,集群中支持同时安装多套NGINX Ingress控制器,该参数值需设置为安装控制器时指定的自定义控制器名称,表示该Ingress由此控制器进行管理。

通过API接口创建Ingress时必须增加该参数。

v1.23及以上集群使用ingressClassName参数代替,详情请参见通过Kubectl命令行创建ELB Ingress

仅v1.21及以下集群

kubernetes.io/elb.port

String

界面上的对外端口,为注册到负载均衡服务地址上的端口。

取值范围:1~65535,HTTP协议默认为80,HTTPS协议默认为443。

说明:

共享型ELB的部分端口为高危端口,默认被屏蔽,如21端口。

v1.9及以上

kubernetes.io/elb.id

String

仅关联已有ELB的场景:该参数可与kubernetes.io/elb.ip二选一填写,二者产生冲突时以kubernetes.io/elb.id为准。

为负载均衡实例的ID。

获取方法:

在控制台的“服务列表”中,单击“网络 > 弹性负载均衡 ELB”,单击ELB的名称,在ELB详情页的“基本信息”页签下找到“ID”字段复制即可。

v1.9及以上

kubernetes.io/elb.ip

String

仅关联已有ELB的场景:该参数可与kubernetes.io/elb.id二选一填写,二者产生冲突时以kubernetes.io/elb.id为准。

为负载均衡实例的服务地址,公网ELB配置为公网IP,私网ELB配置为私网IP。

v1.9及以上

kubernetes.io/elb.autocreate

表13 Object

仅自动创建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":"L7_flavor.elb.pro.max","l4_flavor_name":"","vip_subnet_cidr_id":"*****"}'

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

    值为'{"type":"inner","available_zone":["*****"],"elb_virsubnet_ids":["*****"],"l7_flavor_name":"L7_flavor.elb.pro.max","l4_flavor_name":"","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以上该字段废弃

配置ELB证书

具体使用场景和示例请参见为ELB Ingress配置HTTPS证书

表2 配置ELB证书注解

参数

类型

描述

支持的集群版本

kubernetes.io/elb.tls-certificate-ids

String

ELB服务中的证书ID列表,不同ID间使用英文逗号隔开,列表长度大于等于1。列表中的首个ID为服务器证书,其余ID为SNI证书(SNI证书中必须带有域名)。

获取方法:在CCE控制台,单击顶部的“服务列表 > 网络 > 弹性负载均衡”,并选择“证书管理”。在列表中复制对应证书名称下的ID即可。

v1.19.16-r2、v1.21.5-r0、v1.23.3-r0及以上版本

kubernetes.io/elb.tls-ciphers-policy

String

默认值为“tls-1-2”,为监听器使用的默认安全策略,仅在HTTPS协议下生效。

取值范围:

  • tls-1-0
  • tls-1-1
  • tls-1-2
  • tls-1-2-strict
  • tls-1-0-with-1-3(独享型实例)
  • tls-1-2-fs(独享型实例)
  • tls-1-2-fs-with-1-3(独享型实例)

各安全策略使用的加密套件列表详细参见表3

v1.17.17及以上版本

kubernetes.io/elb.security_policy_id

String

ELB中自定义安全组策略ID,请前往ELB控制台获取。该字段仅在HTTPS协议下生效,且优先级高于默认安全策略。

v1.17.17及以上版本

添加资源标签

具体使用场景和示例请参见添加Ingress时自动创建ELB

表3 添加资源标签注解

参数

类型

描述

支持的集群版本

kubernetes.io/elb.tags

String

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

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

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

使用HTTP/2

具体使用场景和示例请参见为ELB Ingress配置HTTP/2

表4 使用HTTP/2注解

参数

类型

描述

支持的集群版本

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及以上版本

对接HTTPS协议的后端服务

具体使用场景和示例请参见为ELB Ingress配置HTTPS协议的后端服务

表5 对接HTTPS协议的后端服务注解

参数

类型

描述

支持的集群版本

kubernetes.io/elb.pool-protocol

String

对接HTTPS协议的后端服务,取值为'https'。

v1.23.8、v1.25.3及以上

配置Ingress超时时间

具体使用场景和示例请参见为ELB Ingress配置超时时间

表6 配置Ingress超时时间注解

参数

类型

描述

支持的集群版本

kubernetes.io/elb.keepalive_timeout

String

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

取值范围为0-4000s,默认值为60s。

独享型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。

kubernetes.io/elb.member_timeout

String

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

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

设置慢启动持续时间

具体使用场景和示例请参见为ELB Ingress配置慢启动持续时间

表7 设置慢启动持续时间注解

参数

类型

描述

支持的集群版本

kubernetes.io/elb.slowstart

String

参数说明:慢启动持续时间,单位秒。

取值范围:30-1200。

  • 独享型负载均衡器生效。
  • 目标服务分配策略类型为加权轮询算法且不开启会话保持时生效。
说明:

负载均衡器向慢启动模式下Pod线性增加请求分配权重,当配置的慢启动持续时间期限结束后,负载均衡器向Pod发送完整的请求比例,此后本次添加的后端服务器退出慢启动模式。

v1.23及以上

配置多个监听端口

当前支持Ingress配置自定义监听端口。通过该方式,可以将服务同时暴露80端口和443端口。

具体使用场景和示例请参见为ELB Ingress配置多个监听端口

表8 自定义监听端口注解

参数

类型

描述

支持的集群版本

kubernetes.io/elb.listen-ports

String

为同一个Ingress创建多个监听端口,端口号范围为1~65535。

参数值为JSON格式的字符串,示例如下:

kubernetes.io/elb.listen-ports: '[{"HTTP":80},{"HTTPS":443}]'
  • 仅支持同时配置HTTP和HTTPS协议的监听端口。
  • v1.23.18-r10、v1.25.16-r0、v1.27.16-r0、v1.28.13-r0、v1.29.8-r0、v1.30.4-r0以下集群版本中仅支持新建Ingress场景,且配置多个监听端口后annotation不支持修改和删除。v1.23.18-r10、v1.25.16-r0、v1.27.16-r0、v1.28.13-r0、v1.29.8-r0、v1.30.4-r0及以上集群版本中支持修改和删除。
  • 同时指定多监听器(kubernetes.io/elb.listen-ports)和单监听器(kubernetes.io/elb.port)配置时,多监听器优先级更高。
  • Ingress内配置项对多个监听器同时生效,如黑白名单配置、超时时间配置。Ingress开启HTTP/2配置时,HTTP/2仅在HTTPS端口生效。

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

配置转发规则优先级

Ingress使用同一个ELB监听器时,支持按照以下规则进行转发规则优先级排序:

  • 不同Ingress的转发规则:按照“kubernetes.io/elb.ingress-order”注解的优先级(取值范围为1~1000)进行排序,值越小表示优先级越高。
  • 同一个Ingress的转发规则:“kubernetes.io/elb.rule-priority-enabled”注解设置为“true”时,根据创建Ingress时的转发规则先后顺序进行排序,配置在上面的优先级高;未配置该注解时,同一个Ingress的转发规则会使用ELB侧的默认排序。

未配置以上注解时,同一个ELB监听器下无论包含多个Ingress还是同一个Ingress的转发规则,都会使用ELB侧的默认排序规则。

具体使用场景和说明请参见为ELB Ingress配置转发规则优先级

表9 转发规则优先级注解

参数

类型

描述

支持的集群版本

kubernetes.io/elb.ingress-order

String

不同Ingress间的转发规则排序,参数值越小表示优先级越高,且同一个监听内规则优先级必须唯一,取值范围为1~1000。

仅独享型ELB支持配置。

说明:

配置该注解时,默认开启“kubernetes.io/elb.rule-priority-enabled”注解,即同时对每个Ingress的转发规则进行排序。

v1.23.15-r0、v1.25.10-r0、v1.27.7-r0、v1.28.5-r0、v1.29.1-r10及以上版本

kubernetes.io/elb.rule-priority-enabled

String

仅支持设置为“true”,表示对同一个Ingress的转发规则进行排序,系统将会根据创建Ingress时的转发规则先后顺序确定优先级,配置在上面的优先级高。

未开启该参数时,同一个Ingress的转发规则会使用ELB侧的默认排序,开启后则不允许关闭。

仅独享型ELB支持配置。

配置自定义Header转发策略

具体使用场景和示例请参见为ELB Ingress配置自定义Header转发策略

表10 自定义Header转发策略注解

参数

类型

描述

支持的集群版本

kubernetes.io/elb.headers.${svc_name}

String

Ingress关联的Service配置自定义的Header,${svc_name}即对应的Service名称。

格式说明:Json字符串,如 {"key": "test", "values": ["value1", "value2"]}

  • key/value表示自定义Header的键值对,value最多可以配置8个。

    key的取值范围:长度限制1-40字符,只允许包含字母、数字、中划线(-)和下划线(_)

    value的取值范围:长度限制1-128字符,不支持空格,双引号,支持以下通配符:*(匹配0个或更多字符)和?(正好匹配1个字符)

  • 不能和灰度发布同时配置
  • svc_name最大长度51个字符

v1.23.16-r0、v1.25.11-r0、v1.27.8-r0、v1.28.6-r0、v1.29.2-r0及以上版本

配置自定义EIP

具体使用场景和示例请参见为ELB Ingress配置自定义EIP

表11 配置自定义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及以上版本

配置高级转发规则

具体使用场景和示例请参见为ELB Ingress配置高级转发规则

表12 高级转发规则注解

参数

参数类型

描述

支持的集群版本

kubernetes.io/elb.conditions.${svc_name}

String

配置高级转发规则,${svc_name}即对应的Service名称,其最大长度为51个字符。

如果该annotation值配置成[]则表示删除相应的高级转发规则。

注解值格式为Json字符串数组,具体格式请参见表2

须知:
  • 由于ELB的API限制,conditions设置的数量上限为10,即一条kubernetes.io/elb.conditions.{svcName}中,最多包含十条key-value键值对。
  • 一条conditions中的数组中不同的规则是“与”关系,但同一个规则块中的值是“或”关系。例如,Method和QueryString两种转发条件都配置时,需要同时满足,才能实现目标流量分发。但如果Method值为GET,POST,即只需要满足Method为GET或POST,且QueryString满足条件即可。

v1.23.18-r10、v1.25.16-r0、v1.27.16-r0、v1.28.13-r0、v1.29.8-r0、v1.30.4-r0及以上版本

附:关于自动创建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_bgp:全动态BGP

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

vip_subnet_cidr_id

String

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

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

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

获取方式:

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

elb_virsubnet_ids

Array of strings

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

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

示例:

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

获取方式:

登录虚拟私有云控制台,在左侧导航栏选择“子网”,根据集群所在的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协议时必填。

  • 弹性规格:适用于业务用量波动较大的场景,按实际使用量收取每小时使用的容量费用。v1.21.10-r10、v1.23.8-r10、v1.25.3-r10及以上版本集群支持使用弹性规格。
  • 固定规格:适用于业务用量较为稳定的场景,按固定规格折算收取每小时使用的容量费用。

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

l7_flavor_name

String

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

  • 弹性规格:适用于业务用量波动较大的场景,按实际使用量收取每小时使用的容量费用。v1.21.10-r10、v1.23.8-r10、v1.25.3-r10及以上版本集群支持使用弹性规格。
  • 固定规格:适用于业务用量较为稳定的场景,按固定规格折算收取每小时使用的容量费用。

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