全部产品
Search
文档中心

微服务引擎MSE:MSE Ingress支持的Annotation

更新时间:Feb 19, 2024

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

背景信息

Ingress资源是Kubernetes用来管理集群内部服务如何对外暴露的一种方式。随着云原生分布式应用的规模不断扩大,官方标准定义的Ingress资源已无法满足用户对流量管理的诉求。各个负责应用Ingress资源的Ingress-Controller开始针对不同的场景定义适用于自身的Annotation来填补Ingress功能上的不足。其中,比较主流的Nginx-Ingress到目前为止推出了100多个Annotation。

为了进一步融入K8s生态,MSE Ingress支持Nginx-Ingress中比较常用且核心的Annotation,方便您从Nginx-Ingress无缝迁移至MSE Ingress。此外,针对Nginx-Ingress Annotation未涉及的流量治理领域,MSE Ingress推出Annotation来保持您的使用习惯。

Annotation功能概述

Kubernetes标准的Ingress只提供TLS通信加密以及七层HTTP流量的简单路由能力,Ingress Controller一般会通过Annotation来增强Ingress在流量治理和安全防护上的能力。

Annotation支持现状

Nginx Annotation

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

Nginx Annotation

支持总数

备注

支持的注解

51

覆盖90%的用户场景。

不影响功能的注解

15

无需配置。

暂不支持的注解

48

支持中,使用场景少。

无法支持的注解

5

主要涉及Nginx自身的代码片段。

MSE Annotation

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

MSE Annotation

支持总数

备注

扩展的注解

39

在Nginx基础上增强流量治理、安全防护能力。

作用域含义解释

  • Ingress:作用域为Ingress的Annotation的作用范围仅限当前Ingress上定义的路由规则。

  • 域名:作用域为域名的Annotation,其作用范围为当前Ingress上出现的Host,该作用域影响其他Ingress上出现的相同Host。

  • 服务:作用域为服务的Annotation,其作用范围为当前Ingress上出现的Service,该作用域影响其他Ingress上出现的相同Service。

Annotation前缀

MSE Ingress支持所有Nginx Ingress的Annotation,例如nginx.ingress.kubernetes.io/xxx的作用与mse.ingress.kubernetes.io/xxx一致。您可以按照使用习惯使用nginx或者mse业务域前缀。但是MSE 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为正则匹配。

mse.ingress.kubernetes.io/canary-by-query

Ingress

MSE扩展

基于URL Query Parameter流量切分。

mse.ingress.kubernetes.io/canary-by-query-value

Ingress

MSE扩展

基于URL Query Parameter流量切分,Value为精确匹配。

mse.ingress.kubernetes.io/canary-by-query-pattern

Ingress

MSE扩展

基于URL Query Parameter流量切分,Value为正则匹配。

nginx.ingress.kubernetes.io/canary-by-cookie

Ingress

兼容

基于Request Cookie Key流量切分。

mse.ingress.kubernetes.io/canary-by-cookie-value

Ingress

  • MSE扩展

  • 要求网关版本1.2.30

基于Request Cookie Value流量切分,Value为精确匹配。

nginx.ingress.kubernetes.io/canary-weight

Ingress

兼容

基于权重和流量切分。

nginx.ingress.kubernetes.io/canary-weight-total

Ingress

兼容

权重总和。

多服务

注解

作用域

支持度

说明

mse.ingress.kubernetes.io/destination

Ingress

MSE拓展

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

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

说明
  • 配置该注解后,该Ingress上所有路由规则的目标服务修改为该注解指定的服务。

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

语法示例:

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

服务Subset

注解

作用域

支持度

说明

mse.ingress.kubernetes.io/service-subset

Ingress

  • MSE拓展

  • 要求网关版本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。

mse.ingress.kubernetes.io/subset-labels

Ingress

  • MSE拓展

  • 要求网关版本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.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操作策略。

注解

作用域

支持度

说明

mse.ingress.kubernetes.io/request-header-control-add

Ingress

MSE扩展

请求在转发给后端服务时,添加指定Header。若该Header存在,则其值拼接在原有值后面。语法如下:

  • 单个Header:Key Value。

  • 多个Header:使用YAML特殊符号| ,使每对Key Value单独处于一行。

mse.ingress.kubernetes.io/request-header-control-update

Ingress

MSE扩展

请求在转发给后端服务时,修改指定Header。若该Header存在,则其值覆盖原有值。语法如下:

  • 单个Header:Key Value。

  • 多个Header:使用YAML特殊符号| ,使每对Key Value单独处于一行。

mse.ingress.kubernetes.io/request-header-control-remove

Ingress

MSE扩展

请求在转发给后端服务时,删除指定Header。语法如下:

  • 单个Header:Key。

  • 多个Header:使用英文逗号分隔。

mse.ingress.kubernetes.io/response-header-control-add

Ingress

MSE扩展

请求收到后端服务响应后,在转发响应给客户端之前需要添加指定Header。若该Header存在,则其值拼接在原有值后面。语法如下:

  • 单个Header:Key Value

  • 多个Header:使用YAML特殊符号| ,使每对Key Value单独处于一行。

mse.ingress.kubernetes.io/response-header-control-update

Ingress

MSE扩展

请求收到后端服务响应后,在转发响应给客户端之前需要修改指定Header。若该Header存在,则其值覆盖原有值。语法如下:

  • 单个Header:Key Value

  • 多个Header:使用YAML特殊符号| ,使每对Key Value单独处于一行。

mse.ingress.kubernetes.io/response-header-control-remove

Ingress

MSE扩展

请求收到后端服务响应后,在转发响应给客户端之前需要删除指定Header。语法如下:

  • 单个Header:Key。

  • 多个Header:使用英文逗号分隔。

超时

注解

作用域

支持度

说明

mse.ingress.kubernetes.io/timeout

Ingress

MSE扩展

请求的超时时间,单位为秒。默认未配置超时时间。

说明

超时设置作用在应用层,非传输层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重试机制

流量镜像

注解

作用域

支持度

说明

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

Ingress

MSE扩展

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

  • namespace: K8s Service所在的命名空间,可选,默认为Ingress所在的命名空间。

  • name:K8s Service的名称,必选。

  • port:待转发至K8s Service的端口,可选,默认为第一个端口。

域名别名

注解

作用域

支持度

说明

nginx.ingress.kubernetes.io/server-alias

域名

  • 部分兼容(仅支持精确域名和泛域名)

  • 要求网关版本1.2.30

定义该Ingress Spec中出现的域名的别名。域名别名共享源域名的TLS、路由和流量治理配置。

单机限流(即将废弃)

注解

作用域

支持度

说明

mse.ingress.kubernetes.io/route-limit-rpm

Ingress

MSE扩展

该Ingress定义的路由在每个网关实例上每分钟最大请求次数。瞬时最大请求次数为该值乘以limit-burst-multiplier

触发限流时,响应Body内容为local_rate_limited,响应状态码说明:

  • 网关版本小于1.2.23:状态码为503。

  • 网关版本1.2.23及以上:状态码为429。

mse.ingress.kubernetes.io/route-limit-rps

Ingress

MSE扩展

该Ingress定义的路由在每个网关实例上每秒最大请求次数。瞬时最大请求次数为该值乘以limit-burst-multiplier

触发限流时,响应Body内容为local_rate_limited,响应状态码说明:

  • 网关版本小于1.2.23:状态码为503。

  • 网关版本1.2.23及以上:状态码为429。

mse.ingress.kubernetes.io/route-limit-burst-multiplier

Ingress

MSE扩展

瞬时最大请求次数的因子,默认为5。

全局限流控制(推荐)

注解

作用域

支持度

说明

mse.ingress.kubernetes.io/rate-limit

Ingress

  • MSE拓展

  • 要求网关版本1.2.25

该Ingress定义的路由在网关实例上的全局限流,即每秒最大请求数。

mse.ingress.kubernetes.io/rate-limit-fallback-custom-response-code

Ingress

  • MSE拓展

  • 要求网关版本1.2.25

该Ingress定义的路由触发限流时的响应状态码,默认为429。

说明

该注解与rate-limit-fallback-redirect-url互斥,即自定义响应与重定向二选一。

mse.ingress.kubernetes.io/rate-limit-fallback-custom-response-body-type

Ingress

  • MSE拓展

  • 要求网关版本1.2.25

该Ingress定义的路由触发限流时的响应Body的格式,默认为text。

  • 配置为text时:响应的Content-Type的值为text/plain; charset=UTF-8

  • 配置为json时:响应的Content-Type的值为application/json; charset=UTF-8

mse.ingress.kubernetes.io/rate-limit-fallback-custom-response-body

Ingress

  • MSE拓展

  • 要求网关版本1.2.25

该Ingress定义的路由触发限流时的响应Body,默认为sentinel rate limited。

mse.ingress.kubernetes.io/rate-limit-fallback-redirect-url

Ingress

  • MSE拓展

  • 要求网关版本1.2.25

该Ingress定义的路由触发限流时的重定向地址。

说明

该注解与rate-limit-fallback-custom-response-code互斥,即与重定向与自定义响应二选一。

全局并发控制

注解

作用域

支持度

说明

mse.ingress.kubernetes.io/concurrency-limit

Ingress

  • MSE拓展

  • 要求网关版本1.2.25

该Ingress定义的路由在网关实例上的全局并发控制,即瞬时最大正在处理的请求数。

mse.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-code

Ingress

  • MSE拓展

  • 要求网关版本1.2.25

该Ingress定义的路由触发并发控制时的响应状态码,默认为429。

说明

该注解与concurrency-limit-fallback-redirect-url互斥,即自定义响应与重定向二选一。

mse.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-body-type

Ingress

  • MSE拓展

  • 要求网关版本1.2.25

该Ingress定义的路由触发并发控制时的响应Body的格式,默认为text。

  • 配置为text时:响应的Content-Type的值为text/plain; charset=UTF-8

  • 配置为json时:响应的Content-Type的值为application/json; charset=UTF-8

mse.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-body

Ingress

  • MSE拓展

  • 要求网关版本1.2.25

该Ingress定义的路由触发并发控制时的响应Body,默认为sentinel rate limited。

mse.ingress.kubernetes.io/concurrency-limit-fallback-redirect-url

Ingress

  • MSE拓展

  • 要求网关版本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的负载均衡算法,MSE Ingress支持以下几种形式:

  • MSE Ingress支持配置部分Nginx变量:

    • $request_uri:请求的Path(包括路径参数)作为Hash Key。

    • $host:请求的Host作为Hash Key。

    • $remote_addr:请求的客户端IP作为Hash Key。

  • 基于请求Header的一致性Hash。您只需配置为$http_headerName

  • 基于请求路径参数的一致性Hash。您只需配置为$arg_varName

服务预热(无损上线)

注解

作用域

支持度

说明

mse.ingress.kubernetes.io/warmup

服务

MSE扩展

服务预热时间,单位为秒。默认不开启。

重要

服务预热依赖于所选的负载均衡算法,目前仅支持round_robin和least_conn。

Cookie亲和性

注解

作用

支持度

说明

nginx.ingress.kubernetes.io/affinity

服务

兼容

亲和性种类,目前只支持Cookie,默认为cookie

nginx.ingress.kubernetes.io/affinity-mode

服务

部分兼容,暂不支持persistent模式。

亲和性模式,MSE 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地址块,以英文逗号分隔。

说明

该注解的优先级高于MSE拓展的注解mse.ingress.kubernetes.io/blacklist-source-range。

mse.ingress.kubernetes.io/blacklist-source-range

Ingress

MSE扩展

指定路由上的IP黑名单,支持IP地址或CIDR地址块,以英文逗号分隔。

mse.ingress.kubernetes.io/domain-whitelist-source-range

Ingress

MSE扩展

指定域名上的IP白名单,域名优先级低于路由级别,支持IP地址或CIDR地址块,以英文逗号分隔。

mse.ingress.kubernetes.io/domain-blacklist-source-range

Ingress

MSE扩展

指定域名上的IP黑名单,域名优先级低于路由级别,支持IP地址或CIDR地址块,以英文逗号分隔。

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

注解

作用域

支持度

说明

mse.ingress.kubernetes.io/connection-policy-tcp-max-connection

服务

MSE扩展

网关与后端服务之间可以建立连接的最大数量。

mse.ingress.kubernetes.io/connection-policy-tcp-max-connection-per-endpoint

服务

MSE扩展

网关与后端服务的单个节点之间可以建立连接的最大数量。

mse.ingress.kubernetes.io/connection-policy-http-max-request-per-connection

服务

MSE扩展

网关与后端服务之间单个连接上的最大请求数。

安全防护

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

注释

作用域

支持度

说明

mse.ingress.kubernetes.io/tls-min-protocol-version

域名

MSE扩展

指定TLS的最小版本,默认值为TLSv1.0。合法值如下:

  • TLSv1.0

  • TLSv1.1

  • TLSv1.2

  • TLSv1.3

mse.ingress.kubernetes.io/tls-max-protocol-version

域名

MSE扩展

指定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

mse.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的更多信息,请参见官方文档