容器与云原生 / 系统课时
排查 TLS 握手失败
排查 TLS 握手失败
HTTPS 启用后,浏览器报证书错误、curl 握手失败或网关出现 TLS 异常时,先判断故障发生在客户端到入口,还是入口到后端。本课用 SNI、证书、Secret 与控制器状态逐层定位,并用可复制命令完成验证。
学习目标
- 能区分客户端到入口的 TLS 握手问题与入口到后端的协议问题
- 能检查证书域名、有效期、Secret 引用和 SNI 是否一致
- 能按监听器、证书材料和控制器状态的顺序定位 TLS 故障
先判断失败发生在哪一段
TLS 终止在 Ingress Controller 或 Gateway Listener 时,客户端先与入口完成握手,入口再按配置使用 HTTP 或 HTTPS 访问后端。若采用 TLS passthrough 或 TLSRoute,TLS 会话可能由后端终止,此时不能只盯着入口证书 Secret。先确认入口模式,再决定检查哪一段连接。

先用真实业务主机名发起请求。这里保留 -k 只是为了在证书校验失败时继续收集服务端证书和协商信息,不能把它当成最终验收。
curl -vk --resolve app.example.com:443:<IP> https://app.example.com/预期输出会包含实际连接地址、TLS 协商信息和服务端证书;<IP> 替换为入口地址,具体 TLS 版本与证书字段以实际环境为准。
* Added app.example.com:443:<IP> to DNS cache
* Connected to app.example.com (<IP>) port 443
* SSL connection using TLSv1.3 / <VALUE>
* Server certificate:
* subject: <VALUE>
< HTTP/2 200如果这里出现 wrong version number、handshake failure、连接被重置或拿到意外证书,应继续检查入口监听器和证书配置;如果 TLS 已成功协商、随后才返回 502 或 503,则应把注意力转向路由和后端协议。
核对 SNI 与证书域名
HTTPS 客户端通常会在 ClientHello 中携带 SNI,入口据此选择证书。因此,直接访问入口 IP 与通过业务域名访问可能得到不同证书。排障时必须让连接携带真实主机名,否则很容易把默认证书误判为配置错误。
openssl s_client -connect <IP>:443 -servername app.example.com </dev/null 2>/dev/null | openssl x509 -noout -subject -issuer -dates -ext subjectAltName预期输出应能看到证书主题、签发者、有效期和 SAN;字段内容以实际证书为准。
subject=<VALUE>
issuer=<VALUE>
notBefore=<TIME>
notAfter=<TIME>
X509v3 Subject Alternative Name:
DNS:app.example.com重点确认 subjectAltName 覆盖请求域名,并检查 notBefore、notAfter 是否处于有效期内。如果不带 -servername 时得到默认证书,而带 SNI 后得到正确证书,这通常只是虚拟主机的正常证书选择行为。
检查 TLS Secret 与入口引用
对于 Ingress TLS,先确认 spec.tls[].secretName 指向哪个 Secret,再检查 Secret 是否存在于正确的 Namespace。不要直接打印 .data.tls.crt 或 .data.tls.key 来判断字段是否非空;Secret 中的 Base64 内容不是加密数据,尤其不能把私钥材料写入终端回显、流水线日志或审计记录。
kubectl -n <NAMESPACE> get ingress <INGRESS_NAME> -o yaml
kubectl -n <NAMESPACE> describe secret <TLS_SECRET>预期结果中,Ingress 应引用目标 Secret;kubectl describe secret 只显示键名和大小,不显示证书或私钥内容。
Type: kubernetes.io/tls
Data
====
tls.crt: <VALUE> bytes
tls.key: <VALUE> bytes如需确认 Secret 中的证书元数据,可以只解码证书并交给 openssl x509 输出摘要信息,不把完整证书或私钥打印出来。
kubectl -n <NAMESPACE> get secret <TLS_SECRET> -o jsonpath='{.data.tls\.crt}' | base64 -d | openssl x509 -noout -subject -issuer -dates -ext subjectAltName预期输出应与入口实际返回证书的主题、有效期和 SAN 一致。
subject=<VALUE>
issuer=<VALUE>
notBefore=<TIME>
notAfter=<TIME>
X509v3 Subject Alternative Name:
DNS:app.example.comSecret 存在但握手仍失败时,再比较证书公钥与私钥导出的公钥摘要。下面的命令会通过管道读取密钥,但不会把私钥正文打印到终端;两边摘要必须完全一致。
kubectl -n <NAMESPACE> get secret <TLS_SECRET> -o jsonpath='{.data.tls\.crt}' | base64 -d | openssl x509 -pubkey -noout | openssl pkey -pubin -outform DER | openssl sha256
kubectl -n <NAMESPACE> get secret <TLS_SECRET> -o jsonpath='{.data.tls\.key}' | base64 -d | openssl pkey -pubout -outform DER | openssl sha256预期输出中的两个摘要值应相同。
SHA2-256(stdin)= <VALUE>
SHA2-256(stdin)= <VALUE>Gateway API 则检查 HTTPS Listener 的 tls.certificateRefs、Gateway 状态和 Listener Conditions。
kubectl -n <NAMESPACE> get gateway <GATEWAY_NAME> -o yaml
kubectl -n <NAMESPACE> describe gateway <GATEWAY_NAME>预期结果中,目标证书引用应能解析,相关 Accepted、Programmed、ResolvedRefs 条件不应持续为失败状态;具体 Condition 文本由 Gateway 实现决定。若证书跨 Namespace 引用,还要满足 Gateway API 及实现要求的授权规则。
Status:
Conditions:
<VALUE>
Listeners:
<VALUE>检查监听器与控制器是否真正接管配置
资源对象存在,不代表控制器已经成功加载证书并下发监听配置。Ingress 侧检查 IngressClass、地址和事件;Gateway API 侧检查 GatewayClass、Listener Conditions,以及关联 Route 是否被接受。
kubectl -n <NAMESPACE> describe ingress <INGRESS_NAME>
kubectl -n <NAMESPACE> get events --sort-by=.lastTimestamp预期结果中不应持续出现 Secret 不存在、证书解析失败、IngressClass 不受支持或资源引用无法解析等错误。事件原因和文案因控制器不同而不同,应关注配置是否被接管和引用是否成功解析。
Events:
Type Reason Age From Message
<VALUE> <VALUE> <TIME> <VALUE> <VALUE>如果资源状态正常,但入口仍返回意外证书,应回到第一步用相同的业务域名和 SNI 复测,确认请求确实打到当前控制器暴露的入口地址,而不是旧负载均衡器、错误 DNS 记录或其他监听器。
别把后端协议错误当成入口握手错误
如果 openssl s_client 已拿到正确证书,curl 也完成 TLS 协商,但随后返回 502 或 503,客户端到入口的 TLS 已基本正常。此时应检查入口到 Service 使用的是 HTTP 还是 HTTPS,并确认 Service targetPort 对应的容器端口实际监听同一种协议。
kubectl -n <NAMESPACE> run tls-check --rm -i --restart=Never --image=curlimages/curl -- curl -sv http://<SERVICE_NAME>:<PORT>/预期结果应得到后端真实的 HTTP 响应;<PORT> 替换为 Service 暴露端口,Pod IP 等动态值以实际环境为准。
* Connected to <SERVICE_NAME> (<IP>) port <PORT>
> GET / HTTP/1.1
< HTTP/1.1 200 OK如果 HTTP 直连成功,而入口却按 HTTPS 连接该后端,或情况相反,就属于典型协议错配。修复后要去掉 -k 再验证业务域名,确保客户端真正完成证书校验。
curl -v --resolve app.example.com:443:<IP> https://app.example.com/预期结果是握手成功、证书校验通过,并返回符合业务预期的 HTTP 状态码;具体 TLS 版本和响应头可能因环境不同而变化。
* SSL connection using TLSv1.3 / <VALUE>
* SSL certificate verify ok.
< HTTP/2 200最终应同时满足四个条件:SNI 命中正确证书、证书域名和有效期正确、信任链可验证、入口与后端协议一致。