Kubernetes Gateway API 迁移指南：从 Ingress TLS 配置到声明式证书管理

上周五晚上线上一个商户后台突然打不开浏览器直接弹出证书无效警告。我第一反应是证书过期了结果打开Secret一看validTo字段明明还有将近一年。折腾了三个多小时最后才定位到Ingress的tls配置块里Secret跟hostname没有结对上Nginx Ingress Controller在转发时依然使用默认证书连一条有效的报错日志都没留下。这种“证书配置看起来没问题但就是不对”的坑长期维护过Kubernetes集群的人基本都踩过。忍了Ingress注解式TLS这么久我终于把核心服务切到了Kubernetes的Gateway API上它把TLS路由从一个补丁式的配置项变成了有边界的声明式资源证书挂在Gateway上SNI分发发生在监听器里路径和主机名的路由分发放到了Route这一层。每一层出了问题都能在对象的status字段里直接看到原因。这篇博客会按照我从传统Ingress迁移到Gateway API的实际顺序来写先讲Ingress的TLS配置在真实场景里为什么撑不住再拆解GatewayClass、Gateway、HTTPRoute和TLSRoute各自对TLS的职责边界然后给出一套从零配置HTTPS网关的完整链路和验证命令专门讲SNI多证书、TLS透传和证书轮转这几个容易绕晕的场景最后分享一套我自己用的排错链路和工具。适合已经有K8s基础、正在评估或准备迁移Gateway API的读者也适合那些听过Gateway API概念但还不知道TLS具体怎么落地的同学。1. 为什么我放弃了Ingress上的注解式TLS转投Gateway API声明式配置1.1 Ingress的TLS能力为什么撑不住多团队场景Ingress的对象模型本质上是一个反向代理的配置对象核心字段只有rules和tls。TLS相关的配置就更简单了一个tls块里塞一个secretName加一串hosts。这个模型在单人维护的计算节点集群里够用一旦到了多团队、多域名、多证书的生产环境问题就陆续浮出来。首先是证书与后端的绑定关系太弱。Ingress的tls块只会影响入口的证书选择至于这个证书应该服务哪些后端、哪些路径全靠hosts字段来对应。只要hosts写错或者一个Ingress里同时挂了好几个服务控制器大概率会安静地使用默认证书或第一个匹配到的证书。我开头提到的故障就是这种场景Secret内容正确、服务正常、Ingress也显示Accepted但客户端拿到的证书跟域名完全不匹配。整个Ingress体系没有把“列表中的host”和“证书里的SAN”做强校验问题只会在业务侧爆发。其次是多证书、多命名空间的隔离很难做。Ingress机制本身要求Secret和Ingress在同一个命名空间。跨命名空间引用要么把证书Secret复制到每个业务命名空间要么自己修改Ingress Controller的行为。对于有安全审计要求的平台团队来说到处复制证书Secret本身就是审计上的麻烦。证书的敏感性决定了它不应该被无授权地复制和传播。第三个问题是厂商差异全堆在annotation里。nginx.ingress.kubernetes.io/ssl-redirect、cert-manager.io/cluster-issuer、alb.ingress.kubernetes.io/certificate-arn……每个Ingress Controller都有自己的注解体系换一套控制器等于把清单全部重写。TLS路由在Ingress世界里不是标准能力而是各家控制器的方言。Gateway API把入口流量的控制面从一个资源变成分层模型恰好把这些痛点逐层拆解掉了。1.2 Gateway API的三层抽象到底抽象了什么Gateway API把入口流量分成了GatewayClass、Gateway、Route三层。对应到TLS场景里这三层的分工非常清楚GatewayClass声明“谁来提供这个网关能力”比如Contour、Istio、Nginx Gateway Fabric。它不关心证书只负责把具体实现和集群解耦。Gateway声明“在集群边界开放哪些端口和协议”。TCP、UDP、HTTP、HTTPS、TLS这些协议都通过listeners定义证书引用、TLS工作模式都落在这一层。RouteHTTPRoute、TLSRoute、TCPRoute等声明“流量怎么分发到后端服务”。HTTPRoute负责在TLS终止后的七层转发TLSRoute负责四层透明转发。这个分层最大的价值在于平台团队只管GatewayClass和Gateway业务团队只管Route。证书这类基础设施配置被隔离在Gateway层业务团队在Route里看不到也不应该看到私钥相关内容。1.3 从“注解”到“资源”的迁移感受最直观的变化是配置风格的改变。以前一段Ingress的TLS配置是这样写的多个host绑定一个Secret路径规则和TLS配置杂糅在同一个块里apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: app-ingress namespace: apps spec: tls: - hosts: - app.example.com secretName: app-tls rules: - host: app.example.com http: paths: - path: / pathType: Prefix backend: service: name: app-svc port: number: 8080现在同样是为HTTPS服务做入口配置证书定义在Gateway上路由规则在HTTPRoute里两个对象通过parentRefs建立关联。如果配置过程中出问题对象的conditions会直接告诉你监听器为什么拒绝、证书引用是否解析成功、路由有没有匹配上。这种反馈机制是传统Ingress完全没有的。问题维度IngressGateway APITLS配置位置spec.tls与rules杂糅spec.listeners[].tls独立分层证书引用secretName仅限同命名空间certificateRefs跨命名空间需ReferenceGrant授权多证书多域名一个Ingress多个tls块匹配规则模糊多listener按hostname精确SNI分发错误反馈日志含糊经常静默降级status.conditions直接给出拒绝原因从我实际的迁移感受来说Gateway API的模型确实带来了额外的学习成本但TLS配置的可观测性和可审计性提升非常明显。2. TLS到底归谁管GatewayClass、Gateway与Route的职责边界2.1 证书必须落在Gateway监听器上一个Gateway可以定义多个listeners每个监听器由协议、端口、hostname三件套确定。TLS相关的配置就藏在listener的tls块里spec: listeners: - name: app-https port: 443 protocol: HTTPS hostname: *.example.com tls: mode: Terminate certificateRefs: - name: app-tls kind: Secret group: tls块里的mode字段有两档Terminate表示网关自己解密TLS然后把解密后的HTTP请求转发给后端Passthrough表示网关不解密只看SNI做转发原始TLS流量直达后端。certificateRefs只在Terminate模式下生效Passthrough模式下这个字段应当留空。这个点很多人会搞反配置TLS透传时还把证书挂上去控制器虽然不报错但行为不符合预期。2.2 hostname和SNI是怎么被匹配的监听器的hostname不是摆设。客户端发起TLS握手时带着SNIServer Name Indication网关用“端口SNI”的组合去匹配监听器。匹配成功之后才会有后续的Route匹配。这个匹配顺序决定了三层逻辑监听器hostname设成*.example.com可以接app.example.com、api.example.com这些子域的SNI。如果多个域名需要各自不同的证书就必须拆成多个listener端口相同、hostname不同、certificateRefs不同。如果监听器不写hostname它对所有SNI都开放但证书只能引用一份。我在实际配置中发现很多刚接触Gateway API的人直接把监听器的hostname留空以为“反正我有通配符证书”。但一旦某个域名没有证书网关不会聪明地自动回退到默认证书很多控制器会直接拒绝TLS握手。把hostname精确化既能让证书选择变得明确也能让路由绑定的范围更可控。2.3 HTTPRoute和TLSRoute在使用场景上的差异HTTPRoute的使用前提是网关已经终止了TLS或者本身就是HTTP明文Route用hostname和path完成七层分发。TLSRoute则对应Passthrough场景网关拿到TLS握手后只看SNI字段把整个TCP流转发到后端后端服务自己完成解密。两种Route适用于完全不同的架构如果你的后端就是普通HTTP服务应该用HTTPRoutecertificateRefs配置在Gateway上网关统一卸载TLS。如果后端自己就是一个网关、代理或需要保留完整TLS会话的服务用TLSRoute做四层转发更合适。这样做的好处是端到端加密不中断、后端服务对证书有完全控制权同时网关侧的TLS审计点变少了。这类架构在API网关下沉、边缘计算网关等场景非常常见。2.4 为什么证书放Gateway而不是Route我一开始也想不通Route里已经有hostname了为什么不把证书放到Route上使用一段时间之后才理解设计的用意证书本质上是“入口的信任边界”它和“流量的分发规则”是两件生命周期完全不同的事。证书由平台团队统一管理轮换节奏是月级路由规则由业务团队维护发布节奏可能是天级。如果把两者放同一个对象里两边会为了各自的节奏不断互相打扰流程上容易互相阻塞。Gateway API通过对象边界约束了团队协作边界这其实比技术本身更有价值。3. 从零配置一个HTTPS网关使用Contour的完整链路3.1 环境准备和CRD安装动手之前先确认Gateway API的CRD已经安装。可以用官方release的standard-install.yaml也可以到官方仓库的releases页面获取当前版本kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.1.0/standard-install.yaml这一条命令安装好之后可以先用kubectl get crd | grep gateway确认CRD版本。这里提醒一个版本细节Gateway、GatewayClass、HTTPRoute在v1版本里已经是GA了apiVersion用gateway.networking.k8s.io/v1但TLSRoute目前仍处于v1alpha2阶段不同release版本的API版本可能会有差异先查一下自己集群里的CRD再写YAML。控制器我用Contour的Gateway provisioner来演示因为Contour对Gateway API的标准一致性做得比较早也可以用Istio、Traefik等其它实现替换控制器名称等核心字段做相应调整即可。3.2 准备证书和Secret测试环境用openssl自签一张证书就能跑通整个链路openssl req -x509 -nodes -days 365 -newkey rsa:2048 \ -keyout tls.key -out tls.crt \ -subj /CNapp.example.com \ -addext subjectAltNameDNS:app.example.com创建Kubernetes Secret时注意Secret的type必须是kubernetes.io/tls且tls.crt和tls.key两个键必须存在。有的控制器还会对证书内容的格式做进一步校验如果Secret的type写错或者键名不对监听器会直接报InvalidCertificateRefkubectl create secret tls app-tls --certtls.crt --keytls.key -n infra生产环境不建议用自签直接接入cert-manager管理证书这个我在第4部分展开说。3.3 声明GatewayClass和Gateway创建一个带GPRC的GatewayClass和Gateway。GatewayClass的controllerName必须与安装的控制器一致Contour对应的是projectcontour.io/gateway-controllerapiVersion: gateway.networking.k8s.io/v1 kind: GatewayClass metadata: name: contour-gwclass spec: controllerName: projectcontour.io/gateway-controller --- apiVersion: gateway.networking.k8s.io/v1 kind: Gateway metadata: name: my-gateway namespace: infra spec: gatewayClassName: contour-gwclass listeners: - name: app-https port: 443 protocol: HTTPS hostname: *.example.com tls: mode: Terminate certificateRefs: - name: app-tls kind: Secret group: 这段配置的核心就是告诉网关在443端口监听HTTPS对*.example.com这个域名范围内的SNI做TLS终止证书使用infra命名空间下的app-tlsSecret。做完这一步用kubectl get gateway -n infra检查STATUS如果显示AcceptedTrue说明监听器被控制器接受了。3.4 绑定HTTPRoute接着创建HTTPRoute把域名app.example.com的流量路由到后端服务apiVersion: gateway.networking.k8s.io/v1 kind: HTTPRoute metadata: name: app-route namespace: apps spec: parentRefs: - name: my-gateway namespace: infra hostnames: - app.example.com rules: - matches: - path: type: PathPrefix value: / backendRefs: - name: app-svc port: 8080这里有个频繁踩坑的点HTTPRoute的hostnames必须在监听器hostname的覆盖范围内。如果监听器写的是*.example.comRoute里写api.another.com是绑不上的。绑定后可以用kubectl describe httproute app-route -n apps查看Accepted和ResolvedRefs两个condition的状态。3.5 用curl验证HTTPS证书准备好、Gateway正常、Route已绑定之后可以先做一个快速验证curl -k https://app.example.com/-k表示跳过证书校验这一步只能证明TLS握手成功、路由通了。要真正验证证书链、证书内容、SNI选择是否正确就要用openssl s_client这个我在第5部分详细展开。4. SNI分发、TLS透传与证书轮转三个绕晕人的真实场景4.1 SNI多域名多证书一个端口承载十几个域名生产环境里最常见的需求是同一个443端口要承载app.example.com、api.example.com、admin.example.com等多个域名且每个域名用各自独立的证书。Gateway API的做法是在同一个Gateway里配置多个listener端口相同、hostname不同、certificateRefs不同spec: listeners: - name: app-https port: 443 protocol: HTTPS hostname: app.example.com tls: mode: Terminate certificateRefs: - name: app-tls kind: Secret group: - name: api-https port: 443 protocol: HTTPS hostname: api.example.com tls: mode: Terminate certificateRefs: - name: api-tls kind: Secret group: 网关收到api.example.com的TLS握手请求会优先匹配到api-https这个listener使用api-tls证书响应握手。如果收到的SNI不在任何listener的hostname范围内网关不会自作主张地用一个默认证书回应大概率会直接中断握手。你在配置域名列表的时候必须把覆盖范围拉全不能想当然地认为“反正是默认443总会有一个默认证书兜底”。4.2 TLSRoute透传证书不卸载、SNI直达后端另一个常见场景是后端服务自己就是做完TLS的入口。这块我以四层TLS透明转发为例一套独立的API网关或流量网关部署在K8s集群内证书由后端团队自己管理前端的K8s网关只做流量接入和网络策略控制不做TLS卸载。这时需要把Gateway监听器的协议从HTTPS改成TLSmode设为Passthrough证书引用留空apiVersion: gateway.networking.k8s.io/v1 kind: Gateway metadata: name: my-gateway namespace: infra spec: gatewayClassName: contour-gwclass listeners: - name: tls-passthrough port: 443 protocol: TLS hostname: *.example.com tls: mode: Passthrough然后使用TLSRoute做四层转发apiVersion: gateway.networking.k8s.io/v1alpha2 kind: TLSRoute metadata: name: tls-app-route namespace: apps spec: parentRefs: - name: my-gateway namespace: infra hostnames: - app.example.com rules: - backendRefs: - name: app-gateway-svc port: 8443配置的时候注意Protocol是TLS时HTTPRoute没法绑定上去必须用TLSRoute。TLSRoute的hostnames字段在这里的含义就是SNI白名单网关根据SNI匹配到后端后将整个TCP数据流原封不动转发。Terminate和Passthrough两种模式没有绝对的好坏选择依据是你的安全边界到底在哪里是网关统一做TLS卸载方便审计还是后端服务保留完整会话有更细粒度的控制需求。4.3 证书轮转不是改Gateway而是换Secret内容证书轮转时最重要的是不要改Gateway里的certificateRefs。正确操作是更新同一个Secret的内容Gateway对象不需要做任何变化控制器检测到Secret变化后会自动拉取新证书。这个设计非常方便平台团队因为证书轮换是一个内部流程不应该导致入口配置变更也不需要业务团队介入。生产环境建议直接让cert-manager来管理证书和轮换通过Certificate对象把证书写到同一个SecretapiVersion: cert-manager.io/v1 kind: Certificate metadata: name: app-tls-cert namespace: infra spec: secretName: app-tls issuerRef: name: ca-issuer kind: ClusterIssuer dnsNames: - app.example.com - *.example.com证书到期前cert-manager会自动轮换并更新Secret。这里要记住一个经验轮换后如果访问异常先确认Gateway实现是否watch了Secret的变化少数控制器需要重启Pod才能重新加载证书。这个细节在不同厂商的实现上差异不小排查时值得留意。4.4 跨命名空间引用证书ReferenceGrant这道门平台团队通常把证书集中放在infra命名空间统一管理业务团队在自己命名空间绑定Gateway。但Gateway API的默认规则是Secret只能被同一命名空间的Gateway引用跨命名空间引用必须要有一个显式的ReferenceGrant授权。这个机制防止了任意命名空间的Gateway随便引用别的命名空间的证书。我在这个坑上栽过两次。第一次是只看到Gateway的condition报RefNotPermitted完全没反应过来缺ReferenceGrant。第二次是ReferenceGrant写错字段。正确写法是在Secret所在命名空间创建授权对象apiVersion: gateway.networking.k8s.io/v1 kind: ReferenceGrant metadata: name: allow-infra-secret namespace: infra spec: from: - group: gateway.networking.k8s.io kind: Gateway namespace: apps to: - group: kind: Secret核心逻辑是为了引用infra里的Secretapps命名空间的Gateway必须被授权。to字段里的group为空字符串因为内建Secret的group为空。如果Security team有强管控要求还可以在ReferenceGrant里加name字段做更细粒度的限制避免整个命名空间的Secret都被授权出去。5. 证书不生效时怎么自查从status逐级排查到openssl验证5.1 先看对象的conditions再看证书内容TLS路由不通时我的建议顺序是固定的按这个顺序做能快速缩小范围先看Gateway的状态kubectl get gateway -n infra检查listener的Accepted情况再看Route的状态kubectl get httproute -n apps检查Accepted和ResolvedRefs然后看详细描述kubectl describe gateway my-gateway -n infra资源里会有AttachedRoute、InvalidCertificateRef之类的记录最后打开Secret检查确认type是kubernetes.io/tls、tls.crt和tls.key都存在、证书内容里的域名和实际域名匹配。大多数情况下前三步就能定位问题。别一上来就先怀疑证书先看状态再看证书内容。5.2 高频报错与对应修复下面这个表是我这段时间遇到的高频问题信号、可能原因和处理办法一并列出报错信号可能原因处理办法ResolvedRefsFalse, ReasonInvalidCertificateRefSecret不存在、type不是kubernetes.io/tls、证书内容解析失败重建Secret或修正typeListenerCondition AcceptedFalse, ReasonHostnameConflict两个listener的hostname范围重叠调整listener的hostname确保范围不重叠RouteAcceptedFalse, ReasonNoMatchingParentGateway不存在、或者没有匹配的listener检查parentRefs和listener的protocol/hostnameRefNotPermitted跨命名空间引用证书但缺ReferenceGrant创建对应的ReferenceGrant浏览器提示证书无效Secret里的内容看着正常hostname和证书CN/SAN不匹配查看证书SAN重新签发证书轮换后旧证书仍生效控制器没有watch Secret变化确认实现是否支持证书热加载必要时重启控制器5.3 用openssl验证SNI和证书链curl -k看到HTTP 200只能证明路由通不能证明证书可信。验证SNI和证书链路用openssl s_client直接对接网关入口的IP和443端口openssl s_client -connect 网关IP:443 -servername app.example.com -showcerts输出内容中需要重点看几个字段subject和issuer确认证书是谁签发的签发给谁s:与i:下面的CN和SAN是否包含app.example.comVerify return code返回0表示证书链验证通过返回18表示自签证书这在测试环境是预期的返回21或61等其它错误就说明证书链本身不完整或不受信任。另外把-servername参数换成本机IP或其它域名可以观察网关是否根据SNI返回不同的证书这是验证SNI多证书配置是否生效的最直接方法。5.4 我自己的排查习惯最后分享一个实用习惯提交Gateway和Route的YAML之前先用kubectl apply --dry-runclient本地过一遍再分别用kubectl get和describe确认两个对象的status。绝大多数TLS路由问题不管表面症状有多奇怪都能在status里直接看到原因。如果status全部是Accepted客户端还是访问失败这时再深入数据面排查也不迟。这不是什么高端技巧但真的能帮你节省大量时间。比起盯着Ingress日志翻半天这样的排查链路至少让我少加了无数个通宵班。我个人在实际使用中的体会是从Ingress迁移到Gateway APITLS配置是第一个值得动手改造的点它最痛也最容易验证。遇到TLS问题先别急着怀疑证书文件按“监听器→路由→证书引用→数据面”的顺序排查十分钟内基本能定位。最后再补充一个方向Gateway API还在持续演进后端TLS策略这类能力正在把“网关到后端之间的TLS信任”也纳入声明式管理的范畴等它的API进入beta之后整条链路的TLS策略都能统一管理值得保持关注。