K8s Helm 部署 ingress-nginx Ingress Controller 完整实操（环境准备→业务访问）

于 2026-10-26 05:11:52 发布 9 0 0

说明：本文使用 ingress-nginx（社区Nginx Ingress控制器），不是NGINX官方商业版；区分： Ingress资源是路由规则，Ingress Controller才是真正的反向代理Pod，必须先部署控制器，Ingress规则才能生效。集群环境：Kubernetes 1.24+，Helm 3，自建K8s/云厂商集群均可；自建集群Service默认只能用NodePort，云厂商可以LoadBalancer。

一、环境准备

1. 前置检查

# 1. 确认kubectl连通集群
kubectl get nodes

# 2. 确认helm版本（必须helm3，helm2废弃）
helm version

要求：

K8s集群正常，节点Ready
Helm3已安装
集群网络插件正常（Calico/Flannel）
可以拉取镜像（国内环境提前准备镜像加速，否则ingress镜像拉取超时）

2. 添加 ingress-nginx Helm仓库

# 添加仓库
helm repo add ingress-nginx [https://kubernetes.github.io/ingress-nginx](https://kubernetes.github.io/ingress-nginx)

# 更新仓库索引
helm repo update

# 搜索chart
helm search repo ingress-nginx

国内网络访问github.io缓慢：可以使用镜像仓库或者提前helm pull下载包离线安装

二、Helm 安装 ingress-nginx 控制器

方式1：极简安装（快速测试）

helm upgrade --install ingress-nginx ingress-nginx/ingress-nginx \
  --repo [https://kubernetes.github.io/ingress-nginx](https://kubernetes.github.io/ingress-nginx) \
  --namespace ingress-nginx --create-namespace

upgrade --install：幂等命令，不存在则安装，存在则升级
--create-namespace：自动创建ingress-nginx命名空间

方式2：自定义参数安装（推荐生产，可导出values.yaml微调）

# 导出默认配置文件，修改后安装
helm show values ingress-nginx/ingress-nginx --repo [https://kubernetes.github.io/ingress-nginx](https://kubernetes.github.io/ingress-nginx) > values.yaml

# 编辑values.yaml，常见修改点
# controller.replicaCount=2 副本数
# controller.service.type：自建集群用NodePort；公有云用LoadBalancer
# resources 资源限制、nodeSelector、tolerations污点容忍

# 使用自定义values安装
helm upgrade --install ingress-nginx ingress-nginx/ingress-nginx \
  --repo [https://kubernetes.github.io/ingress-nginx](https://kubernetes.github.io/ingress-nginx) \
  --namespace ingress-nginx --create-namespace \
  -f values.yaml

自建物理机/虚拟机集群： controller.service.type=NodePort 公有云EKS/ACK/AKS： controller.service.type=LoadBalancer，云厂商自动分配公网IP

三、验证 ingress-nginx 控制器部署状态

# 查看命名空间下Pod
kubectl get pods -n ingress-nginx -w

# 查看Service
kubectl get svc -n ingress-nginx

输出示例（自建集群NodePort）：

NAME                                 TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)                      AGE
ingress-nginx-controller             NodePort    10.96.xxx.xxx   <none>        80:30080/TCP,443:30443/TCP   2m
ingress-nginx-controller-admission   ClusterIP   10.96.xxx.xxx   <none>        443/TCP                      2m

Pod状态必须是Running；镜像拉取慢会处于ContainerCreating，耐心等待或换国内镜像
记录：NodePort端口 80→30080，443→30443，后续外部访问节点IP+该端口

查看helm发布：

helm list -n ingress-nginx

查看控制器日志（排错用）

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

四、部署测试业务（Deployment + ClusterIP Service）

准备demo-app.yaml，创建一个简单nginx业务：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: demo-nginx
  namespace: default
spec:
  replicas: 2
  selector:
    matchLabels:
      app: demo-nginx
  template:
    metadata:
      labels:
        app: demo-nginx
    spec:
      containers:
      - name: nginx
        image: nginx:alpine
        ports:
        - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: demo-nginx-svc
  namespace: default
spec:
  selector:
    app: demo-nginx
  ports:
  - port: 80
    targetPort: 80
  type: ClusterIP

应用资源：

kubectl apply -f demo-app.yaml

# 验证
kubectl get deploy,pod,svc

Service类型ClusterIP， 只能集群内部访问，外部不能直接访问，需要Ingress做七层路由。

五、创建 Ingress 路由规则（核心）

重点：K8s 1.19+ 使用 networking.k8s.io/v1 API（不再是v1beta1）新建 ingress-demo.yaml

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: demo-ingress
  namespace: default
  annotations:
    # 指定使用 ingress-nginx 控制器（多Ingress控制器场景必须加）
    kubernetes.io/ingress.class: "nginx"
spec:
  rules:
  - host: demo.k8s.local  # 域名，自行修改
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: demo-nginx-svc
            port:
              number: 80

创建Ingress资源：

kubectl apply -f ingress-demo.yaml

# 查看Ingress
kubectl get ingress

输出：

NAME          CLASS    HOSTS           ADDRESS   PORTS   AGE
demo-ingress  nginx    demo.k8s.local            80      30s

等待片刻， ADDRESS字段会填充Ingress Controller Service的IP（云厂商LB IP / 节点IP）

六、域名解析配置 & 业务访问

场景A：自建K8s集群（NodePort模式）

本地/etc/hosts（Linux/Mac）或 C:\Windows\System32\drivers\etc\hosts 添加解析：

# 节点IP      域名
192.168.1.100 demo.k8s.local

192.168.1.100：任意一个K8s工作节点IP

浏览器/ curl访问：

curl [http://demo.k8s.local:30080](http://demo.k8s.local:30080)

原理：流量 → 节点IP:30080 → ingress-nginx-controller Pod → 根据host路由转发到demo-nginx-svc → 后端Pod

场景B：公有云LoadBalancer模式

Ingress Controller Service会拿到公网IP，直接把域名demo.k8s.localDNS解析到LB公网IP，直接访问标准80端口：

curl [http://demo.k8s.local](http://demo.k8s.local)

七、HTTPS TLS 配置（可选）

生成证书secret：

# 自签名证书测试，生产使用可信CA证书
openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout tls.key -out tls.crt -subj "/CN=demo.k8s.local"
kubectl create secret tls demo-tls --cert=tls.crt --key=tls.key

修改Ingress，增加tls配置：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: demo-ingress
  namespace: default
  annotations:
    kubernetes.io/ingress.class: "nginx"
spec:
  tls:
  - hosts:
    - demo.k8s.local
    secretName: demo-tls
  rules:
  - host: demo.k8s.local
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: demo-nginx-svc
            port:
              number: 80

应用后访问 [https://demo.k8s.local](https://demo.k8s.local)

八、常见排错清单

Ingress ADDRESS一直为空：Ingress Controller Pod没正常运行；检查Pod日志
访问404：host域名不匹配、path写错、backend service名称/端口错误
访问连接超时：安全组/防火墙没有放行NodePort/LB端口；自建集群节点防火墙
403：nginx权限问题，业务镜像问题
多Ingress控制器：必须指定ingress.class，否则路由不生效
镜像拉取失败：国内环境替换values.yaml里controller镜像为国内镜像地址

九、卸载（清理环境）

# 删除ingress路由、业务
kubectl delete -f ingress-demo.yaml
kubectl delete -f demo-app.yaml

# helm卸载ingress控制器
helm uninstall ingress-nginx -n ingress-nginx

# 删除命名空间
kubectl delete ns ingress-nginx

https://www.nowcoder.com/discuss/944017776379809792

https://www.nowcoder.com/discuss/944018159693058048

https://www.nowcoder.com/discuss/944018446067433472

https://www.nowcoder.com/discuss/944018709381718016

https://www.nowcoder.com/discuss/944018898788098048

https://www.nowcoder.com/discuss/944019112416509952

https://www.nowcoder.com/discuss/944019302812819456

https://www.nowcoder.com/discuss/944019398254252032

https://www.nowcoder.com/discuss/944019600868401152

https://www.nowcoder.com/discuss/944019485428666368

https://www.nowcoder.com/discuss/944019717772091392

https://www.nowcoder.com/discuss/944019820943507456