跳到主要内容
Kubernetes

JoySSL SSL 证书 Kubernetes 部署教程:Ingress、Secret 与自动续期实战

问题背景与根因:为什么证书放进 Kubernetes 仍会报错

JoySSL 是国产 CA,提供免费 DV 和付费证书,中文审核与本地化支持对国内用户较友好。把 JoySSL 签发的 SSL 证书部署到 Kubernetes 时,Ingress 并不直接读取磁盘文件,而是引用同命名空间下 type 为 kubernetes.io/tls 的 Secret,Secret 中必须包含 tls.crt 与 tls.key。最常见的故障不是「证书没上传」,而是链、域名、私钥、引用四类问题叠加。

根因一:只把叶子证书放进 tls.crt。浏览器往往通过 AIA 自动补链,看起来正常;但 curl、Java、微信小程序等严格客户端会报 curl: (60) SSL certificate problem: unable to get local issuer certificate 或 PKIX path building failed ... unable to find valid certification path to requested target。正确做法是使用 fullchain.pem,顺序为叶子证书在前、中间 CA 在后,根证书不要放入。

根因二:Secret 与 Ingress 不在同一命名空间,或 secretName 拼写不一致;根因三:证书 SAN 不含实际访问域名,或私钥与证书不匹配;根因四:续期后 Secret 已更新,但 Ingress Controller 缓存未刷新。另一个容易忽略的事实是有效期:公共信任 TLS 证书单张最长 398 天,Let’s Encrypt 为 90 天,JoySSL 免费 DV 的具体周期以签发页为准,付费证书通常也不超过 398 天,必须设置到期监控。

准备 JoySSL 证书文件与链完整性校验

在 JoySSL 控制台下载 Nginx 格式证书,通常得到 fullchain.pem 与 example.com.key。不要把 cert.pem 单证书直接当作 fullchain 使用。先检查文件与证书数量:

ls -l fullchain.pem example.com.key
grep -c 'BEGIN CERTIFICATE' fullchain.pem
openssl x509 -in fullchain.pem -noout -subject -issuer -dates -ext subjectAltName

grep -c 预期至少为 2,表示叶子证书加中间 CA;如果只有 1,说明链不完整。SAN 中必须出现 example.com、www.example.com 等实际域名。继续检查链顺序与私钥匹配:

openssl crl2pkcs7 -nocrl -certfile fullchain.pem | openssl pkcs7 -print_certs -noout
openssl x509 -noout -modulus -in fullchain.pem | openssl sha256
openssl rsa -noout -modulus -in example.com.key | openssl sha256

两条 sha256 输出必须一致。如果使用 ECDSA 证书,改用公钥比对:

openssl x509 -pubkey -noout -in fullchain.pem | openssl sha256
openssl pkey -pubout -in example.com.key | openssl sha256

最后做信任链校验,系统 CA 路径按发行版调整:

openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt -untrusted fullchain.pem fullchain.pem

预期输出 fullchain.pem: OK。若报 unable to get local issuer certificate,优先检查 fullchain 是否缺中间 CA、顺序是否颠倒、是否误把根证书放在最前面。证书文件不要有 Windows CRLF 或多余空行,私钥权限建议 600。

用 kubectl 创建可重复执行的 TLS Secret

先确保命名空间存在,再用 --dry-run=client -o yaml | kubectl apply -f - 创建或更新 Secret。这个写法可重复执行,适合续期后滚动替换,不会因 Secret 已存在而失败:

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

创建后验证类型和键名:

kubectl get secret example-com-tls -n prod
kubectl get secret example-com-tls -n prod -o jsonpath='{.type}'
kubectl describe secret example-com-tls -n prod

类型必须是 kubernetes.io/tls,并且存在 tls.crt 与 tls.key 两个键。不要用 kubectl create secret generic 后手工改 type,容易漏掉校验。若报 error: tls: failed to find any PEM data in certificate input,说明 –cert 指向的文件不是 PEM 或内容为空;若报私钥不匹配,回到上一节用 modulus 或公钥哈希核对。

Secret 与 Ingress 必须同命名空间。生产环境建议把命令放进 GitOps 或 CI,证书文件由密钥管理系统下发,不要把私钥提交到 Git。更新 Secret 时仍使用同一条 apply 命令;不要直接 kubectl edit secret 改 base64,容易把换行和链顺序改坏。需要确认 Secret 内实际证书时,可用 go-template 解码:

kubectl get secret example-com-tls -n prod -o go-template='{{index .data "tls.crt" | base64decode}}' | openssl x509 -noout -subject -issuer -dates

预期 subject 含 example.com,issuer 为 JoySSL 对应中间 CA,notAfter 不超过 398 天。

Ingress 配置示例与关键注解

以下 Ingress 使用 networking.k8s.io/v1,TLS 段引用上面的 Secret,hosts 与 rules.host 必须一致。若集群使用 nginx ingress controller,保留 ingressClassName 与强制跳转注解:

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

describe 输出中 TLS 段应显示 example-com-tls,Rules 的 host 应为 example.com。如果 IngressClass 不是 nginx,把 ingressClassName 改为实际值,例如 traefik 或 alb;不同控制器的跳转注解不同,不能照搬 nginx 注解。多域名时在 tls.hosts 和 rules 中同时列出所有域名,并确保证书 SAN 覆盖它们。

常见配置错误是 Ingress 与 Secret 不在同一命名空间,或 secretName 写成 default/example-com-tls。Ingress 的 secretName 只接受同命名空间 Secret 名称,不写命名空间前缀。若后端 Service 端口不是 80,按实际修改 number。部署后先用 kubectl get ingress -n prod -o yaml 检查控制器是否回填了 status.loadBalancer,再进入验证阶段。

续期与滚动更新:手动、cert-manager、CronJob 对比

证书到期前应重新签发并替换 Secret。手动方式与首次创建相同,apply 后观察 Ingress Controller 是否自动 reload:

kubectl create secret tls example-com-tls --cert=fullchain.pem --key=example.com.key -n prod --dry-run=client -o yaml | kubectl apply -f -
kubectl logs -n ingress-nginx deploy/ingress-nginx-controller --tail=100 | grep -i reload
kubectl rollout restart deployment -n ingress-nginx ingress-nginx-controller

最后一条仅在控制器未自动 reload 或缓存异常时执行。cert-manager 适合 ACME 自动化:kubectl get certificate -A 看到 Ready=True;Let’s Encrypt 证书 90 天,通常在到期前 30 天自动续期。若 JoySSL 提供 ACME Directory URL,可把 ClusterIssuer 的 server 换成该地址;若不提供 ACME,不要硬套 Let’s Encrypt 配置,应使用 CronJob 调用 JoySSL API 下载新证书并更新 Secret。

方式 适用场景 续期动作 关键对象/命令 主要风险
手动 Secret 小规模、证书来源固定 到期前重签并 apply kubectl create secret tls … –dry-run=client -o yaml | kubectl apply -f – 忘记续期、链不完整
cert-manager ACME CA 支持 ACME 自动签发与续期 Certificate + Issuer/ClusterIssuer ACME 账户、HTTP01/DNS01、速率限制
CronJob + CA API CA 不提供 ACME 但有 API 定时拉取并更新 Secret CronJob + RBAC + 凭据 Secret API 凭据泄露、更新失败无告警

公共信任 TLS 证书单张有效期上限为 398 天,Let’s Encrypt 为 90 天,JoySSL 免费 DV 周期以签发页为准。无论哪种方式,都要监控 notAfter,并保留回滚用的旧 Secret 副本。

常见错误排查:真实报错与修复命令

下面五类报错在 Kubernetes 部署 JoySSL 证书时最常见,按顺序排查能覆盖大部分问题。

1. curl 报 unable to get local issuer certificate。 典型输出:curl: (60) SSL certificate problem: unable to get local issuer certificate。说明服务端没有发送完整中间链。检查 Secret 中 tls.crt 是否为 fullchain,顺序是否为叶子在前、中间 CA 在后。用 openssl crl2pkcs7 -nocrl -certfile fullchain.pem | openssl pkcs7 -print_certs -noout 查看链,重建 Secret 后观察控制器 reload。

2. Java/小程序报 PKIX path building failed。 典型输出:javax.net.ssl.SSLHandshakeException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target。浏览器能补链,Java 和小程序不会。用 keytool -printcert -sslserver example.com:443 检查服务端链,必须包含中间 CA。

3. 创建 Secret 报 PEM 数据错误。 典型输出:error: tls: failed to find any PEM data in certificate input。检查 file fullchain.pem 与 openssl x509 -in fullchain.pem -noout -text,确认不是 DER、空文件或 CRLF 损坏。

4. 控制器日志报 key values mismatch。 典型输出:SSL_CTX_use_PrivateKey ... key values mismatch。证书与私钥不匹配,用 modulus 或公钥哈希比对,重新下载私钥并重建 Secret。

5. 续期后仍返回旧证书。 用 openssl s_client -connect example.com:443 -servername example.com | openssl x509 -noout -dates 看 notAfter 是否仍为旧值。检查 Secret 是否已更新、Ingress 是否引用正确 secretName、控制器日志是否有 Error reloading NGINX;必要时执行 kubectl rollout restart deployment -n ingress-nginx ingress-nginx-controller。若报 x509: certificate has expired or is not yet valid,同时检查节点与客户端时钟。

效果验证:从 Secret 到客户端全链路检查

先验证 Secret 内证书与 Ingress 引用:

kubectl get secret example-com-tls -n prod -o go-template='{{index .data "tls.crt" | base64decode}}' | openssl x509 -noout -subject -issuer -dates
kubectl describe ingress example-ingress -n prod | grep -A3 TLS
kubectl get certificate -A

预期 Secret 内 subject 含 example.com,notAfter 在未来且不超过 398 天;Ingress 的 TLS 段显示 example-com-tls;使用 cert-manager 时 Certificate 为 Ready=True。再验证线上 TLS:

curl -vI https://example.com
openssl s_client -connect example.com:443 -servername example.com -showcerts | openssl x509 -noout -subject -issuer -dates
echo | openssl s_client -connect example.com:443 -servername example.com -verify_return_error -CAfile /etc/ssl/certs/ca-certificates.crt 2>&1 | grep 'Verify return code'

预期 curl 出现 SSL certificate verify ok,s_client 的 subject 与域名一致,issuer 为中间 CA,verify return code 为 0 (ok)。检查 HTTP 跳转:

curl -I http://example.com

预期返回 301 或 308 并指向 https。Java 客户端可用 keytool -printcert -sslserver example.com:443 查看链;小程序需在后台配置合法域名,并确认证书链完整。最后检查 SAN 与有效期:

openssl x509 -in fullchain.pem -noout -ext subjectAltName -dates

如果浏览器正常但命令行失败,优先怀疑链不完整;如果 curl 正常但 Java 失败,优先怀疑中间 CA 缺失或客户端信任库过旧。验证通过后,把 notAfter 写入监控,提前 30 天告警。

常见问题

必须优先使用包含叶子证书与中间 CA 的 fullchain.pem,私钥单独保存。只放叶子证书时,浏览器可能通过 AIA 补链正常,但 curl、Java、小程序等严格客户端会报 unable to get local issuer certificate 或 PKIX path building failed。


多数 nginx ingress controller 会监听 Secret 并自动 reload,但可能存在缓存或 reload 失败。先看控制器日志是否有 reload 记录,再用 openssl s_client 检查 notAfter;仍为旧证书时执行 kubectl rollout restart deployment -n ingress-nginx ingress-nginx-controller。


取决于 JoySSL 是否提供 ACME Directory。支持时把 Issuer 的 server 指向 JoySSL ACME 地址即可自动签发续期;不支持时用 CronJob 调 CA API 更新 Secret,或手动滚动替换。Let’s Encrypt 的有效期为 90 天。


公共信任 TLS 证书单张有效期上限为 398 天,Let’s Encrypt 为 90 天。JoySSL 免费 DV 的具体周期以签发页为准,付费证书通常也不超过 398 天,部署后应监控 notAfter 并提前 30 天续期。


检查 Secret 的 tls.crt 是否为 fullchain,顺序为叶子证书在前、中间 CA 在后且不含根证书。用 openssl s_client 和 keytool -printcert -sslserver 验证服务端链,重建 Secret 并确认控制器 reload。

内容审核

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