Higress Ingress支持哪些Annotation_API 网关(API Gateway)-阿里云帮助中心

Higress Ingress已支持Nginx Ingress核心和常用的Annotation，方便您从Nginx Ingress无缝迁移至Higress Ingress网关。此外，针对Nginx Ingress Annotation未支持的流量治理配置，Higress Ingress推出额外的Annotation来弥补Nginx Ingress的不足。本文介绍目前Higress Ingress支持的Annotation。

Annotation功能概述

Kubernetes标准的Ingress只提供TLS通信加密以及七层HTTP流量的简单路由能力，Ingress Controller一般会通过Annotation来增强Ingress在流量治理和安全防护上的能力。目前Higress Ingress可以通过Annotation的方式在Ingress资源上实现以下功能。

Ingress Annotation支持现状

Nginx Ingress Annotation

为方便Nginx Ingress用户可以无缝迁移到Higress Ingress上，Higress Ingress对Nginx Ingress Annotation进行大量的支持。支持现状如下表所示。

Nginx Ingress Annotation	支持总数	备注
支持的注解	51	覆盖90%的用户场景。
不影响功能的注解	15	无需配置。
暂不支持的注解	48	支持中，使用场景少。
无法支持的注解	5	主要涉及Nginx自身的代码片段。

说明

由于 Higress 与 Nginx 的实现不同，因此存在一定的差异。

Nginx Ingress Annotation 配置中的 Nginx变量以及代码片段 Snippets 无法兼容。
Nginx Ingress 通过nginx.ingress.kubernetes.io/proxy-body-sizeAnnotation 配置客户端请求的 body 大小限制。如果请求的 body 超过了指定的大小限制，Nginx 会直接返回错误。Higress 云原生网关采用分块流式传输，无需预先设置请求 body 的大小。在超大文件传输场景中，可以在网关实例下的参数配置中适当调整 `DownstreamConnectionBufferLimits` 参数。

Higress Ingress Annotation

针对Nginx Ingress Annotation未涉及的治理能力，Higress Ingress推出额外的Annotation进行补充。如下数据是目前支持现状：

Higress Ingress Annotation	支持总数	备注
扩展的注解	40	在Nginx基础上增强流量治理、安全防护能力。

作用域含义解释

Ingress：作用域为Ingress的Annotation的作用范围仅限当前Ingress上定义的路由规则。
域名：作用域为域名的Annotation，其作用范围为当前Ingress上出现的Host，该作用域影响其他Ingress上出现的相同Host。
服务：作用域为服务的Annotation，其作用范围为当前Ingress上出现的Service，该作用域影响其他Ingress上出现的相同Service。

Annotation前缀

Higress Ingress支持所有Nginx Ingress的Annotation，例如nginx.ingress.kubernetes.io/xxx的作用与higress.ingress.kubernetes.io/xxx一致。您可以按照使用习惯使用nginx或者higress业务域前缀。但是Higress Ingress独有的Annotation不可以用nginx业务域前缀来替换。

Annotation支持汇总

下文主要从流量治理和安全防护两大模块展开说明。

流量治理

灰度发布

注解	作用域	支持度	说明
nginx.ingress.kubernetes.io/canary	Ingress	兼容	开启或关闭灰度发布。
nginx.ingress.kubernetes.io/canary-by-header	Ingress	兼容	基于`Request Header Key`流量切分。
nginx.ingress.kubernetes.io/canary-by-header-value	Ingress	兼容	基于`Request Header Value`流量切分，Value为精确匹配。
nginx.ingress.kubernetes.io/canary-by-header-pattern	Ingress	兼容	基于`Request Header Value`流量切分，Value为正则匹配。
higress.ingress.kubernetes.io/canary-by-query	Ingress	Higress扩展	基于`URL Query Parameter`流量切分。
higress.ingress.kubernetes.io/canary-by-query-value	Ingress	Higress扩展	基于`URL Query Parameter`流量切分，Value为精确匹配。
higress.ingress.kubernetes.io/canary-by-query-pattern	Ingress	Higress扩展	基于`URL Query Parameter`流量切分，Value为正则匹配。
nginx.ingress.kubernetes.io/canary-by-cookie	Ingress	兼容	基于`Request Cookie Key`流量切分。
higress.ingress.kubernetes.io/canary-by-cookie-value	Ingress	Higress扩展要求网关版本1.2.30	基于`Request Cookie Value`流量切分，Value为精确匹配。
nginx.ingress.kubernetes.io/canary-weight	Ingress	兼容	基于权重和流量切分。
nginx.ingress.kubernetes.io/canary-weight-total	Ingress	兼容	权重总和。

多服务

注解

作用域

支持度

说明

higress.ingress.kubernetes.io/destination

Ingress

Higress拓展

为路由配置基于权重的服务分发。

配置语法为：{weight}% {serviceName}.{serviceNamespace}.svc.cluster.local:{port}。

说明

配置该注解后，该Ingress上所有路由规则的目标服务修改为该注解指定的服务。
如果该注解的配置语法不符合要求，则会被忽略。Ingress上所有路由规则的目标服务不会被修改。

语法示例：

annotations:
  # 60%流量到foo服务，40%流量到bar服务。
  higress.ingress.kubernetes.io/destination: |
    60% foo.default.svc.cluster.local:8080
    40% bar.default.svc.cluster.local:9090

服务Subset

注解

作用域

支持度

说明

higress.ingress.kubernetes.io/service-subset

Ingress

Higress拓展
要求网关版本1.2.25

适用于一个Service管理多个Deployment的场景。指定ingress定义的路由转发到该服务下Pod集合的子集。

当subset-labels注解未配置时，该注解的配置值的含义如下：
- 当配置为""或者base时，请求会被转发到Label中含有opensergo.io/canary: ""或不含有任何opensergo.io/canary为前缀的Label Key的Pod集合，即标签上打了空标和未打标的Pod集合。
- 当配置为其他值，请求会被转发到Label中含有opensergo.io/canary-{该值}: "该值"的Pod集合。比如当配置为gray，请求会被转发到Label中含有opensergo.io/canary-gray: gray的Pod集合。
当subset-labels注解配置时，请求仅会转发Label中含有subset-labels注解定义的Key:Value的Pod集合。

说明

当该服务没有含有指定Label的Pod，流量会自动容灾到该服务下的所有Pod。

higress.ingress.kubernetes.io/subset-labels

Ingress

Higress拓展
要求网关版本1.2.25

可选，该注解和service-subset一起工作，用于明确配置含有哪些Label的Pod属于同一Subset。

Fallback （容灾）

注解	作用域	支持度	说明
nginx.ingress.kubernetes.io/default-backend	Ingress	兼容	容灾服务。当Ingress定义的服务没有可用节点时，请求会自动转发该容灾服务。
nginx.ingress.kubernetes.io/custom-http-errors	Ingress	兼容	该注解和`default-backend`一起工作。当后端服务返回指定HTTP响应码，原始请求会被再次转发至容灾服务。重要转发至容灾服务时，请求的Path会被重写为/，该行为与`ingress-nginx`保持一致

正则匹配

注解	作用域	支持度	说明
nginx.ingress.kubernetes.io/use-regex	Ingress	兼容	正则匹配。表明Ingress定义的Path匹配为正则匹配。正则表达式采用RE2语法。

重写

注解	作用域	支持度	说明
nginx.ingress.kubernetes.io/rewrite-target	Ingress	兼容	将Ingress定义的原Path重写为指定目标，支持`Group Capture`。
nginx.ingress.kubernetes.io/upstream-vhost	Ingress	兼容	匹配Ingress定义的路由请求在转发给后端服务时，修改头部Host值为指定值。

重定向

说明

Nginx和Nginx Ingress提供的功能集并不完全一致，其中Nginx具有更广泛的功能。目前Nginx Ingress官方文档尚未提到支持使用Nginx变量进行重定向。尽管某些版本的Nginx Ingress可能支持Nginx变量的配置，但由于未在Nginx Ingress官方文档中明确提及，使用这些变量可能存在兼容性风险。建议避免在Nginx Ingress中使用Nginx变量。

注解	作用域	支持度	说明
nginx.ingress.kubernetes.io/ssl-redirect	Ingress	兼容	HTTP重定向为HTTPS。
nginx.ingress.kubernetes.io/force-ssl-redirect	Ingress	兼容	HTTP重定向为HTTPS。
nginx.ingress.kubernetes.io/permanent-redirect	Ingress	兼容	永久重定向。
nginx.ingress.kubernetes.io/permanent-redirect-code	Ingress	兼容	永久重定向状态码。
nginx.ingress.kubernetes.io/temporal-redirect	Ingress	兼容	临时重定向。
nginx.ingress.kubernetes.io/app-root	Ingress	兼容	修改应用根路径，对于访问/的请求将会被重定向为设置的新路径。

跨域

注解	作用域	支持度	说明
nginx.ingress.kubernetes.io/enable-cors	Ingress	兼容	开启或关闭跨域。
nginx.ingress.kubernetes.io/cors-allow-origin	Ingress	兼容	允许的第三方站点。
nginx.ingress.kubernetes.io/cors-allow-methods	Ingress	兼容	允许的请求方法，如GET、POST、PUT等。
nginx.ingress.kubernetes.io/cors-allow-headers	Ingress	兼容	允许的请求Header。
nginx.ingress.kubernetes.io/cors-expose-headers	Ingress	兼容	允许的暴露给浏览器的响应Header。
nginx.ingress.kubernetes.io/cors-allow-credentials	Ingress	兼容	是否允许携带凭证信息。
nginx.ingress.kubernetes.io/cors-max-age	Ingress	兼容	预检结果的最大缓存时间。

Header控制

说明

正式路由上定义的Header控制的注解不会作用于灰度路由。也就是说，定义在正式路由与灰度路由上的Header控制注解是互不影响并且独立生效。利用该特性，您可以将正式路由和灰度路由的请求分别设置不同的Header操作策略。

注解	作用域	支持度	说明
higress.ingress.kubernetes.io/request-header-control-add	Ingress	Higress扩展	请求在转发给后端服务时，添加指定Header。若该Header存在，则其值拼接在原有值后面。语法如下：单个Header：Key Value。多个Header：使用YAML特殊符号`\|` ，使每对Key Value单独处于一行。
higress.ingress.kubernetes.io/request-header-control-update	Ingress	Higress扩展	请求在转发给后端服务时，修改指定Header。若该Header存在，则其值覆盖原有值。语法如下：单个Header：Key Value。多个Header：使用YAML特殊符号`\|` ，使每对Key Value单独处于一行。
higress.ingress.kubernetes.io/request-header-control-remove	Ingress	Higress扩展	请求在转发给后端服务时，删除指定Header。语法如下：单个Header：Key。多个Header：使用英文逗号分隔。
higress.ingress.kubernetes.io/response-header-control-add	Ingress	Higress扩展	请求收到后端服务响应后，在转发响应给客户端之前需要添加指定Header。若该Header存在，则其值拼接在原有值后面。语法如下：单个Header：`Key Value`。多个Header：使用YAML特殊符号`\|` ，使每对Key Value单独处于一行。
higress.ingress.kubernetes.io/response-header-control-update	Ingress	Higress扩展	请求收到后端服务响应后，在转发响应给客户端之前需要修改指定Header。若该Header存在，则其值覆盖原有值。语法如下：单个Header：`Key Value`。多个Header：使用YAML特殊符号`\|` ，使每对Key Value单独处于一行。
higress.ingress.kubernetes.io/response-header-control-remove	Ingress	Higress扩展	请求收到后端服务响应后，在转发响应给客户端之前需要删除指定Header。语法如下：单个Header：Key。多个Header：使用英文逗号分隔。

超时

注解	作用域	支持度	说明
higress.ingress.kubernetes.io/timeout	Ingress	Higress扩展	请求的超时时间，单位为秒。默认未配置超时时间。说明超时设置作用在应用层，非传输层TCP。

重试

注解	作用域	支持度	说明
nginx.ingress.kubernetes.io/proxy-next-upstream-tries	Ingress	兼容	请求的最大重试次数。默认3次。
nginx.ingress.kubernetes.io/proxy-next-upstream-timeout	Ingress	兼容	请求重试的超时时间，单位为秒。默认未配置超时时间。
nginx.ingress.kubernetes.io/proxy-next-upstream	Ingress	兼容	请求重试条件。详情请参见Nginx重试机制。

流量镜像

注解

作用域

支持度

说明

higress.ingress.kubernetes.io/mirror-target-service

Ingress

Higress扩展

复制流量转发到指定镜像服务。服务格式为：namespace/name:port

namespace: K8s Service所在的命名空间，可选，默认为Ingress所在的命名空间。
name：K8s Service的名称，必选。
port：待转发至K8s Service的端口，可选，默认为第一个端口。

higress.ingress.kubernetes.io/mirror-percentage

Ingress

Higress扩展
要求网关版本1.2.32

复制流量的比例。可配置的值的范围为：0~100，默认100。

域名别名

注解	作用域	支持度	说明
nginx.ingress.kubernetes.io/server-alias	域名	部分兼容（仅支持精确域名和泛域名）要求网关版本1.2.30	定义该Ingress Spec中出现的域名的别名。域名别名共享源域名的TLS、路由和流量治理配置。

单机限流（即将废弃）

注解	作用域	支持度	说明
higress.ingress.kubernetes.io/route-limit-rpm	Ingress	Higress扩展	该Ingress定义的路由在每个网关实例上每分钟最大请求次数。瞬时最大请求次数为该值乘以`limit-burst-multiplier`。触发限流时，响应Body内容为`local_rate_limited`，响应状态码说明：网关版本小于1.2.23：状态码为503。网关版本1.2.23及以上：状态码为429。
higress.ingress.kubernetes.io/route-limit-rps	Ingress	Higress扩展	该Ingress定义的路由在每个网关实例上每秒最大请求次数。瞬时最大请求次数为该值乘以`limit-burst-multiplier`。触发限流时，响应Body内容为`local_rate_limited`，响应状态码说明：网关版本小于1.2.23：状态码为503。网关版本1.2.23及以上：状态码为429。
higress.ingress.kubernetes.io/route-limit-burst-multiplier	Ingress	Higress扩展	瞬时最大请求次数的因子，默认为5。

全局限流控制（推荐）

注解	作用域	支持度	说明
higress.ingress.kubernetes.io/rate-limit	Ingress	Higress拓展要求网关版本1.2.25	该Ingress定义的路由在网关实例上的全局限流，即每秒最大请求数。
higress.ingress.kubernetes.io/rate-limit-fallback-custom-response-code	Ingress	Higress拓展要求网关版本1.2.25	该Ingress定义的路由触发限流时的响应状态码，默认为429。说明该注解与rate-limit-fallback-redirect-url互斥，即自定义响应与重定向二选一。
higress.ingress.kubernetes.io/rate-limit-fallback-custom-response-body-type	Ingress	Higress拓展要求网关版本1.2.25	该Ingress定义的路由触发限流时的响应Body的格式，默认为text。配置为text时：响应的Content-Type的值为text/plain; charset=UTF-8 配置为JSON时：响应的Content-Type的值为application/json; charset=UTF-8
higress.ingress.kubernetes.io/rate-limit-fallback-custom-response-body	Ingress	Higress拓展要求网关版本1.2.25	该Ingress定义的路由触发限流时的响应Body，默认为sentinel rate limited。
higress.ingress.kubernetes.io/rate-limit-fallback-redirect-url	Ingress	Higress拓展要求网关版本1.2.25	该Ingress定义的路由触发限流时的重定向地址。说明该注解与rate-limit-fallback-custom-response-code互斥，即与重定向与自定义响应二选一。

全局并发控制

注解	作用域	支持度	说明
higress.ingress.kubernetes.io/concurrency-limit	Ingress	Higress拓展要求网关版本1.2.25	该Ingress定义的路由在网关实例上的全局并发控制，即瞬时最大正在处理的请求数。
higress.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-code	Ingress	Higress拓展要求网关版本1.2.25	该Ingress定义的路由触发并发控制时的响应状态码，默认为429。说明该注解与concurrency-limit-fallback-redirect-url互斥，即自定义响应与重定向二选一。
higress.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-body-type	Ingress	Higress拓展要求网关版本1.2.25	该Ingress定义的路由触发并发控制时的响应Body的格式，默认为text。配置为text时：响应的Content-Type的值为text/plain; charset=UTF-8 配置为JSON时：响应的Content-Type的值为application/json; charset=UTF-8
higress.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-body	Ingress	Higress拓展要求网关版本1.2.25	该Ingress定义的路由在触发并发控制时的响应Body，默认为sentinel rate limited。
higress.ingress.kubernetes.io/concurrency-limit-fallback-redirect-url	Ingress	Higress拓展要求网关版本1.2.25	该Ingress定义的路由触发并发控制时的重定向地址。说明该注解与concurrency-limit-fallback-custom-response-code互斥，即与重定向与自定义响应二选一。

后端服务使用的协议

注解

作用域

支持度

说明

nginx.ingress.kubernetes.io/backend-protocol

服务

部分兼容，不支持AJP和FCGI。

指定后端服务使用的协议，默认为HTTP，支持：

HTTP
HTTP2
HTTPS
gRPC
gRPCS

负载均衡

注解

作用域

支持度

说明

nginx.ingress.kubernetes.io/load-balance

服务

部分兼容，不支持ewma算法。若配置为EWMA算法，会回退到round_robin算法。

后端服务的普通负载均衡算法。默认为round_robin。合法值如下：

round_robin：基于轮询的负载均衡。
least_conn：基于最小请求数的负载均衡。
random：基于随机的负载均衡。

nginx.ingress.kubernetes.io/upstream-hash-by

服务

部分兼容，暂不支持Nginx变量、常量的组合使用方式。

基于一致Hash的负载均衡算法，Higress Ingress支持以下几种形式：

Higress Ingress支持配置部分Nginx变量：
- $request_uri：请求的Path（包括路径参数）作为Hash Key。
- $host：请求的Host作为Hash Key。
- $remote_addr：请求的客户端IP作为Hash Key。
基于请求Header的一致性Hash。您只需配置为$http_headerName。
基于请求路径参数的一致性Hash。您只需配置为$arg_varName。

服务预热（无损上线）

注解	作用域	支持度	说明
higress.ingress.kubernetes.io/warmup	服务	Higress扩展	服务预热时间，单位为秒。默认不开启。重要服务预热依赖于所选的负载均衡算法，目前仅支持round_robin和least_conn。

Cookie亲和性

注解	作用	支持度	说明
nginx.ingress.kubernetes.io/affinity	服务	兼容	亲和性种类，目前只支持Cookie，默认为`cookie`
nginx.ingress.kubernetes.io/affinity-mode	服务	部分兼容，暂不支持`persistent`模式。	亲和性模式，Higress Ingress目前只支持Balanced模式，默认为`balanced`模式。
nginx.ingress.kubernetes.io/session-cookie-name	服务	兼容	配置指定Cookie的值作为Hash Key。
nginx.ingress.kubernetes.io/session-cookie-path	服务	兼容	当指定Cookie不存在，生成Cookie的Path值，默认为`/`。
nginx.ingress.kubernetes.io/session-cookie-max-age	服务	兼容	当指定Cookie不存在，生成Cookie的过期时间，单位为秒，默认为Session会话级别。
nginx.ingress.kubernetes.io/session-cookie-expires	服务	兼容	当指定Cookie不存在，生成Cookie的过期时间，单位为秒，默认为Session会话级别。

IP访问控制

注解	作用域	支持度	说明
nginx.ingress.kubernetes.io/whitelist-source-range	Ingress	兼容	指定路由上的IP白名单，支持IP地址或CIDR地址块，以英文逗号分隔。
nginx.ingress.kubernetes.io/denylist-source-range	Ingress	兼容要求网关版本1.2.31	指定路由上的IP黑名单，支持IP地址或CIDR地址块，以英文逗号分隔。说明该注解的优先级高于Higress拓展的注解higress.ingress.kubernetes.io/blacklist-source-range。
higress.ingress.kubernetes.io/blacklist-source-range	Ingress	Higress扩展	指定路由上的IP黑名单，支持IP地址或CIDR地址块，以英文逗号分隔。
higress.ingress.kubernetes.io/domain-whitelist-source-range	Ingress	Higress扩展	指定域名上的IP白名单，域名优先级低于路由级别，支持IP地址或CIDR地址块，以英文逗号分隔。
higress.ingress.kubernetes.io/domain-blacklist-source-range	Ingress	Higress扩展	指定域名上的IP黑名单，域名优先级低于路由级别，支持IP地址或CIDR地址块，以英文逗号分隔。

网关与后端服务之间的连接池配置

注解	作用域	支持度	说明
higress.ingress.kubernetes.io/connection-policy-tcp-max-connection	服务	Higress扩展	网关与后端服务之间可以建立连接的最大数量。
higress.ingress.kubernetes.io/connection-policy-tcp-max-connection-per-endpoint	服务	Higress扩展	网关与后端服务的单个节点之间可以建立连接的最大数量。
higress.ingress.kubernetes.io/connection-policy-http-max-request-per-connection	服务	Higress扩展	网关与后端服务之间单个连接上的最大请求数。

安全防护

客户端与网关之间加密通信

注释	作用域	支持度	说明
higress.ingress.kubernetes.io/tls-min-protocol-version	域名	Higress扩展	指定TLS的最小版本，默认值为TLSv1.0。合法值如下： TLSv1.0 TLSv1.1 TLSv1.2 TLSv1.3
higress.ingress.kubernetes.io/tls-max-protocol-version	域名	Higress扩展	指定TLS的最大版本，默认值为TLSv1.3。合法值如下： TLSv1.0 TLSv1.1 TLSv1.2 TLSv1.3
nginx.ingress.kubernetes.io/ssl-cipher	域名	兼容	指定TLS的加密套件，可以指定多个（TLS的加密套件之间使用英文冒号分隔），仅当TLS握手时采用TLSv1.0-1.2生效。默认加密套件如下： ECDHE-ECDSA-AES128-GCM-SHA256 ECDHE-RSA-AES128-GCM-SHA256 ECDHE-ECDSA-AES128-SHA ECDHE-RSA-AES128-SHA AES128-GCM-SHA256 AES128-SHA ECDHE-ECDSA-AES256-GCM-SHA384 ECDHE-RSA-AES256-GCM-SHA384 ECDHE-ECDSA-AES256-SHA ECDHE-RSA-AES256-SHA AES256-GCM-SHA384 AES256-SHA
higress.ingress.kubernetes.io/auth-tls-secret	域名	部分兼容，secret名字格式必须是：（该域名证书所在的secret的名字）`-cacert`	网关使用的CA证书，用于验证MTLS握手期间，客户端提供的证书。该注解主要应用于网关需要验证客户端身份的场景。

网关与后端服务之间通信加密

注解	作用域	支持度	说明
nginx.ingress.kubernetes.io/proxy-ssl-secret	服务	兼容	网关使用的客户端证书，用于后端服务对网关进行身份认证。
nginx.ingress.kubernetes.io/proxy-ssl-name	服务	兼容	TLS握手期间使用的SNI。
nginx.ingress.kubernetes.io/proxy-ssl-server-name	服务	兼容	开启或关闭TLS握手期间使用的SNI。

认证鉴权

Basic

注解	作用域	支持度	说明
nginx.ingress.kubernetes.io/auth-type	Ingress	部分兼容，暂只支持Basic。	认证类型。
nginx.ingress.kubernetes.io/auth-secret	Ingress	兼容	Secret名字，格式支持`<namespace>/<name>`，包含被授予能够访问该Ingress上定义的路由的访问权限的用户名和密码。
nginx.ingress.kubernetes.io/auth-secret-type	Ingress	兼容	Secret内容格式。 `auth-file`：Data的Key为auth，Value为用户名和密码，多账号回车分隔。 `auth-map`：Data的Key为用户名，Value为密码。
nginx.ingress.kubernetes.io/auth-realm	Ingress	兼容	保护域。相同的保护域共享用户名和密码。

关于Nginx Ingress Annotation的更多信息，请参见官方文档。