registry.k8s.io/ingress-nginx/controller 镜像文档

镜像概述

registry.k8s.io/ingress-nginx/controller 是Kubernetes官方维护的Ingress控制器镜像，基于NGINX反向代理实现。该镜像用于在Kubernetes集群中部署Ingress控制器，负责将集群外部的HTTP/HTTPS流量路由到集群内部的服务，是连接外部网络与Kubernetes服务的核心组件。

核心功能与特性

• 流量路由：基于主机名（Host）、路径（Path）、请求头（Header）等规则将外部请求路由至集群内指定服务
• SSL/TLS终结：处理HTTPS加密流量，支持自动证书管理（如Let's Encrypt集成）
• 负载均衡：对后端服务提供Round Robin、IP Hash等负载均衡策略
• 路径重写与重定向：支持URL路径重写、HTTP到HTTPS重定向等功能
• 请求限流与安全防护：提供基于请求速率的限流、WAF规则集成、IP黑白名单等安全控制
• 监控与可观测性：暴露Prometheus metrics指标，支持日志收集与分析
• 自定义配置：允许通过ConfigMap、Annotation等方式扩展NGINX配置

使用场景与适用范围

• Kubernetes集群外部流量入口：作为集群统一入口，管理所有外部HTTP/HTTPS访问
• 微服务架构API网关：为微服务提供路由分发、认证授权等网关能力
• 多环境流量隔离：通过主机名或路径区分开发、测试、生产环境流量
• Web应用负载均衡：为集群内Web应用提供高可用负载均衡能力
• SSL证书集中管理：统一处理集群内服务的HTTPS证书配置

使用方法与配置说明

部署方式

该镜像通常通过Kubernetes资源清单或Helm Chart部署，而非直接使用docker run命令运行。以下是常见部署方式：

1. 通过官方YAML部署

# 获取最新稳定版部署文件
kubectl apply -f [***]

2. 通过Helm Chart部署

# 添加Helm仓库
helm repo add ingress-nginx [***]
helm repo update

# 部署控制器（默认命名空间ingress-nginx）
helm install ingress-nginx ingress-nginx/ingress-nginx --namespace ingress-nginx --create-namespace

核心配置参数

环境变量

通过Pod的env字段配置，常用环境变量包括：

Ingress资源配置示例

创建Ingress资源定义路由规则：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: minimal-ingress
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /$1
spec:
  ingressClassName: nginx
  rules:
  - host: example.com
    http:
      paths:
      - path: /app1(/|$)(.*)
        pathType: Prefix
        backend:
          service:
            name: app1-service
            port:
              number: 80
      - path: /app2
        pathType: Prefix
        backend:
          service:
            name: app2-service
            port:
              number: 80
  tls:
  - hosts:
    - example.com
    secretName: example-tls-cert

扩展配置

通过ConfigMap自定义全局NGINX配置：

apiVersion: v1
kind: ConfigMap
metadata:
  name: ingress-nginx-controller
  namespace: ingress-nginx
data:
  proxy-body-size: "10m"  # 允许上传文件大小
  client-max-body-size: "10m"
  enable-underscores-in-headers: "true"  # 允许请求头包含下划线

注意事项

• 需确保集群已安装Kubernetes 1.19+版本（对应控制器v1.0+）
• 部署时需配置适当的Service类型（NodePort/Load***）以暴露控制器
• 高流量场景下建议调整资源请求（CPU/内存）配置
• 升级控制器前需参考官方升级指南，避免配置兼容性问题