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在流量治理和安全防护上的能力。目前MSE Ingress可以通过Annotation的方式在Ingress资源上实现以下功能。
Ingress Annotation支持现状
Nginx Ingress Annotation
为方便Nginx Ingress用户可以无缝迁移到MSE Ingress上,MSE Ingress对Nginx Ingress Annotation进行大量的支持。支持现状如下表所示。
Nginx Ingress Annotation | 支持总数 | 备注 |
支持的注解 | 51 | 覆盖90%的用户场景。 |
不影响功能的注解 | 15 | 无需配置。 |
暂不支持的注解 | 48 | 支持中,使用场景少。 |
无法支持的注解 | 5 | 主要涉及Nginx自身的代码片段。 |
由于 MSE 与 Nginx 的实现不同,因此存在一定的差异。
Nginx Ingress Annotation 配置中的 Nginx变量以及代码片段 Snippets 无法兼容。
Nginx Ingress 通过
nginx.ingress.kubernetes.io/proxy-body-size
Annotation 配置客户端请求的 body 大小限制。如果请求的 body 超过了指定的大小限制,Nginx 会直接返回错误。MSE 云原生网关采用分块流式传输,无需预先设置请求 body 的大小。在超大文件传输场景中,可以在网关实例下的参数配置中适当调整 `DownstreamConnectionBufferLimits` 参数。
MSE Ingress Annotation
针对Nginx Ingress Annotation未涉及的治理能力,MSE Ingress推出额外的Annotation进行补充。如下数据是目前支持现状:
MSE Ingress Annotation | 支持总数 | 备注 |
扩展的注解 | 40 | 在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 | 兼容 | 基于 |
nginx.ingress.kubernetes.io/canary-by-header-value | Ingress | 兼容 | 基于 |
nginx.ingress.kubernetes.io/canary-by-header-pattern | Ingress | 兼容 | 基于 |
mse.ingress.kubernetes.io/canary-by-query | Ingress | MSE扩展 | 基于 |
mse.ingress.kubernetes.io/canary-by-query-value | Ingress | MSE扩展 | 基于 |
mse.ingress.kubernetes.io/canary-by-query-pattern | Ingress | MSE扩展 | 基于 |
nginx.ingress.kubernetes.io/canary-by-cookie | Ingress | 兼容 | 基于 |
mse.ingress.kubernetes.io/canary-by-cookie-value | Ingress |
| 基于 |
nginx.ingress.kubernetes.io/canary-weight | Ingress | 兼容 | 基于权重和流量切分。 |
nginx.ingress.kubernetes.io/canary-weight-total | Ingress | 兼容 | 权重总和。 |
多服务
注解 | 作用域 | 支持度 | 说明 |
mse.ingress.kubernetes.io/destination | Ingress | MSE拓展 | 为路由配置基于权重的服务分发。 配置语法为: 说明
|
语法示例:
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 |
| 适用于一个Service管理多个Deployment的场景。指定ingress定义的路由转发到该服务下Pod集合的子集。
说明 当该服务没有含有指定Label的Pod,流量会自动容灾到该服务下的所有Pod。 |
mse.ingress.kubernetes.io/subset-labels | Ingress |
| 可选,该注解和 |
Fallback (容灾)
注解 | 作用域 | 支持度 | 说明 |
nginx.ingress.kubernetes.io/default-backend | Ingress | 兼容 | 容灾服务。当Ingress定义的服务没有可用节点时,请求会自动转发该容灾服务。 |
nginx.ingress.kubernetes.io/custom-http-errors | Ingress | 兼容 | 该注解和 重要 转发至容灾服务时,请求的Path会被重写为/,该行为与 |
正则匹配
注解 | 作用域 | 支持度 | 说明 |
nginx.ingress.kubernetes.io/use-regex | Ingress | 兼容 | 正则匹配。表明Ingress定义的Path匹配为正则匹配。正则表达式采用RE2语法。 |
重写
注解 | 作用域 | 支持度 | 说明 |
nginx.ingress.kubernetes.io/rewrite-target | Ingress | 兼容 | 将Ingress定义的原Path重写为指定目标,支持 |
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操作策略。
注解 | 作用域 | 支持度 | 说明 |
mse.ingress.kubernetes.io/request-header-control-add | Ingress | MSE扩展 | 请求在转发给后端服务时,添加指定Header。若该Header存在,则其值拼接在原有值后面。语法如下:
|
mse.ingress.kubernetes.io/request-header-control-update | Ingress | MSE扩展 | 请求在转发给后端服务时,修改指定Header。若该Header存在,则其值覆盖原有值。语法如下:
|
mse.ingress.kubernetes.io/request-header-control-remove | Ingress | MSE扩展 | 请求在转发给后端服务时,删除指定Header。语法如下:
|
mse.ingress.kubernetes.io/response-header-control-add | Ingress | MSE扩展 | 请求收到后端服务响应后,在转发响应给客户端之前需要添加指定Header。若该Header存在,则其值拼接在原有值后面。语法如下:
|
mse.ingress.kubernetes.io/response-header-control-update | Ingress | MSE扩展 | 请求收到后端服务响应后,在转发响应给客户端之前需要修改指定Header。若该Header存在,则其值覆盖原有值。语法如下:
|
mse.ingress.kubernetes.io/response-header-control-remove | Ingress | MSE扩展 | 请求收到后端服务响应后,在转发响应给客户端之前需要删除指定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
|
mse.ingress.kubernetes.io/mirror-percentage | Ingress |
| 复制流量的比例。可配置的值的范围为:0~100,默认100。 |
域名别名
注解 | 作用域 | 支持度 | 说明 |
nginx.ingress.kubernetes.io/server-alias | 域名 |
| 定义该Ingress Spec中出现的域名的别名。域名别名共享源域名的TLS、路由和流量治理配置。 |
单机限流(即将废弃)
注解 | 作用域 | 支持度 | 说明 |
mse.ingress.kubernetes.io/route-limit-rpm | Ingress | MSE扩展 | 该Ingress定义的路由在每个网关实例上每分钟最大请求次数。瞬时最大请求次数为该值乘以 触发限流时,响应Body内容为
|
mse.ingress.kubernetes.io/route-limit-rps | Ingress | MSE扩展 | 该Ingress定义的路由在每个网关实例上每秒最大请求次数。瞬时最大请求次数为该值乘以 触发限流时,响应Body内容为
|
mse.ingress.kubernetes.io/route-limit-burst-multiplier | Ingress | MSE扩展 | 瞬时最大请求次数的因子,默认为5。 |
全局限流控制(推荐)
注解 | 作用域 | 支持度 | 说明 |
mse.ingress.kubernetes.io/rate-limit | Ingress |
| 该Ingress定义的路由在网关实例上的全局限流,即每秒最大请求数。 |
mse.ingress.kubernetes.io/rate-limit-fallback-custom-response-code | Ingress |
| 该Ingress定义的路由触发限流时的响应状态码,默认为429。 说明 该注解与rate-limit-fallback-redirect-url互斥,即自定义响应与重定向二选一。 |
mse.ingress.kubernetes.io/rate-limit-fallback-custom-response-body-type | Ingress |
| 该Ingress定义的路由触发限流时的响应Body的格式,默认为text。
|
mse.ingress.kubernetes.io/rate-limit-fallback-custom-response-body | Ingress |
| 该Ingress定义的路由触发限流时的响应Body,默认为sentinel rate limited。 |
mse.ingress.kubernetes.io/rate-limit-fallback-redirect-url | Ingress |
| 该Ingress定义的路由触发限流时的重定向地址。 说明 该注解与rate-limit-fallback-custom-response-code互斥,即与重定向与自定义响应二选一。 |
全局并发控制
注解 | 作用域 | 支持度 | 说明 |
mse.ingress.kubernetes.io/concurrency-limit | Ingress |
| 该Ingress定义的路由在网关实例上的全局并发控制,即瞬时最大正在处理的请求数。 |
mse.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-code | Ingress |
| 该Ingress定义的路由触发并发控制时的响应状态码,默认为429。 说明 该注解与concurrency-limit-fallback-redirect-url互斥,即自定义响应与重定向二选一。 |
mse.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-body-type | Ingress |
| 该Ingress定义的路由触发并发控制时的响应Body的格式,默认为text。
|
mse.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-body | Ingress |
| 该Ingress定义的路由在触发并发控制时的响应Body,默认为sentinel rate limited。 |
mse.ingress.kubernetes.io/concurrency-limit-fallback-redirect-url | Ingress |
| 该Ingress定义的路由触发并发控制时的重定向地址。 说明 该注解与concurrency-limit-fallback-custom-response-code互斥,即与重定向与自定义响应二选一。 |
后端服务使用的协议
注解 | 作用域 | 支持度 | 说明 |
nginx.ingress.kubernetes.io/backend-protocol | 服务 | 部分兼容,不支持AJP和FCGI。 | 指定后端服务使用的协议,默认为HTTP,支持:
|
负载均衡
注解 | 作用域 | 支持度 | 说明 |
nginx.ingress.kubernetes.io/load-balance | 服务 | 部分兼容,不支持 | 后端服务的普通负载均衡算法。默认为
|
nginx.ingress.kubernetes.io/upstream-hash-by | 服务 | 部分兼容,暂不支持Nginx变量、常量的组合使用方式。 | 基于一致Hash的负载均衡算法,MSE Ingress支持以下几种形式:
|
服务预热(无损上线)
注解 | 作用域 | 支持度 | 说明 |
mse.ingress.kubernetes.io/warmup | 服务 | MSE扩展 | 服务预热时间,单位为秒。默认不开启。 重要 服务预热依赖于所选的负载均衡算法,目前仅支持round_robin和least_conn。 |
Cookie亲和性
注解 | 作用 | 支持度 | 说明 |
nginx.ingress.kubernetes.io/affinity | 服务 | 兼容 | 亲和性种类,目前只支持Cookie,默认为 |
nginx.ingress.kubernetes.io/affinity-mode | 服务 | 部分兼容,暂不支持 | 亲和性模式,MSE Ingress目前只支持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 |
| 指定路由上的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。合法值如下:
|
mse.ingress.kubernetes.io/tls-max-protocol-version | 域名 | MSE扩展 | 指定TLS的最大版本,默认值为TLSv1.3。合法值如下:
|
nginx.ingress.kubernetes.io/ssl-cipher | 域名 | 兼容 | 指定TLS的加密套件,可以指定多个(TLS的加密套件之间使用英文冒号分隔),仅当TLS握手时采用TLSv1.0-1.2生效。 默认加密套件如下:
|
mse.ingress.kubernetes.io/auth-tls-secret | 域名 | 部分兼容,secret名字格式必须是:(该域名证书所在的secret的名字) | 网关使用的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名字,格式支持 |
nginx.ingress.kubernetes.io/auth-secret-type | Ingress | 兼容 | Secret内容格式。
|
nginx.ingress.kubernetes.io/auth-realm | Ingress | 兼容 | 保护域。相同的保护域共享用户名和密码。 |
关于Nginx Ingress Annotation的更多信息,请参见官方文档。