GlobalSign SSL 证书部署到 Kubernetes 全流程:Secret 创建、Ingress 配置与 398 天续期实战
一、问题背景与根因:为什么 GlobalSign 证书在 Kubernetes 里总“装不上”
传统部署把证书写进 /etc/nginx/ssl 目录,Kubernetes 则把证书抽象成 Secret 对象,由 kubelet 挂载进 Pod,或由 Ingress Controller 直接读取。这个模型带来了四类高频故障:
1. 证书链不完整。GlobalSign 采用“叶子证书 + 中间 CA”两段式签发,交付包里通常同时有 example.com.crt、intermediate.crt、fullchain.crt。只把叶子证书塞进 Secret 时,浏览器因为支持 AIA 自动补链会显示正常,但 Java、Go、微信小程序、部分 Android 客户端会直接握手失败。
2. 私钥格式错位。GlobalSign 交付的 RSA 私钥多为 PKCS#1(-----BEGIN RSA PRIVATE KEY-----),若签发的是 ECC 证书则是 -----BEGIN EC PRIVATE KEY-----;二次转换或复制时混入 BOM、Windows 换行,都会让 Secret 创建失败。
3. 命名空间错位。Ingress 只引用同一 namespace 下的 Secret,跨 namespace 引用会被静默忽略,表现为“YAML 写了但站点仍是默认自签证书”。
4. 有效期缩短带来的续期压力。按 CA/B Forum 基线要求,当前公有 SSL 证书最长有效期 398 天,GlobalSign 同样受限;手工替换 Secret 的团队极易漏续期,到期后客户端直接抛 certificate has expired or is not yet valid。
动手前先确认环境版本,避免用到已废弃的 extensions/v1beta1 Ingress:
kubectl version --short
kubectl get ingress -A
kubectl get pods -n ingress-nginx
openssl version -a
如果集群仍在用 networking.k8s.io/v1beta1,请先迁移到 networking.k8s.io/v1,否则 pathType、ingressClassName 等字段都不生效。
二、第一步:从 GlobalSign 交付包整理出可直接使用的证书文件
GlobalSign 交付的压缩包解压后,常见文件有:example.com.crt(叶子证书)、intermediate.crt(中间 CA)、example.com.key(私钥)、fullchain.crt(完整链)。Kubernetes Secret 的 --cert 必须传完整链,绝不能只传叶子证书。
如果交付包里没有 fullchain,需要手工拼接,顺序是“叶子在前、中间在后、不含根证书”:
# 拼接完整链
cat example.com.crt intermediate.crt > fullchain.pem
# 校验链是否完整,输出 example.com.crt: OK 即通过
openssl verify -untrusted intermediate.crt fullchain.pem
# 查看主题、签发者、有效期与 SAN
openssl x509 -in fullchain.pem -noout -subject -issuer -dates -ext subjectAltName
接着确认私钥可用且与证书配对。证书与私钥的模数 MD5 必须完全一致,这是后面排查“私钥不匹配”的关键依据:
# 检查私钥完整性
openssl rsa -in example.com.key -check -noout
# 两个 md5 值必须相同
openssl x509 -in fullchain.pem -noout -modulus | openssl md5
openssl rsa -in example.com.key -noout -modulus | openssl md5
若私钥是 PKCS#1 而 Ingress Controller 报解析错误,可无损转换为 PKCS#8:
openssl pkcs8 -topk8 -nocrypt -in example.com.key -out example.com.pk8.key
注意通配符证书 *.example.com 只覆盖一级子域,a.b.example.com 不在覆盖范围内;多域名证书要确认 subjectAltName 里列出了全部 FQDN,否则会触发 SSL_ERROR_BAD_CERT_DOMAIN。
三、第二步:创建 TLS Secret 的三种方式与校验命令
Kubernetes 的 TLS Secret 类型为 kubernetes.io/tls,只认两个键:tls.crt 与 tls.key。kubectl create secret tls 会自动完成映射,是首选方式。
方式一:命令行直接创建(最常用)
kubectl create secret tls example-com-tls
--cert=fullchain.pem
--key=example.com.key
-n your-namespace
方式二:声明式 apply(推荐配合 GitOps,可重复执行)
kubectl create secret tls example-com-tls
--cert=fullchain.pem
--key=example.com.key
-n your-namespace
--dry-run=client -o yaml > secret.yaml
kubectl apply -f secret.yaml
直接对已存在的 Secret 执行 create 会报错 Error from server (AlreadyExists): secrets 'example-com-tls' already exists,所以续期时务必带 --dry-run=client -o yaml | kubectl apply -f -。
方式三:cert-manager 托管,由控制器自动写入 Secret,后文续期章节展开。
创建后必须回读校验,确认写进集群的内容与本地文件一致:
kubectl get secret example-com-tls -n your-namespace
kubectl get secret example-com-tls -n your-namespace
-o jsonpath='{.data.tls.crt}' | base64 -d |
openssl x509 -noout -subject -issuer -dates -fingerprint -sha256
两条硬性约束:Secret 必须与 Ingress 处于同一 namespace;Secret 名称大小写敏感,example-com-tls 与 Example-Com-TLS 是两个对象。建议给 Secret 打上标签 cert-managed-by=platform,便于批量巡检到期时间。
四、第三步:Ingress 与 Ingress-Nginx 完整配置示例
下面是一份可直接 kubectl apply 的生产级配置,包含 TLS 引用、HTTP 强制跳转、TLS 1.2/1.3 限制、加密套件收敛与 HSTS:
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'
nginx.ingress.kubernetes.io/ssl-ciphers: 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384'
nginx.ingress.kubernetes.io/ssl-prefer-server-ciphers: 'true'
nginx.ingress.kubernetes.io/hsts: 'true'
nginx.ingress.kubernetes.io/hsts-max-age: '31536000'
spec:
ingressClassName: nginx
tls:
- hosts:
- example.com
secretName: example-com-tls
rules:
- host: example.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: web
port:
number: 80
几个易踩坑点:ingressClassName 必须与集群实际的 IngressClass 一致(kubectl get ingressclass 查看);spec.tls[].hosts 里的域名必须与 rules[].host 对应,否则 SNI 匹配失败会回落到默认证书;多域名共用一张证书时,把所有域名都列进 hosts 数组并指向同一个 secretName。
启用 hsts-include-subdomains 前请确认所有子域都已启用 HTTPS,否则会造成子域长时间无法访问(HSTS 由浏览器缓存,无法服务端撤销)。配置变更后可观察控制器日志确认证书加载:
kubectl logs -n ingress-nginx deploy/ingress-nginx-controller --tail=50 | grep -i 'ssl|certificate'
五、第四步:398 天有效期下的续期与滚动替换
GlobalSign 证书最长有效期 398 天,建议在到期前 30 天完成新证书签发与替换,并预留两次发布窗口。核心原则:新证书用 apply 覆盖同名 Secret,让 Ingress 引用保持不变,避免改 YAML 引发额外风险。
# 1. 用新签发的文件覆盖 Secret(幂等,可重复执行)
kubectl create secret tls example-com-tls
--cert=fullchain.pem
--key=example.com.key
-n your-namespace
--dry-run=client -o yaml | kubectl apply -f -
# 2. 确认指纹已更新
kubectl get secret example-com-tls -n your-namespace
-o jsonpath='{.data.tls.crt}' | base64 -d |
openssl x509 -noout -dates -fingerprint -sha256
ingress-nginx 会 watch Secret 变化并自动 reload,通常 30~60 秒生效;其他控制器(Traefik、HAProxy Ingress、云厂商实现)可能需要重启:
kubectl rollout restart deployment/ingress-nginx-controller -n ingress-nginx
kubectl rollout status deployment/ingress-nginx-controller -n ingress-nginx
规模化场景建议交给 cert-manager。GlobalSign 提供 ACME 服务(需在 GlobalSign Atlas 门户开通并获取 EAB 凭据),配置示例如下,server 与 externalAccountBinding 以门户实际下发为准:
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
name: globalsign-acme
spec:
acme:
server: https://acme.globalsign.com/directory
privateKeySecretRef:
name: globalsign-acme-key
externalAccountBinding:
keyID: your-eab-kid
keySecretRef:
name: globalsign-eab
key: hmac
solvers:
- http01:
ingress:
ingressClassName: nginx
若私钥不能出集群,可用 External Secrets Operator 对接 Vault / KMS,由密钥库统一轮转,K8s 侧只同步引用。
六、方案与证书类型对比表
不同团队规模适用的证书分发方式差异很大,先按自动化程度选型:
| 方案 | 自动化程度 | 续期方式 | 适用场景 | 主要风险 |
|---|---|---|---|---|
| kubectl create secret tls 手工 | 低 | 人工重新创建 | 测试环境、单域名 | 漏续期;覆盖无版本可回滚 |
| CI/CD 管道 apply(dry-run 管道) | 中 | 流水线定时触发 | 已有 GitOps 流程 | 流水线失败无告警 |
| cert-manager + GlobalSign ACME | 高 | 到期前自动续签 | 域名多、需全自动 | 需开通 ACME;EAB 凭据泄露 |
| External Secrets + Vault/KMS | 高 | 随密钥库轮转 | 企业合规、私钥不出库 | 组件多,排查链路长 |
| 云负载均衡托管证书 | 高 | 云平台自动 | LB 层终结 TLS | 证书不进 K8s,Ingress 层不可见 |
再按证书类型确认部署差异(有效期均受 398 天上限约束):
| 证书类型 | 典型有效期 | 验证内容 | K8s 部署差异 |
|---|---|---|---|
| DV 单域名 | 最长 398 天 | 仅域名所有权 | 单个 Secret 即可 |
| OV 单域名 | 最长 398 天 | 企业实名审核 | 同上,需留存审核资料 |
| EV 证书 | 最长 398 天 | 严格企业核验 | 同上,浏览器不再特殊展示 |
| 通配符 *.example.com | 最长 398 天 | 覆盖一级子域 | 多 host 共用一个 Secret |
| 多域名 SAN | 最长 398 天 | 多个 FQDN | spec.tls[].hosts 必须列全 |
七、常见错误排查:真实报错与定位命令
1. error: failed to load key pair: tls: failed to find any PEM data in certificate input
证书文件不是 PEM 格式。常见原因:传成了 DER 的 .cer/.der、文件被 BOM 污染、或复制时丢了首行。用 head -1 fullchain.pem 确认首行是 -----BEGIN CERTIFICATE-----,DER 需转换:openssl x509 -inform DER -in cert.cer -out cert.pem。
2. curl: (60) SSL certificate problem: unable to get local issuer certificate
服务端下发的链缺中间 CA。对比 openssl s_client -connect example.com:443 -servername example.com -showcerts 输出的证书数量,正常应为 2 张(叶子 + 中间),只有 1 张说明 Secret 里是叶子证书。
3. tls: private key does not match public key / javax.net.ssl.SSLHandshakeException: PKIX path building failed
前者是证书与私钥不配对,用第二节的 modulus MD5 对比定位;后者是 Java 客户端信任库缺 GlobalSign 根证书,需导入 GlobalSign Root CA - R3 到 cacerts,而不是改服务端配置。
4. nginx: [emerg] PEM_read_bio_X509_AUX() failed (SSL: error:0909006C:PEM routines:get_name:no start line)
证书文件里混入了私钥内容或顺序颠倒。Secret 的 tls.crt 只能放证书链,私钥必须放 tls.key。
5. Secret 已更新但站点仍是旧证书
先比对指纹是否变化,再依次排查:控制器是否 reload(kubectl rollout restart)、前置 CDN/SLB/WAF 是否缓存证书、是否改错了 namespace。
kubectl describe ingress example-ingress -n your-namespace
kubectl get events -n your-namespace --sort-by=.lastTimestamp | tail -20
八、效果验证:从集群内到公网的四层校验
部署完成不等于生效,建议按“Secret 内容 → 控制器加载 → 公网握手 → 多客户端兼容”四层依次验证。
# 第 1 层:Secret 内证书是否正确
kubectl get secret example-com-tls -n your-namespace
-o jsonpath='{.data.tls.crt}' | base64 -d |
openssl x509 -noout -subject -issuer -dates
# 第 2 层:控制器是否已加载该证书
kubectl exec -n ingress-nginx deploy/ingress-nginx-controller --
nginx -T 2>/dev/null | grep -A2 'ssl_certificate'
# 第 3 层:公网握手,确认链与协议版本
openssl s_client -connect example.com:443 -servername example.com
-showcerts </dev/null 2>/dev/null | openssl x509 -noout -issuer -dates -fingerprint -sha256
# 第 4 层:HTTP 跳转与响应头
curl -sSI http://example.com | head -3
curl -vI https://example.com 2>&1 | grep -Ei 'SSL|subject|issuer|expire|strict-transport'
判读要点:issuer 应为 GlobalSign 的中间 CA 而非根;openssl s_client 输出中 Verify return code: 0 (ok) 表示链完整;curl 出现 SSL certificate verify ok 且响应头带 strict-transport-security 说明 HSTS 生效。
最后做多客户端交叉验证:openssl s_client -tls1_2 与 -tls1_3 各跑一次,再用 Java(keytool -printcert -sslserver example.com:443)、微信小程序、Android 真机各测一遍,可提前暴露“浏览器正常但客户端报错”的链问题。上线后建议把证书到期时间接入监控,阈值设为剩余 30 天告警。
常见问题
按 CA/B Forum 基线要求,当前 GlobalSign 公有 SSL 证书最长有效期 398 天。建议在到期前 30 天完成签发与替换,Kubernetes 中至少预留两个发布窗口,先用 apply 覆盖同名 Secret,保持 Ingress 引用不变,避免因改名导致回滚困难。
先回读 Secret 确认指纹已变:kubectl get secret example-com-tls -o jsonpath='{.data.tls.crt}’ | base64 -d | openssl x509 -noout -fingerprint -sha256。若指纹是新的,检查 ingress-nginx 是否已自动 reload(约 30~60 秒),必要时执行 rollout restart;再排查前置 CDN、SLB 或 WAF 是否缓存了旧证书。
典型原因是证书链不完整。浏览器支持 AIA 自动补链,而 Java、Go、小程序严格校验整条链。请把叶子证书与 GlobalSign 中间 CA 拼接成 fullchain.pem 后再创建 Secret,不要只上传 example.com.crt,否则会报 PKIX path building failed。
传 fullchain.pem,即叶子证书在前、中间 CA 在后、不含根证书的完整链文件;–key 传与该叶子证书配对的私钥。可用 openssl x509 -noout -modulus 与 openssl rsa -noout -modulus 分别取 MD5 对比,两个值一致才说明证书与私钥匹配。
可以,前提是证书的 subjectAltName 覆盖全部域名(多域名证书,或通配符 *.example.com 仅覆盖一级子域)。在 Ingress 的 spec.tls[].hosts 中列出所有域名并共用同一个 secretName,但该 Secret 必须与 Ingress 处于同一 namespace。
Let’s Encrypt 有效期 90 天,配合 cert-manager 可全自动签发续期,适合内部系统和快速迭代业务;GlobalSign 提供 DV/OV/EV,OV/EV 需企业实名审核,有效期最长 398 天,适合对外品牌与合规场景。两者都可落成标准 TLS Secret,Ingress 配置方式完全一致。