k8s ingress ssl证书怎么配?Ingress TLS Secret 签发、挂载、轮换与报错排查全流程
1. k8s ingress ssl证书的本质是:把 PEM 证书与私钥存成同命名空间的 kubernetes.io/tls Secret,再在 Ingress 的 spec.tls[].secretName 引用;ingress-nginx 1.11 会监听该 Secret 变化,通常 5~30 秒内热加载,不需要重启 Pod。 2. 手动方式最小命令:kubectl create secret tls shop-tls --cert=tls.crt --key=tls.key -n prod,Secret 与 Ingress 必须同 namespace,否则 controller 报 secret not found,443 回落到 Fake Certificate。 3. cert-manager v1.16 方案只需在 Ingress 上加注解 cert-manager.io/cluster-issuer: letsencrypt-prod,且 tls.secretName 与 Certificate 的 secretName 完全一致,Certificate READY=True 一般耗时 30~90 秒。 4. 验证一条命令:openssl s_client -connect :443 -servername shop.example.com -showcerts /dev/null | openssl x509 -noout -subject -issuer -dates,重点看 SAN 是否覆盖域名、notAfter 是否大于 30 天。 5. Let's Encrypt 限制为每注册域名每周 50 张、重复证书每周 5 张、验证失败每小时 5 次,调试期先切 staging 端点 https://acme-staging-v02.api.letsencrypt.org/directory。
为什么 k8s ingress ssl证书配完仍然报证书错误?先看这 5 个根因
配完 Ingress TLS 却还是报证书错误,八成不是 controller 的锅,而是下面 5 个根因之一。先记住一个前提:Ingress 对象本身不存证书。据 Kubernetes 官方文档 Ingress 的 TLS 章节,networking.k8s.io/v1 的 Ingress 只有 spec.tls[].hosts 和 spec.tls[].secretName 两个字段,证书实体始终在 Secret 里,Ingress 只是”引用”。搞清这条引用链在哪一环断掉,问题就定位了。
根因 1:Secret 类型或键名不对,controller 直接忽略
Secret 必须是 type: kubernetes.io/tls,且同时含 tls.crt、tls.key 两个键。用 Opaque 存证书时 ingress-nginx 不会报错,只是静默跳过——这是最隐蔽的一种失败。
# 正确创建方式,kubectl 会校验键名与 PEM 格式
kubectl create secret tls shop-tls
--cert=fullchain.pem # 叶证书 + 中间证书,顺序不可颠倒
--key=privkey.pem # 必须与证书公钥匹配,否则 create 阶段即失败
-n shop
# 自检:type 是否为 kubernetes.io/tls,两个键是否都在
kubectl get secret shop-tls -n shop -o jsonpath='{.type}{"n"}{.data}' | head -c 200
根因 2:跨命名空间引用——apply 不报错,日志才报错
Secret 只能被同 namespace 的 Ingress 引用。把 secretName: shop-tls 写进另一个 namespace 的 Ingress,kubectl apply 依然成功(API Server 不做跨对象校验),但 ingress-nginx 日志会出现:
unexpected error obtaining pem ... secret "shop-tls" not found
此时 443 端口回落到 controller 的默认证书。排查命令:
kubectl get ingress shop -n shop -o jsonpath='{.spec.tls[0].secretName}{"n"}'
kubectl get secret shop-tls -n shop # 换成 Ingress 所在 namespace 再查一次
根因 3:SNI 匹配失败
spec.tls[].hosts 与 spec.rules[].host 不一致,或客户端访问了未列出的域名时,nginx 用 default_server 证书应答。典型报错:
curl: (60) SSL: no alternative certificate subject name matches target host name
# Go 客户端侧表现为
x509: certificate is valid for ingress.local, not shop.example.com
浏览器则提示证书域名不符。修复要点:spec.tls[].hosts 必须覆盖 rules[].host,通配符 *.example.com 仅匹配一级子域。
根因 4:证书链不完整
只上传叶证书、漏掉中间证书时,浏览器与 Go 客户端报 x509: certificate signed by unknown authority。正确顺序是叶证书在前、中间证书在后,根证书不要放(据 Let’s Encrypt 文档,其 fullchain 已含中间证书;把根证书也拼进去会让握手体积变大,且部分客户端的校验路径判断异常)。验证:
openssl s_client -connect shop.example.com:443 -servername shop.example.com -showcerts /dev/null | grep -c "BEGIN CERTIFICATE" # 期望 ≥2
openssl verify -untrusted chain.pem leaf.pem
根因 5:签发侧失败被 Ingress 掩盖
cert-manager 的 Certificate 处于 False 状态时,Ingress 依然创建成功,kubectl get ingress 看起来一切正常,实际 443 用的是名为 Kubernetes Ingress Controller Fake Certificate 的自签占位证书。必须查 Certificate 资源才能发现:
kubectl get certificate -n shop
# NAME READY SECRET AGE
# shop-tls False shop-tls 5m ← READY 为 False 即签发失败
kubectl describe certificate shop-tls -n shop | tail -20 # 看 Events 里的 ACME 错误
常见后续错误是 ACME HTTP-01 校验不通(Waiting for HTTP-01 challenge propagation),根因往往又回到第 3 条的 host 不一致。五个根因常常连锁出现,按”Secret 类型 → namespace → SNI host → 证书链 → 签发状态”的顺序逐层排除,比直接怀疑 controller 快得多。
k8s ingress ssl证书从零到生效的 6 个操作步骤
问:从零开始,让 shop.example.com 走 HTTPS 最少要几步?答:六步,顺序不能乱。DNS 没生效,HTTP-01 自检必挂;IngressClass 名字差一个字符,Challenge 就永远停在 pending。下面每一步都给出可直接复制的命令,以及“怎么算成功”的判据。
-
准备域名解析。先拿到入口地址,再把 A 记录指过去(云上 LoadBalancer 场景也可用 CNAME),TTL 设 300 秒便于回滚。据 ingress-nginx 官方文档,请求打到 controller 但没有匹配规则时返回 404,所以
curl看到 404 反而是“链路已通”的好消息。# 取入口地址:云上看 EXTERNAL-IP,自建裸机看节点 IP + NodePort kubectl get svc -n ingress-nginx ingress-nginx-controller -o wide # DNS 服务商处:shop.example.com A -> 上面的 IP,TTL=300 dig +short shop.example.com # 期望返回该 IP curl -I http://shop.example.com # 返回 404 属正常:流量已到 controller,只是暂无匹配 Ingress -
安装 ingress-nginx 1.11.x。chart 4.11.3 对应 controller v1.11.x,两者版本号不是一回事,别混用旧 chart。
helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx helm repo update helm upgrade --install ingress-nginx ingress-nginx/ingress-nginx --version 4.11.3 -n ingress-nginx --create-namespace kubectl get ingressclass # 期望 NAME=nginx,CONTROLLER=k8s.io/ingress-nginx -
安装 cert-manager v1.16.1。单文件清单包含 CRD、webhook 与 cainjector,必须三个 Pod 全 Running 才继续,否则后面创建 ClusterIssuer 会报
no matches for kind "ClusterIssuer"。kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.16.1/cert-manager.yaml kubectl get pod -n cert-manager -w # cert-manager / cainjector / webhook 三个 Pod 均 Running -
创建 ClusterIssuer。生产环境 ACME server 填
https://acme-v02.api.letsencrypt.org/directory,调试期换成https://acme-staging-v02.api.letsencrypt.org/directory(协议遵循 RFC 8555)。solvers.http01.ingress.ingressClassName必须与步骤 2 里 IngressClass 的名字 逐字一致,否则 challenge 生成的临时 Ingress 不会被 controller 接管,HTTP-01 自检永远 404。# clusterissuer.yaml apiVersion: cert-manager.io/v1 kind: ClusterIssuer metadata: name: letsencrypt-prod spec: acme: server: https://acme-v02.api.letsencrypt.org/directory # 调试期改 staging 地址 email: ops@example.com # 到期提醒发这里 privateKeySecretRef: name: letsencrypt-prod-account-key # ACME 账户私钥存放的 Secret solvers: - http01: ingress: ingressClassName: nginx # 必须等于 kubectl get ingressclass 的名字kubectl apply -f clusterissuer.yaml kubectl get clusterissuer # READY 列应为 True,否则 describe 看 Events -
创建带注解的 Ingress。注解
cert-manager.io/cluster-issuer触发 ingress-shim 自动生成 Certificate CR;若你选择手写 Certificate,则其spec.secretName必须与 Ingress 里spec.tls[].secretName逐字相同,否则证书签出来了却不被使用。apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: shop namespace: prod annotations: cert-manager.io/cluster-issuer: letsencrypt-prod # 触发自动签发 spec: ingressClassName: nginx tls: - hosts: ["shop.example.com"] secretName: shop-example-com-tls # 签发结果写入此 Secret rules: - host: shop.example.com http: paths: - path: / pathType: Prefix backend: service: name: shop-svc port: number: 80 -
观察签发链路。按 Order → Challenge → Certificate 的顺序推进,据 cert-manager 文档,DNS 与网络正常时全程 30~90 秒。典型失败事件是
Waiting for HTTP-01 challenge propagation: wrong status code '404', expected '200',九成是ingressClassName不匹配或 DNS 尚未生效。kubectl get certificate,order,challenge -n prod -w # 看到 Certificate READY=True 即可 Ctrl+C kubectl get secret shop-example-com-tls -n prod # TYPE=kubernetes.io/tls,DATA=2(tls.crt + tls.key) kubectl describe challenge -n prod # 卡住时看 Events 定位
| 对比项 | 生产 acme-v02 | 预发 acme-staging-v02 |
| 浏览器/客户端信任 | 是 | 否,链由 Fake LE Root 签发 |
| 速率限制 | 每个注册域名每周 50 张证书,重复证书 5 张/周 | 限制宽松,适合反复调试 |
| 适用阶段 | 上线 | 联调、验证 YAML 正确性 |
补一句常被忽略的点:Secret 里 DATA=2 是硬指标,只有 1 项说明只写入了 tls.crt 而缺私钥,nginx 会报 cannot load certificate ... No such file or directory 或 PEM_read_bio_X509 错误——此时回到步骤 5 检查 Certificate 的 status.conditions,而不是去改 Ingress 注解。
k8s ingress ssl证书的配置与命令示例(ingress-nginx 1.11 + cert-manager 1.16)
Ingress 里 TLS 到底写在哪、写什么?证书本身不进 Ingress,Ingress 只声明“哪个域名用哪个 Secret”。K8s 1.28–1.31 通用的写法如下(networking.k8s.io/v1,pathType 自 1.19 起为必填):
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: shop
namespace: prod
annotations:
cert-manager.io/cluster-issuer: letsencrypt-prod # 触发 cert-manager 自动签发
nginx.ingress.kubernetes.io/ssl-redirect: "true" # 默认即 true,此处显式写出便于 review
spec:
ingressClassName: nginx
tls:
- hosts: ["shop.example.com"]
secretName: shop-example-com-tls # 必须与签发/上传的 Secret 同名、同 namespace
rules:
- host: shop.example.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: shop
port:
number: 80
让 cert-manager 1.16 自动签发要配什么?一个 ClusterIssuer 即可,HTTP-01 校验会由 cert-manager 自动创建临时 Ingress 完成(协议见 RFC 8555):
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
name: letsencrypt-prod
spec:
acme:
server: https://acme-v02.api.letsencrypt.org/directory # 测试先用 staging 避免触发速率限制
privateKeySecretRef:
name: le-prod-account-key # ACME 账户私钥,集群级复用
solvers:
- http01:
ingress:
ingressClassName: nginx
已有证书怎么手动塞进去?注意 --cert 传的是“叶证书 + 中间证书”拼接的 fullchain,只传叶证书会让部分客户端报 unable to get local issuer certificate:
# fullchain.pem = 服务器证书 + 中间 CA,顺序不能颠倒
kubectl create secret tls shop-example-com-tls
--cert=fullchain.pem --key=privkey.pem -n prod
--dry-run=client -o yaml | kubectl apply -f -
# 确认类型,必须输出 kubernetes.io/tls
kubectl get secret shop-example-com-tls -n prod -o jsonpath='{.type}'
ingress-nginx 1.11 中几个高频 annotation 的默认值,务必记牢,都能在 Ingress 上逐条覆盖(据 ingress-nginx 官方 annotation 文档):
| Annotation | 默认值 | 说明 |
|---|---|---|
| ssl-redirect | "true" |
只要 Ingress 含 tls 段就 301 到 https;设为 false 可保留明文入口 |
| force-ssl-redirect | "false" |
对“未配 TLS 的 Ingress”也强制跳转,用于全局收口 |
| ssl-protocols | "TLSv1.2 TLSv1.3"(1.10 起) |
老客户端兼容才加 TLSv1.1,会削弱安全性 |
| proxy-ssl-verify | "off" |
回源不校验后端证书;开 on 需配 proxy-ssl-secret |
怎么确认 controller 真的加载了新证书?直接看渲染后的 nginx.conf,比看 Secret 更可靠:
kubectl exec -n ingress-nginx deploy/ingress-nginx-controller --
nginx -T 2>/dev/null | grep -A2 ssl_certificate
# 期望看到 /etc/ingress-controller/ssl/prod-shop-example-com-tls.pem
# 若仍是 default-fake-certificate.pem,说明 Secret 名/namespace 不匹配或 controller 未 reload
自签或内部 CA 怎么做双向 TLS?kubectl create secret tls 只能生成 tls.crt/tls.key 两个键,要带 ca.crt 必须手写 YAML 的三个 base64 字段(type: kubernetes.io/tls)。ingress-nginx 1.11 会把 ca.crt 一并下发给客户端;配合 nginx.ingress.kubernetes.io/auth-tls-verify-client: "on" 与 auth-tls-secret 即可校验客户端证书。密码套件可参考 Mozilla SSL Configuration Generator 的 intermediate 档位填入 ssl-ciphers,避免落到 DEFAULT 的弱套件。
手动 Secret、cert-manager、云托管:k8s ingress ssl证书三种来源怎么选
三种来源没有绝对优劣,选型的核心变量是域名数量、续期自动化的落地成本、以及出问题时你愿意在几个控制台之间跳转。下面这张表按 2025 年常见价格与限制整理,可直接对照团队现状做取舍。
| 方案 | 证书存放位置 | 续期方式 | 适合规模 | 关键限制 |
|---|---|---|---|---|
手动 kubectl create secret tls |
自建 kubernetes.io/tls Secret |
人工,90 天一次 | 域名 ≤5 个、内网或自签 | 易漏续期,无审计记录 |
| cert-manager + Let’s Encrypt | Certificate CR 自动生成 Secret | 到期前自动,renewBefore 默认 2/3 时长 |
10~500 个域名 | 需公网可达做 HTTP-01,每注册域名每周 50 张 |
| 云厂商托管(阿里云 CAS、AWS ACM + CLB/NLB) | 云侧证书,通过 LB 注解或监听器绑定 | 云平台自动 | 已使用云 LB 的集群 | Ingress 层看不到 tls.crt,排障要转到云控制台 |
| 商业 CA 泛域名(DigiCert、Sectigo OV) | 手动 Secret 或 cert-manager 外部签发 | 1 年有效期,人工续 | 对外品牌站、合规要求 | 约 1000~6000 元/年,签发需 1~3 个工作日 |
域名 20 个以内、团队还没有 CI/CD 流水线,手动 Secret 真的不能用吗?可以用,但必须补一条到期告警,否则”证书过期”会是你在凌晨被叫醒的最常见原因。据 RFC 5280,浏览器只校验 notAfter,一旦过期就是硬失败,没有灰度余地。
# 适用 kubectl ≥ 1.24;fullchain.pem 必须含完整链(服务器证书在前、中间证书在后),
# 顺序写反会让部分客户端报 unable to get local issuer certificate
kubectl create secret tls shop-example-tls
--cert=fullchain.pem --key=privkey.pem -n prod
# 校验实际写入 Secret 的到期时间(OpenSSL 1.1.1 / 3.x 通用)
kubectl get secret shop-example-tls -n prod -o jsonpath='{.data.tls.crt}'
| base64 -d | openssl x509 -noout -subject -enddate
# 纯手动 Secret 场景:用 blackbox_exporter 探针指标兜底,阈值 1209600 秒 = 14 天
groups:
- name: tls-expiry
rules:
- alert: IngressTLSCertExpiringSoon
expr: probe_ssl_earliest_cert_expiry - time() < 1209600
for: 1h
labels: {severity: warning}
cert-manager 的额外成本在哪?不在安装,而在 DNS-01 凭证与 RBAC。泛域名 *.example.com 无法用 HTTP-01 验证,必须走 dns01;据 cert-manager 官方文档,renewBefore 默认取证书时长的 2/3,90 天证书即在剩余 30 天时续期。建议单独建一个只具备 DNS 解析权限的 RAM 子账号或 Cloudflare Token,而不是复用主账号 AccessKey。
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata: {name: letsencrypt-dns01}
spec:
acme:
server: https://acme-v02.api.letsencrypt.org/directory
privateKeySecretRef: {name: le-account-key}
solvers:
- dns01:
cloudflare:
apiTokenSecretRef: {name: cf-api-token, key: api-token} # 仅 Zone:DNS:Edit
selector:
dnsZones: ["example.com"]
为什么云托管证书写不进 Ingress 的 tls.secretName?因为 AWS ACM 不导出私钥,Secret 里没有 tls.key 可放。这类集群按 AWS Load Balancer Controller v2.x 文档,在 Service 上用注解绑定,TLS 在 LB 侧终结:
service.beta.kubernetes.io/aws-load-balancer-ssl-cert: arn:aws:acm:cn-north-1:123456789012:certificate/abcd
service.beta.kubernetes.io/aws-load-balancer-ssl-ports: "443"
# 副作用:nginx.ingress.kubernetes.io/ssl-redirect 不再生效,需应用侧或 LB 监听器规则做跳转
比较实用的混合策略:对外主域名交给 cert-manager 自动签发,内部服务用 cert-manager 的 CA Issuer 签发 90 天短证书(内部域名本就无法做公网 HTTP-01),两者共用同一套 Ingress 注解与发布流程,避免维护两套 k8s ingress ssl证书 的更新路径。给关键对外域名单独设 renewBefore: 720h(30 天)比默认值更保守,留足 Let’s Encrypt 速率限制触发时的回退时间——据 Let’s Encrypt 速率限制文档,每注册域名每周最多 50 张证书,反复失败的自动重试很容易撞上这条线。
k8s ingress ssl证书常见报错与排查:7 条真实错误信息对照
排查 k8s ingress ssl证书 问题有一条固定路径:先确认 Secret 是否存在,再确认 Secret 里的 PEM 是否合法,最后确认证书 SAN 是否覆盖当前域名。下面按报错原文逐条对照。
| 报错原文 | 根因 | 第一条排查命令 |
|---|---|---|
secret "shop-example-com-tls" not found |
命名空间或名字不匹配 | kubectl get secret -n prod | grep tls |
Kubernetes Ingress Controller Fake Certificate |
controller 未取到有效 PEM | kubectl describe ingress |
x509: certificate is valid for a.example.com, not b.example.com |
SAN 不覆盖域名 | openssl x509 -text |
X509_check_private_key:key values mismatch |
证书与私钥不配对 | openssl modulus | md5 |
Waiting for HTTP-01 challenge propagation ... 404 |
challenge 路径被 rewrite | kubectl describe challenge |
too many failed authorizations recently |
Let’s Encrypt 账户级限流 | 切 staging 端点 |
x509: certificate has expired or is not yet valid |
续期中断 | openssl x509 -dates |
1. Secret not found:先查命名空间,再查大小写。Ingress 的 spec.tls[].secretName 只在同一个命名空间内解析,跨命名空间引用不会生效,也绝不会回退到 default 命名空间。
# 列出 prod 下所有 TLS 类型 Secret,确认名字与大小写
kubectl get secret -n prod --field-selector type=kubernetes.io/tls
# 打印 Ingress 实际引用的 secretName
kubectl get ingress shop-web -n prod -o jsonpath='{.spec.tls[*].secretName}'
# 打印 cert-manager 实际写入的 secretName,逐字符比对
kubectl get certificate -n prod -o jsonpath='{range .items[*]}{.metadata.name}{"t"}{.spec.secretName}{"n"}{end}'
Ingress 的 tls.secretName 与 Certificate 的 spec.secretName 差一个字符(例如 -tls 写成 -ssl),443 端口就会静默无证书。
2. Fake Certificate:controller 没读到有效 PEM。NGINX Ingress Controller 在没有匹配证书时,会返回内置自签的 Kubernetes Ingress Controller Fake Certificate(可用 --default-ssl-certificate 覆盖)。此时 kubectl describe ingress 的事件里常出现 ingress does not contain a valid TLS certificate。直接验证 Secret 内容:
# 解码 tls.crt 并解析,若报 "unable to load certificate" 说明 Secret 内容本身是坏的
kubectl get secret shop-example-com-tls -n prod -o jsonpath='{.data.tls.crt}'
| base64 -d | openssl x509 -noout -subject -issuer -dates
注意 .data.tls.crt 里的 . 必须转义为 .,否则 jsonpath 会按层级解析而返回空串。
3. SAN 不匹配。现代浏览器只认 SAN,不看 CN。泛域名证书 *.example.com 只覆盖一级子域,a.b.example.com 不在其内(RFC 6125 亦明确通配符仅匹配一个标签)。
openssl x509 -in tls.crt -noout -text | grep -A1 'Subject Alternative Name'
4. key values mismatch。证书与私钥不配对时,NGINX 会打印 SSL_CTX_use_PrivateKey() failed (SSL: error:0B080074:x509 certificate routines:X509_check_private_key:key values mismatch)。用模数哈希比对,两个值必须完全一致:
openssl x509 -noout -modulus -in tls.crt | openssl md5
openssl rsa -noout -modulus -in tls.key | openssl md5
# ECDSA 证书没有 modulus,改用公钥比对:
# openssl x509 -in tls.crt -noout -pubkey | openssl md5
# openssl pkey -in tls.key -pubout | openssl md5
5. HTTP-01 404。cert-manager 自检 GET http://域名/.well-known/acme-challenge/<token> 返回 404,常见原因是 Ingress 上加了 nginx.ingress.kubernetes.io/rewrite-target 把 challenge 路径改写掉了,或 solver 创建的临时 Ingress 使用了不存在的 ingressClassName。kubectl describe challenge -n prod 的 State 与 Reason 字段会直接指出卡在哪一步。
- SSL域名证书申请 · 小程序证书 · 国外SSL证书
- 代购 SSL 证书 · DigiCert / GeoTrust / RapidSSL 单域名与通配符
- SSL/HTTPS 证书配置 · 证书安装 · 证书申请
6. too many failed authorizations recently。据 Let’s Encrypt 速率限制文档,同一账户对同一主机名每小时最多 5 次验证失败,超限后需等待约 1 小时窗口。正确做法是先把 Issuer 的 server 改成 staging 端点(https://acme-staging-v02.api.letsencrypt.org/directory)调通链路,再切回生产,避免消耗生产配额。
7. 证书过期。先看日期,再看 Certificate 状态;notAfter 已过通常意味着续期早已失败:
kubectl get secret shop-example-com-tls -n prod -o jsonpath='{.data.tls.crt}'
| base64 -d | openssl x509 -noout -dates
kubectl describe certificate shop-example-com-tls -n prod # 看 Status.Conditions 与 Events
kubectl get certificaterequest -n prod # 定位失败的 CR
Ready 为 False 且 Reason 为 DoesNotExist/Failed 时,续期链已断,需修复 Issuer 引用或 DNS 解析后手动删除待处理的 CertificateRequest 触发重签。
怎么确认 k8s ingress ssl证书真的生效了?6 条验证命令
Ingress 里写了 tls: 段不代表证书就生效了——Secret 没被挂载、nginx 没 reload、SNI 分流走错、中间证书缺失,每一环都可能静默失败。按下面 6 条命令从资源层往上逐层验证,哪一层先失败就停在哪一层排查。
-
资源层:Ingress 引用的 Secret 名与 Certificate 状态
kubectl get ingress shop -n prod -o jsonpath='{.spec.tls[0].secretName}'; echo # 期望输出:shop-example-com-tls(须与 Certificate 生成的 Secret 同名、同 namespace) kubectl get certificate -n prod # NAME READY SECRET AGE RENEWAL TIME # shop-example-com True shop-example-com-tls 9d 79dREADY 必须为 True,且 AGE 与 RENEWAL TIME 两列要一起看。据 cert-manager 文档,未显式设置
renewBefore时默认在证书有效期约 2/3 处续期,对 Let’s Encrypt 的 90 天证书即提前约 30 天。只看 AGE 会漏掉“续期已失败但旧证书尚未过期”的危险窗口。 -
握手层:证书主体、签发者与到期时间
openssl s_client -connect shop.example.com:443 -servername shop.example.com -showcerts </dev/null 2>/dev/null | openssl x509 -noout -subject -issuer -dates # subject=CN = shop.example.com # issuer=C = US, O = Let's Encrypt, CN = R11 # notAfter=...(距今应大于 30 天)issuer 为 R10/R11 说明走的是 Let’s Encrypt 现行中间 CA(2024 年起替代 R3);若 issuer 显示
CN = Kubernetes Ingress Controller Fake Certificate,说明 Secret 根本没被加载,此时浏览器会直接报证书不受信任。 -
协议层:确认 TLSv1.0/1.1 已关闭
echo | openssl s_client -connect shop.example.com:443 -servername shop.example.com -tls1_1 2>&1 | grep -E 'Protocol|alert' # 期望:alert protocol version,且不出现 Protocol : TLSv1.1据 Mozilla Server Side TLS 指南的 intermediate 配置,应只启用 TLSv1.2/1.3,这也符合 RFC 8996 对 TLSv1.0/1.1 的弃用要求(RFC 8996 于 2021 年 3 月将二者标记为 Historic)。
-
HTTP 层:业务可达与强制跳转
curl -sSI https://shop.example.com | head -1 # HTTP/2 200 或 301 curl -sSI http://shop.example.com | head -3 # 301,Location: https://shop.example.com/第二条验证
nginx.ingress.kubernetes.io/ssl-redirect(ingress-nginx 默认值为true)确实生效,避免 HSTS 与明文入口并存。 -
链完整层:客户端能否验证到根
openssl s_client -connect shop.example.com:443 -servername shop.example.com -verify_return_error </dev/null 2>&1 | grep 'Verify return code' # 期望:Verify return code: 0 (ok)返回码 含义 常见原因 0 (ok) 链完整、域名匹配 — 20 (unable to get local issuer certificate) 缺中间证书 Secret 的 tls.crt 只放了叶子证书 21 (unable to verify the first certificate) 服务端未下发中间证书 未拼接 intermediate 成 fullchain 10 (certificate has expired) 证书已过期 自动续期失败 62 (hostname mismatch) SAN 不含该域名 证书与 Ingress host 不一致 出现 20/21 时先查 Secret 内容而非 Ingress:
kubectl get secret shop-example-com-tls -n prod -o jsonpath='{.data.tls.crt}' | base64 -d | grep -c 'BEGIN CERTIFICATE',输出 2 表示叶子+中间证书齐全,1 表示缺中间证书。 -
配置层:nginx 是否真的加载并 reload
# 统计已加载证书数量,应等于所有 Ingress 的 spec.tls 条目总数 kubectl exec -n ingress-nginx deploy/ingress-nginx-controller -- nginx -T 2>/dev/null | grep -c 'ssl_certificate ' # 确认控制器已热加载(无输出说明没感知到变更) kubectl logs -n ingress-nginx deploy/ingress-nginx-controller --since=10m | grep -i 'reload'数量对不上或没有 reload 日志,最常见原因是 Secret 与 Ingress 不在同一 namespace——Ingress 的
tls.secretName只能引用同 namespace 内的 Secret,跨 namespace 引用会被静默忽略。
k8s ingress ssl证书轮换:Secret 更新后多久生效、怎么强制续期
Secret 更新后多久生效?ingress-nginx 通过 fsnotify 监听 /etc/ingress-controller/ssl 目录,Secret 的 data.tls.crt/tls.key 变化后,通常 5~30 秒内触发 reload,不需要执行 kubectl rollout restart deploy/ingress-nginx-controller。若 60 秒后仍返回旧证书,再查 controller 日志中的 reload 记录:
# 查看线上实际返回的 notAfter 与 Subject
openssl s_client -connect shop.example.com:443 -servername shop.example.com /dev/null
| openssl x509 -noout -dates -subject
# 查看 ingress-nginx 最近 5 分钟的 reload/ssl 日志
kubectl logs -n ingress-nginx deploy/ingress-nginx-controller --since=5m | grep -Ei 'reload|ssl'
手动轮换 k8s ingress ssl证书时,推荐声明式 apply,避免先 delete Secret 造成 443 短暂中断。apply 只更新 data 字段,Secret 名称不变,Ingress 无需改动:
# 用新证书原地更新 Secret;--dry-run=client 只生成 YAML,不落盘
kubectl create secret tls shop-example-com-tls
--cert=fullchain.pem --key=privkey.pem -n prod
--dry-run=client -o yaml | kubectl apply -f -
# 校验 Secret 内证书有效期
kubectl get secret shop-example-com-tls -n prod
-o jsonpath='{.data.tls.crt}' | base64 -d | openssl x509 -noout -dates
cert-manager 默认 renewBefore 为证书总时长的 2/3,即 90 天证书在剩余 30 天时自动续期;可在 Certificate 上显式提前,最小粒度到分钟:
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: shop-example-com
namespace: prod
spec:
secretName: shop-example-com-tls
renewBefore: 360h # 15 天;默认约为总时长 2/3,90 天证书即 720h
dnsNames:
- shop.example.com
issuerRef:
name: letsencrypt-prod
kind: ClusterIssuer
需要立即换发时,用 cert-manager v1.16 配套 CLI:cmctl renew shop-example-com-tls -n prod,随后 cmctl status certificate shop-example-com-tls -n prod 观察 Issuing 状态;也可删除关联 Order 触发重建:kubectl delete order -n prod -l cert-manager.io/certificate-name=shop-example-com。据 cert-manager 文档,自动续期还带随机抖动,避免集中请求 ACME。
| 轮换方式 | 典型命令 | 生效时间 | 风险 |
|---|---|---|---|
| 手动 apply Secret | kubectl create secret tls ... --dry-run=client -o yaml | kubectl apply -f - |
通常 5~30 秒 | 低,推荐 |
| 删除后重建 Secret | kubectl delete secret ... |
取决于重建速度 | 可能 443 短暂中断 |
| cert-manager 强制续期 | cmctl renew ... |
数秒至数分钟,取决于 ACME | 低 |
监控建议采集 certmanager_certificate_expiration_timestamp_seconds 与 certmanager_certificate_ready_status,告警阈值设剩余 14 天:certmanager_certificate_expiration_timestamp_seconds - time() < 14*24*3600。据 Let’s Encrypt 公告,其 OCSP 响应服务自 2025 年起逐步停用并改用 CRL,依赖 OCSP stapling 做吊销检查的链路需同步调整。
多域名与泛域名:k8s ingress ssl证书的 SNI 规划与 Gateway API 差异
一个 Ingress 可以写多个 spec.tls 条目,每条带自己的 hosts 与 secretName,ingress-nginx 在 TLS 握手中按客户端 SNI 匹配并下发对应证书。要验证实际下发了哪张证书,不要靠猜,直接用 SNI 探测:
# 适用 ingress-nginx v1.x(Helm chart 4.x),OpenSSL 1.1.1+
# -servername 模拟客户端 SNI,-showcerts 打印完整链
openssl s_client -connect ingress.example.com:443
-servername api.example.com
-showcerts /dev/null
| openssl x509 -noout -subject -issuer -ext subjectAltName
一个坑:同一个 host 若同时出现在两个 tls 条目里,以 YAML 中靠前的一条为准。ingress-nginx 按顺序构建 SNI 映射,后者被静默忽略,kubectl apply 不报任何 warning,只有日志里能看到。排查时先看顺序,再看 Secret 是否存在。
泛域名 *.example.com 只能走 DNS-01,据 Let’s Encrypt 文档,HTTP-01 不支持通配符,因为校验必须由 CA 直接发起,无法验证“所有子域”的归属。cert-manager 侧要显式配 solvers.dns01 与服务商 API 凭证(cloudflare、alidns、route53 等):
# cert-manager v1.14+ 验证通过;ClusterIssuer 片段
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
name: letsencrypt-dns01
spec:
acme:
server: https://acme-v02.api.letsencrypt.org/directory
privateKeySecretRef:
name: le-account-key
solvers:
- dns01:
cloudflare:
apiTokenSecretRef: # 凭证 Secret 需与 ClusterIssuer 同 ns 或引用
name: cloudflare-api-token
key: api-token
selector:
dnsZones: ["example.com"] # 限定生效区域,避免误签其他域
关键点:*.example.com 不覆盖 example.com 本身,必须在 dnsNames 里额外加一条。据 RFC 6125 的通配符匹配规则,通配符只匹配一级标签,*.example.com 也不匹配 a.b.example.com。
Let’s Encrypt 单张证书上限 100 个 SAN(见其速率限制文档)。TLS 握手时整张证书走 Certificate 消息,每个 SAN 约 20~40 字节,域名多会逼近握手包上限并加重首包延迟。超过 30 个域名建议按业务域拆成多张证书,分别挂到不同 Ingress。
| 维度 | Ingress spec.tls[].secretName |
Gateway API listener.tls.certificateRefs |
|---|---|---|
| 跨命名空间引用 Secret | 不支持(v1 规范至今无此字段) | 支持,需配套 ReferenceGrant |
| 多证书(同一 listener) | 不支持,一 host 一 Secret | 支持 certificateRefs 列表 |
| SNI 匹配位置 | controller 内部映射 | 由 Listener hostname 显式声明 |
| 未匹配请求默认证书 | controller 启动参数 --default-ssl-certificate |
由默认 listener / 实现决定 |
未匹配任何 SNI 的请求(如客户端用裸 IP 直连、或 SNI 被剥离)会落到默认证书;不指定时暴露的是 ingress-nginx 的 Fake Certificate,部分客户端会直接报 NET::ERR_CERT_AUTHORITY_INVALID。用 controller 启动参数覆盖:
# 适用 ingress-nginx v1.9+;Helm chart 中对应 controller.extraArgs
helm upgrade ingress-nginx ingress-nginx/ingress-nginx
--namespace ingress-nginx --reuse-values
--set-json 'controller.extraArgs.default-ssl-certificate="ingress-nginx/default-tls"'
默认值为空(即使用内置 Fake Certificate)。同一 Ingress 里多域名规划时,把每个 host 的 Secret 单独命名(如 api-example-tls、wild-example-tls),比塞一张巨型证书更易轮换——这也是后续做 k8s ingress ssl证书 轮换与告警的基础。若已在评估 Gateway API,跨命名空间引用 Secret 是迁移中最直接的收益点:Secret 集中在 infra 命名空间,业务 Ingress 不再需要复制证书。
必须与 Ingress 同命名空间。跨命名空间引用在 kubectl apply 阶段不会报错,但 ingress-nginx 解析不到 PEM,443 会回落到 Kubernetes Ingress Controller Fake Certificate,controller 日志出现 secret not found。多命名空间共用一张证书时,在每个 namespace 各建一份同名 Secret,或改用 Gateway API 的 certificateRefs + ReferenceGrant。
域名超过 10 个、有稳定 CI/CD 流程时选 cert-manager,90 天证书在剩余 30 天自动续期,Secret 原地更新后 ingress-nginx 5~30 秒热加载,几乎零运维。域名少于 5 个或必须用商业 OV/EV 证书时手动 Secret 更直接,但要配到期告警。两者可以共存:主域名走 cert-manager,合规站点用手动 Secret 挂商业证书。
不需要。ingress-nginx 1.11 监听 /etc/ingress-controller/ssl 目录变化,Secret 更新后通常 5~30 秒内自动 reload。若 60 秒后 openssl s_client 仍显示旧 notAfter,检查 controller 日志中的 reload 记录,以及是否误改了 Secret 名称导致 Ingress 引用的还是旧对象。
先执行 kubectl get secret xxx-tls -n 确认存在,再用 kubectl get secret xxx-tls -n prod -o jsonpath='{.type}' 确认类型是 kubernetes.io/tls,最后用 base64 -d 解出 tls.crt 并 openssl x509 -noout -subject 验证内容合法。三步都通过仍报错,就看 kubectl describe ingress 的 Events 与 controller 日志里的 obtaining pem 相关行。
可以,spec.tls 是数组,每个条目包含独立的 hosts 与 secretName,controller 按 SNI 选择证书。泛域名 *.example.com 必须用 DNS-01 验证,cert-manager 需配置 dns01 solver 和服务商 API 凭证;同时记得把裸域 example.com 单独加进 dnsNames,否则主域访问会证书不匹配。
ingress-nginx 从 1.10 起 ssl-protocols 默认值为 "TLSv1.2 TLSv1.3",基于 OpenSSL 3.x 构建的镜像默认启用 TLS 1.3。需要收紧时在 Ingress 上加注解 nginx.ingress.kubernetes.io/ssl-protocols: "TLSv1.2 TLSv1.3",需要兼容老旧客户端才临时加回 TLSv1.1,但不建议长期保留,RFC 8996 已将其标记为废弃。
cert-manager 暴露 certmanager_certificate_expiration_timestamp_seconds 指标,用 Prometheus 规则 (certmanager_certificate_expiration_timestamp_seconds – time()) < 14*24*3600 触发告警即可。手动 Secret 场景可用 blackbox_exporter 的 probe_ssl_earliest_cert_expiry 指标,或在 CronJob 里跑 openssl s_client 解析 notAfter 后推送告警。
本文由 sslgood.com 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。