Kubernetes Nginx Ingress Controller 安装与测试文档

本文档介绍了如何使用 Helm 在 Kubernetes 集群中部署 Nginx Ingress Controller。为了应对国内网络限制，文档中包含了离线获取 Chart 包以及替换镜像源的完整解决方案，并采用了 DaemonSet + HostNetwork 的高性能部署模式。最后提供了一个 Nginx 应用作为测试案例。

零、 安装 Helm (如已安装可跳过)

在部署 Ingress 之前，需要确保你的主控节点上已经安装了 Helm 工具。

# 下载安装脚本
curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3

# 赋予执行权限
chmod 700 get_helm.sh

# 执行安装
./get_helm.sh

# 验证安装是否成功
helm version

一、 准备 Helm Chart

1. 添加官方仓库并更新

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

# 更新本地仓库缓存
helm repo update

# (可选) 搜索可用的 chart 版本
helm search repo ingress-nginx/ingress-nginx -l

2. 下载 Chart 包

由于国内网络环境限制，直接使用 helm pull 可能会遇到 connection reset by peer 错误。

方式一：使用 Helm 直接拉取（网络通畅时）

helm pull ingress-nginx/ingress-nginx --version 4.15.1

方式二：备选下载方式（网络受限时）
直接使用 wget 或通过浏览器下载 GitHub Releases 上的压缩包：

wget https://github.com/kubernetes/ingress-nginx/releases/download/helm-chart-4.15.1/ingress-nginx-4.15.1.tgz

下载完成后，解压并进入目录：

tar -zxvf ingress-nginx-4.15.1.tgz
cd ingress-nginx

---

二、 镜像准备（应对拉取困难）

官方使用的镜像托管在 registry.k8s.io，国内可能无法直接访问。你可以选择 手动替换并分发镜像 或 在 Helm 安装时动态指定代理源。

方案 A：手动下载并分发镜像（适合内网完全断网环境）

注：以下操作需在所有计划部署 Ingress 的节点上执行，或在一台机器操作后通过 ctr 导出分发。以 Chart 对应的 v1.11.3 和 v1.4.4 版本为例，假设你找到了华为云等替代镜像。

# === 处理 controller 镜像 ===
# 1. 从替代源拉取镜像 (使用 crictl)
crictl pull swr.cn-north-4.myhuaweicloud.com/ddn-k8s/registry.k8s.io/ingress-nginx/controller:v1.11.3

# 2. 将镜像重新打标签，使其与官方名称一致 (crictl 不支持 tag，使用 ctr 指定 k8s 命名空间)
ctr -n k8s.io images tag swr.cn-north-4.myhuaweicloud.com/ddn-k8s/registry.k8s.io/ingress-nginx/controller:v1.11.3 registry.k8s.io/ingress-nginx/controller:v1.11.3

# 3. (可选) 保存镜像为 tar 文件，用于分发
ctr -n k8s.io images export ncontroller.tar registry.k8s.io/ingress-nginx/controller:v1.11.3

# === 处理 kube-webhook-certgen 镜像 ===
# 1. 从替代源拉取镜像
crictl pull swr.cn-north-4.myhuaweicloud.com/ddn-k8s/registry.k8s.io/ingress-nginx/kube-webhook-certgen:v1.4.4

# 2. 重新打标签
ctr -n k8s.io images tag swr.cn-north-4.myhuaweicloud.com/ddn-k8s/registry.k8s.io/ingress-nginx/kube-webhook-certgen:v1.4.4 registry.k8s.io/ingress-nginx/kube-webhook-certgen:v1.4.4

# 3. (可选) 保存镜像为 tar 文件
ctr -n k8s.io images export certgen.tar registry.k8s.io/ingress-nginx/kube-webhook-certgen:v1.4.4

# === 在其他目标节点上分发与加载 ===
# 4. (如果使用了 .tar 文件) 将 tar 文件拷贝到其他节点
# scp ncontroller.tar root@<other-node-ip>:/root
# scp certgen.tar root@<other-node-ip>:/root

# 5. (如果使用了 .tar 文件) 在其他节点导入镜像到 k8s 命名空间
# ctr -n k8s.io images import ncontroller.tar
# ctr -n k8s.io images import certgen.tar

确保在执行 Helm 安装之前，所有目标节点上都存在 registry.k8s.io/ingress-nginx/controller:v1.11.3 和 registry.k8s.io/ingress-nginx/kube-webhook-certgen:v1.4.4 这两个本地镜像。

方案 B：Helm 动态指定代理镜像源（推荐，适合有公网能力的集群）

在下文的安装步骤中，我们将直接使用 k8s.m.daocloud.io 作为镜像代理地址。

---

三、 执行安装

我们采用 DaemonSet 结合 HostNetwork 的模式部署，以获得最低的网络转发延迟。同时配置 ClusterFirstWithHostNet 确保在主机网络模式下，Pod 依然能正确解析集群内部的 DNS。

如果之前安装过失败的版本，可以先执行卸载：helm uninstall ingress-nginx -n ingress-nginx

在解压后的 ingress-nginx 目录下，执行以下命令安装：

helm install ingress-nginx --debug \
  --namespace ingress-nginx --create-namespace \
  --set controller.hostNetwork=true \
  --set controller.kind=DaemonSet \
  --set controller.service.type=ClusterIP \
  --set controller.dnsPolicy=ClusterFirstWithHostNet \
  --set controller.image.registry=k8s.m.daocloud.io \
  --set controller.image.image=ingress-nginx/controller \
  --set controller.admissionWebhooks.patch.image.registry=k8s.m.daocloud.io \
  --set controller.admissionWebhooks.patch.image.image=ingress-nginx/kube-webhook-certgen \
  --set controller.admissionWebhooks.create.image.registry=k8s.m.daocloud.io \
  --set controller.admissionWebhooks.create.image.image=ingress-nginx/kube-webhook-certgen \
  .

---

四、 部署测试应用

部署一个简单的 Nginx 网页服务，并为其创建 Service 和 Ingress 路由规则。

1. 创建部署文件 my-nginx.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-nginx
spec:
  selector:
    matchLabels:
      run: my-nginx
  replicas: 2
  template:
    metadata:
      labels:
        run: my-nginx
    spec:
      containers:
      - name: my-nginx
        image: nginx:latest
        resources:
          limits:
            memory: "128Mi"
            cpu: "500m"
        ports:
        - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: nginx-service
spec:
  selector:
    run: my-nginx
  type: ClusterIP
  ports:
  - protocol: TCP
    port: 8080
    targetPort: 80
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ingress
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /$1
spec:
  ingressClassName: nginx
  rules:
    - host: test.ingress.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: nginx-service
                port:
                  number: 8080

2. 应用配置

kubectl apply -f my-nginx.yaml

---

五、 验证测试

在配置了本机 hosts 或内部 DNS 将 test.ingress.com 解析到任意一台运行了 Ingress Controller 的 Node IP 后，发起请求测试：

curl -H "Host: test.ingress.com" http://<运行Ingress的Node_IP>
# 或者配置 hosts 后直接请求：
# curl http://test.ingress.com

如果返回了标准的 Nginx 欢迎页面 (Welcome to nginx!)，则说明 Ingress Controller 部署并路由成功！