容器与云原生 / 系统课时
配置 Ingress TLS
配置 Ingress TLS
本课解决 Ingress HTTPS 入口配置问题。你将创建 TLS Secret,把证书与域名绑定到 Ingress,并用 curl 与 openssl 验证入口实际返回的证书、SNI 名称和 HTTP 路由是否一致。
学习目标
- 能使用
kubernetes.io/tlsSecret 为 Ingress 配置 HTTPS - 能理解 TLS Secret、
spec.tls.hosts与spec.rules.host的匹配关系 - 能通过握手证书与 HTTP 响应定位常见 TLS 配置错误
准备证书与 Secret
Ingress TLS 通常使用 kubernetes.io/tls 类型的 Secret 保存证书链与私钥,键名为 tls.crt 和 tls.key。已有测试证书时,可直接创建:
kubectl create secret tls app-example-tls --cert=<PATH>/tls.crt --key=<PATH>/tls.key预期结果
secret/app-example-tls created<PATH> 替换为实际目录。证书的 SAN 必须覆盖 app.example.com;仅有相同 CN 不能替代 SAN 校验。被 secretName 引用的 Secret 还必须与 Ingress 位于同一 Namespace,否则控制器无法按该引用读取证书。
在 Ingress 中声明 TLS
spec.tls[].hosts 是域名数组,secretName 指向对应证书 Secret;spec.rules[].host 决定 HTTP 请求进入哪条业务路由。下面示例假设 demo-web Service 已存在:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: demo-https
spec:
tls:
- hosts:
- app.example.com
secretName: app-example-tls
rules:
- host: app.example.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: demo-web
port:
number: 80配置文件保存为 <PATH>/demo-https.yaml 后应用:
kubectl apply -f <PATH>/demo-https.yaml预期结果
ingress.networking.k8s.io/demo-https created若对象已存在,结果可能是 configured 或 unchanged。TLS 握手阶段,客户端通过 SNI 发送 app.example.com,入口应返回 SAN 覆盖该名称的证书;握手完成后,HTTP Host 再参与 Ingress Rule 匹配。TLS Secret 只提供证书材料,并不会让其他 Host 自动复用同一业务路由。

验证证书与 HTTPS 请求
先确认 Secret 和 Ingress 的关联,再从能访问入口的环境发起带正确域名的 HTTPS 请求:
kubectl get secret app-example-tls
kubectl describe ingress demo-https
curl -vk --resolve app.example.com:443:<IP> https://app.example.com/预期结果
NAME TYPE DATA AGE
app-example-tls kubernetes.io/tls 2 <AGE>
TLS:
app-example-tls terminates app.example.com
< HTTP/1.1 200 OK
...<IP> 替换为 Ingress 入口地址,<AGE> 等动态值会随环境变化,kubectl describe 的排版也可能因版本和控制器不同而变化。-k 只适合测试排障,它会跳过客户端对证书信任链和名称的校验;正式验收应使用受信任证书并去掉 -k。同时要确认 HTTP 响应确实来自预期后端,而不只是看到 TLS 握手成功。
用 openssl 检查入口实际证书
浏览器提示证书错误时,不要只检查 Secret 内容。直接查看入口实际返回的证书,可以识别证书未加载、SNI 不匹配或控制器仍返回默认证书等问题:
openssl s_client -connect <IP>:443 -servername app.example.com < /dev/null 2>/dev/null | openssl x509 -noout -issuer -dates -ext subjectAltName预期结果
issuer=<ISSUER>
notBefore=<TIME>
notAfter=<TIME>
X509v3 Subject Alternative Name:
DNS:app.example.com字段顺序和签发者会随证书而不同,验收重点是实际返回证书的 SAN 覆盖 app.example.com,并且有效期符合预期。Secret 中存有正确证书,不等于入口控制器已经成功加载它。
常见失败定位
Secret 不存在、类型不正确或证书与私钥不匹配时,应先查看 Ingress Controller 的事件或日志;SNI 与配置域名不一致时,客户端可能拿到默认证书;证书正确但请求返回 404、502 或其他异常时,应继续检查 Ingress Rule、Path、Service 和后端 Pod,而不是反复替换证书。
不要只访问 https://<IP>/ 来验证域名入口。这样无法证明 app.example.com 的 SNI、证书名称和 Host 路由同时正确。curl --resolve 可以在连接指定入口 IP 的同时保留正确的 URL Host 与 SNI。只有 Ingress 正确引用 TLS Secret、实际握手返回覆盖目标域名的证书,并且 HTTPS 请求进入预期 Service,这条 TLS 入口才算验收完成。