Skip to content

在 Kubernetes 中配置证书自动申请与更新 ​

本文适用于已有 Kubernetes 网站和 HTTPS 入口、需要自动更新证书的场景。使用 cert-manager 接入 CertCloud ACME,将证书写入 TLS Secret,再由原 Gateway 或 Ingress Controller 加载。示例使用 Cloudflare 完成 DNS-01 验证;网站 Service 和入口保持原配置,不为续期重建网站。

本教程使用 Kubernetes 开源组件 cert-manager,与 TrustAsia 的 CertManager 产品不同。DNS 验证示例采用 Cloudflare;使用其他 DNS 服务商时,按对应说明选择验证器。

操作流程: 找到原证书 Secret → 获取并保存凭据 → 配置 Issuer → 接管证书 → 检查入口和网站。

下文输出摘自测试集群实际执行结果,域名替换为 example.com,资源名称与本文示例对齐,省略无关记录和字段。IP、运行时长和证书日期以实际输出为准。

方案与基本概念 ​

浏览器访问网站和 cert-manager 申请证书的流程如下:

cert-manager 向 CertCloud 申请证书,保存到 web-tls Secret,现有网站入口读取它提供 HTTPS。使用 Ingress 的网站沿用原入口,不必改成 Gateway。

示例命名空间和证书 Secret 分别为 web、web-tls;请将 example.com 和 mail@example.com 替换为实际域名和联系邮箱。术语说明见文末术语速查。

本教程仅用于操作引导与示例演示。读者应自行评估生产环境的网络架构、HTTPS 入口、软件版本、部署方式及业务要求,对文中的命令、配置和脚本进行适配,并在测试环境验证后再应用于生产环境。

网络放行 ​

cert-manager 所在网络需能访问订单的 ACME 服务地址和 Cloudflare API(HTTPS,通常 TCP 443),并能进行 DNS 查询和访问 Kubernetes API。自己的电脑需能访问网站 HTTPS。安装组件时还需能下载安装清单和容器镜像。

第一步:找到网站当前使用的 TLS Secret ​

在平时管理集群的终端操作,YAML 文件也在该机器上保存并通过 kubectl 应用。先确认当前集群和 cert-manager 的运行状态:

bash
kubectl config current-context
kubectl get pods -n cert-manager

确认连接的是目标集群,cert-manager 组件处于 Running 且已就绪。尚未安装时,按安装说明准备;已有组件但未就绪时,先检查错误并恢复运行。

按网站现有入口选择一种查询,名称及 Namespace 换成实际值:

bash
# 使用 Gateway 的网站
kubectl get gateway web-gateway -n web -o yaml

# 使用 Ingress 的网站
kubectl get ingress web-ingress -n web -o yaml

找到网站域名对应的证书引用,按下表记录:

Gateway 查询结果中,目标 HTTPS listener 的关键字段如下(其余字段省略):

yaml
metadata:
  name: web-gateway
  namespace: web
spec:
  listeners:
    - hostname: example.com
      name: https
      port: 443
      protocol: HTTPS
      tls:
        certificateRefs:
          - group: ""
            kind: Secret
            name: web-tls
        mode: Terminate

找到 hostname: example.com,再看该监听的 certificateRefs 内 name: web-tls;不要把监听名称 https 当成 Secret 名称。

Ingress 查询结果的关键字段如下:

yaml
metadata:
  name: web-ingress
  namespace: web
spec:
  tls:
    - hosts:
        - example.com
      secretName: web-tls

找到 hosts 中的网站域名,记下同一项的 secretName: web-tls。以上为已有配置的查询节选,不需要重新应用。

从原配置取得后面填写到哪里
Gateway 的 HTTPS listener 中 tls.certificateRefs[].name,或 Ingress 的 spec.tls[].secretName第四步 Certificate 的 spec.secretName
入口的 metadata.namespace凭据 Secret、Issuer、Certificate 的 metadata.namespace
网站实际域名第四步 Certificate 的 dnsNames,以及浏览器访问地址

本文按入口和证书 Secret 同在 web Namespace、Secret 名为 web-tls 操作,替换为刚查到的值。沿用原入口和网站路由。示例的 renewBeforePercentage 需要 cert-manager v1.16.3 或更新版本。

在创建 Certificate 前,确认目标 Secret 由谁维护。已有 Certificate 时使用原资源;由其他工具管理时,先协调接管方式,避免两套工具同时更新同一个 Secret。

第二步:取得并保存接入凭据 ​

在 CertCloud 订单中获取 ACME 凭据 ​

已有订单先确认该订单支持 ACME 自动化接入,无需为了使用本教程重复购买。打开 CertCloud 中的目标证书订单,在订单下方找到自动化配置,进入 ACME,按页面提示开启或查看该订单的 ACME 接入信息。记录页面提供的完整 ACME Directory URL、EAB Key ID 和 EAB HMAC Key,分别用于第三步的 server、keyID 和第二步的 hmac-key。页面没有 ACME 入口时,先确认订单是否支持此接入方式;不要用其他订单的凭据替代。

CertCloud 订单下方的自动化配置与 ACME 入口

在 Cloudflare 创建 DNS API Token ​

登录托管目标域名的 Cloudflare 账户,进入管理账户中的 账户API令牌 页面,创建一个专用于证书域名验证的 Token。设置 Zone / DNS / Edit 和 Zone / Zone / Read 两项权限,并在 Zone Resources 中只选择目标域名所在的 Zone,不要授权所有域名区域。 Cloudflare DNS API Token 权限配置 保存创建后显示的 Token,并在下一节将它写入 cloudflare-dns-token Secret。该 Token 用于添加和清理 _acme-challenge TXT 记录;CertCloud EAB 凭据则用于 ACME 账户注册,两者分别配置。请妥善保管 Token,避免在公开截图中展示。

保存两种凭据 ​

这两种凭据用途不同:EAB 凭据用于向 CertCloud 注册 ACME 账户,Cloudflare Token 用于添加和清理 DNS 验证记录。 将下面的内容保存为 credentials.yaml,在 web 命名空间中创建两个 Secret。不要把填入真实密钥的文件提交到 Git。

yaml
apiVersion: v1
kind: Secret
metadata:
  name: certcloud-eab
  namespace: web
type: Opaque
stringData:
  hmac-key: "REPLACE_WITH_EAB_HMAC_KEY"
---
apiVersion: v1
kind: Secret
metadata:
  name: cloudflare-dns-token
  namespace: web
type: Opaque
stringData:
  api-token: "REPLACE_WITH_CLOUDFLARE_API_TOKEN"

替换占位值后执行。若同名 Secret 已存在,先确认其归属;不要覆盖其他订单或工具的凭据:

bash
kubectl apply -f credentials.yaml
kubectl get secret certcloud-eab cloudflare-dns-token -n web

查询实测输出(名称已对齐):

text
NAME                   TYPE     DATA   AGE
certcloud-eab          Opaque   1      28m
cloudflare-dns-token   Opaque   1      28m

确认两条记录都存在、TYPE=Opaque、各有一个数据项;这里无需显示密钥内容。

stringData 直接接收原始字符串。EAB HMAC Key 按平台提供的值填写,不解码或再次编码。这里只检查 Secret 是否存在,不读取内容;真实凭据文件和 Secret 应按现有凭据管理方式限制访问,不提交到 Git。

第三步:配置证书签发方 ​

创建命名空间级 Issuer,为 cert-manager 指定证书签发配置,包括 CertCloud 接入地址、EAB 凭据,以及通过 Cloudflare 完成 DNS-01 验证的方法。

将下面内容保存为 issuer.yaml;把 server 替换为 CertCloud 提供的完整 URL(包含 https://),并填写实际 Key ID 与联系邮箱:

yaml
apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: certcloud-acme
  namespace: web
spec:
  acme:
    email: mail@example.com
    server: "REPLACE_WITH_COMPLETE_ACME_DIRECTORY_URL"
    externalAccountBinding:
      keyID: "REPLACE_WITH_EAB_KEY_ID"
      keySecretRef:
        name: certcloud-eab
        key: hmac-key
    privateKeySecretRef:
      name: certcloud-acme-account
    solvers:
      - dns01:
          cloudflare:
            apiTokenSecretRef:
              name: cloudflare-dns-token
              key: api-token
bash
kubectl apply -f issuer.yaml
kubectl wait -n web --for=condition=Ready issuer/certcloud-acme --timeout=120s

等待命令的实测输出:

text
issuer.cert-manager.io/certcloud-acme condition met

命令显示 condition met 表示 Issuer 已就绪,即 ACME 账户已注册;此时尚未申请网站证书。账户私钥 Secret certcloud-acme-account 由 cert-manager 自动创建,不要预先创建空 Secret。若等待超时,运行 kubectl describe issuer certcloud-acme -n web,检查 URL、EAB 和网络。

第四步:让 cert-manager 管理原证书 Secret ​

Certificate 声明域名、签发方和目标 TLS Secret。将 secretName 填为现有入口使用的 Secret 名称,域名填写当前网站的实际域名;示例为 web-tls 和 example.com。需要签发时,cert-manager 生成私钥、通过 ACME 申请证书并完成 DNS-01 验证。已有 Secret 中的证书仍有效且符合配置时,接管后可能直接显示 Ready,按计划等待续期,不一定立即申请新证书。

先保存现有证书和入口配置。已有 Certificate 时编辑原清单,不让两套任务同时更新同一个 Secret。实际签发或续期时会生成新私钥,请按目标订单的 ACME 接入说明确认签发影响,并及时检查新证书的加载结果。

将下面内容保存为 certificate.yaml,替换 Namespace、域名、目标 Secret 和 Issuer 名称:

yaml
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: web-tls
  namespace: web
spec:
  secretName: web-tls
  dnsNames:
    - example.com
  renewBeforePercentage: 33
  privateKey:
    algorithm: RSA
    size: 2048
    rotationPolicy: Always
  usages:
    - digital signature
    - key encipherment
    - server auth
  issuerRef:
    name: certcloud-acme
    kind: Issuer
    group: cert-manager.io

域名和密钥参数须符合实际产品要求,usages 不保证签发方一定按请求保留所有用途。rotationPolicy: Always 表示每次签发使用新的私钥;renewBeforePercentage: 33 表示剩余约 33% 有效期时尝试续期,不表示每 33 天执行一次。

bash
kubectl apply -f certificate.yaml
kubectl get certificate,certificaterequest -n web
kubectl get orders.acme.cert-manager.io,challenges.acme.cert-manager.io -n web
kubectl wait -n web --for=condition=Ready certificate/web-tls --timeout=600s
kubectl get secret web-tls -n web

成功时 Certificate 的 READY 为 True,web-tls Secret 的 TYPE 为 kubernetes.io/tls。其中 tls.crt 是证书,tls.key 是私钥;不要打印私钥,也不要让其他工具同时管理这个 Secret。若等待超时,检查 kubectl describe certificate web-tls -n web 和域名验证对象 Challenge 的事件;DNS 传播或订单审核可能需要更久,超时不表示申请已取消。

接管已有有效证书的输出示例(摘录目标资源):

text
NAME                                   READY   SECRET    AGE
certificate.cert-manager.io/web-tls     True    web-tls   0s
certificate.cert-manager.io/web-tls condition met
NAME      TYPE                DATA   AGE
web-tls   kubernetes.io/tls   2      6m34s

重点看 READY=True、SECRET=web-tls:当前证书可用,管理的是第一步记录的 Secret。该示例中原证书仍有效,cert-manager 接管后等待续期,尚未创建新的 CertificateRequest 或 ACME Order。

第五步:检查入口和网站访问 ​

检查入口状态 ​

确认入口仍引用第一步记录的 Secret。按现有入口选择下面一种检查,名称和 Namespace 换成实际值。

Gateway:

bash
kubectl get gateway,httproute -n web
kubectl describe gateway web-gateway -n web
kubectl describe httproute web -n web

在 describe gateway 的 Status > Conditions 中检查 Accepted=True 和 Programmed=True,确认控制器已接受 Gateway 配置并完成相应配置下发;在目标 HTTPS 监听的 Listeners > Conditions 中检查 ResolvedRefs=True,确认相关资源引用已成功解析。再检查 describe httproute 的 Status > Parents > Conditions,确认 Accepted=True 和 ResolvedRefs=True。这些状态检查通过后,仍需检查入口实际返回的证书和网站访问;Certificate 已就绪不代表网站入口已就绪。

实际输出中,条件按下面的形式排列(节选):

text
Status: True
Type:   Accepted
Status: True
Type:   Programmed

每个 Type 与它上面的 Status 配对;同样查看目标 listener 和 HTTPRoute 的 ResolvedRefs 是否为 True。

Ingress:

bash
kubectl describe ingress web-ingress -n web

确认 TLS 部分的域名、Secret 与第一步一致,后端仍为原 Service。入口不可达时,可参考首次部署的入口说明。

实测输出中的 TLS 部分如下:

text
TLS:
  web-tls terminates example.com

这里的 web-tls 应与第四步 spec.secretName 相同,example.com 应为网站域名。

检查网站访问 ​

在集群管理终端查看 TLS Secret 中的网站证书信息,供浏览器检查时对照:

bash
kubectl get secret web-tls -n web -o jsonpath='{.data.tls\.crt}' \
  | openssl base64 -d -A \
  | openssl x509 -noout -subject -dates

上面命令的实测输出(域名已替换):

text
subject=CN=example.com
notBefore=Oct  9 23:00:00 2026 GMT
notAfter=Apr 26 22:59:59 2027 GMT

subject 显示证书主体,notBefore、notAfter 分别为生效和到期时间(此处为 GMT)。浏览器查看器可能按本地时区显示日期。

在自己的电脑上用浏览器打开网站原 HTTPS 地址,例如 https://example.com/,使用第一步记录的实际域名和端口:

  1. 打开的是自己的网站,浏览器没有证书错误提示。
  2. 从地址栏的网站信息中查看证书,确认证书覆盖当前访问的域名,且仍在有效期内,并与 Secret 中的证书核对。如果接管后继续使用原证书,其有效期不会变化;实际签发新证书后,应按新证书检查,需要准确确认时比较两者的 SHA-256 指纹。
  3. 浏览常用页面,确认图片和页面样式显示正常,登录等业务功能可用。

使用 CDN 等代理或怀疑显示旧证书时,按证书检查说明核对集群入口的证书。

完成条件: Certificate 显示 Ready=True,入口引用正确且状态正常,浏览器或实际客户端的证书域名和信任链校验通过,网站业务可用。入口控制器通常会检测 Secret 变化并加载新证书,请按所用控制器的实际行为检查,无需默认在每次换证时重启应用 Pod。

后续维护与异常恢复 ​

cert-manager 负责在证书到期前尝试重新签发。查看计划续期时间和到期时间:

bash
kubectl get certificate web-tls -n web \
  -o jsonpath='{.status.renewalTime}{"\n"}{.status.notAfter}{"\n"}'

输出示例:

text
2027-02-20T06:55:11Z
2027-04-26T22:59:59Z

第一行是计划续期时间,第二行是证书到期时间,Z 表示 UTC。你的日期取决于实际证书;正常接管后无需另外注册 Cron。

定期检查 Certificate 的 READY 状态、实际入口证书、Cloudflare Token 权限,以及 CertCloud 订单服务期与审核状态。**证书自动续期不等于订单自动续费。**配置变更触发的重新签发可以验证证书替换,但不能证明未来进入续期窗口后一定成功。

遇到问题时,先查看对象状态与事件,保留正在服务的旧 TLS Secret,不要靠删除 Secret 排障:

bash
kubectl describe issuer certcloud-acme -n web
kubectl describe certificate web-tls -n web
kubectl get events -n web --sort-by=.metadata.creationTimestamp
  • Issuer 不就绪:核对 ACME 地址、EAB 凭据和出站网络。
  • Challenge 一直 pending:核对 Cloudflare Token 权限、域名的权威 DNS 与 TXT 传播。
  • 证书已 Ready,网站却超时或返回旧证书:核对 Gateway 状态、入口地址、客户端网络和实际终止 TLS 的位置。

异常恢复 ​

签发失败而原 Secret 尚未更新时,先修正凭据、验证或网络,保留原入口和有效证书,不删除 Secret 重新申请。ACME 等待超时不代表订单已取消,也不应连续修改 Certificate 强行触发重签。

若换证后入口异常,先检查 Secret 引用和入口控制器状态。需要恢复旧证书时,应先停止该 Certificate 的自动管理,避免恢复结果被控制器覆盖。请通过原 Helm、GitOps 或发布流程暂停该资源的同步,按下一节解除管理,再使用妥善保存的备份证书和匹配私钥更新原 Secret:

bash
NAMESPACE='web'
TLS_SECRET='web-tls'
BACKUP_CERT='/root/cert-backup/fullchain.pem'
BACKUP_KEY='/root/cert-backup/privkey.pem'

set -o pipefail
kubectl create secret tls "$TLS_SECRET" -n "$NAMESPACE" \
  --cert="$BACKUP_CERT" --key="$BACKUP_KEY" --dry-run=client -o yaml \
  | kubectl apply -f -

NAMESPACE 填原 Secret 所在的命名空间,TLS_SECRET 填原 Secret 名称。两个备份路径分别填写完整证书链和匹配私钥的路径,备份证书必须仍有效、未被吊销且覆盖网站域名。请执行整段命令,避免将包含私钥的 YAML 输出到终端或日志。恢复前,应确认原 Secret 为该网站专用,且没有其他工具继续管理它。

入口配置有误时,通过原发布流程恢复入口清单,不重建 Namespace 或 Controller。恢复后按第五步验收;重新接入前修复根因,恢复原 Certificate 清单及同步流程并观察签发与加载结果。重新启用可能触发签发,不保证继续使用备份证书。

停用自动更新或卸载 ​

需要停止管理或卸载时,展开操作说明

只停用一个网站的证书自动更新时,解除对应 Certificate 的管理,保留有效 TLS Secret 和入口。不要卸载全局 cert-manager,以免影响其他网站。

先备份原 Certificate 清单、TLS Secret 和入口配置,并限制备份文件的访问权限。确认当前没有进行中的签发任务,暂停会重新创建该 Certificate 的 GitOps 或 Helm 同步流程,再按实际名称在管理终端执行:

bash
NAMESPACE='web'
CERTIFICATE_NAME='web-tls'

kubectl delete certificate "$CERTIFICATE_NAME" -n "$NAMESPACE" --cascade=orphan
kubectl get secret web-tls -n "$NAMESPACE"

CERTIFICATE_NAME 是 Certificate 资源名称,不一定等于 Secret 名称;最后一条的 web-tls 也需替换为原 spec.secretName。--cascade=orphan 用于保留从属资源,避免启用 Certificate→Secret owner reference 的环境连带删除证书。操作前仍须确认实际资源归属、备份和其他自动化管理方;保留下来的请求等资源后续按需处理,不批量删除共享对象。

解除管理不会撤销平台订单,也不关闭已有 HTTPS,但此后需手动换证或交由其他工具接管。Issuer、EAB 和 DNS 凭据可能被其他证书使用,不随此操作删除。确实需要卸载整个 cert-manager 时,先安排所有受管证书的接管,再按原 Helm/GitOps 安装方式及官方卸载说明处理,不直接删除 Namespace 或 CRD。

补充配置与适用情况 ​

以下补充 cert-manager 安装和其他 DNS 服务商的配置方式。Gateway 安装和裸机入口配置见首次部署篇,已有正常入口可直接沿用。

安装 cert-manager ​

如果 kubectl get pods -n cert-manager 的查询结果中没有相关 Pod,或 Pod 尚未就绪,请先确认 cert-manager 是否已安装,并检查组件运行状态。下面的安装命令适用于尚未安装 cert-manager、且集群版本与所选版本兼容的环境。已有安装的维护和升级应沿用原 Helm/GitOps 流程。

集群管理员可安装固定版本的 cert-manager v1.21.2,并等待三个组件就绪:

bash
kubectl apply --server-side -f \
  https://github.com/cert-manager/cert-manager/releases/download/v1.21.2/cert-manager.yaml
kubectl wait -n cert-manager --timeout=10m --for=condition=Available \
  deployment/cert-manager deployment/cert-manager-cainjector deployment/cert-manager-webhook

Ingress 的证书引用核对已包含在第一步,加载结果检查见第五步。DNS-01 使用 DNS 验证,不需要额外创建 HTTP 验证路由。

其他 DNS 服务商 ​

第二、三步采用了 Cloudflare 专用的 Token 与 solvers[].dns01.cloudflare 配置。若域名的权威 DNS 由其他服务商管理,先确认 cert-manager 是否有对应 DNS-01 solver,再按该服务商要求准备凭据,并将 Issuer 中的 cloudflare 段替换成对应 solver。仅修改 Secret 名称或 DNS Token 字符串不能让 Cloudflare solver 控制其他 DNS 服务商。

更换 solver 后,第四步的 Certificate 和第五步的 Gateway 逻辑不变;签发前确认 cert-manager 能访问该 DNS 服务商 API,并能从公网查询临时 TXT 记录。如果使用与标准 DNS-01 不同的持久验证方案,应先确认签发方与客户端是否同时支持,再决定是否改变 solver,不应直接删除 DNS-01 配置。

术语速查 ​

名称在本文中的作用
ACME / EABACME 用于自动申请证书;EAB Key ID 和 HMAC Key 用于关联 CertCloud 接入资格。
DNS-01临时写入 TXT 记录,证明域名管理权。
cert-manager集群中的证书管理程序,负责申请和续期。
Issuer / Certificate前者保存签发方配置,后者声明域名和证书保存位置。
Secret / NamespaceSecret 保存凭据或证书;Namespace 是资源所属分组,本例为网站所在的 web。
Pod / ServicePod 运行业务程序,Service 提供访问这些程序的内部地址。
Gateway Controller / GatewayClassController 实现网关,GatewayClass 指定使用哪个实现;只创建资源定义不会处理请求。
Gateway / HTTPRouteGateway 配置 HTTPS 入口,HTTPRoute 指定后端 Service;实际请求由网关代理处理。