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资源上实现以下功能。

1

Annotation支持现状

Nginx Annotation

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

Nginx Annotation 支持总数 备注
支持的注解 47 覆盖90%的用户场景。
不影响功能的注解 13 支持中。
暂不支持的注解 21 支持中。
无法支持的注解 4 主要涉及Nginx自身的代码片段。

MSE Annotation

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

MSE Annotation 支持总数 备注
拓展的注解 16 在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为正则匹配。
    nginx.ingress.kubernetes.io/canary-by-cookie Ingress 兼容 基于Request Cookie Key流量切分。
    nginx.ingress.kubernetes.io/canary-weight Ingress 兼容 基于权重和流量切分。
    nginx.ingress.kubernetes.io/canary-weight-total Ingress 兼容 权重总和。
  • 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/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/route-limit-rpm Ingress MSE拓展 该Ingress定义的路由在每个网关实例上每分钟最大请求次数。瞬时最大请求次数为该值乘以limit-burst-multiplier。
    mse.ingress.kubernetes.io/route-limit-rps Ingress MSE拓展 该Ingress定义的路由在每个网关实例上每秒最大请求次数。瞬时最大请求次数为该值乘以limit-burst-multiplier。
    mse.ingress.kubernetes.io/route-limit-burst-multiplier Ingress MSE拓展 瞬时最大请求次数的因子，默认为5。
  • 后端服务使用的协议
    注解 作用域 支持度 说明
    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地址块，以英文逗号分隔。
    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/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的更多信息，请参见官方文档。