当前位置：首页 > 问答 > 正文

K8s里Nginx Ingress那些Annotation配置，平时用过几个你真懂吗？

盘雅霜
问答
2025-12-30 19:49:26
3

（来源：K8s运维实践社区）直接开始：

“上回有个同事问我，为什么Nginx Ingress的annotation配置写了总是不生效？我让他把yaml发过来一看，好家伙，annotations缩进错了，直接跟spec平级了！这玩意儿看似简单，但里面门道真不少，今天咱就捞干的说,这些annotation可不是随便写写就完事的。

先说最常用的kubernetes.io/ingress.class（来源：Nginx Ingress Controller官方文档），现在这注解其实有点过时了，新版本推荐用ingressClassName字段，但老项目里遍地都是，它的作用就一句话：告诉K8s集群，‘这个Ingress规则归Nginx管，别的Ingress Controller别插手！’比如你集群里同时装了Nginx和Traefik两种控制器，要是没这个注解，俩控制器可能都会来抢这个Ingress资源，那就乱套了，一般就这么写：annotations: kubernetes.io/ingress.class: "nginx"，但你得先确认你的Nginx Ingress Controller启动时有没有设置--ingress-class参数,两边得对上号才行。

接着是扛流量必备的nginx.ingress.kubernetes.io/limit-rpm（来源：Nginx Ingress限流配置文档），这可不是限制转速啊，是每分钟请求数（Requests Per Minute），曾经有个血泪教训：有个新服务上线，忘了配这个，结果被爬虫狂刷，直接把后端Pod全打挂了，配置起来很简单：nginx.ingress.kubernetes.io/limit-rpm: "1000"，意思是同一个IP地址一分钟内最多允许1000个请求，超了怎么办？Nginx直接返回503错误，保护后端服务，但这里有个坑：它默认是基于客户端IP限流的，如果用户都通过同一个NAT网关出口访问，那就变成整个公司共享这个额度了，这时候得结合nginx.ingress.kubernetes.io/limit-rps（每秒请求数）和nginx.ingress.kubernetes.io/limit-connections（并发连接数）一起用。

K8s里Nginx Ingress那些Annotation配置，平时用过几个你真懂吗？

重头戏来了：nginx.ingress.kubernetes.io/rewrite-target（来源：Nginx Ingress路径重写案例），这个十个里有八个会踩坑，比如你的服务API路径是/api/v1/users，但你想让用户通过/gateway/users来访问,很多人会这么写：

annotations:
  nginx.ingress.kubernetes.io/rewrite-target: /api/v1/$2

然后在path里写path: /gateway/(.*)，看着没问题对吧？但实际一访问就404，为啥？因为rewrite-target这个值里的$1、$2对应的是path里正则表达式捕获组的位置，上面例子中是第一个捕获组，所以应该用$1，不是$2！更坑的是，不同版本的Nginx Ingress Controller对正则语法要求还不一样，老版本用开头表示正则,新版本直接path里写正则就行。

K8s里Nginx Ingress那些Annotation配置，平时用过几个你真懂吗？

还有个小而美的nginx.ingress.kubernetes.io/app-root（来源：社区实践分享），比如你的应用根路径是/admin，但你想让用户访问域名abc.com直接跳转到abc.com/admin，一行注解搞定：nginx.ingress.kubernetes.io/app-root: /admin，比写一堆重写规则清爽多了，不过注意，这会产生302重定向,前端要是跨域还得额外处理。

说到跨域，nginx.ingress.kubernetes.io/enable-cors（来源：Nginx Ingress跨域配置指南）必须拥有姓名，设为"true"就自动给你加上一堆CORS头，但生产环境千万别只开这个就完事了，得配合nginx.ingress.kubernetes.io/cors-allow-origin指定具体域名，比如https://www.xxx.com，不然就等于允许所有域名跨域访问,安全漏洞妥妥的。

最后提个监控相关的nginx.ingress.kubernetes.io/server-snippet（来源：运维监控实战），这个注解允许你在Nginx的server配置块里插入自定义配置，我们曾经用它来解决一个诡异问题：某个服务响应慢，但查日志啥都没有，后来在server-snippet里加了proxy_pass_request_headers on;和自定义日志格式，把上游响应时间全打出来，才发现是某个第三方接口偶尔超时,配置长这样：

annotations:
  nginx.ingress.kubernetes.io/server-snippet: |
    location /log {
      access_log /var/log/nginx/slow.log custom_format;
      proxy_pass http://backend;
    }

但用这个要特别小心,写错了可能导致整个Ingress配置失效。

其实这些annotation本质就是Nginx配置的‘快捷方式’，真正想玩得转，最好还是懂点Nginx原生配置，不然就像我那个同事，注解写错位置了还死活查不出原因，最后发现是缩进两个空格和四个空格混用了——YAML的坑，那又是另一个故事了。”