dyrnq/ingress-nginx-controller

Ingress-NGINX Controller 镜像文档

一、镜像概述和主要用途

1.1 概述

ingress-nginx/controller 是 Kubernetes 官方维护的 Ingress 控制器实现，基于 NGINX 构建，用于管理 Kubernetes 集群的入站流量。该镜像提供了 NGINX 反向代理与 Kubernetes API 的集成能力，支持通过 Kubernetes Ingress 资源定义 HTTP/HTTPS 路由规则，实现集群内服务的外部访问控制。

1.2 官方镜像仓库

该镜像通过以下官方仓库提供（不同仓库内容一致，可根据网络环境选择）：

• registry.k8s.io/ingress-nginx/controller（Kubernetes 官方镜像仓库，推荐）
• k8s.gcr.io/ingress-nginx/controller（GCR 镜像仓库）
• quay.io/kubernetes-ingress-controller/nginx-ingress-controller（Quay 镜像仓库）

二、核心功能和特性

2.1 流量路由

• HTTP/HTTPS 路由：基于域名、路径、请求头匹配流量，转发至集群内服务。
• 路径重写：支持修改请求路径（如 /api/v1/* 重写为 /v1/*）。
• 虚拟主机：通过 host 字段区分多域名路由规则。

2.2 安全与加密

• SSL/TLS 终止：支持自动配置 SSL 证书（需配合 cert-manager 等工具），终止 HTTPS 连接并转发 HTTP 流量至后端服务。
• HTTPS 重定向：强制将 HTTP 请求重定向至 HTTPS。
• 客户端证书验证：支持通过 nginx.ingress.kubernetes.io/auth-tls-verify-client 配置客户端证书验证。

2.3 负载均衡与高可用

• 负载均衡策略：支持轮询、IP 哈希（会话亲和性）、最少连接数等负载均衡算法。
• 健康检查：集成 NGINX 主动健康检查，自动剔除异常后端服务。
• 动态配置更新：通过 Kubernetes API 监听 Ingress/Service 资源变化，实时更新 NGINX 配置，无需重启。

2.4 扩展性与定制化

• 自定义 NGINX 配置：通过 nginx.ingress.kubernetes.io/configuration-snippet 注解注入原生 NGINX 配置片段。
• 插件支持：集成 ModSecurity WAF、Lua 脚本扩展等高级功能。
• 监控集成：暴露 Prometheus 指标接口（默认端口 ***），支持流量、错误率、响应时间等指标采集。

三、使用场景和适用范围

3.1 适用场景

• Kubernetes 集群统一入口：为集群内多服务提供单一访问域名/IP。
• 生产环境流量控制：需 SSL 终止、负载均衡、路径路由的生产级部署。
• 微服务架构路由：按路径或子域名路由至不同微服务（如 api.example.com 路由至 API 服务，web.example.com 路由至前端服务）。
• 多租户隔离：通过 IngressClass 区分不同租户/环境的流量规则。

3.2 环境要求

• Kubernetes 集群版本：v1.24+（与控制器版本匹配，具体参考 https://kubernetes.github.io/ingress-nginx/%EF%BC%89%E3%80%82
• 网络插件：支持 Service 类型为 NodePort 或 LoadBalancer（取决于集群网络配置）。

四、使用方法和配置说明

4.1 部署前准备

• 已部署 Kubernetes 集群（v1.24+）。
• kubectl 工具已配置集群访问权限。

4.2 部署方法

4.2.1 官方 YAML 部署（推荐）

通过 Kubernetes 官方提供的静态 YAML 文件部署，自动创建 Deployment、Service、ConfigMap 等资源：

bash
# 部署最新稳定版（请替换为官方最新版本链接）
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.8.2/deploy/static/provider/cloud/deploy.yaml

版本说明：访问 https://github.com/kubernetes/ingress-nginx/releases 获取最新版本的 YAML 链接。

4.2.2 Helm Chart 部署

通过 Helm 快速部署，支持自定义配置：

bash
# 添加 Helm 仓库
helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update

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

4.2.3 Docker 容器直接运行（仅测试用）

注意：该方式仅用于本地测试，生产环境需通过 Kubernetes 部署以确保与集群集成。

bash
docker run -d \
  --name ingress-nginx-controller \
  --net=host \  # 需与主机网络共享（模拟 NodePort 场景）
  -v /var/run/kubernetes.sock:/var/run/kubernetes.sock \  # 挂载 K8s API 套接字
  -e POD_NAME=test-pod \
  -e POD_NAMESPACE=default \
  registry.k8s.io/ingress-nginx/controller:v1.8.2 \
  /nginx-ingress-controller \
  --default-backend-service=default/nginx-default-backend \
  --ingress-class=nginx

4.3 路由规则配置（Ingress 资源）

通过 Kubernetes Ingress 资源定义路由规则，示例如下：

4.3.1 基本 HTTP 路由

将 example.com/app 路由至 app-service:80，example.com/api 路由至 api-service:80：

yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: basic-ingress
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /$2  # 路径重写（移除 /app 前缀）
spec:
  ingressClassName: nginx  # 指定 IngressClass（需与控制器配置匹配）
  rules:
  - host: example.com
    http:
      paths:
      - path: /app(/|$)(.*)
        pathType: Prefix
        backend:
          service:
            name: app-service
            port:
              number: 80
      - path: /api
        pathType: Prefix
        backend:
          service:
            name: api-service
            port:
              number: 80

4.3.2 HTTPS 路由（SSL 终止）

配合 cert-manager 自动签发 Let's Encrypt 证书，实现 HTTPS 访问：

yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: https-ingress
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod  # cert-manager 集群签发者
    nginx.ingress.kubernetes.io/ssl-redirect: "true"  # HTTP 重定向至 HTTPS
spec:
  ingressClassName: nginx
  tls:
  - hosts:
    - example.com
    secretName: example-tls  # 存储证书的 Secret（由 cert-manager 自动创建）
  rules:
  - host: example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: web-service
            port:
              number: 80

4.4 控制器配置参数

4.4.1 全局配置（ConfigMap）

通过 ingress-nginx-controller ConfigMap 配置 NGINX 全局参数（默认位于 ingress-nginx 命名空间）：

yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: ingress-nginx-controller
  namespace: ingress-nginx
data:
  worker-processes: "auto"  # NGINX worker 进程数（默认 auto）
  keepalive-timeout: "65"   # 客户端连接超时时间（秒）
  proxy-body-size: "10m"    # 允许的请求体最大尺寸

4.4.2 命令行参数与环境变量

控制器启动参数可通过 Deployment 的 args 字段配置，常用参数：

环境变量（部分由 Kubernetes 自动注入）：

4.5 监控与日志

4.5.1 查看控制器日志

bash
kubectl logs -n ingress-nginx deployment/ingress-nginx-controller -f

4.5.2 Prometheus 监控

控制器默认暴露 metrics 接口（端口 ***），Prometheus 配置示例：

yaml
scrape_configs:
- job_name: 'ingress-nginx'
  static_configs:
  - targets: ['ingress-nginx-controller.ingress-nginx.svc:10254']

五、升级与回滚

5.1 升级控制器

通过官方 YAML 或 Helm 升级：

bash
# YAML 方式（替换为新版本链接）
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.8.3/deploy/static/provider/cloud/deploy.yaml

# Helm 方式
helm upgrade ingress-nginx ingress-nginx/ingress-nginx --namespace ingress-nginx

5.2 回滚

bash
# 回滚至前一版本 Deployment
kubectl rollout undo -n ingress-nginx deployment/ingress-nginx-controller

六、注意事项

1. 版本兼容性：控制器版本需与 Kubernetes 集群版本匹配（参考 https://kubernetes.github.io/ingress-nginx/%EF%BC%89%E3%80%82
2. 资源限制：根据流量规模调整控制器 Pod 的 CPU/内存资源（推荐至少 1 CPU 核、2GiB 内存）。
3. 安全加固：限制 hostNetwork 使用，通过 NetworkPolicy 隔离控制器 Pod，避免暴露敏感端口。