跳到主要内容
Kubernetes

GeoTrust SSL 证书部署到 Kubernetes:Secret、Ingress 与 cert-manager 实操指南

问题背景与根因:GeoTrust 证书上 Kubernetes 为什么会出现客户端校验失败

GeoTrust 现属 DigiCert 旗下,定位中端,价格通常比主品牌低约 40%,OV 审核稳定,适合预算有限但需要组织验证的企业。把 GeoTrust SSL 证书部署到 Kubernetes 时,TLS 通常在 Ingress Controller 终止:证书和私钥保存为 Secret,Ingress 通过 tls.secretName 引用。最常见的根因不是证书本身,而是 Secret 中只放了叶子证书、缺少中间 CA,导致浏览器能靠缓存或 AIA 补链,而 curl、Java、微信小程序等严格客户端报错。另一个根因是 Secret 与 Ingress 不在同一 namespace,或更新 Secret 后 Ingress Controller 未及时 reload。需要记住:GeoTrust 商业证书最长有效期按行业规则为 398 天,Let’s Encrypt 为 90 天,续期前应核对到期时间。排查时可先执行 curl -vI https://example.com,观察是否出现 curl: (60) SSL certificate problem: unable to get local issuer certificate,再用 openssl s_client -connect example.com:443 -servername example.com -showcerts 查看链。若报 x509: certificate signed by unknown authority,优先检查 fullchain.pem 是否包含中间证书,以及客户端 CA 库是否受信。Kubernetes 侧还要检查 kubectl -n your-namespace get secret example-com-tls 是否存在,describe ingress 是否显示 TLS 配置。上述问题都指向同一原则:Secret 的 tls.crt 应使用 fullchain.pem,tls.key 使用未加密私钥,且命名空间、secretName、主机名三者一致。

准备 GeoTrust 证书文件:fullchain、私钥与有效期核对

从 CA 交付包中通常拿到站点证书、中间 CA、根 CA 和私钥文件。Kubernetes 不需要根证书,tls.crt 使用 fullchain.pem,顺序为站点叶子证书在前、中间 CA 在后;tls.key 使用 PEM 格式且未加密的私钥。先核对证书主题、签发者、SAN 和有效期:

openssl x509 -in fullchain.pem -noout -subject -issuer -dates -ext subjectAltName
openssl crl2pkcs7 -nocrl -certfile fullchain.pem | openssl pkcs7 -print_certs -noout
openssl rsa -in example.com.key -check -noout
openssl x509 -in fullchain.pem -noout -modulus | openssl sha256
openssl rsa -in example.com.key -noout -modulus | openssl sha256

最后两条命令输出的哈希必须一致,否则证书与私钥不匹配,Ingress Controller 会拒绝加载。若私钥带密码,先解密再创建 Secret:openssl pkey -in encrypted.key -out example.com.key。fullchain.pem 中不要放根证书,根证书应存在于客户端信任库;把根证书塞进 tls.crt 不会解决链不完整问题,反而可能增大握手包。用 openssl crl2pkcs7 列出证书数量,正常应看到叶子证书和至少一张中间 CA。GeoTrust OV 证书常见 SAN 包含主域名和 www 域名,Ingress 的 host 必须落在 SAN 内。证书有效期最长 398 天,Let’s Encrypt 为 90 天,建议在到期前 30 天更新 Secret。若使用 cert-manager 管理 ACME 证书,则默认按 90 天周期自动续期,不要套用商业证书 398 天的节奏。

用 kubectl 创建和更新 TLS Secret(可直接执行)

Kubernetes 的 TLS Secret 类型为 kubernetes.io/tls,固定键为 tls.crt 与 tls.key。先确保命名空间存在,再以 dry-run 幂等创建,避免重复执行报 AlreadyExists:

kubectl create namespace your-namespace --dry-run=client -o yaml | kubectl apply -f -
kubectl -n your-namespace create secret tls example-com-tls --cert=fullchain.pem --key=example.com.key --dry-run=client -o yaml | kubectl apply -f -
kubectl -n your-namespace describe secret example-com-tls
kubectl -n your-namespace get secret example-com-tls -o yaml

创建后检查 Type 是否为 kubernetes.io/tls,Data 是否包含 tls.crt 和 tls.key。Secret 必须与 Ingress 在同一 namespace;Ingress 的 tls.secretName 只会在同 namespace 查找,跨 namespace 不会自动解析。续期时不要先 delete Secret,直接用同一条 dry-run apply 命令滚动替换,减少证书空窗。替换后 Ingress Controller 通常通过 watch 自动 reload;若仍返回旧证书,可执行 kubectl rollout restart deployment -n ingress-nginx ingress-nginx-controller。若报 error: tls: private key does not match public key,回到上一节比较 modulus 哈希。若报 error: failed to load key pair: tls: failed to find any PEM data in certificate input,说明文件路径错误或 tls.crt 不是 PEM。更新后可用 kubectl -n your-namespace get secret example-com-tls -o yaml 确认 resourceVersion 已变化,并检查 Ingress 事件中是否出现证书加载失败。

Ingress 配置示例:强制 HTTPS 与证书引用

以下示例使用 networking.k8s.io/v1,适用于 NGINX Ingress Controller。tls.hosts 与 rules.host 必须一致,secretName 指向刚创建的 Secret;annotations 中的 ssl-redirect 与 force-ssl-redirect 用于把 HTTP 跳到 HTTPS:

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'
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

执行 kubectl apply -f example-ingress.yaml 后,用 kubectl -n your-namespace describe ingress example-ingress 查看 TLS 段是否显示 example-com-tls,并确认 Events 无 local SSL certificate your-namespace/example-com-tls was not found。若使用 cert-manager,可额外加 cert-manager.io/cluster-issuer: letsencrypt-prod,由 cert-manager 生成同名 Secret;商业 GeoTrust 证书通常仍走手动 Secret 或外部签发流程。注意不要同时让 cert-manager 和人工更新同一个 Secret,否则可能互相覆盖。若后端是 HTTPS 服务,还需配置 backend-protocol 注解,避免 Ingress 到后端仍用 HTTP 导致 502。

手动 Secret、cert-manager 与云负载均衡方案对比

GeoTrust 商业证书与 ACME 证书的部署方式不同,选择方案时重点看续期责任和运维成本:

方案 适用场景 续期方式 优点 风险与注意
手动 Secret GeoTrust OV 等商业证书 到期前重新签发,kubectl dry-run apply 更新 证书品牌可控,OV 信息稳定,有效期最长 398 天 需人工跟踪到期,易漏中间 CA,Secret 必须与 Ingress 同 namespace
cert-manager ACME Let’s Encrypt 等免费证书 自动续期,默认 90 天周期 自动化程度高,适合大量域名 依赖 ACME 挑战与 DNS/HTTP 可达性,商业 OV 不能直接自动下单
云负载均衡托管证书 使用云厂商 LB 终止 TLS 控制台或 API 上传/托管续期 与 K8s Ingress 解耦,证书集中管理 需确认 LB 到后端链路,证书链和 SNI 配置不同

若企业要求 GeoTrust 品牌和 OV 组织验证,通常选手动 Secret 或云 LB 上传;若只是加密传输且可接受 90 天自动续期,选 cert-manager 更省人力。混合架构中可让 LB 终止 GeoTrust 证书,Ingress 内部再用 cert-manager 管理集群内证书,但要避免同一域名两层证书过期时间不一致。无论哪种方案,都应把 fullchain.pem 和私钥纳入受控流程,禁止把私钥提交到 Git;推荐用 SealedSecret、External Secrets 或云密钥管理服务注入。

常见错误排查:真实报错与定位命令

第一类报错是链不完整:curl: (60) SSL certificate problem: unable to get local issuer certificate、Java 的 PKIX path building failed、小程序提示证书链不完整。处理方法是把 tls.crt 换成 fullchain.pem,并用 openssl s_client -connect example.com:443 -servername example.com -showcerts 确认服务端返回了中间 CA。第二类是证书与私钥不匹配:error: tls: private key does not match public key,用 modulus 哈希比对。第三类是 Secret 找不到:local SSL certificate your-namespace/example-com-tls was not found,检查 namespace 和 secretName 拼写。第四类是过期或时间错误:x509: certificate has expired or is not yet valid,检查节点时间与证书 notBefore/notAfter。第五类是 cert-manager 未就绪:kubectl get certificate -A 显示 Ready=False,用 kubectl describe certificate 和 kubectl get challenge,order 查看 ACME 挑战失败原因。第六类是客户端信任库问题:x509: certificate signed by unknown authority 在服务端链完整时,需更新客户端 CA 或检查是否被中间人代理替换。排查时保留 kubectl -n your-namespace describe ingress example-ingress、kubectl logs -n ingress-nginx deploy/ingress-nginx-controller | grep -i ssl 与 curl -vI https://example.com 三份输出,能快速区分 Secret、Ingress 和客户端问题。

效果验证与续期检查

部署后先验证 Kubernetes 对象:kubectl -n your-namespace get secret example-com-tls 应存在且类型为 kubernetes.io/tls;cert-manager 场景执行 kubectl get certificate -A 确认 Ready=True。再验证外部握手:curl -vI https://example.com 应看到 SSL certificate verify ok,以及新的 subject、issuer 和 expire date;openssl s_client -connect example.com:443 -servername example.com -showcerts /dev/null | openssl x509 -noout -subject -issuer -dates 可精确读取服务端证书。检查链是否完整可看 openssl s_client -connect example.com:443 -servername example.com -CAfile /etc/ssl/certs/ca-certificates.crt 2>/dev/null | grep 'Verify return code',返回 0 (ok) 才算通过。HTTP 跳转用 curl -I http://example.com 验证是否 301/308 到 HTTPS。若更新 Secret 后仍返回旧证书,执行 kubectl rollout restart deployment -n ingress-nginx ingress-nginx-controller,并确认没有多个 Ingress 同时匹配同一 host。最后把到期时间纳入监控,GeoTrust 按 398 天有效期提前 30 天续期,Let’s Encrypt 按 90 天周期由 cert-manager 自动续期。

常见问题

按行业规则,GeoTrust 商业 SSL 证书最长有效期为 398 天;Let’s Encrypt 证书为 90 天。到期前应重新签发并更新 Kubernetes Secret,避免因过期导致客户端报 x509 证书过期。

tls.crt 应使用 fullchain.pem,即叶子证书在前、中间 CA 在后;tls.key 使用未加密私钥。只放叶子证书会导致 curl、Java、小程序等严格客户端报证书链不完整。

常见原因是 Ingress Controller 缓存未刷新、Secret 与 Ingress 不在同一 namespace,或 secretName 指向错误。确认对象正确后可执行 kubectl rollout restart deployment -n ingress-nginx ingress-nginx-controller 触发重载。

cert-manager 主要自动管理 ACME 证书,例如 Let’s Encrypt 90 天证书;GeoTrust OV 商业证书通常不能直接自动下单和续期,仍需人工签发后更新 Secret,或通过外部集成流程处理。

分别对证书和私钥执行 modulus 后做 sha256 哈希,两个哈希一致才匹配。若不一致,kubectl 创建 Secret 会报 tls: private key does not match public key,需重新配对证书和私钥。

内容审核

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