GlobalSign SSL 证书 Kubernetes 部署与自动续期实战(Ingress + cert-manager)
问题背景与根因:GlobalSign 证书在 K8s 里为何“装上了却不生效”
Kubernetes 不读取磁盘上的证书文件,所有 TLS 材料必须封装成 type: kubernetes.io/tls 的 Secret,再由 Ingress 的 spec.tls[].secretName 引用。这条链路只有三步,但线上故障几乎都集中在下面五类根因上。
根因一:证书链不完整。GlobalSign 签发完成后通常给出服务器证书、中间证书(例如 GlobalSign RSA OV SSL CA 2018,由 GlobalSign Root CA - R3 签发)和根证书。Ingress Controller 会把 Secret 里的内容原样下发给客户端,如果 tls.crt 只放了服务器证书,握手时只会返回一张叶子证书。浏览器具备 AIA 自动补链能力,所以“浏览器打开正常”;而 curl 7.x、Java 的 PKIX、微信小程序、Android OkHttp、Go 的 crypto/x509 会直接报证书链错误。
根因二:私钥格式不对。GlobalSign 控制台下载的私钥可能是带口令的 PKCS#8(-----BEGIN ENCRYPTED PRIVATE KEY-----)或 .p12/.pfx,而 kubectl create secret tls 只接受未加密的 PEM 私钥。
根因三:键名或类型错误。Secret 的键必须是 tls.crt 和 tls.key,用 --from-file 随手指定的文件名会让 Controller 找不到证书。
根因四:跨命名空间引用。Secret 是命名空间级资源,Ingress 只能引用同命名空间的 Secret,引用不到时不会报错,而是静默回落到默认自签证书。
根因五:有效期与域名。GlobalSign 公有 TLS 证书单张最长有效期 398 天(CA/B 论坛规则,后续还将分阶段缩短至 200 天、100 天、47 天),过期后 Ingress 仍会把旧证书发出去,只是客户端拒绝握手。另外 www.example.com 与 example.com 是两个身份,证书 SAN 只写其中一个,另一个必然报错。
第一步:准备并校验证书文件
不要跳过这一步。把 GlobalSign 交付的压缩包解压后,先确认 fullchain.pem 里到底有几张证书、私钥能不能用。
# 1) 列出证书链中的所有证书(只输出 subject / issuer)
openssl crl2pkcs7 -nocrl -certfile fullchain.pem | openssl pkcs7 -print_certs -noout
# 2) 查看叶子证书的域名与有效期
openssl x509 -in fullchain.pem -noout -subject -issuer -dates -ext subjectAltName
# 3) 校验私钥与证书是否配对(RSA / ECDSA 通用,比对公钥指纹)
openssl x509 -in fullchain.pem -noout -pubkey | openssl md5
openssl pkey -in example.com.key -pubout | openssl md5
第 1 条命令应输出 2 段(叶子证书 + 中间证书)。如果只有 1 段,说明缺中间证书,把 GlobalSign 提供的中间证书追加进去:
cat example.com.crt globalsign_intermediate.crt > fullchain.pem
第 3 条命令两行输出的 MD5 必须完全一致,否则 kubectl create secret tls 会报 error: tls: private key does not match public key;即使 Secret 建成功,nginx reload 时也会报 SSL_CTX_use_PrivateKey() failed ... key values mismatch。
如果私钥是加密的,先解密再使用(口令只在这一步输入):
openssl pkey -in example.com.key -out example.com.dec.key
最后做一次链验证,把 fullchain 拆成单张证书后逐级校验,输出必须是 cert1.pem: OK:
awk '/BEGIN CERTIFICATE/{n++} n>0{print > ("cert" n ".pem")}' fullchain.pem
ls cert1.pem cert2.pem
openssl verify -CAfile GlobalSignRootR3.pem -untrusted cert2.pem cert1.pem
注意 -CAfile 用 GlobalSign 对应根证书(RSA 证书用 GlobalSign Root CA - R3,ECC 证书用 GlobalSign ECC Root CA R4),-untrusted 传入中间证书。根证书不要放进 fullchain.pem,它已在客户端信任库中,多带一张只会增加握手体积。
第二步:创建 TLS Secret 并接入 Ingress
推荐用 --dry-run=client -o yaml | kubectl apply -f - 的写法,它同时具备创建和幂等更新两种能力,续期时不用改命令。
kubectl create namespace your-namespace --dry-run=client -o yaml | kubectl apply -f -
kubectl create secret tls example-com-tls
--cert=fullchain.pem
--key=example.com.dec.key
-n your-namespace
--dry-run=client -o yaml | kubectl apply -f -
创建后立刻验证 Secret 的类型和内容,避免把错误带进 Ingress:
kubectl get secret example-com-tls -n your-namespace -o jsonpath='{.type}'; echo
kubectl get secret example-com-tls -n your-namespace -o go-template='{{index .data "tls.crt"}}' | base64 -d | openssl x509 -noout -subject -enddate
kubectl get secret example-com-tls -n your-namespace -o go-template='{{index .data "tls.crt"}}' | base64 -d | grep -c 'BEGIN CERTIFICATE'
第一条应输出 kubernetes.io/tls;第三条应输出 2,表示叶子证书加中间证书,输出 1 说明 fullchain.pem 用错了。
GitOps 场景下不要把私钥明文提交到仓库,改用 SealedSecret、External Secrets Operator 或 Vault Agent Injector 同步;这类工具同步出来的 Secret 键名同样必须是 tls.crt 与 tls.key,否则需要通过 spec.target.template 做键名映射。
另外确认执行者的 RBAC 权限,最小集合为:
kubectl auth can-i create secrets -n your-namespace
kubectl auth can-i update ingresses.networking.k8s.io -n your-namespace
配置示例:Ingress 引用与 cert-manager 自动签发
手工 Secret 方案下,Ingress 只需要引用 secretName。关键是 tls.hosts 与 rules[].host 保持一致,并把 TLS 版本下限抬到 1.2:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: example-ingress
namespace: your-namespace
annotations:
nginx.ingress.kubernetes.io/ssl-redirect: 'true'
nginx.ingress.kubernetes.io/force-ssl-redirect: 'true'
nginx.ingress.kubernetes.io/ssl-protocols: 'TLSv1.2 TLSv1.3'
spec:
ingressClassName: nginx
tls:
- hosts:
- example.com
- www.example.com
secretName: example-com-tls
rules:
- host: example.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: web
port:
number: 80
域名多、续期频繁时建议交给 cert-manager。GlobalSign 提供 ACME 接入(Atlas ACME),在控制台开通后拿到 Directory URL 填进 Issuer:
apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
name: globalsign-acme
namespace: your-namespace
spec:
acme:
server: https://<GlobalSign-ACME-Directory-URL>
privateKeySecretRef:
name: globalsign-acme-account-key
solvers:
- http01:
ingress:
ingressClassName: nginx
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: example-com
namespace: your-namespace
spec:
secretName: example-com-tls
duration: 2160h
renewBefore: 720h
commonName: example.com
dnsNames:
- example.com
- www.example.com
issuerRef:
name: globalsign-acme
kind: Issuer
duration 只是请求值,CA 返回多少就存多少:GlobalSign 公有证书最长 398 天,ACME 自动签发通常按 CA 策略下发(常见 90 天)。renewBefore 建议设为实际有效期的 1/3——90 天证书用 720h(30 天),398 天证书用 2880h(约 120 天)。若使用商业 OV/EV 证书并希望由 cert-manager 托管,可改用 Venafi Issuer 对接 GlobalSign Atlas,此时签发走 GlobalSign API 而非 ACME。
证书续期:398 天有效期下的滚动替换流程
GlobalSign 公有 TLS 证书最长 398 天,ACME 或内部 CA 下发的更短,务必把续期排进值班日历。手工续期的关键是“先更新 Secret,再让 Controller 重新加载”:
kubectl create secret tls example-com-tls
--cert=fullchain-2026.pem
--key=example.com.dec.key
-n your-namespace
--dry-run=client -o yaml | kubectl apply -f -
kubectl rollout restart deployment/ingress-nginx-controller -n ingress-nginx
kubectl rollout status deployment/ingress-nginx-controller -n ingress-nginx
较新版本的 ingress-nginx 会 watch Secret 变化并自动 reload,但混合版本集群以及通过 ConfigMap 挂载证书的老部署方式仍需重启。更新前后用序列号确认确实换成了新证书:
kubectl get secret example-com-tls -n your-namespace -o go-template='{{index .data "tls.crt"}}' | base64 -d | openssl x509 -noout -serial -enddate
cert-manager 管理的证书不需要手工干预,但可以主动触发一次续期做演练:
kubectl get certificate -n your-namespace
kubectl get certificaterequest -n your-namespace
kubectl cert-manager renew example-com -n your-namespace
演练时注意 ACME 速率限制:Let’s Encrypt 对同一组域名有每周 5 次重复证书限制,GlobalSign ACME 同样有配额。建议先用 staging Directory URL 在预发环境跑通流程,生产只执行一次。
最后一个高频事故:续期脚本生成了新名字的 Secret(如 example-com-tls-2026),却没有更新 Ingress 的 secretName,旧 Secret 仍被引用,客户端拿到的还是过期证书。续期脚本里应固定 Secret 名称,用 kubectl apply 覆盖而不是新建。
方案对比:手工 Secret、cert-manager 与外部密钥管理
选型时重点看三个维度:谁能签发(CA 能力)、谁能续期(自动化程度)、谁能管控私钥(合规要求)。下表按实际落地经验整理:
| 方案 | 证书来源 | 续期方式 | 单张有效期 | 运维成本 | 适用场景 |
|---|---|---|---|---|---|
| 手工 kubectl Secret | GlobalSign 控制台签发 | 人工 apply + reload | 最长 398 天 | 中,需值班表 | 域名少于 10 个、要求固定 CA 与 OV/EV |
| cert-manager + ACME | GlobalSign ACME / Let’s Encrypt | 全自动 | 按 CA 策略,常见 90 天 | 低 | 域名多、内部服务、测试环境 |
| cert-manager + Venafi Issuer | GlobalSign Atlas 商业证书 | 全自动 | 最长 398 天 | 中 | 需要 OV/EV 且要自动化 |
| External Secrets Operator + Vault | 任意 CA | 自动同步 | 依证书而定 | 中高 | 多集群统一管控、私钥不出 Vault |
再对比最常见的两个 CA 选择:
| 维度 | GlobalSign | Let’s Encrypt |
|---|---|---|
| 验证类型 | DV / OV / EV | 仅 DV |
| 单张有效期上限 | 398 天 | 90 天 |
| 信任根 | GlobalSign Root CA – R3 / R6、ECC Root CA R4 | ISRG Root X1 / X2 |
| 自动化接口 | ACME、REST API、Venafi 集成 | 仅 ACME |
| 费用 | 付费,按域名与年限计价 | 免费 |
| 典型用途 | 对外商业站点、需要企业身份与合规审计 | 内部系统、海量域名、CI 临时环境 |
选型还有两个容易被忽略的点:第一,Secret 是命名空间级资源,多命名空间共用同一张证书时需要复制 Secret,或改用 ClusterIssuer 加每个命名空间各建一个 Certificate;第二,通配符证书 *.example.com 只匹配一级子域,api.dev.example.com 这类两级子域仍会报域名不匹配,必须单独加 SAN。实践中的常见组合是:对外主站用 GlobalSign OV 走手工或 Venafi 自动化,内部与预发用 Let’s Encrypt 走 cert-manager,两者共用同一个 Ingress Controller,通过不同 secretName 隔离。
常见错误排查:从真实报错定位到具体文件
下面这些报错在 GlobalSign + Kubernetes 组合里出现频率最高,按“客户端现象 → 根因 → 验证命令”的顺序排查最快。
- curl 报
SSL certificate problem: unable to get local issuer certificate:链不完整。用echo | openssl s_client -connect example.com:443 -servername example.com -showcerts 2>/dev/null | grep -c 'BEGIN CERTIFICATE'确认服务端返回的证书数量,正常应为 2 到 3 张。 - Go 服务报
x509: certificate signed by unknown authority:同样是链不完整,或用了自签中间证书但客户端未安装对应根证书。 - Java 报
PKIX path building failed: unable to find valid certification path to requested target:Java 默认不补链,必须是完整链;若链已完整,检查 JDK 版本是否过老、cacerts 里是否缺少 GlobalSign Root CA – R3。 - kubectl 报
error: failed to load key pair: tls: failed to find any PEM data in certificate input:文件里混入 BOM、Windows CRLF 或说明文字。用file fullchain.pem与head -1 fullchain.pem确认首行是-----BEGIN CERTIFICATE-----。 - kubectl 报
error: tls: private key does not match public key:私钥与证书不是同一次生成的,用第一步的公钥 MD5 比对法确认。 - ingress-nginx 日志报
SSL_CTX_use_PrivateKey() failed (SSL: error:0B080074:x509 certificate routines:X509_check_private_key:key values mismatch):同样是密钥不匹配,或私钥未解密。 - ingress-nginx 日志报
local SSL certificate your-namespace/example-com-tls was not found:命名空间写错,或 Secret 键名不是tls.crt/tls.key。 - 报
x509: certificate is valid for example.com, not api.example.com:SAN 不含该域名,需重新签发或改用通配符证书。 - 报
certificate has expired:Secret 未更新或 Controller 未 reload,用openssl x509 -noout -enddate确认 Secret 内的 notAfter。
快速收集证据的两条命令:
kubectl logs -n ingress-nginx deploy/ingress-nginx-controller --tail=200 | grep -iE 'ssl|certificate|secret'
echo | openssl s_client -connect example.com:443 -servername example.com -showcerts 2>/dev/null | openssl x509 -noout -subject -issuer -dates
效果验证:kubectl、openssl、curl 三重确认
部署完成后不要只看浏览器,按下面三层依次验证,每层都能独立定位问题。
第一层,集群内对象状态。
kubectl get ingress example-ingress -n your-namespace
kubectl describe ingress example-ingress -n your-namespace | grep -A3 'TLS'
kubectl get certificate -A
kubectl get certificate example-com -n your-namespace -o jsonpath='{.status.conditions[*].reason}'; echo
cert-manager 场景下 kubectl get certificate -A 的 READY 列必须为 True;为 False 时继续看 kubectl describe certificate 的 Events,常见原因是 HTTP-01 挑战被防火墙拦截或 Ingress Class 不匹配。
第二层,TLS 握手与证书链。
openssl s_client -connect example.com:443 -servername example.com -verify_return_error </dev/null 2>&1 | grep -E 'Verify return code|subject=|issuer='
echo | openssl s_client -connect example.com:443 -servername example.com -showcerts 2>/dev/null | grep -c 'BEGIN CERTIFICATE'
期望看到 Verify return code: 0 (ok),证书数量为 2 或 3,issuer 显示 GlobalSign RSA OV SSL CA 2018 之类的中间 CA 名称。
第三层,HTTP 层与客户端兼容性。
curl -vI https://example.com --resolve example.com:443:203.0.113.10
curl -sI https://example.com -o /dev/null -w '%{http_code} %{ssl_verify_result}n'
keytool -printcert -sslserver example.com:443 | head -12
--resolve 可以绕过本地 DNS 缓存直接打到 Ingress 的负载均衡 IP,避免“证书换了但解析还指向旧集群”的误判;ssl_verify_result 为 0 表示校验通过;keytool 用来模拟 Java 客户端,是排查小程序、Android 兼容问题最接近生产的手段。
最后做一次到期巡检,并判断某张证书是否在 30 天内过期(命令返回 Certificate will expire 即需立即续期):
for ns in $(kubectl get ns -o jsonpath='{.items[*].metadata.name}'); do
kubectl get secrets -n $ns --field-selector type=kubernetes.io/tls -o name
done
kubectl get secret example-com-tls -n your-namespace -o go-template='{{index .data "tls.crt"}}' | base64 -d | openssl x509 -noout -checkend 2592000
常见问题
公有 TLS 证书单张最长有效期 398 天,ACME 或内部 CA 下发的通常更短(常见 90 天)。建议把 renewBefore 设为实际有效期的 1/3,并配置到期巡检,提前 30 天完成续期与 Secret 替换。
放服务器证书加全部中间证书,通常 2 张;根证书不要放,它已在客户端信任库中。可用 openssl crl2pkcs7 -nocrl -certfile fullchain.pem | openssl pkcs7 -print_certs -noout 确认链中共有几张证书。
浏览器支持 AIA 自动补链,服务端只返回叶子证书也能成功;Java 的 PKIX、OkHttp、Go 的 crypto/x509 不会补链,必须由服务端下发完整链。检查 tls.crt 是否误用了叶子证书而非 fullchain。
较新版本的 ingress-nginx 会 watch Secret 变化并自动 reload,多数情况无需重启;但混合版本集群、或通过 ConfigMap 挂载证书的部署方式仍需执行 kubectl rollout restart deployment/ingress-nginx-controller -n ingress-nginx 才能生效。
可以。GlobalSign 提供 ACME 接入(Atlas ACME),用 ACME Issuer 填 Directory URL 即可;若要走商业 OV/EV 证书签发,可改用 Venafi Issuer 对接 GlobalSign Atlas,通过其 REST API 完成自动签发与续期。
不能。kubectl create secret tls 只接受未加密的 PEM 私钥,遇到 BEGIN ENCRYPTED PRIVATE KEY 或 p12 文件时,先执行 openssl pkey -in example.com.key -out example.com.dec.key 解密,再用解密后的文件创建 Secret。