文档

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/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 兼容 预检结果的最大缓存时间

重试

注解 作用域 支持度 说明
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 兼容 请求重试条件,参考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

Cookie亲和性

注解 作用 支持度 说明
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-range Ingress 兼容 指定路由上的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-type Ingress 部分兼容。暂只支持Basic。 认证类型
nginx.ingress.kubernetes.io/auth-secret Ingress 兼容 Secret名字,格式支持/,包含被授予能够访问该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的更多信息,请参阅官方文档(https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#annotations)。