跳到主要内容
Kubernetes

JoySSL SSL 证书 Kubernetes 安装部署与自动续期实战

问题背景与根因:Kubernetes 中证书为什么容易部署失败

在 Kubernetes 中部署 JoySSL SSL 证书,表面上是把 PEM 文件放进 Secret,实际涉及证书链、私钥匹配、命名空间、Ingress Controller 热加载和续期。K8s 的 Ingress 不直接读取节点磁盘上的证书文件,而是通过 secretName 引用 kubernetes.io/tls 类型 Secret,该 Secret 必须包含 tls.crt 与 tls.key。最常见根因有四类:一是只上传了叶子证书,未带中间 CA,浏览器可能正常但 curl、Java、小程序报 unable to get local issuer certificate;二是证书与私钥不是同一对,Controller 日志出现 key values mismatch;三是 Secret 与 Ingress 不在同一 namespace,Events 报 secret not found;四是续期后只替换文件或 Secret,Controller 未 reload,仍返回旧证书。还要注意有效期:公共信任 TLS 证书单张最长 398 天,Let’s Encrypt 为 90 天,JoySSL 具体产品有效期以签发页为准。此外,Ingress 的 hosts 必须出现在证书 SAN 中,否则 TLS 握手可能成功但客户端主机名校验失败;使用 CDN/WAF 时还要确认回源和边缘证书不是同一张。上线前应把 fullchain.pem、example.com.key、Secret 名称、Ingress host 四者对齐,并用 openssl 和 kubectl 双重校验,避免把证书问题误判为网络或后端问题。

准备 JoySSL 证书文件与上线前校验

从 JoySSL 下载证书包后,先确认文件角色:服务器证书通常是 example.com.crt 或 fullchain.pem,私钥为 example.com.key,中间 CA 可能是 ca_bundle.crt。若压缩包只给叶子证书和中间证书,需要按“服务器证书在前、中间证书在后”的顺序拼接:

cat example.com.crt ca_bundle.crt > fullchain.pem
openssl x509 -in fullchain.pem -noout -subject -issuer -dates
openssl x509 -in fullchain.pem -noout -text | grep -A1 'Subject Alternative Name'

接着校验私钥匹配,两条命令输出的 MD5 必须完全一致:

openssl x509 -noout -modulus -in fullchain.pem | openssl md5
openssl rsa -noout -modulus -in example.com.key | openssl md5

再验证证书链。若手头有根证书和中间证书,可执行:

openssl verify -CAfile root_ca.pem -untrusted intermediate_ca.pem fullchain.pem

输出 fullchain.pem: OK 才建议进入 K8s。检查链中证书数量:grep -c ‘BEGIN CERTIFICATE’ fullchain.pem,公网证书通常至少 2 张,即叶子加中间 CA;根证书一般不必放入 fullchain。还要确认 SAN 包含 Ingress 使用的域名,证书剩余有效期大于 30 天。公共信任 TLS 证书单张上限 398 天,Let’s Encrypt 90 天,JoySSL 免费 DV 与付费证书有效期以签发页面为准。私钥权限建议 chmod 600 example.com.key,不要提交到 Git。

创建 TLS Secret:kubectl create secret tls 完整步骤

先确保命名空间存在,再用 kubectl create secret tls 创建 Secret。下面命令可直接执行,并用 dry-run 加 apply 实现幂等更新:

kubectl create namespace demo --dry-run=client -o yaml | kubectl apply -f -
kubectl create secret tls example-com-tls --cert=fullchain.pem --key=example.com.key -n demo --dry-run=client -o yaml | kubectl apply -f -
kubectl get secret example-com-tls -n demo
kubectl get secret example-com-tls -n demo -o yaml | grep -E 'tls.crt|tls.key'

Secret 类型应为 kubernetes.io/tls,data 中只有 tls.crt 和 tls.key 两个键。若用 –from-file 手工创建,键名容易变成 fullchain.pem,Ingress Controller 可能无法识别。创建后检查 Secret 内容:

kubectl get secret example-com-tls -n demo -o jsonpath='{.type}'; echo
kubectl get secret example-com-tls -n demo -o yaml | grep -E 'tls.crt|tls.key'

更新已有 Secret 时不要先 delete,否则 Ingress 会短暂无证书。使用上面的 dry-run 管道直接 apply,K8s 会更新 Secret 资源。多数 ingress-nginx 版本会监听 Secret 变化并热加载;若日志没有 reload,或客户端仍看到旧证书,执行 kubectl rollout restart deployment -n ingress-nginx ingress-nginx-controller。若 Ingress 与 Secret 不在同一 namespace,必须在 Ingress 所在 namespace 复制 Secret,secretName 不能写 ns/name。最后用 kubectl describe secret 查看 Events,确认没有证书解析错误。

Ingress 配置示例:引用 Secret 并强制 HTTPS

Ingress 通过 spec.tls.secretName 引用 Secret,hosts 必须与证书 SAN 一致。以下示例使用 networking.k8s.io/v1,并开启 HTTP 到 HTTPS 跳转:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ingress
  namespace: demo
  annotations:
    nginx.ingress.kubernetes.io/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 ingress.yaml
kubectl get ingress example-ingress -n demo
kubectl describe ingress example-ingress -n demo

describe 输出中 TLS 段应显示 example-com-tls,Events 不应出现 secret not found。若集群有多个 Ingress Controller,ingressClassName 必须写对,否则规则不会被目标 Controller 处理。hosts 与证书 SAN 不一致时,curl 可能报证书主题名不匹配;通配符证书只能覆盖一级域名,例如 *.example.com 不匹配 a.b.example.com。测试时不要直接改 DNS,可用 –resolve 指向测试入口:

curl -vkI https://example.com --resolve example.com:443:203.0.113.10

确认返回 HTTP/2 或 HTTP/1.1 200/301,并且证书 subject、issuer、有效期正确。若使用 CDN,需同时检查边缘证书和回源证书。

续期与更新:手动 Secret、cert-manager、External Secrets 对比

证书续期是 K8s 部署中最容易遗漏的环节。公共信任 TLS 证书单张有效期上限 398 天,Let’s Encrypt 为 90 天,JoySSL 不同产品有效期以签发页为准。建议在到期前 30 天完成更新,并把 Secret 更新纳入流水线。手动方案适合证书数量少的团队:重新签发后执行 kubectl create secret tls … –dry-run=client -o yaml | kubectl apply -f -,再观察 Controller 是否热加载;未生效时 rollout restart ingress-nginx-controller。cert-manager 适合 ACME 型 CA,可创建 Certificate 资源自动续期;JoySSL 是否提供 ACME 端点需以其文档为准,若不支持 ACME,可用 CronJob 调用 JoySSL API 更新 Secret,或由 CI 推送。External Secrets 适合把 Vault、云密钥管理中的证书同步为 K8s Secret。

方案 适用场景 更新方式 优点 风险
手动 Secret 少量域名、固定证书 dry-run apply 加 rollout restart 简单直观 易忘续期
cert-manager ACME CA、自动签发 Certificate CRD 自动续期 自动化高 JoySSL 非 ACME 时需确认支持
CronJob 加 API JoySSL 人工或 API 签发 定时申请并 apply Secret 流程可控 需处理失败告警
External Secrets 多集群、集中密钥 从 Vault 或云 Secret 同步 集中管理 依赖外部系统

无论哪种方案,都要监控证书剩余天数:openssl x509 -in fullchain.pem -noout -checkend 2592000,返回 0 表示 30 天内到期。cert-manager 环境可执行 kubectl get certificate -A 和 kubectl describe certificate -n demo example-com,确认 Ready=True。更新 Secret 后必须用 openssl s_client 验证实际下发证书,而不是只看 Secret 内容。

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

排查时先分清是证书链、私钥、Secret 引用还是 Controller 缓存问题。下面列出真实高频报错与定位命令。

  • curl: (60) SSL certificate problem: unable to get local issuer certificate。根因是服务端未发送中间 CA,客户端无法构建链。检查 fullchain.pem 是否包含中间证书,执行 openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null 2>/dev/null | openssl x509 -noout -subject -issuer -dates。
  • Java 报 sun.security.validator.ValidatorException: PKIX path building failed。Java 信任库不信任该根或链不完整;确认 fullchain 顺序为叶子到中间,重启应用,必要时用 keytool -list -cacerts 检查。
  • x509: certificate signed by unknown authority。客户端不信任签发根,常见于内网或自签环境;公网证书需确认 JoySSL 根是否在目标客户端信任库。
  • tls: private key does not match public key 或 nginx SSL_CTX_use_PrivateKey … key values mismatch。证书和私钥不匹配,重新用 modulus 比对。
  • kubectl describe ingress 报 secret example-com-tls not found。Secret 与 Ingress 不同 namespace 或名称拼写错误,执行 kubectl get secret -n demo。
  • x509: certificate has expired or is not yet valid。证书过期或系统时间错误;更新 Secret 并 reload,检查节点时间。

Controller 侧可查日志:kubectl logs -n ingress-nginx deploy/ingress-nginx-controller | grep -i -E ‘ssl|secret|certificate’。若日志显示 local SSL certificate was not found,优先检查 secretName 和 namespace。不要只重启后端 Pod,TLS 终止通常发生在 Ingress Controller。

效果验证与上线检查清单

上线前按清单验证,避免只看浏览器。第一步检查资源:kubectl get secret example-com-tls -n demo,kubectl get ingress example-ingress -n demo,kubectl describe ingress example-ingress -n demo 中 TLS 段与 Events 正常。第二步检查实际握手证书:

curl -vI https://example.com
openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null 2>/dev/null | openssl x509 -noout -subject -issuer -dates
openssl x509 -in fullchain.pem -noout -checkend 2592000

checkend 返回 0 表示 30 天内到期,需要立即续期。第三步检查 HTTP 跳转:curl -I http://example.com 应返回 301 或 308 并指向 https。第四步检查证书链数量与 SAN:grep -c ‘BEGIN CERTIFICATE’ fullchain.pem,openssl x509 -in fullchain.pem -noout -text | grep DNS。第五步检查 TLS 版本,禁用 TLS 1.0/1.1 后执行 openssl s_client -connect example.com:443 -tls1_2 -servername example.com </dev/null。第六步查看 Controller 日志是否有 reload 错误。最后用 Java、小程序或 Android 客户端各测一次,因为它们对证书链和 SNI 更敏感。把域名、Secret 名称、证书到期日、负责人写入监控,才能避免续期后不生效。

常见问题

用 fullchain.pem 作为 –cert,example.com.key 作为 –key,不要只传叶子证书。fullchain 应包含服务器证书和中间 CA,根证书通常不必放入。创建前用 openssl verify 和 modulus 比对确认链完整、私钥匹配,再执行 kubectl create secret tls。


先确认 Ingress 与 Secret 同 namespace 且 secretName 一致,再检查 ingress-nginx 日志是否 reload。执行 kubectl rollout restart deployment -n ingress-nginx ingress-nginx-controller,随后用 curl -vI 和 openssl s_client 查看实际下发证书,注意 CDN 边缘证书可能未更新。


取决于 JoySSL 是否提供 ACME 接口。cert-manager 原生适合 ACME CA;若 JoySSL 仅支持人工或 API 签发,可用 CronJob 调用接口更新 Secret,或由 CI/External Secrets 同步。不要假设所有 CA 都能直接接入 cert-manager。


检查 Java 信任库是否包含签发根证书,确认 fullchain 顺序为叶子证书在前、中间证书在后,并重启 Java 应用。用 keytool -list -cacerts 查看信任库,确保访问主机名在证书 SAN 中,且没有中间证书缺失。


Ingress 只能引用同 namespace 的 Secret,secretName 不能写成 ns/name。若 Secret 在 default、Ingress 在 demo,就会报 secret not found。用 kubectl get secret -n demo 和 kubectl describe ingress 检查 Events,必要时在 Ingress 所在 namespace 重新创建 Secret。


公共信任 TLS 证书单张有效期上限为 398 天,Let’s Encrypt 当前为 90 天,JoySSL 具体产品以签发页为准。建议到期前 30 天更新 Secret,并用 openssl x509 -checkend 2592000 和监控告警验证,避免续期后 Controller 未加载旧证书。

内容审核

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