K8s Ingress 怎么用?3 步把服务暴露到集群外

技术教程 · K8s · 网络 · 2026-10-15

K8s Ingress 怎么用?3 步把服务暴露到集群外

一句话开头

Service 建完默认是 ClusterIP,集群外访问不了;改用 NodePort 又要记 30000 多号的随机端口。Ingress 干的事就是给集群加一个 80/443 的统一入口,按域名 + 路径把流量分给不同的 Service。这篇从装 Controller 到验证走一遍,最后是 5 个最常见的坑。

前置准备

步骤 1:安装 ingress-nginx

用 Helm 一条命令就够:

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

等控制器就绪,再拿入口地址:

kubectl wait --namespace ingress-nginx \
  --for=condition=ready pod \
  --selector=app.kubernetes.io/component=controller \
  --timeout=120s

kubectl get service ingress-nginx-controller --namespace=ingress-nginx

云上 EXTERNAL-IP 会分配一个负载均衡地址。如果是 <pending>,说明你的集群没有 LoadBalancer 实现——看下面「常见坑 4」。

自建 / 裸机集群可以直接用官方 baremetal 清单(默认走 NodePort,端口落在 30000-32767):

kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.15.1/deploy/static/provider/baremetal/deploy.yaml

步骤 2:部署一个要被暴露的应用

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  replicas: 2
  selector:
    matchLabels: {app: web}
  template:
    metadata:
      labels: {app: web}
    spec:
      containers:
        - name: web
          image: nginx:stable-alpine
          ports:
            - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: web
spec:
  selector: {app: web}
  ports:
    - port: 80
      targetPort: 80
kubectl apply -f web.yaml
kubectl get svc web        # EXTERNAL-IP 是 <none>,ClusterIP 只在集群内可达

步骤 3:写 Ingress,把域名路由进来

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: web-ingress
spec:
  ingressClassName: nginx
  rules:
    - host: demo.localdev.me
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: web
                port:
                  number: 80
kubectl apply -f web-ingress.yaml
kubectl get ingress web-ingress     # 看 CLASS / HOSTS / ADDRESS
kubectl describe ingress web-ingress

不配 DNS 也能验证,把控制器端口转发到本地再带上 Host 测:

kubectl port-forward --namespace=ingress-nginx service/ingress-nginx-controller 8080:80
curl --resolve demo.localdev.me:8080:127.0.0.1 http://demo.localdev.me:8080

返回 nginx 欢迎页就通了。生产环境只要把域名 A 记录指到 controller 的 EXTERNAL-IP。

要加逻辑时:同一个 host 下配多条 path 就是扇出(/api → api-svc,/web → web-svc);配多个 host 就是命名虚拟主机,同一个 IP 按 Host 头分流。host 还支持通配符(*.foo.com)。

步骤 4(可选):挂上 HTTPS

kubectl create secret tls demo-tls --cert=tls.crt --key=tls.key

然后在 Ingress 的 spec 里加:

  tls:
    - hosts:
        - demo.localdev.me
      secretName: demo-tls

Secret 类型必须是 kubernetes.io/tls,tls.crt / tls.key 两个键都要有;tls.hosts 要和 rules 里的 host 完全一致。线上建议上 cert-manager 做自动签发和续期。

常见坑

1. 只建了 Ingress,没装 Controller。 kubectl get ingress 的 ADDRESS 一直空,访问也没反应。Ingress 只是声明,真正干活的是 Controller。

2. 忘写 pathType。 直接过不了合法性检查,报 pathType must be specified。常用 Prefix,精确匹配用 Exact。语义也别想当然:/foo/bar 能匹配 /foo/bar/baz,但不匹配 /foo/barbaz(官方文档专门提醒过)。多条路径都命中时最长前缀优先,长度相同则 Exact 优先。

3. ingressClassName 写错或不写。 Ingress 会被控制器忽略,请求落到默认后端回 404。注意新的 ingressClassName 字段和老的 kubernetes.io/ingress.class 注解不完全等价:注解写的是控制器名字,字段引用的是 IngressClass 资源。另外,如果集群里有两个 IngressClass 都被标成默认(ingressclass.kubernetes.io/is-default-class: "true"),准入控制器会直接拒绝创建不带 ingressClassName 的 Ingress。

4. 自建集群 EXTERNAL-IP 永远 <pending>。 裸机没有 LoadBalancer 实现,要么用 NodePort(30000-32767),要么装 MetalLB 给 Service 分 IP。别拿 kubectl port-forward 当生产入口,它只在本地测试有意义。

5. rewrite-target 必须写捕获组。 用 ingress-nginx 做路径改写时,nginx.ingress.kubernetes.io/rewrite-target 从 0.22 起不再兼容老写法:想让 /something/xxx 转发到后端 /xxx,得配 path: /something(/|$)(.*) + pathType: ImplementationSpecific + rewrite-target: /$2,同时打开 nginx.ingress.kubernetes.io/use-regex: "true"。

6.(作者补充)backend 里没有 namespace 字段。 Ingress 的 backend 只能写 service.name 和 port,不能指定 namespace,所以只能指向同 namespace 的 Service。集群里按团队划分 namespace 时,这个坑踩得最多——解决方案是在目标 namespace 里各建一个 Ingress,或者换 Gateway API / 自建反代层。

一句话总结

Ingress = 集群的 HTTP 入口:先装 Controller,再用 rules 把域名/路径映射到 Service。排障顺序永远固定:Controller 在不在跑 → ingressClassName 对不对 → host/path 匹配上没匹配上。顺带提一句,K8s 官方已经冻结 Ingress API 并推荐 Gateway API,新项目可以顺便看一眼 Gateway。