5.1 Ingress 控制器的分布式路由
卷二讲过 Service 是四层(L4)虚拟 IP:把流量按端口转发到一组 Pod,不关心 HTTP 语义。但真实产品入口几乎都是七层(L7)需求——按域名区分租户、按路径区分服务、按规则做金丝雀。K8s 用一个声明式资源回答「流量按什么规则进集群」:Ingress;再用一个分布式组件回答「声明怎么变成路由表」:Ingress 控制器。
本节把 Ingress 拆成「声明」与「执行」两半:声明是用户写的 networking.k8s.io/v1 资源,执行是控制器里把 host+path 规则翻译成数据面配置的那条链路。理解这条链路,就理解了为什么 Ingress 不是资源本身在路由,而是控制器进程在路由。
为什么需要七层入口
四层 Service 把「端口 → 后端组」固定死,无法表达「同一个 IP 上按域名分流」。对比两者:
| 维度 | Service(L4) | Ingress(L7) |
|---|---|---|
| 匹配单位 | IP + 端口 | host + path + 请求头 |
| 表达内容 | 后端选择 | 路由规则(谁到谁) |
| 谁实现 | kube-proxy(数据面) | 控制器 + 第三方数据面 |
| 更新代价 | 端点变化 | 规则变化要重建路由表 |
| 典型场景 | Pod 间互访 | 外部 HTTP 流量入口 |
关键区别在「谁实现」:Service 的虚拟 IP 由集群内 kube-proxy 负责(卷二第 2 章);Ingress 的七层路由没有内置实现,K8s 只提供声明,路由能力由你安装的控制器提供。这是 Ingress 架构的第一原则:资源与实现解耦。
Ingress 资源模型:声明不是规则
一个最小 Ingress 长这样(networking.k8s.io/v1):
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: api-ingress
spec:
ingressClassName: nginx
rules:
- host: api.example.com
http:
paths:
- path: /v1
pathType: Prefix
backend:
service:
name: api-v1
port:
number: 80
字段语义与判断点:
| 字段 | 含义 | 判据 |
|---|---|---|
ingressClassName | 指定由哪个控制器实现 | 指向 IngressClass 资源 |
rules[].host | 精确域名(空 = 任意 host) | 精确匹配,不模糊 |
http.paths[].path | 路径(配合 pathType) | 前缀/精确/实现相关 |
pathType | Prefix / Exact / ImplementationSpecific | 决定匹配算法 |
backend | 命中后的目标 Service | 名字 + 端口 |
注意 pathType 是匹配算法的开关:Prefix 按路径元素前缀匹配,Exact 要求完全相等,ImplementationSpecific 把语义交给控制器(多数控制器按 Prefix 解释)。Ingress 对象本身不含路由逻辑——它只是数据,真正的逻辑在控制器里。
Ingress 控制器:把声明变成路由规则
控制器是一个独立的分布式组件,循环做三件事:watch 变化 → 构建路由配置 → 下发到数据面。常见实现与下发方式差异很大:
| 控制器 | 数据面 | 规则下发方式 | 数据面形态 |
|---|---|---|---|
| ingress-nginx | Nginx | 生成 nginx.conf,测试后 reload | 每节点 DaemonSet / 部署 |
| HAProxy Ingress | HAProxy | 生成 haproxy.cfg,graceful reload | 部署 |
| Traefik | 自研 Go 代理 | 配置热更新,无需 reload | 部署 |
| Contour | Envoy | xDS(ADS)流式推送 | Envoy 集群 |
表中「下发方式」决定了一个关键性质:规则变化对数据面是「全量替换」还是「增量推送」。nginx/HAProxy 系是前者——控制器把整个路由配置重新生成再原子替换;Envoy 系是后者——通过 xDS 协议只推增量。无论哪种,用户写 Ingress 的体验都一样:改声明,流量自动变。这背后是卷二第 5 章的控制回路:期望状态(Ingress 声明)与当前状态(数据面配置)反复对齐。
host 匹配:精确为主
Ingress 的 host 语义很简单:精确匹配。host: api.example.com 只匹配 api.example.com,不匹配 api.example.com. 或 www.api.example.com;host 留空表示匹配所有 Host。规则之间是「命中一条即路由」的关系,host 相同时由 path 进一步区分。
一个容易混淆的点:*.example.com 形式的通配 host 只有在控制器明确支持时才生效(多数控制器支持一级通配),但它不属于 networking.k8s.io/v1 的强约束,而是控制器的实现能力。依赖通配 host 前,先查控制器的文档,而不是默认它有。
path 匹配:前缀语义与最长优先
path 是路由的细分维度。pathType: Prefix 的官方语义按 / 做元素级前缀匹配:规则 /api 匹配 /api、/api/、/api/v1,不匹配 /apix、/apibar。当多个 path 同时命中时,规范要求最长匹配优先:规则 /api/v2 与 /api 都命中 /api/v2/users 时,选更长的 /api/v2。
这正是本节 lab 的核心行为,gateway.go 的 Match 用两条规则表达:一是 host 精确,二是 path 前缀 + 最长优先。真实 ingress-nginx 的行为与之一致:对每个 host,把 path 按长度排序,长者在先。
| 请求路径 | 规则 /api | 规则 /api/v2 | 结果 |
|---|---|---|---|
/api | 命中 | 不命中 | /api |
/api/v2/users | 命中 | 命中(更长) | /api/v2 |
/apix | 不命中(边界规则) | 不命中 | 无 |
路径边界的坑:/api 不应匹配 /apix
前缀匹配最容易踩的坑是把「字符串前缀」当成「路径前缀」。/api 是 /apix 的字符串前缀,但不是路径前缀——按 / 元素切分后,/api 的元素是 ["api"],/apix 的元素是 ["apix"],前者不是后者的元素前缀。K8s 规范明确规定 /foo 不匹配 /foobar。
真实事故里最常见的配置错误就是:
- path: /api # pathType: Prefix
backend: { service: { name: api } }
- path: /apix # 期望独立服务
backend: { service: { name: apix } }
如果控制器把 /api 当字符串前缀,/apix/... 的流量会被 /api 规则抢走,用户看到「/apix 的服务间歇性被错误路由」。ingress-nginx 等主流控制器都按元素级前缀处理,所以 /api 不会吞掉 /apix;但不要假设所有控制器都这样——ImplementationSpecific 的语义完全由控制器决定,跨控制器迁移前必须验证边界行为。
控制器的分布式属性
把 Ingress 控制器放进分布式系统框架看,它有四个显眼的属性:
| 属性 | 在 Ingress 控制器里的体现 |
|---|---|
| 状态感知 | watch Ingress/Service/EndpointSlice/Secret,维护本地缓存 |
| 决策集中 | 路由表在控制器内构建,数据面不参与决策 |
| 下发解耦 | 通过 reload / xDS 把规则交给独立数据面进程 |
| 最终一致 | 声明更新到流量生效之间有传播延迟 |
最后一条值得展开:控制器 watch 到新 Ingress 后,构建配置、reload 数据面、新连接按新规则路由,整个过程是秒级的。在到达新配置之前,旧规则仍在服务——这正是卷二反复强调的「最终一致」:Ingress 的规则更新不是原子切换,而是异步收敛。理解这点,排障时就不会在「我改了 Ingress 但流量没变」上浪费时间,而会去看控制器日志确认规则是否已下发。
多规则求值:host 分组与默认后端
多条规则求值时,Ingress 的实际做法是先按 host 分组,再在组内按 path 最长优先。匹配不是「全局最长 path 先赢」,而是「先锁定 host,再在锁定的组里比 path」。这个两级顺序对排障很重要:
| 请求 | host 命中 | path 命中 | 最终后端 |
|---|---|---|---|
| api.example.com /v1/users | api.example.com | /v1(最长) | api-v1 |
| api.example.com /healthz | api.example.com | /(兜底) | api-default |
| other.example.com /x | other.example.com | / | other |
注意上表第二行:存在 /v1 规则,但请求 /healthz 不命中它,于是落到 path: / 的默认路径——Ingress 没有「路径不存在就 404」的强约束,命中与否取决于声明了哪些 path。如果一个 host 下只有 /v1 一条规则,/x 请求通常得到 404,而不是落到别处。这个兜底行为由控制器实现决定,跨控制器存在差异,依赖前先验证。
控制器的高可用:多副本与单写者
控制器是「多副本部署」还是「单写者」?这由实现决定,两种模型都存在:
| 模型 | 数据面 | 典型场景 |
|---|---|---|
| 每副本独立 | 每个 Pod 都有自己的数据面实例,前置 LB 分发 | ingress-nginx 多副本 |
| 单写者 + 选举 | leader 生成配置并下发,其余副本 standby | 部分控制器 |
共同点是数据面可水平扩展:无论哪种模型,多副本都提升入口容量,而「谁生成配置」的语义不同。排障时先确认控制器属于哪一种——如果是每副本独立,那么「我改了 Ingress,某个副本还是旧规则」是正常现象,直到该副本 watch 到更新;如果是单写者,则要看 leader 是否正常。这一层差异再次说明:Ingress 资源是稳定的,控制器是可替换的。
从声明到流量:一次配置下发的时间线
把 5.1 节全链路串成一次事件的时间线,看清「改了 Ingress 到流量变化」中间发生了什么:
| 时刻 | 事件 | 说明 |
|---|---|---|
| t0 | 用户 apply Ingress | 写入 etcd,资源可见 |
| t0+Δ1 | 控制器 watch 到事件 | informer 收到增量 |
| t0+Δ2 | 构建新路由配置 | 读取 Service/EndpointSlice |
| t0+Δ3 | 下发数据面 | reload / xDS 推送 |
| t0+Δ4 | 新连接按新规则路由 | 生效完成 |
Δ1–Δ4 加起来通常亚秒到秒级;若配置校验失败,控制器会保持旧配置并报事件。「改了没生效」先按时间线定位在哪个阶段:etcd 里有没有、控制器日志有没有 build、数据面有没有 reload——这条线也是 5.3 节多集群一致性边界的单集群版本。
三个常见误解
- 「Ingress 是 K8s 内置的路由器,资源一创建就生效」——错误。K8s 只提供声明资源,没有内置数据面;没有控制器时 Ingress 什么都不做,只躺在 etcd 里。
- 「Ingress 的路径匹配就是字符串前缀」——错误。
pathType: Prefix按/元素级匹配,/api不匹配/apix;字符串前缀是错误模型。 - 「Ingress 路由是原子切换,改完立即生效」——错误。控制器 watch→构建→下发是异步收敛,新旧规则之间有一个过渡窗口,行为是最终一致的。
一句话总结本节
Ingress 把七层入口抽象成「host+path 声明」,Ingress 控制器把声明翻译成数据面路由规则。收成三个要点:
- 声明与执行解耦:资源描述「想要的路由」,控制器负责「把路由变成数据面配置」,没有控制器就没有路由。
- 匹配语义明确:host 精确、path 按元素级前缀 + 最长优先,
/api不匹配/apix。 - 异步收敛:规则更新靠 watch→构建→下发链路,生效是最终一致而非原子切换。
下一节看 Ingress 的进化版:Gateway API 如何把入口抽象成角色分离的资源模型。
本节 lab
本节把「host+path 匹配与最长前缀优先」落到 gateway.go 的 Ingress.Match:
cd private/labs/k8s-net-lab
go test ./gateway -run TestIngressHostPathMatch -v
go test ./gateway -run TestIngressLongestPrefix -v
TestIngressHostPathMatch 覆盖 host 精确、默认路径、未知 host 无后端四条断言;TestIngressLongestPrefix 验证最长前缀优先与边界规则——/api 命中 /api/v2 而非 /api,且 /apix 不命中 /api。这正是本节匹配语义的最小落地:host 精确、path 前缀、最长优先、边界不被字符串前缀吞掉。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。