《Kubernetes 分布式系统原理深入解析》5.1 Ingress 控制器的分布式路由

Ingress 是把外部流量声明成 host+path 路由规则的七层入口资源,Ingress 控制器则是把声明翻译成数据面路由规则的分布式组件:watch Ingress/Service、按 host 精确 + path 最长前缀匹配、把规则下发到 nginx/HAProxy 等数据面。本节给出匹配语义与路径边界规则(/api 不匹配 /apix),并拆解控制器 watch→构建→下发的链路。lab 用 gateway.go 验证 host+path 匹配与最长前缀优先。

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)前缀/精确/实现相关
pathTypePrefix / Exact / ImplementationSpecific决定匹配算法
backend命中后的目标 Service名字 + 端口

注意 pathType 是匹配算法的开关:Prefix 按路径元素前缀匹配,Exact 要求完全相等,ImplementationSpecific 把语义交给控制器(多数控制器按 Prefix 解释)。Ingress 对象本身不含路由逻辑——它只是数据,真正的逻辑在控制器里。

Ingress 控制器:把声明变成路由规则

控制器是一个独立的分布式组件,循环做三件事:watch 变化 → 构建路由配置 → 下发到数据面。常见实现与下发方式差异很大:

控制器数据面规则下发方式数据面形态
ingress-nginxNginx生成 nginx.conf,测试后 reload每节点 DaemonSet / 部署
HAProxy IngressHAProxy生成 haproxy.cfg,graceful reload部署
Traefik自研 Go 代理配置热更新,无需 reload部署
ContourEnvoyxDS(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/usersapi.example.com/v1(最长)api-v1
api.example.com /healthzapi.example.com/(兜底)api-default
other.example.com /xother.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 前缀、最长优先、边界不被字符串前缀吞掉。

继续阅读

探索更多技术文章

浏览归档,发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「books」更多文章

  1. 《大规模分布式计算深入解析》15.3 落地:从 Neo4j 到自研图引擎
  2. 《大规模分布式计算深入解析·图计算与图数据库内核》 · 目录与学习路径(45 篇)
  3. 《大规模分布式计算深入解析》15.2 十一卷主线:从切分到图