用于配置ELB Ingress的注解（Annotations）

ELB配置

• 对接ELB的基本配置
• 添加资源标签

端口/协议配置

• 配置ELB证书
• 使用HTTP/2
• 对接HTTPS/GRPC协议的后端服务
• 配置多个监听端口

ELB监听器高级配置

• 配置Ingress超时时间
• 设置慢启动持续时间
• 黑名单/白名单设置
• 配置HTTP/HTTPS头字段
• 开启gzip压缩
• 配置自定义EIP

转发策略配置

• 配置灰度发布
• 配置URL重定向
• 配置Rewrite重写
• 配置HTTP重定向到HTTPS
• 配置转发规则优先级
• 配置自定义Header转发策略
• 配置跨域访问
• 写入/删除Header
• 配置高级转发规则

kubernetes.io/elb.class

String

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

取值如下：

• union：共享型负载均衡。
• performance：独享型负载均衡，仅支持1.17及以上集群，详情请参见共享型弹性负载均衡与独享型负载均衡的功能区别。

v1.9及以上

kubernetes.io/ingress.class

String

• cce：表示使用自研ELB Ingress。
• nginx：表示使用Nginx Ingress。

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

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

仅v1.21及以下集群

kubernetes.io/elb.port

String

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

取值范围：1~65535。

v1.9及以上

kubernetes.io/elb.id

String

仅关联已有ELB的场景：必填。

为负载均衡实例的ID。

获取方法：

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

v1.9及以上

kubernetes.io/elb.ip

String

仅关联已有ELB的场景：必填。

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

v1.9及以上

kubernetes.io/elb.autocreate

表22 Object

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

示例：

• 自动创建公网共享型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以上该字段废弃

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.tags

String

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

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

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

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

kubernetes.io/elb.pool-protocol

String

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

v1.23.8、v1.25.3及以上

对接GRPC协议的后端服务，取值为'grpc'。

v1.23.10-r20、v1.25.5-r20、v1.27.2-r20、v1.28.1-r0及以上

kubernetes.io/elb.keepalive_timeout

String

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

取值：

• 若为TCP协议，取值范围为（10-4000s）默认值为300s。
• 若为HTTP/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。

使用说明：仅协议为HTTP/HTTPS的监听器支持该字段。

最小值：1

最大值：300

缺省值：60

kubernetes.io/elb.member_timeout

String

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

取值：1-300s，默认为60s。

使用说明：仅支持协议为HTTP/HTTPS的监听器。

最小值：1

最大值：300

缺省值：60

kubernetes.io/elb.slowstart

String

参数说明：慢启动持续时间，单位秒。

取值范围：30-1200。

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

v1.23及以上

kubernetes.io/elb.canary

string

设置Ingress灰度发布的开关。设置为true后，配合不同的注解，可以实现不同的灰度发布功能。

取值范围：true

• 独享型负载均衡器生效。
• 设置为true后，不允许删除或修改。

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

kubernetes.io/elb.canary-weight

string

权重灰度发布权重值，设置后Ingress以权重灰度形式发布。

• 取值为0-100的正整数，为灰度流量分配的百分比。
• 发布成权重灰度Ingress时，该参数必填。
• 不能与其他灰度发布功能同时设置。

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

kubernetes.io/elb.session-affinity-mode

string

开启权重灰度发布后，配置会话保持能力。

灰度发布仅支持设置为 "HTTP_COOKIE"。

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

kubernetes.io/

elb.session-affinity-option

string

开启权重灰度发布会话保持能力后，会话保持的超时时间。

参数值为json字符串，格式如下：

{"persistence_timeout": "1440"}

参数说明：

• 超时时间范围为1-1440。
• 默认值为1440。

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

kubernetes.io/elb.canary-by-header

string

header灰度发布的Key值，表示请求头参数的名称。需要与kubernetes.io/elb.canary-by-header-value成对使用。

参数说明：

长度限制1-40字符，只允许包含字母、数字、中划线（-）和下划线（_）。

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

kubernetes.io/elb.canary-by-header-value

string

header灰度发布的Values值，需要与kubernetes.io/elb.canary-by-header成对使用。

参数值为json格式的数组，例如：

'{"values":["a","b"]}'

参数说明：

• Values数组长度：至少需要配置1个Values值。
  • 如果Ingress转发策略配置了域名和路径，最多支持配置8个Values值。
  • 如果Ingress转发策略仅配置了路径，最多支持配置9个Values值。
• Values数组取值：长度限制1-128字符，不支持空格，双引号，支持以下通配符：*（匹配0个或更多字符）和？（正好匹配1个字符）。

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

kubernetes.io/elb.canary-by-cookie

string

cookie灰度发布的key值，表示请求cookie参数的名称。需要与kubernetes.io/elb.canary-by-cookie-value成对使用。

参数说明：

长度限制1-100字符，支持包含字母、数字、以及 !%'"()*+,./:=?@^\\-_`~ 等字符。

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

kubernetes.io/elb.canary-by-cookie-value

string

cookie灰度发布的values值，需要与kubernetes.io/elb.canary-by-cookie成对使用。

参数值为json格式的数组，例如：

'{"values":["a","b"]}'

参数说明：

• Values数组长度：至少需要配置1个Values值。
  • 如果Ingress转发策略配置了域名和路径，最多支持配置8个Values值。
  • 如果Ingress转发策略仅配置了路径，最多支持配置9个Values值。

• Values数组取值：长度限制1-100字符，不支持空格，支持包含字母、数字、以及 !%'"()*+,./:=?@^\\-_`~ 等字符。

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

kubernetes.io/elb.canary-related-ingress-uid

string

灰度发布Ingress关联的原始Ingress的uid信息，用于前端展示原始Ingress和灰度发布的Ingress的关联关系。

● 参数格式：字符串

● 取值：原始Ingress的metadata.uid字段

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

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

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

kubernetes.io/elb.x-forwarded-port

String

ELB可通过X-Forwarded-Port头字段获取监听器的端口号，传输到后端服务器的报文中。

• true：开启获取监听器端口号开关。
• false：关闭获取监听器端口号开关。

v1.23.13-r0、v1.25.8-r0、v1.27.5-r0、v1.28.3-r0及以上版本

kubernetes.io/elb.x-forwarded-for-port

String

ELB可通过X-Forwarded-For-Port头字段获取客户端请求的端口号，传输到后端服务器的报文中。

• true：开启获取客户端请求端口号开关。
• false：关闭获取客户端请求端口号开关。

kubernetes.io/elb.x-forwarded-host

String

• true：开启重写X-Forwarded-Host开关，ELB以客户端请求头的Host重写X-Forwarded-Host传递到后端服务器。
• false：关闭重写X-Forwarded-Host开关，ELB透传客户端的X-Forwarded-Host到后端服务器。

kubernetes.io/elb.gzip-enabled

String

LoadBalancer支持开启数据压缩，通过数据压缩可缩小传输文件大小，提升文件传输效率减少带宽消耗。

开启将对特定文件类型进行压缩，关闭则不会对任何文件类型进行压缩。在默认情况下数据压缩为关闭。

支持的压缩类型如下：

• Brotli支持压缩所有类型。
• Gzip支持压缩的类型包括：text/xml text/plain text/css application/javascript application/x-javascript application/rss+xml application/atom+xml application/xml application/json。

仅独享型ELB的HTTP/HTTPS类型监听器支持配置。删除开启数据压缩高级配置或对应的annotation，将不会对ELB侧配置进行修改。

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

kubernetes.io/elb.redirect-url

String

重定向URL信息。

格式说明：以 "http://" 或 "https://" 开头的合法的URL，如 https://example.com/。

参数说明：对单个Ingress下所有的转发规则均生效，配置删除后自动清理对应的重定向URL规则。

该注解不能和灰度发布的注解一起配置。

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

kubernetes.io/elb.redirect-url-code

String

重定向URL后的返回码。

格式说明：支持返回码包括"301"、"302"、"303"、"307"、"308"。

参数说明：默认值为"301"。

kubernetes.io/elb.rewrite-target

String

重写路径的信息。

格式说明：以 "/" 开头的合理的正则匹配规则。

参数说明：对单个Ingress下正则匹配的URL转发规则生效，配置删除后自动清理对应的重写规则。

该注解不能和灰度发布的注解一起配置。

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

kubernetes.io/elb.ssl-redirect

String

是否开启HTTP重定向到HTTPS。

格式说明：支持字段 "true" 和 "false"

参数说明："true" 表示开启重定向能力，"false"或参数不存在表示不开启重定向能力

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

kubernetes.io/elb.ingress-order

String

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

仅独享型ELB支持配置。

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支持配置。

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

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

kubernetes.io/elb.cors-allow-origin

Array[string]

指定Access-Control-Allow-Origin响应头的值，表示允许访问的域。

支持以下取值：

• 通配符*：表示允许所有域名访问。
• 配置域名列表：必须为http://或者https://开头的域名，支持填写一级泛域名。格式为“http(s)://example.com”或“http(s)://example.com:port”，端口范围为1~65535。

  可填写多个值，以英文逗号分隔。

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.cors-allow-headers

Array[string]

指定Access-Control-Allow-Headers响应头的值，表示允许的请求头。可填写多个值，以英文逗号分隔。

kubernetes.io/elb.cors-expose-headers

Array[string]

指定Access-Control-Expose-Headers响应头的值，表示可以被跨域请求读取的自定义响应头部，例如通过客户端的JavaScript代码获取非标准响应头字段。可填写多个值，以英文逗号分隔。

kubernetes.io/elb.cors-allow-methods

Array[string]

指定Access-Control-Allow-Methods响应头的值，表示允许的HTTP请求方法。

可填写多个值，以英文逗号分隔。

kubernetes.io/elb.cors-allow-credentials

String

指定Access-Control-Allow-Credentials响应头的值，表示是否允许发送凭据（如Cookies）。

取值如下：

• true：允许发送凭据。
• false：不允许发送凭据。

设置后不允许删除，如需可通过kubernetes.io/elb.cors-disabled删除所有跨域配置。

kubernetes.io/elb.cors-max-age

String

指定Access-Control-Max-Age响应头的值，表示CORS预检请求的缓存时长。单位：秒。取值范围：-1~172800。

该参数值应该根据实际需求合理设置。如果设置得太短，可能会导致频繁的预检请求；如果设置得太长，可能会在CORS策略更新后延迟生效。

kubernetes.io/elb.cors-disabled

String

该参数用于关闭所有跨域配置。取值如下：

• true：关闭所有跨域配置。YAML中的参数值不会被删除，但所有配置均不生效。
• false：默认取值，跨域配置将根据用户设置生效。

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

String

Ingress关联的Service配置重写Header，${svc_name}即对应的Service名称，其最大长度为51个字符。

如果该annotation值配置成[]则表示删除相应的重写Header的策略。

注解值格式为Json字符串数组，例如：

[{"type":"InsertHeader","InsertHeaderConfig":{"key":"aa","value_type":"USER_DEFINED","value":"aa"}}]

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.conditions.${svc_name}

String

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

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

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

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

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带宽支持范围设置。

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

四层负载均衡实例规格名称。

可以通过查询规格列表获取所有支持的类型。

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

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，仅使用双栈集群时需填写。

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