v5cn/ingress-nginx-controller

ingress-nginx controller:v0.46.0 镜像文档

镜像概述

k8s.gcr.io/ingress-nginx/controller:v0.46.0 是 ingress-nginx 项目的核心控制器组件，用于实现 Kubernetes Ingress 资源定义的外部流量路由规则。作为 Kubernetes 集群的"流量入口网关"，该镜像版本（v0.46.0）提供了稳定的 Ingress 资源解析与流量控制能力，是连接集群外部请求与内部服务的关键桥梁。

核心功能与特性

流量路由与负载均衡

• 基于 HTTP/HTTPS 协议的请求路由，支持按主机名（Host）、路径（Path）匹配规则
• 集成负载均衡能力，支持轮询（Round Robin）、IP 哈希（IP Hash）等分发策略
• 支持后端 Service 动态发现，自动适配 Pod 扩缩容场景

安全与加密

• SSL/TLS 终止：支持配置证书实现 HTTPS 加密，卸载后端服务的 SSL 处理压力
• 支持 HTTP 到 HTTPS 的自动重定向（通过 annotation 配置）
• 可集成外部认证服务（如 OAuth2、JWT）实现请求鉴权（需配合第三方插件）

高级流量控制

• 路径重写（Rewrite Target）、请求头/响应头修改
• 会话亲和性（Session Affinity）：基于 Cookie 保持客户端与后端 Pod 的会话绑定
• 速率限制（Rate Limiting）：通过 annotation 配置请求频率限制

可观测性与可靠性

• 内置健康检查机制，自动剔除异常后端 Pod
• 暴露 Prometheus 监控指标（如请求量、响应时间、错误率）
• 详细访问日志记录，支持日志格式自定义

使用场景

• 微服务架构入口：作为集群内多微服务的统一访问入口，通过 Ingress 规则路由不同服务请求
• Web 应用发布：为集群内 Web 应用提供域名访问能力，配置 SSL 证书实现 HTTPS 部署
• API 网关功能：实现 API 请求的路径路由、版本控制、跨域资源共享（CORS）配置
• 多环境隔离：通过不同 Host 或路径规则区分开发、测试、生产环境的服务入口

使用方法与配置说明

部署方式

1. 基于官方 Manifest 部署

通过 kubectl 应用官方提供的部署清单（需提前准备 RBAC 权限、ConfigMap 等依赖资源）：

bash
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v0.46.0/deploy/static/provider/cloud/deploy.yaml

2. Helm Chart 部署

使用 Helm 安装（需添加 ingress-nginx 仓库）：

bash
helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm install ingress-nginx ingress-nginx/ingress-nginx --version 3.34.0  # v3.34.0 对应控制器 v0.46.0

基础配置示例

Ingress 资源定义

创建 Ingress 资源以定义路由规则（以下为基本 HTTP 路由示例）：

yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: minimal-ingress
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /$2  # 路径重写配置
spec:
  ingressClassName: nginx  # 指定使用 ingress-nginx 控制器
  rules:
  - host: api.example.com  # 匹配主机名
    http:
      paths:
      - path: /service-a(/|$)(.*)  # 匹配路径前缀
        pathType: Prefix
        backend:
          service:
            name: service-a  # 目标后端服务名
            port:
              number: 80  # 目标服务端口
  - host: web.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: web-service
            port:
              number: 80

SSL 配置示例

通过 secretName 指定 TLS 证书（需提前创建包含证书和私钥的 Secret）：

yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: tls-ingress
spec:
  ingressClassName: nginx
  tls:
  - hosts:
    - secure.example.com
    secretName: example-tls-secret  # 包含 TLS 证书的 Secret 名称
  rules:
  - host: secure.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: secure-service
            port:
              number: 443

核心配置参数

通过 Ingress Annotation 配置

通过 ConfigMap 全局配置

控制器支持通过名为 ingress-nginx-controller 的 ConfigMap 调整全局参数（部分示例）：

yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: ingress-nginx-controller
  namespace: ingress-nginx
data:
  proxy-connect-timeout: "10s"  # 与后端服务的连接超时时间
  client-body-buffer-size: "1m"  # 客户端请求体缓冲区大小
  log-format-upstream: '$remote_addr [$time_local] "$request" $status $request_time "$http_referer" "$http_user_agent"'  # 自定义上游日志格式

兼容性说明

• 支持 Kubernetes 版本：1.16+（建议使用 1.18+ 以获得最佳兼容性）
• Ingress API 版本：支持 networking.k8s.io/v1、networking.k8s.io/v1beta1（v1beta1 已逐步废弃，推荐使用 v1）
• 运行时依赖：需配合 ingress-nginx/admission-webhook 及 ingress-nginx/defaultbackend 组件使用（部署清单中已包含）

注：完整配置参数及使用细节请参考 https://github.com/kubernetes/ingress-nginx/releases/tag/controller-v0.46.0%E3%80%82