首页/云/Kubernetes 速查/ingress-nginx 常用注解
网络与服务55 条

ingress-nginx 常用注解

nginx 控制器通过注解精细控制行为:路径重写、请求体大小、超时、后端协议等;注解写错不报错但行为不符合预期。

Kubernetes 速查云更新于 2026-10-12

常用注解示例

常用注解示例
metadata:
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
    nginx.ingress.kubernetes.io/use-regex: "true"
    nginx.ingress.kubernetes.io/proxy-body-size: "50m"
    nginx.ingress.kubernetes.io/proxy-read-timeout: "120"
    nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
    nginx.ingress.kubernetes.io/force-ssl-redirect: "true"

注解速查

注解作用
rewrite-target重写转发路径(常配 use-regex)
proxy-body-size允许的请求体上限(上传/大 JSON)
proxy-read-timeout后端读取超时(长轮询/流式)
backend-protocol转发到后端的协议 HTTP/HTTPS/GRPC
force-ssl-redirectHTTP 强制跳 HTTPS
rewrite-target 与 pathType Prefix 组合时语义微妙,先在小流量域名验证重写结果。

易错点

  • 注解值必须是字符串,YAML 里写 true 而不加引号可能被转成布尔导致失效
  • 不同控制器(traefik/HAProxy)注解完全不通用,迁移要逐条翻译

数据来源与参考

  • ingress-nginx 官方文档 · Annotations
​‌‌​​‌​​​‌‌​‌‌‌‌​‌‌​​​‌‌​‌‌‌​​‌‌​​‌​‌‌‌​​‌‌‌​​​‌​‌‌​‌​​‌​‌‌‌​​​‌​‌‌​‌​​‌​‌‌​​​‌‌​‌‌‌​‌​​​‌‌​‌‌‌‌​​‌​‌‌‌​​‌‌​​​‌‌​‌‌​‌‌‌‌​‌‌​‌‌​‌