密码学与证书 / 系统课时
把证书接入 Ingress 与 Gateway
把证书接入 Ingress 与 Gateway
入口层真正使用的是 TLS Secret,而不是 Certificate 对象本身。本篇分别展示 Ingress 与 Gateway API 如何引用同一个证书 Secret,并通过外部 TLS 握手验证证书轮换后控制器是否已经把新证书切到真实流量上。
学习目标
- 能让 Ingress 和 Gateway HTTPS Listener 正确引用
kubernetes.io/tlsSecret - 理解证书 Secret 更新后入口控制器的监听、重载与新连接生效过程
- 能通过证书指纹验证自动更新是否已经到达外部流量路径
让 Ingress 消费 TLS Secret
假设命名空间 edge 中已有 Certificate/web-example-com,其 secretName 为 web-example-com-tls,并已有 Service web:80。Ingress 只需要在 spec.tls[].secretName 指向该 Secret。
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web
namespace: edge
spec:
ingressClassName: nginx
tls:
- hosts:
- web.example.com
secretName: web-example-com-tls
rules:
- host: web.example.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: web
port:
number: 80应用并确认引用关系:
kubectl apply -f ingress.yaml
kubectl -n edge get ingress web \
-o jsonpath='{.spec.tls[0].secretName}{"\n"}'预期输出
ingress.networking.k8s.io/web created
web-example-com-tls如果控制器支持该 IngressClass,它会监听 Secret 变化并更新 TLS 配置。DNS、负载均衡地址和控制器就绪状态仍需按所用 Ingress Controller 单独确认。
让 Gateway Listener 引用证书
Gateway API 的对应字段位于 HTTPS Listener 的 tls.certificateRefs。下面是片段示例:它依赖集群已安装 Gateway API CRD,且存在名为 public-gateway 的 GatewayClass;HTTPRoute 不在本课展开。
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: public-web
namespace: edge
spec:
gatewayClassName: public-gateway
listeners:
- name: https
hostname: web.example.com
port: 443
protocol: HTTPS
tls:
mode: Terminate
certificateRefs:
- kind: Secret
name: web-example-com-tls同命名空间引用最简单:Gateway 与 Secret 都在 edge。若要跨命名空间引用证书,需要额外遵循 Gateway API 的授权机制,并确认所用实现支持该模式,不能只改一个 namespace 字段就默认可用。
验证 Listener 实际引用的 Secret:
kubectl apply -f gateway.yaml
kubectl -n edge get gateway public-web \
-o jsonpath='{.spec.listeners[0].tls.certificateRefs[0].name}{"\n"}'预期输出
gateway.gateway.networking.k8s.io/public-web created
web-example-com-tlsIngress 与 Gateway 通常是两种入口方案,不要为了演示在同一生产域名上同时配置两个会争抢流量的入口。这里的共同原则只是:两者都消费稳定命名的 TLS Secret。
看懂自动更新如何到达真实流量
当 cert-manager 重新签发证书后,它更新原 Secret 的 tls.crt 和 tls.key。Ingress Controller 或 Gateway 实现观察到 Secret 变化后,重新加载证书;已经建立的 TLS 连接通常继续使用旧会话,而后续新握手应拿到新证书。

因此“Secret 已经更新”只证明证书管理链路完成了一半;入口控制器是否监听到更新、数据面是否完成重载、客户端是否看到新证书,必须分别验证。
用外部握手验收证书轮换
下面的测试脚本先读取当前站点证书 SHA-256 指纹,再通过 cmctl renew 主动触发一次续期,随后每 5 秒重新建立 TLS 连接,直到外部端点返回不同指纹。请在测试证书、内部 CA 或允许重签的环境使用,避免无意义消耗生产 CA 的签发配额。
read_fingerprint() {
openssl s_client \
-connect web.example.com:443 \
-servername web.example.com \
</dev/null 2>/dev/null \
| openssl x509 -noout -fingerprint -sha256 \
| cut -d= -f2
}
before="$(read_fingerprint)"
cmctl renew -n edge web-example-com
for _ in $(seq 1 60); do
sleep 5
after="$(read_fingerprint)"
if [ -n "$after" ] && [ "$after" != "$before" ]; then
printf 'rotated: %s -> %s\n' "$before" "$after"
exit 0
fi
done
echo "certificate did not rotate within the test window" >&2
exit 1预期输出
Manually triggered issuance of Certificate edge/web-example-com
rotated: <VALUE> -> <VALUE><VALUE> 是实际证书指纹。若 Secret 中的证书已变化但外部指纹始终不变,故障点通常已经不在 cert-manager,而是在入口控制器监听、配置下发、负载均衡到旧副本、TLS 会话缓存或 DNS 指向错误。
确认你验证的是流量切换
排查时按链路从内到外检查:先确认 Certificate 已完成新一轮签发,再确认 Secret 数据和资源版本更新,然后看 Ingress/Gateway 的状态与控制器日志,最后用带正确 SNI 的新 TLS 握手检查外部证书。
只要入口始终引用稳定的 Secret 名称,正常续期不应要求修改 Ingress 或 Gateway 配置。真正可靠的验收标准也不是“资源看起来 Ready”,而是新连接已经收到新证书,且业务流量在轮换过程中持续可用。