Ingress Annotation 配置说明

Ingress Annotaion 配置说明

标准的K8s Ingress资源只能处理简单场景下的HTTP(S)流量路由,无法处理流量切分,超时重试,Header控制和跨域等问题。因此,不同的Ingress Controller利用自定义的Ingress Annotation增强Ingress能力。常见的Nginx Ingress Controller引入了100多个Annotation对Ingress在流量治理和安全防护上进行了扩展实现。目前,Higress已经全面兼容了大部分Nginx Ingress Annotation,方便用户从Nginx Ingress无缝迁移至Higress,本文主要介绍Higress关于Ingress Annotation的配置说明。

Ingress Annotation

特殊说明

Annotation Key 前缀

以下出现的Nginx Ingress Annotation都已被Higress支持,您可以根据使用习惯继续使用Nginx Ingress的Annotation前缀nginx.ingress.kubernetes.io,或者使用Higress Ingress的Annotation前缀higress.io,两者是等价的。

作用域说明

  • Ingress:作用域为Ingress的Annotation的作用范围仅限当前Ingress上定义的路由规则。
  • 域名:作用域为域名的Annotation,其作用范围为所有Ingress上出现的相同Host。
  • 服务:作用域为服务的Annotation,其作用范围为所有Ingress上出现的相同Service。

流量治理

灰度发布

注解作用域支持度说明
nginx.ingress.kubernetes.io/canaryIngress兼容开启或关闭灰度发布
nginx.ingress.kubernetes.io/canary-by-headerIngress兼容基于Request Header Key 流量切分
nginx.ingress.kubernetes.io/canary-by-header-valueIngress兼容基于Request Header Value 流量切分,Value为精确匹配
nginx.ingress.kubernetes.io/canary-by-header-patternIngress兼容基于Request Header Value 流量切分,Value为正则匹配
nginx.ingress.kubernetes.io/canary-by-cookieIngress兼容基于Request Cookie Key 流量切分
nginx.ingress.kubernetes.io/canary-weightIngress兼容基于权重 流量切分
nginx.ingress.kubernetes.io/canary-weight-totalIngress兼容权重总和

Fallback(容灾)

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

重写

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

重定向

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

跨域

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

超时

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

单机限流

注解作用域支持度说明
higress.io/route-limit-rpmIngressHigress 扩展该Ingress定义的路由在每个网关实例上每分钟最大请求次数。瞬时最大请求次数为该值乘以limit-burst-multiplier。
higress.io/route-limit-rpsIngressHigress 扩展该Ingress定义的路由在每个网关实例上每秒最大请求次数。瞬时最大请求次数为该值乘以limit-burst-multiplier。
higress.io/route-limit-burst-multiplierIngressHigress 扩展瞬时最大请求次数的因子,默认为5。

重试

注解作用域支持度说明
nginx.ingress.kubernetes.io/proxy-next-upstream-triesIngress兼容请求的最大重试次数。默认3次。
nginx.ingress.kubernetes.io/proxy-next-upstream-timeoutIngress兼容请求重试的超时时间,单位秒。默认未配置超时时间。
nginx.ingress.kubernetes.io/proxy-next-upstreamIngress兼容请求重试条件,参考http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_next_upstream

后端服务使用的协议

注解作用域支持度说明
nginx.ingress.kubernetes.io/backend-protocol服务部分兼容。不支持AJP和FCGI指定后端服务使用的协议,默认为HTTP,支持HTTP、HTTP2、HTTPS、GRPC和GRPCS

负载均衡

注解作用域支持度说明
nginx.ingress.kubernetes.io/load-balance服务部分兼容。不支持ewma算法后端服务的普通负载均衡算法。默认为round_robin。
合法值如下:
- round_robin:基于轮询的负载均衡。
- least_conn:基于最小请求数的负载均衡。
- random:基于随机的负载均衡。
> 注意:Higress不支持ewma算法,若配置为ewma算法,会回退到round_robin算法。
nginx.ingress.kubernetes.io/upstream-hash-by服务部分兼容。暂不支持Nginx变量、常量的组合使用方式基于一致Hash的负载均衡算法,Higress支持以下几种形式:
1. Higress支持配置部分nginx变量:
- $request_uri:请求的Path(包括路径参数)作为Hash Key
- $host:请求的Host作为Hash Key
- $remote_addr:请求的客户端IP作为Hash Key。
2. 基于请求header的一致性Hash。您只需配置为$http_headerName。
3. 基于请求路径参数的一致性Hash。您只需配置为$arg_varName
注解作用支持度说明
nginx.ingress.kubernetes.io/affinity服务兼容亲和性种类,目前只支持cookie,默认为cookie。
nginx.ingress.kubernetes.io/affinity-mode服务部分兼容。暂不支持persistent模式亲和性模式,云原生网关目前只支持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-rangeIngress兼容指定路由上的IP白名单,支持IP地址或CIDR地址块,以逗号分隔。

安全防护

客户端与网关之前的通信加密

注解作用域支持度说明
nginx.ingress.kubernetes.io/ssl-cipher域名兼容指定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
nginx.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-typeIngress部分兼容。暂只支持Basic。认证类型
nginx.ingress.kubernetes.io/auth-secretIngress兼容Secret名字,格式支持<namespace>/<name>,包含被授予能够访问该Ingress上定义的路由的访问权限的用户名和密码。
nginx.ingress.kubernetes.io/auth-secret-typeIngress兼容Secret内容格式。
- auth-file:data的key为auth;value为用户名和密码,多帐号回车分隔
- auth-map:data的key为用户名;value为密码
nginx.ingress.kubernetes.io/auth-realmIngress兼容保护域。相同的保护域共享用户名和密码。

备注

关于以上提到的Nginx Ingress Annotation的更多信息,请参阅官方文档(https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#annotations)。