跳到主要内容
Kubernetes

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。

内容审核

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