用于配置ELB Ingress的注解(Annotations)
通过在YAML中添加注解Annotation(注解),您可以实现更多的Ingress高级功能。本文介绍在创建ELB类型的Ingress时可供使用的Annotation。
索引
功能分类 |
Ingress注解配置 |
---|---|
ELB配置 |
|
端口/协议配置 |
|
ELB监听器高级配置 |
|
转发策略配置 |
对接ELB的基本配置
- 关联已有ELB场景:详情请参见添加Ingress时对接已有ELB
- 自动创建ELB场景:详情请参见添加Ingress时自动创建ELB
参数 |
类型 |
描述 |
支持的集群版本 |
---|---|---|---|
kubernetes.io/elb.class |
String |
请根据不同的应用场景和功能需求选择合适的负载均衡器类型。 取值如下:
|
v1.9及以上 |
kubernetes.io/ingress.class |
String |
通过API接口创建Ingress时必须增加该参数。 v1.23及以上集群使用ingressClassName参数代替,详情请参见通过Kubectl命令行创建ELB Ingress。 |
仅v1.21及以下集群 |
kubernetes.io/elb.port |
String |
界面上的对外端口,为注册到负载均衡服务地址上的端口。 取值范围:1~65535。
说明:
部分端口为高危端口,默认被屏蔽,如21端口。 |
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的场景:必填。 示例: |
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字符。
|
v1.11.7-r0以下必填 v1.11.7-r0以上该字段废弃 |
配置ELB证书
具体使用场景和示例请参见通过kubectl命令行配置。
参数 |
类型 |
描述 |
支持的集群版本 |
---|---|---|---|
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及以上版本 |
添加资源标签
具体使用场景和示例请参见添加Ingress时自动创建ELB。
参数 |
类型 |
描述 |
支持的集群版本 |
---|---|---|---|
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。
参数 |
类型 |
描述 |
支持的集群版本 |
---|---|---|---|
kubernetes.io/elb.http2-enable |
String |
表示HTTP/2功能的开启状态。开启后,可提升客户端与ELB间的访问性能,但ELB与后端服务器间仍采用HTTP1.X协议。 取值范围:
注意:只有当监听器的协议为HTTPS时,才支持开启或关闭HTTP/2功能。当监听器的协议为HTTP时,该字段无效,默认将其设置为false。 |
v1.23.13-r0、v1.25.8-r0、v1.27.5-r0、v1.28.3-r0及以上版本 |
对接HTTPS/GRPC协议的后端服务
具体使用场景和示例请参见为ELB Ingress配置HTTPS协议的后端服务和为ELB Ingress配置GRPC协议的后端服务。
参数 |
类型 |
描述 |
支持的集群版本 |
---|---|---|---|
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及以上 |
配置Ingress超时时间
具体使用场景和示例请参见为ELB Ingress配置超时时间。
参数 |
类型 |
描述 |
支持的集群版本 |
---|---|---|---|
kubernetes.io/elb.keepalive_timeout |
String |
客户端连接空闲超时时间,在超过keepalive_timeout时长一直没有请求, 负载均衡会暂时中断当前连接,直到下一次请求时重新建立新的连接。 取值:
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 |
等待客户端请求超时时间,包括两种情况:
取值范围为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 |
设置慢启动持续时间
具体使用场景和示例请参见为ELB Ingress配置慢启动持续时间。
参数 |
类型 |
描述 |
支持的集群版本 |
---|---|---|---|
kubernetes.io/elb.slowstart |
String |
参数说明:慢启动持续时间,单位秒。 取值范围:30-1200。
说明:
负载均衡器向慢启动模式下Pod线性增加请求分配权重,当配置的慢启动持续时间期限结束后,负载均衡器向Pod发送完整的请求比例,此后本次添加的后端服务器退出慢启动模式。 |
v1.23及以上 |
配置灰度发布
具体使用场景和示例请参见为ELB Ingress配置灰度发布。
参数 |
参数类型 |
描述 |
支持的集群版本 |
---|---|---|---|
kubernetes.io/elb.canary |
string |
设置Ingress灰度发布的开关。设置为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以权重灰度形式发布。
|
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"} 参数说明:
|
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"]}' 参数说明:
|
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"]}' 参数说明:
|
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及以上版本 |
黑名单/白名单设置
具体使用场景和示例请参见为ELB Ingress配置黑名单/白名单访问策略。
参数 |
类型 |
描述 |
支持的集群版本 |
---|---|---|---|
kubernetes.io/elb.acl-id |
String |
|
v1.23.12-r0、v1.25.7-r0、v1.27.4-r0、v1.28.2-r0及以上 |
kubernetes.io/elb.acl-status |
String |
为ELB设置IP地址黑名单或白名单时需填写,取值如下:
|
v1.23.12-r0、v1.25.7-r0、v1.27.4-r0、v1.28.2-r0及以上 |
kubernetes.io/elb.acl-type |
String |
为ELB设置IP地址黑名单或白名单时需填写,取值如下:
|
v1.23.12-r0、v1.25.7-r0、v1.27.4-r0、v1.28.2-r0及以上 |
配置多个监听端口
当前支持Ingress配置自定义监听端口。通过该方式,可以将服务同时暴露80端口和443端口。
具体使用场景和示例请参见为ELB Ingress配置多个监听端口。
参数 |
类型 |
描述 |
支持的集群版本 |
---|---|---|---|
kubernetes.io/elb.listen-ports |
String |
为同一个Ingress创建多个监听端口,端口号范围为1~65535。 参数值为JSON格式的字符串,示例如下: kubernetes.io/elb.listen-ports: '[{"HTTP":80},{"HTTPS":443}]'
|
v1.23.14-r0、v1.25.9-r0、v1.27.6-r0、v1.28.4-r0及以上版本 |
配置HTTP/HTTPS头字段
具体使用场景和示例请参见为ELB Ingress配置HTTP/HTTPS头字段。
参数 |
类型 |
描述 |
支持的集群版本 |
---|---|---|---|
kubernetes.io/elb.x-forwarded-port |
String |
ELB可通过X-Forwarded-Port头字段获取监听器的端口号,传输到后端服务器的报文中。
|
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头字段获取客户端请求的端口号,传输到后端服务器的报文中。
|
|
kubernetes.io/elb.x-forwarded-host |
String |
|
开启gzip压缩
具体使用场景和示例请参见为ELB Ingress配置gzip数据压缩。
参数 |
类型 |
描述 |
支持的集群版本 |
---|---|---|---|
kubernetes.io/elb.gzip-enabled |
String |
LoadBalancer支持开启数据压缩,通过数据压缩可缩小传输文件大小,提升文件传输效率减少带宽消耗。 开启将对特定文件类型进行压缩,关闭则不会对任何文件类型进行压缩。在默认情况下数据压缩为关闭。 支持的压缩类型如下:
仅独享型ELB的HTTP/HTTPS类型监听器支持配置。删除开启数据压缩高级配置或对应的annotation,将不会对ELB侧配置进行修改。 |
v1.23.14-r0、v1.25.9-r0、v1.27.6-r0、v1.28.4-r0及以上版本 |
配置URL重定向
具体使用场景和示例请参见为ELB Ingress配置URL重定向。
参数 |
类型 |
描述 |
支持的集群版本 |
---|---|---|---|
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"。 |
配置Rewrite重写
具体使用场景和示例请参见为ELB Ingress配置Rewrite重写。
参数 |
类型 |
描述 |
支持的集群版本 |
---|---|---|---|
kubernetes.io/elb.rewrite-target |
String |
重写路径的信息。 格式说明:以 "/" 开头的合理的正则匹配规则。 参数说明:对单个Ingress下正则匹配的URL转发规则生效,配置删除后自动清理对应的重写规则。 该注解不能和灰度发布的注解一起配置。 |
v1.23.14-r0、v1.25.9-r0、v1.27.6-r0、v1.28.4-r0及以上版本 |
配置HTTP重定向到HTTPS
具体使用场景和示例请参见为ELB Ingress配置HTTP重定向到HTTPS。
参数 |
类型 |
描述 |
支持的集群版本 |
---|---|---|---|
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及以上版本 |
配置转发规则优先级
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配置转发规则优先级。
参数 |
类型 |
描述 |
支持的集群版本 |
---|---|---|---|
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转发策略。
参数 |
类型 |
描述 |
支持的集群版本 |
---|---|---|---|
kubernetes.io/elb.headers.${svc_name} |
String |
Ingress关联的Service配置自定义的Header,${svc_name}即对应的Service名称。 格式说明:Json字符串,如 {"key": "test", "values": ["value1", "value2"]} |
v1.23.16-r0、v1.25.11-r0、v1.27.8-r0、v1.28.6-r0、v1.29.2-r0及以上版本 |
配置自定义EIP
具体使用场景和示例请参见为ELB Ingress配置自定义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配置跨域访问。
参数 |
参数类型 |
描述 |
支持的集群版本 |
---|---|---|---|
kubernetes.io/elb.cors-allow-origin |
Array[string] |
指定Access-Control-Allow-Origin响应头的值,表示允许访问的域。 支持以下取值:
|
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)。 取值如下:
设置后不允许删除,如需可通过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 |
该参数用于关闭所有跨域配置。取值如下:
|
写入/删除Header
具体使用场景和示例请参见为ELB Ingress配置写入/删除Header。
参数 |
参数类型 |
描述 |
支持的集群版本 |
---|---|---|---|
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"}}]
说明:
最多添加5条写入Header或删除Header配置。 |
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 Ingress配置高级转发规则。
参数 |
参数类型 |
描述 |
支持的集群版本 |
---|---|---|---|
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及以上版本 |
附:关于自动创建ELB的参数说明
参数 |
是否必填 |
参数类型 |
描述 |
---|---|---|---|
name |
否 |
String |
自动创建的负载均衡的名称。 取值范围:只能由中文、英文字母、数字、下划线、中划线、点组成,且长度范围为1-64个字符。 默认名称:cce-lb+service.UID |
type |
否 |
String |
负载均衡实例网络类型,公网或者私网。
默认类型:inner |
bandwidth_name |
公网型负载均衡必填 |
String |
带宽的名称,默认值为:cce-bandwidth-******。 取值范围:只能由中文、英文字母、数字、下划线、中划线、点组成,且长度范围为1-64个字符。 |
bandwidth_chargemode |
否 |
String |
带宽付费模式。
默认类型:bandwidth |
bandwidth_size |
公网型负载均衡必填 |
Integer |
带宽大小,默认1Mbit/s~2000Mbit/s,请根据Region带宽支持范围设置。
调整带宽时的最小单位会根据带宽范围不同存在差异。
|
bandwidth_sharetype |
公网型负载均衡必填 |
String |
带宽共享方式。
|
eip_type |
公网型负载均衡必填 |
String |
弹性公网IP类型。
具体类型以各区域配置为准,详情请参见弹性公网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,仅使用双栈集群时需填写。 独享型负载均衡器独有字段。 |