密码学与证书 / 系统课时
配置 Issuer 与 ClusterIssuer
配置 Issuer 与 ClusterIssuer
这一课把证书请求连接到真正的签发入口:既能配置面向公共或私有 ACME 服务的 ClusterIssuer,也能配置使用内部 CA 密钥的命名空间级 Issuer。重点不是背 YAML,而是正确处理作用域、Secret 所在位置与证书请求的引用关系。
学习目标
- 根据租户和命名空间边界选择
Issuer或ClusterIssuer - 配置 ACME 与内部 CA 两类常见签发入口
- 验证 Issuer Ready 状态,并识别 Secret 放错命名空间的问题
先决定作用域
Issuer 是命名空间级资源,只能被同一命名空间中的 Certificate 引用;它适合团队隔离、不同命名空间使用不同 CA 凭据的场景。ClusterIssuer 是集群级资源,可被多个命名空间引用,适合统一的公共 ACME 或平台级签发入口。
两者最容易混淆的是 Secret 查找位置。Issuer 引用的 Secret 位于它自己的命名空间;ClusterIssuer 引用的 Secret 则位于 cert-manager 的 cluster resource namespace,默认通常是 cert-manager,而不是申请证书的业务命名空间。

配置 ACME ClusterIssuer
公共 ACME 入口通常希望跨命名空间复用,因此下面使用 ClusterIssuer。示例采用 ACME staging 端点和 HTTP-01,便于先验证流程;将邮箱、IngressClass 和服务器地址替换为你的实际配置后再进入生产签发。
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
name: acme-staging
spec:
acme:
email: pki-ops@example.com
server: https://acme-staging-v02.api.letsencrypt.org/directory
privateKeySecretRef:
name: acme-staging-account-key
solvers:
- http01:
ingress:
ingressClassName: nginx这个配置创建的是集群级签发入口。ACME 账户私钥对应的 acme-staging-account-key 由 cert-manager 管理,并放在 cluster resource namespace;HTTP-01 求解器则要求所选 Ingress Controller 能把挑战路径暴露给 ACME 服务端。
保存为 clusterissuer-acme.yaml 后应用并等待 Ready:
kubectl apply -f clusterissuer-acme.yaml
kubectl wait --for=condition=Ready clusterissuer/acme-staging --timeout=120s预期输出
clusterissuer.cert-manager.io/acme-staging created
clusterissuer.cert-manager.io/acme-staging condition metReady 只表示签发器自身完成初始化或账户注册,不等于某个域名一定能通过 HTTP-01;域名解析、Ingress 路由和外部可达性仍要在实际 Certificate 请求中验证。
配置内部 CA Issuer
内部 CA 更适合按命名空间隔离。下面假设平台已经提供一个专门用于在线签发的中间 CA 证书 ca.crt 和私钥 ca.key,不要把离线根 CA 私钥直接放进 Kubernetes。
先创建业务命名空间和 CA Secret:
kubectl create namespace payments
kubectl create secret tls internal-ca-keypair \
--cert=ca.crt \
--key=ca.key \
--namespace payments预期输出
namespace/payments created
secret/internal-ca-keypair created然后创建只在 payments 命名空间可用的 Issuer:
apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
name: internal-ca
namespace: payments
spec:
ca:
secretName: internal-ca-keypair该 Issuer 会读取同一命名空间中的 CA 证书与私钥,并用于签署 payments 内引用它的证书请求。若 Secret 缺少有效的 tls.crt、tls.key,或证书本身不具备 CA 签发能力,Issuer 不会进入可用状态。
用 Ready 状态验证入口
创建 Issuer 后,不要只看 YAML 是否成功提交,应检查 Condition 和事件。下面同时验证命名空间级 Issuer,并查看 ACME ClusterIssuer 的详细状态。
kubectl apply -f issuer-internal-ca.yaml
kubectl wait --for=condition=Ready issuer/internal-ca -n payments --timeout=60s
kubectl get issuer/internal-ca -n payments
kubectl get clusterissuer/acme-staging预期输出
issuer.cert-manager.io/internal-ca created
issuer.cert-manager.io/internal-ca condition met
NAME READY AGE
internal-ca True <TIME>
NAME READY AGE
acme-staging True <TIME><TIME> 为动态值。若 Issuer 报找不到 Secret,先确认 Secret 与 Issuer 是否在同一命名空间;若 ClusterIssuer 报找不到 Secret,则检查 cluster resource namespace,而不是业务命名空间。
在 Certificate 中正确引用
后续 Certificate 通过 issuerRef 选择签发入口:引用 Issuer 时 kind 写 Issuer,并保持在同一命名空间;引用 ClusterIssuer 时写 ClusterIssuer,即可跨命名空间使用。平台设计上应尽量只暴露业务确实需要的签发入口,并用 RBAC 与策略限制谁能创建 Certificate、可申请哪些 DNS 名称。
把作用域、Secret 位置和 CA 类型三件事分开判断,基本就能避免 Issuer 配置中最常见的“资源存在但控制器找不到凭据”问题。