Kubernetes Ingress-Nginx 注解配置全解析
项目地址: https://gitcode.com/GitHub_Trending/in/ingress-nginx 前言
在 Kubernetes 集群中使用 Ingress-Nginx 作为入口控制器时，注解(Annotations)是配置 Ingress 资源行为的重要方式。本文将全面解析 Ingress-Nginx 支持的各种注解及其使用场景，帮助开发者更好地控制流量路由、安全认证、会话保持等关键功能。
注解基础概念
注解是 Kubernetes 中为资源添加元数据的键值对，在 Ingress-Nginx 中，注解用于定制 Ingress 对象的行为。使用时需要注意：
- 所有注解的键和值都必须是字符串类型
- 布尔值或数字必须用引号包裹，如
"true"、"100" - 默认注解前缀为
nginx.ingress.kubernetes.io/，可通过命令行参数修改
核心注解分类解析
1. 金丝雀发布(Canary)
金丝雀发布是一种渐进式发布策略，允许将少量流量导向新版本服务进行测试。相关注解：
nginx.ingress.kubernetes.io/canary: "true" # 启用金丝雀
nginx.ingress.kubernetes.io/canary-by-header: "X-Canary" # 基于请求头路由
nginx.ingress.kubernetes.io/canary-by-header-value: "test" # 指定头值匹配
nginx.ingress.kubernetes.io/canary-by-cookie: "canary" # 基于Cookie路由
nginx.ingress.kubernetes.io/canary-weight: "30" # 流量权重(0-100)
评估优先级：请求头 > Cookie > 权重
注意事项：
- 每个 Ingress 规则最多应用一个金丝雀配置
- 启用金丝雀后，大部分非金丝雀注解会被忽略
2. 路径重写(Rewrite)
当后端服务暴露的 URL 与 Ingress 规则中指定的路径不同时，需要使用重写功能：
nginx.ingress.kubernetes.io/rewrite-target: /newpath # 重写目标路径
nginx.ingress.kubernetes.io/app-root: /app # 应用根路径重定向
3. 会话保持(Session Affinity)
确保用户请求始终路由到同一后端服务器：
nginx.ingress.kubernetes.io/affinity: "cookie" # 目前仅支持cookie方式
nginx.ingress.kubernetes.io/affinity-mode: "balanced" # balanced或persistent
nginx.ingress.kubernetes.io/session-cookie-name: "MYCOOKIE" # 自定义cookie名
Cookie 高级配置：
nginx.ingress.kubernetes.io/session-cookie-expires: "3600" # 过期时间(秒)
nginx.ingress.kubernetes.io/session-cookie-samesite: "Lax" # SameSite属性
nginx.ingress.kubernetes.io/session-cookie-change-on-failure: "true" # 失败后变更
4. 认证配置(Authentication)
支持多种认证方式：
基础认证(Basic/Digest)
nginx.ingress.kubernetes.io/auth-type: "basic" # basic或digest
nginx.ingress.kubernetes.io/auth-secret: "basic-auth" # 包含用户密码的Secret
nginx.ingress.kubernetes.io/auth-realm: "Authentication Required" # 认证域提示
客户端证书认证
nginx.ingress.kubernetes.io/auth-tls-secret: "ca-secret" # CA证书
nginx.ingress.kubernetes.io/auth-tls-verify-client: "on" # 开启客户端验证
外部认证
nginx.ingress.kubernetes.io/auth-url: "http://auth-service/auth" # 认证服务URL
nginx.ingress.kubernetes.io/auth-cache-duration: "200 202 10m" # 认证缓存
5. 跨域配置(CORS)
nginx.ingress.kubernetes.io/enable-cors: "true" # 启用CORS
nginx.ingress.kubernetes.io/cors-allow-methods: "GET, PUT, POST" # 允许方法
nginx.ingress.kubernetes.io/cors-allow-origin: "*" # 允许来源
nginx.ingress.kubernetes.io/cors-max-age: "600" # 预检请求缓存时间
6. 流量控制
限流配置
nginx.ingress.kubernetes.io/limit-connections: "100" # 并发连接数限制
nginx.ingress.kubernetes.io/limit-rps: "50" # 每秒请求数限制
代理参数
nginx.ingress.kubernetes.io/proxy-body-size: "20m" # 请求体大小限制
nginx.ingress.kubernetes.io/proxy-connect-timeout: "30" # 连接超时(秒)
nginx.ingress.kubernetes.io/proxy-read-timeout: "60" # 读取超时
7. SSL/TLS 配置
nginx.ingress.kubernetes.io/ssl-redirect: "true" # HTTP强制跳转HTTPS
nginx.ingress.kubernetes.io/ssl-passthrough: "false" # SSL透传
nginx.ingress.kubernetes.io/ssl-ciphers: "HIGH:!aNULL:!MD5" # 加密套件
高级功能注解
自定义Nginx配置片段
nginx.ingress.kubernetes.io/server-snippet: |
if ($host = 'example.com') {
return 301 https://www.example.com;
}
nginx.ingress.kubernetes.io/configuration-snippet: |
more_set_headers "X-Custom-Header: Value";
黑白名单控制
nginx.ingress.kubernetes.io/whitelist-source-range: "192.168.0.0/24" # 白名单
nginx.ingress.kubernetes.io/denylist-source-range: "10.0.0.0/8" # 黑名单
ModSecurity Web应用防火墙
nginx.ingress.kubernetes.io/enable-modsecurity: "true" # 启用ModSecurity
nginx.ingress.kubernetes.io/enable-owasp-core-rules: "true" # 启用OWASP核心规则
最佳实践建议
- 合理使用注解前缀：如需自定义前缀，确保集群内统一
- 注解值类型处理：特别注意布尔值和数字必须加引号
- 会话保持权衡：
balanced模式适合大多数场景，persistent模式提供最高粘性 - 金丝雀发布策略：建议先使用权重方式，再逐步过渡到头/Cookie方式
- 安全配置：生产环境应避免使用宽松的CORS配置和弱加密套件
总结
Ingress-Nginx 的注解系统提供了强大的流量控制能力，从基础的重定向、负载均衡到高级的金丝雀发布、WAF 防护等。合理运用这些注解可以构建出既灵活又稳定的入口层配置。建议开发者根据实际需求选择合适的注解组合，并通过逐步验证确保配置的正确性。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
