跳到主要内容
Kubernetes

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 配置方式完全一致。

内容审核

长期从事 SSL/TLS 证书部署与 HTTPS 运维,负责本站证书选型、安装配置与故障排查内容的编写与审核。