k8s ingress ssl证书安装全流程:Secret 创建、Ingress TLS 配置与报错排查
k8s ingress ssl证书安装本质只有两步:把 fullchain 证书与私钥放进与 Ingress 同 namespace 的 kubernetes.io/tls Secret,再在 spec.tls[].secretName 引用它,Ingress 本身不解析证书文件。 secretName 拼错或跨 namespace 引用时不会报硬错误,ingress-nginx 会回落内置自签证书,浏览器显示签发者为 kubernetes ingress controller fake certificate。 证书必须是 PEM 且含中间 CA:cat cert.crt chain.crt > fullchain.pem,否则 Android 7+ 与 Java 客户端报 unable to get local issuer certificate。 Let's Encrypt 证书有效期 90 天,建议用 cert-manager v1.14+ 的 Certificate CRD,renewBefore 设 720h,避免每 3 个月手工执行一次 kubectl create secret tls。 验证命令:openssl s_client -connect 1.2.3.4:443 -servername example.com -showcerts /dev/null | openssl x509 -noout -issuer -dates,看到 Verify return code: 0 (ok) 才算 k8s ingress ssl证书安装成功。
k8s ingress ssl证书安装为什么经常“装完不生效”:三个断点与根本原因
很多人执行完 kubectl create secret tls、在 Ingress 里加了两行 tls:,浏览器却依然报证书错误。原因几乎都能归到下面三个断点,外加两个容易被忽略的”静默覆盖”机制。
断点一:Secret 和 Ingress 不在同一个 namespace
Ingress 的 spec.tls[].secretName 只在同 namespace 内解析。据 Kubernetes 官方 API 参考,IngressTLS.secretName 的语义就是”同一 namespace 中的 Secret 名称”,至今没有跨 namespace 引用字段;跨 namespace 的引用授权直到 Gateway API 才通过 ReferenceGrant 解决。所以 prod 的 Ingress 引用 dev 的 Secret 会静默失败——kubectl describe ingress 的 Events 里通常只有一行:
# 定位:Secret 与 Ingress 的 namespace 必须一致
kubectl get ingress my-app -n prod -o jsonpath='{.spec.tls[0].secretName}{"n"}'
kubectl get secret my-app-tls -n prod # 若报 NotFound,就是断点一
# 正确做法:在目标 namespace 重建同名 Secret(或用 external-secrets 等同步过去)
kubectl create secret tls my-app-tls -n prod --cert=fullchain.pem --key=privkey.pem
# describe 中典型事件:secret "my-app-tls" not found
断点二:证书不是合法 PEM
kubectl create secret tls 只做 PEM 解析,不做证书链完整性和私钥匹配校验。上传 .pfx/.p12/.der 会直接失败:
error: failed to load key pair: tls: failed to find any PEM data in certificate input
先转换再上传(OpenSSL 1.1.1 / 3.x 均适用):
# pfx → 证书(-clcerts 只导叶子证书,-nokeys 不导私钥)
openssl pkcs12 -in cert.pfx -nokeys -clcerts -out cert.pem
openssl pkcs12 -in cert.pfx -nocerts -nodes -out privkey.pem
# 上传前自检:Subject 与 SAN 是否正确、私钥是否匹配
openssl x509 -in cert.pem -noout -subject -ext subjectAltName
openssl x509 -noout -modulus -in cert.pem | openssl md5
openssl rsa -noout -modulus -in privkey.pem | openssl md5 # 两行 md5 必须一致
断点三:host 与证书 SAN 不逐字匹配
spec.rules[].host 必须与 SAN 里的 DNS 名逐字相同(含 www. 前缀)。通配符 *.example.com 按 RFC 6125 只覆盖一级子域,a.b.example.com 不在覆盖范围内,浏览器报 NET::ERR_CERT_COMMON_NAME_INVALID。可在本地验证:
openssl x509 -in cert.pem -noout -checkhost www.example.com # 输出 Hostname ... does match/does NOT match
为什么”装了却没生效”:默认证书与 API 版本两个静默陷阱
ingress-nginx 有启动参数 --default-ssl-certificate,默认值为空。当 SNI 未匹配到任何 Ingress 的 tls 段时,控制器回落到内置自签证书,CN 为 kubernetes ingress controller fake certificate、有效期 3650 天——这正是”配置写了但浏览器还是报假证书”的高频原因。检查方式:
kubectl -n ingress-nginx get deploy ingress-nginx-controller
-o jsonpath='{.spec.template.spec.containers[0].args}' | tr ',' 'n' | grep default-ssl
另一个陷阱是 API 版本:networking.k8s.io/v1 自 Kubernetes 1.19 GA,1.22 起移除 extensions/v1beta1/v1beta1。在 1.22+ 集群 apply 旧清单会直接失败,tls 段自然不会下发到 nginx.conf:
error: resource mapping not found ... no matches for kind "Ingress" in version "extensions/v1beta1"
| 断点 | 典型现象 | 一条命令定位 |
|---|---|---|
| Secret 跨 namespace | Events: secret “xxx-tls” not found | kubectl get secret xxx-tls -n <ingress 所在 ns> |
| 非 PEM 格式 | failed to find any PEM data | openssl x509 -in cert.pem -noout -subject |
| host 与 SAN 不符 | NET::ERR_CERT_COMMON_NAME_INVALID | openssl x509 -in cert.pem -noout -checkhost <host> |
| 回落到默认自签证书 | CN = fake certificate,3650 天 | 检查 --default-ssl-certificate 与 SNI 匹配 |
| API 版本过旧 | no matches for kind “Ingress” | kubectl api-resources | grep ingress |
k8s ingress ssl证书安装的完整实操步骤(8 步,可直接照做)
在开始之前先说清楚一个前提:k8s ingress ssl证书安装能否一次成功,八成取决于前面两步的“体检”,而不是 YAML 写得多漂亮。据 Kubernetes 官方文档,networking.k8s.io/v1 自 1.19 起 GA,extensions/v1beta1 已在 1.22 移除;如果你在旧清单上照抄,报错会非常隐蔽。
步骤 1:确认集群版本与控制器版本。先看 Server Version(建议 1.24+,1.24 起 ServiceAccount 不再自动生成长期 Token,很多老清单会连带出问题),再反查 ingress-nginx 控制器镜像版本。
# Server Version 建议 ≥ 1.24
kubectl version --short
# 输出示例:Server Version: v1.28.6
# 注:kubectl 1.28 起 --short 被标记弃用,若提示 unknown flag,直接执行 kubectl version 看 Server Version 一行
# 查看控制器镜像,命名空间按实际安装调整(官方清单默认 ingress-nginx)
kubectl -n ingress-nginx get deploy ingress-nginx-controller
-o jsonpath='{.spec.template.spec.containers[0].image}{"n"}'
# 典型输出:registry.k8s.io/ingress-nginx/controller:v1.10.1
镜像地址能反推清单新旧:k8s.gcr.io/ingress-nginx/controller 是 v1.6 及更早的老仓库,v1.7 之后官方迁移到 registry.k8s.io(据 ingress-nginx 官方发布说明)。仓库还是旧的,说明你的控制器已经落后好几个小版本。
步骤 2:确认 Ingress API 版本存在。
kubectl api-resources | grep -i ingress
# 期望包含这一行(SHORTNAMES 列可能为空):
# ingresses ing networking.k8s.io/v1 true Ingress
如果只看到 networking.k8s.io/v1beta1 或 extensions/v1beta1,本节后面的 YAML 一律不适用,请先升级集群。
步骤 3:整理 fullchain 与无口令私钥。证书顺序必须是“站点证书在前、中间证书在后”,反了会出现 curl: (60) unable to get local issuer certificate。私钥若带 passphrase,kubelet 无法交互输入,Secret 里必须是明文私钥。
# 拼接完整链:站点证书 + 中间证书
cat example.com.crt intermediate.crt > fullchain.pem
# 私钥去口令(OpenSSL 3.x 推荐 pkey,会提示输入原口令,输出为不加密私钥)
openssl pkey -in example.com.key -out privkey.pem
# 旧写法(OpenSSL 1.1.1 亦可):openssl rsa -in example.com.key -out privkey.pem
chmod 600 fullchain.pem privkey.pem # 避免私钥进镜像层或 Git 历史
| 文件 | 内容 | 对应参数 | 常见错误 |
|---|---|---|---|
fullchain.pem |
站点证书 + 中间证书 | --cert |
只放站点证书 → 链不完整 |
privkey.pem |
无口令私钥(RSA/ECDSA) | --key |
带 passphrase → 加载失败 |
example.com.crt |
仅站点证书 | 不直接用 | 浏览器报“证书链不完整” |
步骤 4:校验私钥与证书是否配对。这一步能省掉后面 90% 的排查时间。
openssl x509 -noout -pubkey -in fullchain.pem | openssl sha256
openssl pkey -pubout -in privkey.pem | openssl sha256
# 两行 sha256 必须完全一致
不一致时,下一步会直接报:error: tls: private key does not match public key。顺便可用 openssl pkey -in privkey.pem -noout -check 确认私钥本身没损坏。
步骤 5:创建 Secret。这就是 k8s ingress ssl证书安装 里最容易被 GitOps 卡住的一环。
kubectl create secret tls example-tls --cert=fullchain.pem --key=privkey.pem -n prod
# 走 GitOps 时先导出 YAML 再提交(注意 base64 私钥会进仓库,建议配 SealedSecret/External Secrets)
kubectl create secret tls example-tls --cert=fullchain.pem --key=privkey.pem -n prod
--dry-run=client -o yaml > secret.yaml
据 Kubernetes 文档,单个 Secret/ConfigMap 对象总大小上限为 1MiB;RSA 4096 + 完整中间链通常在 4–6KB,容量上不必担心。
步骤 6:在 Ingress 中写入 tls 段。关键约束:spec.tls[0].hosts 与 spec.rules[].host 必须逐字符一致(含是否带 www.),secretName 指向刚建的 example-tls。
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: example
namespace: prod
annotations:
# ingress-nginx 中该项默认即为 "true",此处显式声明只为可读性
nginx.ingress.kubernetes.io/ssl-redirect: "true"
spec:
ingressClassName: nginx # 1.18+ 用它替代 kubernetes.io/ingress.class 注解
tls:
- hosts:
- example.com # 必须与下方 rules[].host 完全一致
secretName: example-tls
rules:
- host: example.com
http:
paths:
- path: /
pathType: Prefix # v1 中必填,漏写报 spec.rules[0].http.paths[0].pathType: Required value
backend:
service:
name: web
port:
number: 80
步骤 7:应用清单。
kubectl apply -f ingress.yaml
# 期望输出:ingress.networking.k8s.io/example created
步骤 8:基础核对。先看 describe 的 TLS 段,再用证书本身反查有效期,最后用 --resolve 绕过 DNS 直接验证 SNI 握手(SNI 定义见 RFC 6066)。
kubectl describe ingress example -n prod
# 期望看到:
# TLS:
# example-tls terminates example.com
kubectl get secret example-tls -n prod -o jsonpath='{.data.tls.crt}'
| base64 -d | openssl x509 -noout -subject -dates
# 确认 subject 与 notAfter 符合预期
curl -vI https://example.com --resolve example.com:443:<ingress-ip> 2>&1 | grep -E 'SSL|subject|issuer'
若 describe 里 TLS 段为空,先查 kubectl get ingress example -n prod -o yaml 确认 spec.tls 真的被提交;若 TLS 段正常但浏览器报错,问题通常已转移到控制器日志与证书链本身,属于下一节的排查范围。
配置与命令示例:Secret、Ingress、cert-manager 三份可套用清单(含版本与参数)
只想快速套用,最少要写几份 YAML?三份:一份 kubernetes.io/tls 类型的 Secret(或交给 cert-manager 自动生成)、一份 networking.k8s.io/v1 的 Ingress、以及一份 cert-manager 的 Issuer/Certificate(如果走自动签发)。下面三份清单可直接改域名套用。
第一份是 Secret。type 必须是 kubernetes.io/tls,data 下的键名固定为 tls.crt 与 tls.key,值均为 base64。注意 tls.crt 要放 fullchain(站点证书 + 中间证书,至少两段 -----BEGIN CERTIFICATE-----),否则部分客户端会报 unable to get local issuer certificate。
# 适用:所有 Kubernetes 1.9+ 版本;命名空间按需替换
apiVersion: v1
kind: Secret
metadata:
name: example-tls
namespace: prod
type: kubernetes.io/tls
data:
# fullchain.pem 的 base64:必须含 2 段及以上 BEGIN CERTIFICATE
tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t...
# 私钥的 base64:PEM 格式且不能带 passphrase,否则 ingress-nginx 加载失败
tls.key: LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0t...
---
# 更省事的写法:直接用文件生成,避免手工 base64
# kubectl create secret tls example-tls -n prod --cert=fullchain.pem --key=tls.key --dry-run=client -o yaml
用 stringData 写明文确实可以,apiserver 会自动编码进 data,但明文会残留在 kubectl.kubernetes.io/last-applied-configuration 注解里,任何有 get secret 权限的人都能读回——生产环境建议始终用 data 或 kubectl create secret tls。
第二份是 Ingress。据 ingress-nginx 文档,proxy-body-size 默认值仅为 1m,上传稍大的文件就会返回 413 Request Entity Too Large;ssl-protocols 在较新版本默认已是 TLSv1.2 TLSv1.3,显式写出便于审计。
# 适用:Kubernetes 1.19+(networking.k8s.io/v1 GA)、ingress-nginx v1.9+
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web
namespace: prod
annotations:
nginx.ingress.kubernetes.io/proxy-body-size: "20m" # 默认 1m
nginx.ingress.kubernetes.io/ssl-protocols: "TLSv1.2 TLSv1.3" # 对齐 Mozilla intermediate
cert-manager.io/cluster-issuer: letsencrypt-prod # 触发自动签发/续期
spec:
ingressClassName: nginx
tls:
- hosts: ["example.com"]
secretName: example-tls # spec.tls 是数组,可写多组 hosts+secretName 挂多张证书
rules:
- host: example.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: web
port:
number: 80
第三份是 cert-manager(v1.14+,CRD 为 cert-manager.io/v1)。duration 默认 2160h(90 天,也是 Let’s Encrypt 的上限),renewBefore 默认到期前 720h 续期。据 Let’s Encrypt 文档,ACME 目录必须用 acme-v02,v1 端点已于 2021 年下线。
apiVersion: cert-manager.io/v1 # 需 cert-manager v1.14 及以上
kind: ClusterIssuer
metadata:
name: letsencrypt-prod
spec:
acme:
server: https://acme-v02.api.letsencrypt.org/directory
email: ops@example.com
privateKeySecretRef:
name: letsencrypt-prod-account-key
solvers:
- http01:
ingress:
ingressClassName: nginx # v1.14 用 ingressClassName;更早版本字段名为 class
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: example-tls
namespace: prod
spec:
secretName: example-tls
duration: 2160h # 90 天
renewBefore: 720h # 提前 30 天续期
dnsNames:
- example.com
- "*.example.com"
issuerRef:
name: letsencrypt-prod
kind: ClusterIssuer
仅在测试环境用自签证书时,注意 -addext 需要 OpenSSL 1.1.1 及以上;1.0.2 需改用 -extfile:
# OpenSSL 1.1.1+;1.0.2 请改用 -extfile <(printf "subjectAltName=DNS:example.com,DNS:*.example.com")
openssl req -x509 -newkey rsa:2048 -nodes -keyout tls.key -out tls.crt -days 365
-subj "/CN=example.com"
-addext "subjectAltName=DNS:example.com,DNS:*.example.com"
kubectl create secret tls example-tls -n prod --cert=tls.crt --key=tls.key
怎么确认装进去的证书是对的?解出 Secret 里的证书直接看主题、签发者与有效期:
kubectl get secret example-tls -n prod -o jsonpath='{.data.tls.crt}'
| base64 -d | openssl x509 -noout -subject -issuer -dates
# subject=CN = example.com
# issuer=C = US, O = Let's Encrypt, CN = R3 (2024 年后新签发多为 E5/E6/R10/R11,以实际为准)
# notBefore=Mar 14 08:00:00 2025 GMT
# notAfter=Jun 12 08:00:00 2025 GMT
控制器侧还能在 ConfigMap 里统一覆盖:ssl-ciphers(默认对齐 Mozilla intermediate)、ssl-protocols、ssl-session-cache(默认 shared:SSL:10m)。若集群前面还有云 SLB 的 TCP 四层监听,TLS 仍在 Ingress 层终止,不要在 LB 上再上传同一张证书,否则会形成两层 TLS 并引发 SNI 错配。
| 证书来源 | 有效期/续期 | 适用场景 | 主要风险 |
|---|---|---|---|
手工 Secret(kubernetes.io/tls) |
由 CA 决定,需人工轮换 | 已有商业证书、内网域名 | 忘记续期导致 certificate has expired |
| cert-manager + Let’s Encrypt | 2160h,提前 720h 自动续 | 公网可解析域名 | http01 需 80 端口可达;有速率限制 |
| openssl 自签 | -days 指定,如 365 |
仅 staging/联调 | 浏览器报 NET::ERR_CERT_AUTHORITY_INVALID |
k8s ingress ssl证书安装的 5 种方案对比与选型建议
问:k8s ingress ssl证书安装到底有几种做法,我该选哪一种?
答:主流是五种,差别不在”能不能用”,而在私钥存放位置和续期由谁负责。先看对比表,再按三个问题做决策。
| 方案 | 证书来源 / 续期方式 | 典型有效期 | 典型失败表现 | 适用规模 |
|---|---|---|---|---|
A 手动 Secret(kubectl create secret tls) |
商业 CA 或自签,人工续期 | 365 天 | 忘记更新后 notAfter 过期,浏览器 NET::ERR_CERT_DATE_INVALID |
<5 张证书、变更走审批的小集群 |
| B cert-manager + Let’s Encrypt | ACME(RFC 8555)自动签发与续期 | 90 天,提前 1/3 续期 | ACME challenge 长时间 pending |
域名多、要求自动化的生产集群 |
| C 云厂商 LB 托管证书 | 控制台上传,云平台推送续期 | 随购买周期 | 监听器未绑定证书、443 未放行 | 私钥不允许进集群的合规场景 |
| D ingress-nginx 默认证书 | 一张泛域名兜底 | 自定 | SNI 未命中时回落到 fake 证书,NET::ERR_CERT_AUTHORITY_INVALID |
内部测试域名、兜底 |
| E Istio Gateway SDS | Secret 或 istiod 下发 | 自定 | Secret 命名空间不对,网关起不来 | 已上 Service Mesh、需 mTLS |
方案 A 的最小完整命令(适用于 kubectl 1.20+):
# 1) 创建 tls 类型 Secret;--cert 必须是包含中间证书的 fullchain,顺序不能反
kubectl create secret tls shop-tls
--cert=fullchain.pem
--key=privkey.pem
-n prod
# 2) 核对有效期:notAfter 即到期时间(定义见 RFC 5280)
kubectl get secret shop-tls -n prod -o jsonpath='{.data.tls.crt}'
| base64 -d | openssl x509 -noout -subject -dates
方案 B 的核心是 Certificate 资源。据 cert-manager 官方文档,renewBefore 不填时默认为证书有效期的 1/3,90 天证书即约 720h:
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: shop-tls
namespace: prod
spec:
secretName: shop-tls # cert-manager 自动写入同名 Secret
duration: 2160h # 90 天
renewBefore: 720h # 提前 30 天续期
issuerRef:
name: letsencrypt-prod
kind: ClusterIssuer
dnsNames:
- shop.example.com
challenge 卡住的常见原文是 Waiting for HTTP-01 challenge propagation: failed to perform self check GET request,多半是 Service 未暴露 /.well-known/acme-challenge 或 80 端口被安全组拦截。
方案 D 只需给 ingress-nginx Controller 加一个启动参数(默认值为空,即不启用):
# ingress-nginx v1.x,写在 Controller Deployment 的 args 里
- --default-ssl-certificate=ingress-nginx/fallback-tls
方案 E 在 Istio 1.20+ 的 Gateway 中通过 SDS 引用 Secret,注意 Secret 必须与网关同一命名空间:
servers:
- port: {number: 443, name: https, protocol: HTTPS}
tls:
mode: SIMPLE
credentialName: shop-tls # 与 Gateway 同命名空间
hosts: ["shop.example.com"]
选型判断一:域名数量与续期频率。3 个域名以内、每年集中更换一次,手动 Secret 的运维成本可接受;超过 10 个域名或含大量二级子域,cert-manager 的自动化收益明显,单集群每年可省 20–40 次人工操作。
选型判断二:私钥能否出集群。金融与等保场景常要求私钥不落地到业务集群,此时优先方案 C,把 TLS 终止放在云 LB,Ingress 只处理 HTTP 并透传 X-Forwarded-Proto。
选型判断三:是否需要 OCSP Stapling 与 HTTP/2。ingress-nginx v1.x 支持 OCSP Stapling(前提是证书链完整,可参考 Mozilla Server Side TLS 的链配置建议),且默认开启 HTTP/2;云 LB 的 OCSP 支持依厂商而定,采购前需确认。
成本区间参考:Let’s Encrypt 免费;DV 单域名商业证书约 100–600 元/年,OV 约 800–3000 元/年,通配符 OV 常见 3000–8000 元/年;cert-manager 本身免费,但需要额外的监控与告警投入(例如对 certmanager_certificate_expiration_timestamp_seconds 做 21 天告警)。
如果你的集群同时存在对外主域名和内部测试域名,实践中常见的是 B + D 组合:主域名走 cert-manager 自动续期,内部域名交给 --default-ssl-certificate 兜底,既避免 SNI 未命中时的证书告警,又不用为测试环境单独采购证书。
k8s ingress ssl证书安装常见报错与排查路径(附真实报错信息)
把报错先分类,排查能省一半时间。k8s ingress ssl证书安装 的失败几乎都落在下面六类,先用一条命令定位再动手改:
| 现象 / 报错原文 | 根因 | 一条命令定位 |
|---|---|---|
| unable to get local issuer certificate / x509: certificate signed by unknown authority | 证书链缺中间 CA | openssl s_client -showcerts 数证书条数 |
| tls: private key does not match public key | 私钥与证书不配对 | modulus / 公钥指纹比对 |
| NET::ERR_CERT_COMMON_NAME_INVALID | host 不在 SAN 里 | openssl x509 -text 看 SAN |
| 显示 kubernetes ingress controller fake certificate | secretName 拼错或 namespace 不一致 | kubectl describe ingress 看 Events |
| Order invalid / Certificate is not valid for the requested domain | HTTP-01 挑战路径不可达 | kubectl describe challenge |
| SSL_do_handshake() failed (SSL: error:0A00018A:SSL routines::dh key too small) | DH 参数低于 2048 位 | 换 ECDSA 证书或显式指定 dh-param |
为什么浏览器/客户端说“证书签发者未知”?因为 Secret 里只放了叶证书,没带中间 CA。据 Let’s Encrypt 文档,fullchain.pem 必须是“叶证书在前、中间证书在后”的拼接,顺序颠倒同样握手失败。先验证服务端实际下发的条数,返回 1 就是缺链:
# 数服务端下发的证书条数;1 = 只有叶证书,缺中间 CA,应为 2 或以上
openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null 2>/dev/null
| grep -c "BEGIN CERTIFICATE"
# 修复:把 intermediate.crt 追加到 fullchain.pem 末尾,再重建 Secret
cat fullchain.pem intermediate.crt > fullchain-new.pem
kubectl create secret tls example-tls -n prod
--cert=fullchain-new.pem --key=privkey.pem
--dry-run=client -o yaml | kubectl apply -f -
# 说明:type 固定为 kubernetes.io/tls,--dry-run=client 便于幂等更新
报 tls: private key does not match public key 怎么办?多半是 CSR 重签后旧私钥没换。RSA 证书比对 modulus 的 MD5;ECDSA 证书没有 modulus 字段,必须改比公钥指纹,这是最容易踩空的一步:
# RSA 证书
openssl x509 -noout -modulus -in fullchain.pem | openssl md5
openssl rsa -noout -modulus -in privkey.pem | openssl md5
# 两值不同即确认不配对
# ECDSA 证书(P-256 等)用公钥指纹比对
openssl x509 -in fullchain.pem -noout -pubkey | openssl sha256
openssl pkey -in privkey.pem -pubout | openssl sha256
NET::ERR_CERT_COMMON_NAME_INVALID 一定是证书错了吗?不是,是 Ingress 里写的 host 没落在证书 SAN 列表中。CA/Browser Forum 基线要求自 2017 年起 CN 被忽略、只认 SAN,所以别去看 Subject 的 CN:
# macOS 上 base64 -d 换成 base64 -D 或 base64 --decode
kubectl get secret example-tls -n prod -o jsonpath='{.data.tls.crt}' | base64 -d
| openssl x509 -noout -text | grep -A1 "Subject Alternative Name"
为什么浏览器显示的是 fake certificate?说明 Ingress 根本没引用到你的 Secret,nginx-ingress 回落到内置自签证书。名字拼错、Secret 建在 default 而 Ingress 在 prod,都会这样:
kubectl describe ingress example -n prod | sed -n '/Events/,$p'
# 典型输出:Error: secret "example-tls" not found
kubectl get secret -n prod | grep tls # 核对名称与 namespace
cert-manager 的 Order 卡在 invalid 呢?按 ingress-nginx 文档,HTTP-01 需要 /.well-known/acme-challenge/ 走明文 80;若 Ingress 开了 nginx.ingress.kubernetes.io/ssl-redirect: "true",挑战会被 301 到 443 而失败,需为该路径单独放行 HTTP,同时确认 ingressClassName 与 controller 一致:
kubectl get certificate,order,challenge -n prod
kubectl describe challenge -n prod <challenge-name> | tail -20
dh key too small 从哪来?旧环境迁移的 DH 参数常为 1024 位,OpenSSL 3.x(RFC 7919 推荐的 FFDHE 为 2048 位起)直接拒绝。最省事的做法是换 ECDSA P-256 证书;必须用 RSA 时,在 ConfigMap 中显式指定 ssl-dh-param 指向 ≥2048 位文件并重载 controller:
# 生成 2048 位 DH 参数(耗时数十秒)
openssl dhparam -out /etc/ingress-controller/ssl/dhparam.pem 2048
kubectl -n ingress-nginx edit configmap ingress-nginx-controller
# data:
# ssl-dh-param: ingress-nginx/dhparam
证书装上去了不等于生效。Secret 类型对了、Ingress 也引用了,仍可能因为缺 SNI、证书链顺序错、controller 没热加载而让浏览器报警。按下面 5 层由外到内逐层验证,每一层都有可判定的通过信号。
第一层:openssl 直连,验证 TLS 握手本身。绕过 DNS 打入口 IP,用 -servername 显式携带 SNI——这一步不能省,否则 nginx-ingress 会回落到 default 证书,验证就变成假阳性。
openssl s_client -connect 1.2.3.4:443 -servername example.com -showcerts </dev/null 2>/dev/null
| grep -E 'Protocol|Cipher|Verify return code'
# 期望输出:
# Protocol : TLSv1.3
# Cipher : TLS_AES_128_GCM_SHA256
# Verify return code: 0 (ok)
据 OpenSSL 文档,-showcerts 会打印服务端下发的完整证书链;TLS 1.3 的 AEAD 套件命名规则见 RFC 8446 附录 B.4。若 Protocol 显示 TLSv1.2 而期望 1.3,先查 Ingress 的 ssl-protocols 注解与 controller 版本(ingress-nginx 1.9+ 默认已含 TLSv1.3)。
第二层:curl 带 SNI 解析,验证应用层与重定向。
curl -vI https://example.com --resolve example.com:443:1.2.3.4 2>&1
| grep -E 'SSL certificate verify|subjectAltName|HTTP/'
# 期望:SSL certificate verify ok.
# subjectAltName: host "example.com" matched cert's "example.com"
# HTTP/2 200
# 若得到 HTTP/1.1 301 且 Location: https://...,说明 ssl-redirect 生效
# (ingress-nginx 该注解默认值为 false,需显式开启)
--resolve 不污染 DNS,适合在切流量前灰度验证新入口。subjectAltName 列表必须覆盖实际访问的域名,Let’s Encrypt 签发的证书不再使用 CN 匹配,仅看 subjectAltName。
第三层:查集群对象状态,排除”证书没问题但对象没挂上”。
kubectl get ingress example -n prod
# ADDRESS 列应为 LB IP/域名,空白说明 controller 未 watch 到该 IngressClass
kubectl describe ingress example -n prod | sed -n '/TLS:/,/Rules:/p'
# 期望:TLS: example-tls Hosts: example.com
kubectl get secret example-tls -n prod -o jsonpath='{.type}{"n"}'
# 期望:kubernetes.io/tls;且 tls.crt、tls.key 两个 key 缺一不可
第四层:证书链完整性。本地 openssl verify 与 SSL Labs 报告互相印证:
openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt fullchain.pem
# 期望:fullchain.pem: OK
awk '/BEGIN CERTIFICATE/{c++} END{print c" certs"}' fullchain.pem
# 期望:2~3 certs(叶子证书 + 中间证书,根证书可省略)
SSL Labs 报告中 Chain issues 应为 None;出现 “Incomplete chain” 或 “Contains anchor” 说明中间证书缺失或顺序颠倒。只发叶子证书是 502 与”证书不受信任”的高发原因。
第五层:续期与到期监控。
kubectl get certificate -n prod
# NAME READY SECRET AGE
# example-tls True example-tls 30d
kubectl get certificate example-tls -n prod -o jsonpath='{.status.renewalTime}{"n"}'
# cert-manager 未设 renewBefore 时默认取证书时长的 2/3,且不早于到期前 30 天
# 外部监控:blackbox_exporter 的 probe_ssl_earliest_cert_expiry 返回 Unix 时间戳
# 告警阈值建议:(probe_ssl_earliest_cert_expiry - time()) / 86400 < 21
| 层级 | 关键命令 | 通过判据 | 典型失败信号 |
|---|---|---|---|
| 1 TLS 握手 | openssl s_client -servername | Verify return code: 0 | 返回 default 证书、CN 不符 |
| 2 应用层 | curl -vI –resolve | HTTP/2 200 + verify ok | 421/SSL_ERROR_BAD_CERT_DOMAIN |
| 3 对象状态 | kubectl get/describe | ADDRESS 有值、TLS 段有 secretName | ADDRESS 空白、Secret 类型为 Opaque |
| 4 链完整性 | openssl verify -CAfile | fullchain.pem: OK | unable to get local issuer certificate |
| 5 续期 | kubectl get certificate | READY=True、renewalTime 合理 | READY=False,Events 报 ACME 校验失败 |
把 5 层做成一个上线检查脚本,每次 k8s ingress ssl证书安装 后跑一遍,能挡掉绝大多数”看起来装好了但用户报错”的返工。
很多人把k8s ingress ssl证书安装当成一次性动作——Secret 建好、Ingress 挂上、浏览器出现小锁,任务就结束了。真正的问题在 60 天后:证书过期,用户看到 NET::ERR_CERT_DATE_INVALID,而你还在翻当时的操作记录。这一节讲清楚两条轮换路线(cert-manager 自动、手动换名切流)、怎么监控剩余天数、以及参数该填多少。
cert-manager 场景:续签为什么不需要重启 Pod?
据 cert-manager 官方文档,Certificate 资源的 renewBefore 默认取 duration 的 1/3;duration 默认 2160h(90 天),因此默认就是到期前 720h(30 天)触发续签。签发成功后,cert-manager 会原地覆盖同名 Secret。ingress-nginx 通过 informer 监听 Secret 变更,证书走动态加载路径,controller 不需要重启,nginx 也不做整体 reload,已有连接不中断——这是很多人误以为“必须滚动重启”的地方。
# cert-manager v1.14+ 验证:duration/renewBefore 是否生效
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: example-tls
namespace: prod
spec:
secretName: example-tls # 续签后写回这个同名 Secret
duration: 2160h # 默认 90 天,Let's Encrypt 上限也是 90 天
renewBefore: 720h # 到期前 30 天续签,默认值即 duration 的 1/3
issuerRef:
name: letsencrypt-prod
kind: ClusterIssuer
dnsNames:
- www.example.com
---
# 检查续签时间点与状态
kubectl -n prod describe certificate example-tls | grep -E 'Renewal Time|Not After|Status'
# Status: True / Renewal Time: ... / Not After: ...
注意:把 duration 设成大于 90 天对 Let’s Encrypt 无效,CA 返回什么就用什么;商业证书 365 天有效期时,renewBefore 建议改成 1080h(45 天),给审批和采购留出余量。
手动场景:为什么推荐“换名再切流”而不是直接覆盖?
直接覆盖同名 Secret 技术上可行,但一旦新证书链拼错(漏了中间证书)或私钥不匹配,旧证书已经被冲掉,你只能重新申请。换名切流把“发布”和“清理”拆成两步,回滚就是把 Ingress 的 secretName 改回去。
# 1) 新证书先落到新名字
kubectl -n prod create secret tls example-tls-v2 --cert=fullchain.pem --key=privkey.pem
# 2) 只改 Ingress 的 tls 引用
kubectl -n prod patch ingress web --type=json
-p='[{"op":"replace","path":"/spec/tls/0/secretName","value":"example-tls-v2"}]'
# 3) 观察 5-10 分钟:证书主题、到期时间、是否出现 5xx
curl -svI https://www.example.com 2>&1 | grep -E 'subject:|expire date:'
# 4) 有异常立刻回滚
kubectl -n prod patch ingress web --type=json
-p='[{"op":"replace","path":"/spec/tls/0/secretName","value":"example-tls"}]'
# 5) 确认稳定后删除旧 Secret
kubectl -n prod delete secret example-tls
| 轮换方式 | 回滚成本 | 是否重启工作负载 | 适用场景 |
|---|---|---|---|
| cert-manager 自动续签(覆盖同名 Secret) | 低,重签即可 | 否 | ACME 证书、域名固定 |
| 手动换名再切流 | 极低,改回 secretName | 否 | 商业证书、需人工审批 |
| 手动直接覆盖同名 Secret | 高,旧私钥丢失 | 否 | 仅应急修补 |
过期监控的最小实现是什么?
不需要一上来就上完整可观测平台,一条命令就能验证券书剩余天数;openssl x509 -checkend 在证书于指定秒数内过期时返回 1,非常适合做探针。
# 打印到期时间
kubectl -n prod get secret example-tls -o jsonpath='{.data.tls.crt}'
| base64 -d | openssl x509 -noout -enddate -subject
# 剩余不足 21 天(1814400 秒)时返回 1,可作为告警判定
kubectl -n prod get secret example-tls -o jsonpath='{.data.tls.crt}'
| base64 -d | openssl x509 -noout -checkend 1814400 || echo "TLS 证书将在 21 天内过期"
集群内更推荐 blackbox_exporter 的 probe_ssl_earliest_cert_expiry(Unix 时间戳),每 6 小时采集一次,告警规则写成 (probe_ssl_earliest_cert_expiry - time()) / 86400 < 21 即可覆盖所有 Ingress 域名。
非 Ingress 终止 TLS 的场景要不要 reloader?
如果 TLS 在 Ingress 终止,上面的热加载已足够,不需要额外组件。但应用自己读取挂载的 Secret 文件(例如 Go 服务只在启动时加载证书),文件更新后进程仍用旧证书。此时可用 stakater/reloader v1.x,在 Deployment 上加注解 reloader.stakater.com/auto: "true",它监听同命名空间 Secret 变更并触发滚动重启。代价是重启会中断连接,因此务必配合 maxUnavailable: 0 的滚动策略。
判断标准很简单:Secret 的生命周期由人管,就必须有人盯到期时间;交给 cert-manager,就把它当成不可变基础设施,只在告警里留一条兜底规则。
不需要。证书以 kubernetes.io/tls 类型的 Secret 存在 etcd 中,ingress-nginx 通过 API Server 监听并加载,节点本地不落地文件。只有当你使用 hostPath 挂载或自建 nginx 不用 Ingress 时,才需要关心节点上的证书路径。
说明传入的不是 PEM 文本。先用 file cert.pfx 确认格式,若为 PKCS#12 执行 openssl pkcs12 -in cert.pfx -nokeys -clcerts -out cert.pem 转换;若为 DER 执行 openssl x509 -inform der -in cert.der -out cert.pem,并确认文件首行是 —–BEGIN CERTIFICATE—–。
不是必须。cert-manager 解决的是签发与续期自动化,ingress-nginx 只负责终止 TLS 并引用 Secret。若使用商业证书或云 LB 托管证书,完全可以只做 kubectl create secret tls,只是每 90 天到 1 年需要人工更换一次。
看私钥合规要求与运维边界。Ingress 方案证书随代码走 GitOps、灰度方便,适合域名多且团队自己管集群;云 LB 托管方案私钥不进集群、续期由平台推送,适合等保要求私钥不出云控制台的场景。两者不要在同一链路重复终止 TLS。
可以。spec.tls 是数组,每项包含 hosts 与 secretName,nginx 按 SNI 选择证书。泛域名 *.example.com 写进 Certificate 的 dnsNames 后,Ingress 的 host 只能填一级子域如 api.example.com,a.b.example.com 需要单独签发。
先确认 Secret 内容确实变了:kubectl get secret example-tls -o jsonpath='{.data.tls.crt}' | base64 -d | openssl x509 -noout -serial。若 Secret 已更新但浏览器仍旧,多为前面还有 CDN 或四层 LB 缓存了旧证书,或本地 DNS 解析到了未更新的节点。
检查 Ingress 注解 nginx.ingress.kubernetes.io/ssl-redirect 是否被显式设为 “false”,以及是否配置了 force-ssl-redirect。若前面有云 LB 做四层转发,跳转发生在 Ingress 层,需要确认 80 端口确实转发到了 controller 的 80 端口而非直接丢弃。
本文由 sslgood.com 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。