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

©著作权归作者所有,转载或内容合作请联系作者
  • 人面猴
    序言：七十年代末，一起剥皮案震惊了整个滨河市，随后出现的几起案子，更是在滨河造成了极大的恐慌，老刑警刘岩，带你破解...
    沈念sama阅读 216,591评论 6赞 501
  • 死咒
    序言：滨河连续发生了三起死亡事件，死亡现场离奇诡异，居然都是意外死亡，警方通过查阅死者的电脑和手机，发现死者居然都...
    沈念sama阅读 92,448评论 3赞 392
  • 救了他两次的神仙让他今天三更去死
    文/潘晓璐 我一进店门，熙熙楼的掌柜王于贵愁眉苦脸地迎上来，“玉大人，你说我怎么就摊上这事。” “怎么了？”我有些...
    开封第一讲书人阅读 162,823评论 0赞 353
  • 道士缉凶录：失踪的卖姜人
    文/不坏的土叔 我叫张陵，是天一观的道长。 经常有香客问我，道长，这世上最难降的妖魔是什么？ 我笑而不...
    开封第一讲书人阅读 58,204评论 1赞 292
  • 港岛之恋（遗憾婚礼）
    正文 为了忘掉前任，我火速办了婚礼，结果婚礼上，老公的妹妹穿的比我还像新娘。我一直安慰自己，他们只是感情好，可当我...
    茶点故事阅读 67,228评论 6赞 388
  • 恶毒庶女顶嫁案：这布局不是一般人想出来的
    文/花漫 我一把揭开白布。 她就那样静静地躺着，像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上，一...
    开封第一讲书人阅读 51,190评论 1赞 299
  • 城市分裂传说
    那天，我揣着相机与录音，去河边找鬼。 笑死，一个胖子当着我的面吹牛，可吹牛的内容都是我干的。 我是一名探鬼主播，决...
    沈念sama阅读 40,078评论 3赞 418
  • 双鸳鸯连环套：你想象不到人心有多黑
    文/苍兰香墨 我猛地睁开眼，长吁一口气：“原来是场噩梦啊……” “哼！你这毒妇竟也来了？” 一声冷哼从身侧响起，我...
    开封第一讲书人阅读 38,923评论 0赞 274
  • 万荣杀人案实录
    序言：老挝万荣一对情侣失踪，失踪者是张志新（化名）和其女友刘颖，没想到半个月后，有当地人在树林里发现了一具尸体，经...
    沈念sama阅读 45,334评论 1赞 310
  • 护林员之死
    正文 独居荒郊野岭守林人离奇死亡，尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 37,550评论 2赞 333
  • 白月光启示录
    正文 我和宋清朗相恋三年，在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 39,727评论 1赞 348
  • 活死人
    序言：一个原本活蹦乱跳的男人离奇死亡，死状恐怖，灵堂内的尸体忽然破棺而出，到底是诈尸还是另有隐情，我是刑警宁泽，带...
    沈念sama阅读 35,428评论 5赞 343
  • 日本核电站爆炸内幕
    正文 年R本政府宣布，位于F岛的核电站，受9级特大地震影响，放射性物质发生泄漏。R本人自食恶果不足惜，却给世界环境...
    茶点故事阅读 41,022评论 3赞 326
  • 男人毒药：我在死后第九天来索命
    文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹，春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 31,672评论 0赞 22
  • 一桩弑父案，背后竟有这般阴谋
    文/苍兰香墨 我抬头看了看天上的太阳。三九已至，却和暖如春，着一层夹袄步出监牢的瞬间，已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 32,826评论 1赞 269
  • 情欲美人皮
    我被黑心中介骗来泰国打工， 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留，地道东北人。 一个月前我还...
    沈念sama阅读 47,734评论 2赞 368
  • 代替公主和亲
    正文 我出身青楼，却偏偏与公主长得像，于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子，可洞房花烛夜当晚...
    茶点故事阅读 44,619评论 2赞 354

推荐阅读更多精彩内容