ingress-nginx常用注解指南
前言
k8s ingress-nginx是个好东西，而如何用好ingress-nginx，抛开运维这块不说，对于ingress-nginx annotations掌握的好坏，决定了你在日常开发是否能使用好ingress-nginx ，因为ingress-nginx大部分能力都可以通过配置annotations实现出来。今天这篇文章主要是对ingress-nginx annotations一些常用功能做个分类，便于大家查阅
正文
流量治理
1、灰度发布
注解 | 说明 |
nginx.ingress.kubernetes.io/canary | 开启或关闭灰度发布 |
nginx.ingress.kubernetes.io/canary-by-header | 基于Request Header Key 流量切分 |
nginx.ingress.kubernetes.io/canary-by-header-value | 基于Request Header Value 流量切分，Value为精确匹配 |
nginx.ingress.kubernetes.io/canary-by-header-pattern | 基于Request Header Value 流量切分，Value为正则匹配 |
nginx.ingress.kubernetes.io/canary-by-cookie | 基于Request Cookie Key 流量切分 |
nginx.ingress.kubernetes.io/canary-weight | 基于权重流量切分 |
nginx.ingress.kubernetes.io/canary-weight-total | 权重总和 |
注：灰度规则优先级由高到低：canary-by-header -> canary-by-cookie -> canary-weight
官方链接：https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#canary
官方配置示例：
https://kubernetes.github.io/ingress-nginx/examples/canary/
2、Fallback（容灾）
注解 | 说明 |
nginx.ingress.kubernetes.io/default-backend | 容灾服务。当Ingress定义的服务没有可用节点时，请求会自动转发该容灾服务。 |
nginx.ingress.kubernetes.io/custom-http-errors | 该注解和default-backend一起工作。当后端服务返回指定HTTP响应码，原始请求会被再次转发至容灾服务。注意：转发至容灾服务时，请求的Path会被重写为/，该行为与ingress-nginx保持一致 |
官方链接：https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#default-backend
官方配置示例：https://kubernetes.github.io/ingress-nginx/examples/customization/custom-errors/
3、重写
注解 | 说明 |
nginx.ingress.kubernetes.io/rewrite-target | 将Ingress定义的原path重写为指定目标，支持Group Capture. |
nginx.ingress.kubernetes.io/upstream-vhost | 匹配Ingress定义的路由的请求在转发给后端服务时，修改头部host值为指定值。 |
官方链接：https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#rewrite
官方配置示例：https://kubernetes.github.io/ingress-nginx/examples/rewrite/
4、重定向
注解 | 说明 |
nginx.ingress.kubernetes.io/ssl-redirect | HTTP 重定向为HTTPS |
nginx.ingress.kubernetes.io/force-ssl-redirect | HTTP 重定向为HTTPS |
nginx.ingress.kubernetes.io/permanent-redirect | 永久重定向 |
nginx.ingress.kubernetes.io/permanent-redirect-code | 永久重定向状态码 |
nginx.ingress.kubernetes.io/temporal-redirect | 临时重定向 |
nginx.ingress.kubernetes.io/app-root | 修改应用根路径，对于访问/的请求将会被重定向为设置的新路径 |
官方链接：https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#server-side-https-enforcement-through-redirect
配置示例：https://docs.daocloud.io/network/modules/ingress-nginx/redirect/#_2
5、跨域
注解 | 说明 |
nginx.ingress.kubernetes.io/enable-cors | 开启或关闭跨域 |
nginx.ingress.kubernetes.io/cors-allow-origin | 允许的第三方站点 |
nginx.ingress.kubernetes.io/cors-allow-methods | 允许的请求方法，如GET、POST、PUT等 |
nginx.ingress.kubernetes.io/cors-allow-headers | 允许的请求Header |
nginx.ingress.kubernetes.io/cors-expose-headers | 允许的暴露给浏览器的响应Header |
nginx.ingress.kubernetes.io/cors-allow-credentials | 是否允许携带凭证信息 |
nginx.ingress.kubernetes.io/cors-max-age | 预检结果的最大缓存时间 |
官方链接：https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#enable-cors
官方配置示例：https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#enable-cors
6、重试
注解 | 说明 |
nginx.ingress.kubernetes.io/proxy-next-upstream-tries | 请求的最大重试次数。默认3次。 |
nginx.ingress.kubernetes.io/proxy-next-upstream-timeout | 请求重试的超时时间，单位秒。默认未配置超时时间。 |
nginx.ingress.kubernetes.io/proxy-next-upstream | 请求重试条件，参考：http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_next_upstream |
官方链接：https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#custom-timeouts
配置示例：https://docs.daocloud.io/network/modules/ingress-nginx/timeout/#_3
7、后端服务使用的协议
注解 | 说明 |
nginx.ingress.kubernetes.io/backend-protocol | 指定后端服务使用的协议，默认为HTTP，支持HTTP、HTTP2、HTTPS、GRPC和GRPCS |
官方链接：https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#backend-protocol
官方配置示例：https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#backend-protocol
8、负载均衡
注解 | 说明 |
nginx.ingress.kubernetes.io/load-balance | 后端服务的普通负载均衡算法。默认为round_robin。合法值如下：round_robin：基于轮询的负载均衡;least_conn：基于最小请求数的负载均衡;random：基于随机的负载均衡。 |
nginx.ingress.kubernetes.io/upstream-hash-by | 基于一致Hash的负载均衡算法 |
官方链接：https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#custom-nginx-load-balancing
配置示例：https://docs.daocloud.io/network/modules/ingress-nginx/proxy/#_5
9、Cookie亲和性
注解 | 说明 |
nginx.ingress.kubernetes.io/affinity | 亲和性种类，目前只支持cookie，默认为cookie。 |
nginx.ingress.kubernetes.io/affinity-mode | 亲和性模式，默认为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会话级别。 |
官方链接：https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#session-affinity
官方配置示例：https://kubernetes.github.io/ingress-nginx/examples/affinity/cookie/
10、IP访问控制
注解 | Col2 |
nginx.ingress.kubernetes.io/whitelist-source-range | 指定路由上的IP白名单，支持IP地址或CIDR地址块，以逗号分隔。 |
官方链接：https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#whitelist-source-range
官方配置示例：https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#whitelist-source-range
11、镜像流量
注解 | 说明 |
nginx.ingress.kubernetes.io/mirror-target | 指定流量目标地址。支持 Service 和外部地址，例如设置为 https://test.env.com/$request_uri，$request_uri可以选择将原始请求的 URI 添加到目标 URL 的末尾。 |
nginx.ingress.kubernetes.io/mirror-request-body | 是否镜像请求流量的 Body |
nginx.ingress.kubernetes.io/mirror-host | 指定用于转发请求 Host 信息 |
官方链接：https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#mirror
官方配置示例：https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#mirror
安全防护
1、客户端与网关之前的通信加密
注解 | 说明 |
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 | 网关使用的CA证书，用于验证MTLS握手期间，客户端提供的证书。该注解主要应用于网关需要验证客户端身份的场景 |
官方链接：https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#ssl-ciphers
官方配置示例：https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#ssl-ciphers
2、网关与后端服务之间通信加密
注解 | 说明 |
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 |
官方链接：https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#backend-certificate-authentication
官方示例配置：https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#backend-certificate-authentication
3、Basic认证
注解 | 说明 |
nginx.ingress.kubernetes.io/auth-type | 认证类型 |
nginx.ingress.kubernetes.io/auth-secret | Secret名字，格式支持/，包含被授予能够访问该Ingress上定义的路由的访问权限的用户名和密码。 |
nginx.ingress.kubernetes.io/auth-secret-type | Secret内容格式。auth-file：data的key为auth；value为用户名和密码，多帐号回车分隔;auth-map：data的key为用户名；value为密码 |
nginx.ingress.kubernetes.io/auth-realm | 保护域。相同的保护域共享用户名和密码。 |
官方配置：https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#authentication
官方配置示例：https://kubernetes.github.io/ingress-nginx/examples/auth/basic/
总结
本文的大部分分类是来自阿里的higress官方文档，但因higress annotations大部分都和ingress-nginx annotations兼容，因此我就站在巨人的肩膀上做了一下调整。其次本文涵盖了大部分ingress-nginx，剩余的部分，大家可以直接去官网查阅
参考链接
https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#annotations
https://higress.io/zh-cn/docs/user/annotation.html