首页 容器服务 ACK Serverless容器集群ASK 网络 MSE Ingress管理 MSE Ingress支持的Annotation

MSE Ingress支持的Annotation

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为正则匹配。

    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流量切分。

    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/mirror-target-service

    Ingress

    MSE扩展

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

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

    • name：K8s Service的名称，必选。

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

  • 单机限流

    注解

    作用域

    支持度

    说明

    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/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的更多信息，请参见官方文档。

阿里云首页 容器服务 ACK 相关技术圈