K8s Ingress 怎么用?3 步把服务暴露到集群外
技术教程 · K8s · 网络 · 2026-10-15
K8s Ingress 怎么用?3 步把服务暴露到集群外
一句话开头
Service 建完默认是 ClusterIP,集群外访问不了;改用 NodePort 又要记 30000 多号的随机端口。Ingress 干的事就是给集群加一个 80/443 的统一入口,按域名 + 路径把流量分给不同的 Service。这篇从装 Controller 到验证走一遍,最后是 5 个最常见的坑。
前置准备
-
一个可用集群 + 配好的
kubectl -
一条硬性前提:集群里必须跑着 Ingress Controller。官方文档的原话是「仅创建 Ingress 资源本身没有任何效果」
-
控制器选型:
ingress-nginx(本文用它)、Traefik、各家云厂商的 Ingress 实现
步骤 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。