nginx/nginx-ingress-operator

NGINX Ingress Operator

![项目状态: 活跃 – 项目已达到稳定可用状态，且正在积极开发中。]([***] !商业支持

镜像概述和主要用途

NGINX Ingress Operator 是一个 Kubernetes/OpenShift 组件，用于部署和管理一个或多个 https://github.com/nginx/kubernetes-ingress%EF%BC%8C%E8%BF%9B%E8%80%8C%E5%A4%84%E7%90%86%E9%9B%86%E7%BE%A4%E4%B8%AD%E8%BF%90%E8%A1%8C%E7%9A%84%E5%BA%94%E7%94%A8%E7%A8%8B%E5%BA%8F%E7%9A%84 Ingress 流量。

关于 Operator 的更多信息，请参见 Kubernetes 文档。

核心功能和特性

1. 版本对应管理：通过特定版本的 Operator 可安装对应版本的 NGINX Ingress Controller，版本映射关系明确。
2. Helm 驱动部署：1.0.0 及以上版本基于 NGINX Ingress Controller Helm 图表 构建，配置与 Helm 图表完全兼容。
3. 多实例支持：支持在集群中部署多个 NGINX Ingress Controller 实例，满足不同流量管理需求。
4. NGINX Plus 兼容：可配置部署 NGINX Plus Ingress Controller，需指定对应镜像及认证信息。
5. 灵活配置：支持通过自定义资源（Custom Resource）配置 Ingress Controller 的各项参数，包括 TLS、服务账户、RBAC 等。

使用场景和适用范围

• Kubernetes/OpenShift 集群 Ingress 管理：适用于需要统一管理集群入口流量的场景，支持 HTTP/HTTPS 路由、负载均衡等。
• 多团队/多环境隔离：通过部署多个 Ingress Controller 实例，实现不同团队或环境的流量隔离。
• NGINX Plus 企业级需求：满足对商业支持、高级负载均衡特性（如会话保持、健康检查）有需求的企业环境。
• 版本控制与标准化：通过 Operator 简化 Ingress Controller 的版本管理和部署标准化。

版本对应关系

使用 Operator 安装特定版本的 NGINX Ingress Controller 时，需确保 Operator 版本与 Controller 版本匹配。以下是两者的版本对应关系表：

注意：NGINX Ingress Operator 仅支持 NGINX Ingress Controller 版本 1.7.0 及以上。

使用方法和配置说明

前提条件

• Kubernetes 或 OpenShift 集群（版本需兼容目标 NGINX Ingress Controller）。
• kubectl 或 oc 命令行工具已配置集群访问权限。
• （可选）Helm 客户端（如需手动查看/调试 Helm 图表配置）。

安装步骤

1. 安装 NGINX Ingress Operator

参考 安装文档 完成 Operator 安装。

注意：若需使用 TransportServers 配置，需在启动 Operator 前 创建 GlobalConfiguration 资源，详情参见 说明。

2. 准备默认服务器证书（可选）

建议用户提供自定义证书，可参考 https://github.com/nginx/nginx-ingress-helm-operator/blob/main/examples/default-server-secret.yaml 创建 default-server-secret.yaml，并应用到集群：

shell
kubectl apply -f default-server-secret.yaml

3. OpenShift 环境额外配置

在 OpenShift 集群中，需创建 SCC（Security Context Constraint）资源：

shell
kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-ingress-helm-operator/main/resources/scc.yaml

4. 部署 NGINX Ingress Controller

通过自定义资源（Custom Resource）部署 Ingress Controller，示例配置如下（基于 https://github.com/nginx/nginx-ingress-helm-operator/blob/main/config/samples/charts_v1alpha1_nginxingress.yaml%EF%BC%89%EF%BC%9A

yaml
apiVersion: charts.nginx.org/v1alpha1
kind: NginxIngress
metadata:
  name: example-nginxingress
spec:
  # 完整配置参考 Helm 文档：https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-helm/#configuration
  controller:
    # 默认 TLS 证书（格式：namespace/name）
    defaultTLS:
      secret: "default/default-server-secret"
    # 若使用 NGINX Plus，需开启以下配置
    nginxPlus: true
    # NGINX Plus 镜像仓库及标签
    image:
      repository: "nginx-plus-ingress"
      tag: "5.2.0"
    # （可选）镜像拉取密钥（如需访问私有仓库）
    serviceAccount:
      imagePullSecretName: "nginx-plus-pull-secret"

应用自定义资源：

shell
kubectl apply -f charts_v1alpha1_nginxingress.yaml

关键配置参数说明

配置参数基于 NGINX Ingress Controller Helm 图表，详细说明参见 Helm 配置文档。常用参数如下：

多实例部署注意事项

1. 通用多 Ingress Controller 说明

关于在集群中运行多个 NGINX Ingress Controller 的通用信息，参见 NGINX 文档。

2. 同一命名空间多实例部署

在同一命名空间部署多个由 Operator 管理的 Ingress Controller 实例时：

• 需将 rbac.create 设为 false，并独立创建 ServiceAccount 和 ClusterRoleBinding。
• controller.serviceAccount.imagePullSecretName 参数将被忽略，需在独立创建的 ServiceAccount 中配置镜像拉取密钥。
• ClusterRoleBinding 需绑定至 nginx-ingress-operator-nginx-ingress-admin ClusterRole。

示例 RBAC 配置参见 示例文件。

3. 共享 IngressClass 的多实例部署

在不同命名空间部署多个实例并共享 IngressClass 时：

• 需将 controller.ingressClass.name 设为空字符串，并独立创建 IngressClass 资源。
• controller.ingressClass.setAsDefaultIngress 参数将被忽略，需在独立创建的 IngressClass 中配置默认 ingress 类。

示例 IngressClass 配置参见 示例文件。

升级说明

升级 NGINX Ingress Operator 需遵循版本对应关系，详细步骤参见 升级文档。

发布信息

NGINX Ingress Operator 发布在 GitHub，最新稳定版本为 https://github.com/nginx/nginx-ingress-helm-operator/releases/tag/v3.3.1%E3%80%82%E7%94%9F%E4%BA%A7%E7%8E%AF%E5%A2%83%E5%BB%BA%E8%AE%AE%E4%BD%BF%E7%94%A8%E6%9C%80%E6%96%B0%E7%A8%B3%E5%AE%9A%E7%89%88%E3%80%82

查看所有发布版本：https://github.com/nginx/nginx-ingress-helm-operator/releases%E3%80%82

开发指南

本地运行 Operator

适用于测试或开发场景：

1. 确保已访问 Kubernetes/OpenShift 集群。

2. 安装自定义资源定义（CRD）：

   shell
   make install
   

3. 本地运行 Operator：

   shell
   make run
   

此时 Operator 将在本地运行，并与集群通信。

贡献

如需贡献代码，参见 贡献指南。