1. 先搞懂一件事：为什么有了Service还不够，还要Ingress
我们从上手K8s第一天起就一直跟Service打交道。一开始用ClusterIP，集群内部访问服务；后来想从外面访问，打上NodePort，把端口暴露到节点上；再往后上云了，整一个LoadBalancer，云厂商给一公网IP，流量走进来。按三部曲走，好像什么场景都能应付。
但实际做项目，问题就来了。一个服务端口暴露三四个，外部访问要记一堆IP和随机的NodePort端口。服务稍微多一点，整个端口规划乱成一团。最尴尬的是，NodePort凭端口号区分服务，生产环境几乎没法用——你不能让用户访问的时候还要带上奇怪的三万端口吧。
这时候，Ingress就出来了。
Ingress干的是一件很本质的事情：把原本"一个服务一个入口（IP+Port）"的模型，升级成"一个入口，按域名和路径分发到多个服务"的模型。你可以把它理解成K8s集群的前置网关，或者更直白一点——K8s里的反向代理规则管理器。它让外部流量先打到一个统一入口，再由入口按照URL规则分流到各个Service，整套链路就走通了。
这篇文章是我学习K8s的第十二篇笔记，聊的就是Service体系里的Ingress部分。我会从原理讲到实战，包含坑和排错手段，把Ingress Controller安装、Ingress规则编写、路径重写、TLS、灰度发布这些都过一遍。适合已经会用Service、想进一步把对外暴露方式做规范化的朋友，如果你连Service的三种类型还没搞明白，建议先把前面那篇翻出来读一遍再回来。
2. Ingress的运作机制拆解——Controller和Ingress资源各管什么事
2.1 你创建的不是流量入口，而是一个“声明”
刚接触Ingress的人，最容易产生一个误解：以为创建了一个Ingress资源，集群入口就自动出现了。实际上Ingress这个对象本身不干活，它只是一份流量规则的声明——声明了"哪个域名、哪个路径，转发到哪个Service的哪个端口"。
真正落地这份声明、承担流量转发工作的，是Ingress Controller。
这点要分得非常清楚，否则后面排查问题的时候你会疯掉。打个比方，Ingress资源相当于你给快递公司贴了一张配送单，写明"这个包裹送到哪栋楼哪个房间"；而Ingress Controller才是那个真正的配送员，他跑到这张单子，把包裹送到位。
Ingress Controller是一个独立运行在集群里的工作负载，一般是Deployment形式部署的，它会持续监听API Server上Ingress资源的变化。一旦有新的Ingress被创建，Controller就把它翻译成自己的配置（比如Nginx风格的upstream和server配置），然后重新加载配置，让流量开始按规则转发。
2.2 一个Ingress对象里到底能写什么
看一个Ingress的YAML是最直观的。拿一个典型例子：
apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: demo-ingress namespace: default annotations: nginx.ingress.kubernetes.io/rewrite-target: / spec: ingressClassName: nginx tls: - hosts: - demo.example.com secretName: demo-tls-secret rules: - host: demo.example.com http: paths: - path: /api pathType: Prefix backend: service: name: api-service port: number: 8080 - path: /web pathType: Prefix backend: service: name: web-service port: number: 80核心就三块。
第一块是ingressClassName。它声明"这份规则要交给哪个Controller来处理"。集群里可以装多套不同的Ingress Controller，比如社区常用的nginx-ingress（泛指一类基于Nginx内核的解决方案，下文统称为Nginx Ingress）、还有集群内部自带的那种默认Controller。通过这个字段指定用哪套，互不干扰。
第二块是rules。每条rule包含一个可选host（域名），以及一组HTTP路径映射。每个path对应一个backend，backend就是后端的Service名称和端口。如果rule里没有写host，就代表该规则匹配所有未指定域名的流量，也就是默认规则。
第三块是tls。它声明了哪些域名走HTTPS，证书秘钥放在哪个Secret对象里。这个Secret的类型是kubernetes.io/tls，里面需要按标准格式包含tls.crt证书和tls.key私钥。
2.3 流量完整链路：从域名到Pod要经过几道弯
从用户请求到Pod，整条链路的顺序是：
用户请求某个域名 --> DNS解析到Ingress Controller的负载均衡器/节点IP --> 经过Ingress Controller（按Ingress规则做路由匹配） --> 转发到对应的Service ClusterIP --> 由Service的Endpoints转发到某个后端Pod注意，Ingress Controller转发到后端时，默认走的是Service的ClusterIP。这意味着即使你后端Service选的类型是ClusterIP，只要Ingress规则正确解析到Service名，流量就能从外部到达Pod。
中间每一环都有可能出现断点，这也是后面排查问题的主线逻辑：DNS是否解析到了Controller -> 流量是否命中了Ingress Controller的监听端口 -> Controller规则是否匹配了正确的Service -> Service后端Pod是否健康。
3. 环境准备：装一套可用的Ingress Controller
3.1 怎么选Controller——不是只有Nginx一种
在开始动手之前，先把Controller的选型讲清楚。K8s社区的生态里，Ingress Controller的常见方案有这么几类：
- 基于Nginx内核的Ingress Controller：社区最流行，资料最多，功能覆盖最全。我们日常说的"ingress-nginx"一般就是它。企业内部自建集群，绝大多数默认选它。
- 基于HAProxy的方案：性能很好，但社区资料和配置示例相对少一些。
- 云厂商自带的原生Ingress：比如在托管的集群里直接用厂商提供的入口网关，好处是跟云负载均衡器深度集成，但规则字段和社区Nginx的方案不完全一致。
我自己平时的选择很简单：自建集群一律用基于Nginx核心的方案，因为资料多、排错有人问、踩坑经验满地都是。如果你用的是托管集群，那直接用厂商自带的Ingress更省事，毕竟它已经跟云上的LB、证书服务打好了配合。
3.2 从零部署一套Nginx Ingress Controller
部署方式有两种主流路线，一种是用Helm，一种是用官方发布的YAML文件。我实际操作下来，YAML方式更适合学习阶段——你能看清楚它到底创建了哪些资源，也更方便排查问题。
以社区版本为例，最基础的部署命令长这样（下面这条命令中的版本号请以官方仓库发布的最新稳定版为准）：
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.8.1/deploy/static/provider/baremetal/deploy.yaml这个YAML文件会一次性创建一系列资源，包括一个独立的命名空间，Controller的Deployment，给Controller使用的Service，还有对应的RBAC权限、配置字典、服务账号等等。
部署完成后，观察一下Controller的运行状态：
kubectl get pod -n ingress-nginx正常情况下你会看到一个Running状态的Pod。如果是CrashLoopBackOff，优先看日志：
kubectl logs -n ingress-nginx -l app.kubernetes.io/name=ingress-nginx在我实际部署中，最常见的启动失败原因有两类。一类是镜像拉不下来，这个跟网络环境关系很大，建议提前把镜像拉到节点上或者配置好节点的镜像加速。另一类是端口冲突，Controller默认要占用节点的80和443端口，如果节点上已经有别的进程占用了这两个端口，Pod会一直起不来。
3.3 让外部流量真正打到Controller上
针对自建集群或者说裸金属环境，Controller的Service一般推荐用NodePort方式暴露，或者直接在Controller Pod上挂hostNetwork，让Pod直接复用节点IP和80/443端口。
我个人的实践是：如果在自建环境里，直接给Controller的Service设置externalTrafficPolicy: Cluster，然后用NodePort暴露；如果是在云上，直接把Service类型改成LoadBalancer，云平台会给它分配一个公网IP。
有一点需要注意：如果你的公司还在用比较老的K8s版本，比如1.18及以前的集群，而Controller版本已经用了最新的，那你可能会碰到兼容性报错——Ingress资源的apiVersion还是networking.k8s.io/v1beta1，而新的Controller要求是v1。这种问题多数出现在公司里"集群版本不统一+参考网上过时资料"的情况下。我建议先确认集群版本，再选对应的Controller版本，不要盲目上最新版。
4. 第一次用Ingress：从部署测试服务到写规则
4.1 准备一个最简单的后端服务
为了做实验，先部署一个简单的测试服务。你可以在本地写一个极简的HTTP服务镜像也好，直接用现成的demo镜像也好。这里以我自己常用的方式举例：随便起个回显服务，请求什么路径，它都把访问的路径和Host信息原样返回，这样调试路由规则时你能一眼看出来请求到底到了谁那儿。
先创建命名空间和Service：
kubectl create ns demo kubectl create deployment demo-app --image=nginxdemos/hello --port=80 -n demo kubectl expose deployment demo-app --port=80 --target-port=80 --name=demo-svc -n demo实际上我更喜欢用一个更简单的临时sleep镜像配合curl来做，但从演示效果来说，返回页面能直接显示"我访问的是哪个路径"更直观。所以上面的nginxdemos/hello就很好用。
确认Service正常工作：
kubectl get svc -n demo到这里，你已经拥有了一个后端服务。接下来要做的，就是让外部流量通过Ingress到这个服务来。
4.2 写一份最基础的Ingress规则
在当前集群里创建一个Ingress规则，把demo.example.com这个域名下所有路径都转发给demo-svc：
apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: demo-ingress namespace: demo spec: ingressClassName: nginx rules: - host: demo.example.com http: paths: - path: / pathType: Prefix backend: service: name: demo-svc port: number: 80应用它：
kubectl apply -f ingress-demo.yaml然后看一下规则是否生效：
kubectl get ingress -n demo输出的ADDRESS字段如果显示的是Controller的地址或节点IP，说明规则已经被Controller接收了。
4.3 测试流量：不改DNS也能验证
因为我们是在实验环境，没有实际把demo.example.com解析到Controller的IP上，所以直接用curl加Host头的方式模拟域名访问：
curl -H "Host: demo.example.com" http://<Controller的IP或节点IP>/这里的Controller IP怎么找？如果是NodePort方式暴露的，就用节点的IP加上Service的NodePort端口：
kubectl get svc -n ingress-nginx ingress-nginx-controller这条命令能看到对外端口，假设80端口映射成了31826，那么访问命令就变成：
curl -H "Host: demo.example.com" http://<节点IP>:31826/如果一切配置正常，你会看到demo-app返回的页面，说明请求已经通过Ingress规则打到了后端的Pod里。
4.4 多路径路由：一个入口分流两个服务
上面只是最简单的全量转发，实际项目里更常见的需求是同一个域名，不同路径分给不同后端。举个例子：
apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: multi-path-ingress namespace: demo spec: ingressClassName: nginx rules: - host: demo.example.com http: paths: - path: /api pathType: Prefix backend: service: name: api-svc port: number: 8080 - path: / pathType: Prefix backend: service: name: web-svc port: number: 80这一段逻辑跟前面的区别在于：同一份规则里配置了多个path，流量进入后Controller按最长路径优先匹配原则，把/api开头的请求转给api-svc，其余的走web-svc。
这里有一个非常常见的坑：很多人把路径和rewrite-target搞混。上面这个配置，请求打的是/api/user，后端web-svc收到的是/api/user，路径不变。如果你后端服务里路由根本不识别/api前缀（比如你的API服务只认/user），那就需要动用重写机制，也就是接下来要讲的内容。
4.5 路径重写：为什么明明看到404，但调试感觉啥都对
rewrite-target是Ingress使用率最高的一个注解。它的作用是把匹配到的路径在转发到后端之前重写掉。最常见的用法是：
metadata: annotations: nginx.ingress.kubernetes.io/rewrite-target: /$2 spec: rules: - host: demo.example.com http: paths: - path: /api(/|$)(.*) pathType: ImplementationSpecific backend: service: name: api-svc port: number: 8080这里($2)代表正则中第二个括号匹配到的部分。请求/api/user经过重写后，后端的service收到的是/user。
为什么需要这个？因为很多后端应用内置的路由是不带前缀的。你在前端通过/api/user访问网关，网关把请求转发给后端微服务时，后端只认识/user。如果后端不做前缀剥离，就会一直报404。这个重写就用在这里。
如果你用的是Prefix路径类型并希望把所有前缀都剥掉、统一重写到根路径，可以用：
nginx.ingress.kubernetes.io/rewrite-target: /这样一切到达的路径都会变成根路径/转发到后端。这种配置在只跑一个前端静态页面、且页面里全部用相对路径引资源时比较实用，但也容易引起页面静态资源404——因为请求/assets/main.css被改成根路径/之后，后端找不到对应文件，所以实际生产里我建议按需用正则精确重写，不要一刀切重写根。
5. 大杀器：TLS配置与多环境灰度发布
5.1 给Ingress挂上HTTPS：从自签证书到Secret
生产环境中，所有到达集群的流量都应该走HTTPS。Ingress的TLS配置并不复杂，第一步是准备证书。平台或运维一般会给你一套符合内部域名规范的证书，实验环境可以用openssl自签一张：
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \ -keyout tls.key -out tls.crt -subj "/CN=demo.example.com" -addext "subjectAltName=DNS:demo.example.com"然后把证书导入K8s的Secret：
kubectl create secret tls demo-tls --key=tls.key --cert=tls.crt -n demo接着在Ingress的spec里挂上tls字段：
spec: tls: - hosts: - demo.example.com secretName: demo-tls rules: - host: demo.example.com http: paths: - path: / pathType: Prefix backend: service: name: demo-svc port: number: 80应用后，Controller会自动监听443端口。用curl验证：
curl -k -H "Host: demo.example.com" https://<节点IP>:<443端口>/-k是因为自签证书不受系统信任，实验时可以跳过校验。
我踩过一个坑是：TLS配置后访问居然还是HTTP响应，没有跳转HTTPS。原因是Nginx Ingress默认不会强制跳转，需要加上注解：
nginx.ingress.kubernetes.io/ssl-redirect: "true"加了之后，HTTP请求访问会返回301，自动跳转到HTTPS。
5.2 给多个域名分别挂不同证书
如果你的集群需要服务多个团队或产品线，比如app-a.example.com和app-b.example.com，并且每个域名都有自己的证书，可以分别创建Secret，然后在不同的Ingress里分别引用对应的Secret。
也可以在一个Ingress里同时声明多个host、多个Secret：
spec: tls: - hosts: - app-a.example.com secretName: app-a-cert - hosts: - app-b.example.com secretName: app-b-cert rules: - host: app-a.example.com http: ... - host: app-b.example.com http: ...证书选择按host来区分，Controller在建立TLS握手时根据SNI匹配对应的证书。实际运维中，证书过期是一个很容易被忽略的点，建议为证书过期时间加监控告警，服务上线一年后突然所有人打不开页面，那种体验真的很酸爽。
5.3 用Ingress做蓝绿发布和灰度发布
Ingress不只是对外暴露入口这么简单，它还能做流量的精细化控制。Nginx Ingress Controller原生支持基于权重或基于请求头的灰度发布。
先看基于权重的方式：
metadata: annotations: nginx.ingress.kubernetes.io/canary: "true" nginx.ingress.kubernetes.io/canary-weight: "10" spec: ingressClassName: nginx rules: - host: demo.example.com http: paths: - path: / pathType: Prefix backend: service: name: demo-app-v2 port: number: 80这个叫canary的Ingress和主Ingress指向同一个域名，但带上了canary注解。canary-weight为10表示有10%的流量被转发给v2版本的服务，主Ingress继续处理剩余90%。这样可以小流量验证新版本，稳定后再逐步抬高权重，最后把主Ingress的backend切到新版本，再删掉canary规则。
还有基于Header的方式，比如内部测试人员带一个自定义请求头才能命中新版：
metadata: annotations: nginx.ingress.kubernetes.io/canary: "true" nginx.ingress.kubernetes.io/canary-by-header: "x-canary" nginx.ingress.kubernetes.io/canary-by-header-value: "true"这个玩法在做内部验收、特定用户灰度测试时非常香。有一次我们做全链路联调，前端团队要拿正式域名测新版本，同时又不想影响真实用户，就用这个Header灰度方式，联调人员在浏览器装一个改请求头的插件，爽爽地测了一整天，用户侧完全无感知。
5.4 限流、白名单、超时——日常用得上的几个注解
Ingress还有一些实用注解值得记下来。
限流：
nginx.ingress.kubernetes.io/limit-rps: "100" nginx.ingress.kubernetes.io/limit-connections: "20"IP白名单：
nginx.ingress.kubernetes.io/whitelist-source-range: "10.0.0.0/8, 172.16.0.0/12"连接超时：
nginx.ingress.kubernetes.io/proxy-connect-timeout: "30" nginx.ingress.kubernetes.io/proxy-read-timeout: "60"我的经验是：限流和连接数这两个几乎每个生产Ingress都要加，不加的后果就是上游一个慢Query就能把整个Controller拖垮。白名单字段注意逗号分隔，不要用竖线。
6. 踩坑实录：Ingress相关常见故障排查手册
6.1 症状1：访问报404（规则未生效/路径不匹配）
排查路线：
- 先确认Ingress规则有没有被Controller加载：
kubectl get ingress -n demo。如果ADDRESS字段为空，说明Controller没有接收规则，继续往下面查。 - 查看Controller日志：
kubectl logs -n ingress-nginx <controller-pod名称>，看有没有关于Ingress同步的错误。 - 确认ingressClassName写的是不是Controller实际监听的名字。很多人升级后把这个字段漏了，导致Controller根本不处理这个Ingress。
- 检查路径匹配规则。如果你写的是Exact类型，请求路径只要比规则多一个字符就会不匹配。生产环境建议用Prefix，注意它匹配的是路径前缀，
/api会匹配/api/v1/user，但不会匹配/apixxx。
6.2 症状2：访问报502（后端服务不通）
502是Controller和后端之间的通信出了问题。核心排查方向：
kubectl get ep -n demo kubectl get po -n demo如果Endpoints为空，说明Service的selector没有匹配到任何Pod，或者Pod没就绪。这里最常见的坑是selector写错，比如Deployment里的label是app: demo，但Service里的selector写成了app: demo-app，永远匹配不上。
其次，确认Pod的端口和Service的targetPort对得上。如果Pod监听的端口是8080，Service里写的是80，那流量转发必然失败。
还有一个容易忽略的：Pod的readinessProbe返回失败会踢出Endpoints。如果你配置了健康检查，先确认探针接口返回200，否则即使Pod是Running状态，流量也进不去。
6.3 症状3：证书配置了但还是HTTP/TLS告警
排查思路：
- 确认Secret存在且类型正确：
kubectl get secret -n demo，TYPE必须显示为kubernetes.io/tls。用kubectl get secret demo-tls -o yaml检查data字段里必须要有tls.crt和tls.key两个key。 - 确认ingress里的secretName和Secret实际名字大小写一致。
- 访问时带上域名：
curl -H "Host: demo.example.com" https://IP/，不要用IP去访问，否则SNI不匹配，Controller选不到证书。
6.4 症状4：配置了rewrite但页面资源还是404
我之前讲过，rewrite-target如果直接重写到根路径，静态资源全挂。推荐的方案是这样的：
nginx.ingress.kubernetes.io/rewrite-target: /$2 spec: paths: - path: /app(/|$)(.*)把/app/xxx重写成/xxx，而不是全部变成根路径。
如果你用的是Prefix路径类型加上rewrite到根的配置，基本等于自废武功。优先改用正则路径配合组引用，这是处理带前缀前端应用的最稳妥姿势。
另外要注意：如果你的页面里写的是绝对路径/static/xxx，那不管你怎么重写，请求都会落到根路径下找static资源，这时候后端必须有对应的静态目录，或者你需要给静态资源单独配一条规则，而不是硬扛在一条重写规则里。
6.5 症状5：Ingress规则变更后流量没变化
Controller的配置不是实时的，它有一层缓存。如果你改了Ingress但感觉流量没变，通常等几秒就好。如果等了一段时间还是老样子，可以强制触发一次reload：
kubectl exec -n ingress-nginx <controller-pod> -- nginx -s reload另外确认一下你有没有多套Controller混用。如果集群里有多个Ingress Controller，而你的Ingress没有指定ingressClassName，新版本默认会有一个默认Controller来接管，旧版本则可能随机被某一个Controller捡起来，造成越改越乱。强烈建议在集群里只保留一套生产用Controller，并给每个Ingress都明确写上ingressClassName。
6.6 症状6：日志提示upstream timed out
请求进了Controller，但后端响应太慢，触发了上游超时。常规处理是放大概率超时参数：
nginx.ingress.kubernetes.io/proxy-read-timeout: "300" nginx.ingress.kubernetes.io/proxy-send-timeout: "300"但更重要的是判断后端为什么慢。有可能是某个Pod的数据库连接慢，某个接口本身耗时长，或者连接数被打满排队。只看现象改超时只是治标。
7. 实践经验总结：Ingress最值钱的价值是“统一”
聊到这里，Ingress的原理和实操就基本覆盖完了。如果让我提炼一个核心观点，我会说：Ingress最值钱的地方在于它把集群外部流量的接入标准统一了。
以前每接一个新服务，都要跟网络组要端口、跟DNS组加记录，防火墙开一堆口子。有了Ingress之后，就固定一个入口，按域名和路径灵活分发，后端Service全跑ClusterIP就行，整个暴露面收得非常干净。同时因为入口集中了，限流、鉴权、访问日志、证书管理都可以在这个统一的入口层面上做文章，省掉大量重复配置。
最后再分享两个实操中过来的细节建议。
第一，所有生产环境的Ingress一定要加ingressClassName，不要依赖默认Controller的自动接管。这能让配置在多人协作出问题的时候少很多无谓的纷争。
第二，建议给Ingress资源统一配置一个公用的annotations模板放团队规范里，把全局限流、连接数、超时这些基础参数都写进去，新服务加进来时不用再一个个讨论该配多少，减少很大的沟通成本。
我和Ingress的渊源不算浅，一开始踩过404，也被证书问题坑到半夜拉群处理。但系统玩明白之后，它带来的便利性是真的高。希望这篇笔记能帮你少走一点弯路，把Ingress真正地用起来，而不是停留在看过文档、建过资源的阶段。
语法分析器Java实现：从LR(0)项目集到ACTION/GOTO表)
