密码学与证书 / 系统课时

配置 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,而不是申请证书的业务命名空间。

Issuer 与 ClusterIssuer 的作用域及 CA 连接路径

配置 ACME ClusterIssuer

公共 ACME 入口通常希望跨命名空间复用,因此下面使用 ClusterIssuer。示例采用 ACME staging 端点和 HTTP-01,便于先验证流程;将邮箱、IngressClass 和服务器地址替换为你的实际配置后再进入生产签发。

yaml
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:

bash
kubectl apply -f clusterissuer-acme.yaml
kubectl wait --for=condition=Ready clusterissuer/acme-staging --timeout=120s

预期输出

text
clusterissuer.cert-manager.io/acme-staging created
clusterissuer.cert-manager.io/acme-staging condition met

Ready 只表示签发器自身完成初始化或账户注册,不等于某个域名一定能通过 HTTP-01;域名解析、Ingress 路由和外部可达性仍要在实际 Certificate 请求中验证。

配置内部 CA Issuer

内部 CA 更适合按命名空间隔离。下面假设平台已经提供一个专门用于在线签发的中间 CA 证书 ca.crt 和私钥 ca.key,不要把离线根 CA 私钥直接放进 Kubernetes。

先创建业务命名空间和 CA Secret:

bash
kubectl create namespace payments
kubectl create secret tls internal-ca-keypair \
  --cert=ca.crt \
  --key=ca.key \
  --namespace payments

预期输出

text
namespace/payments created
secret/internal-ca-keypair created

然后创建只在 payments 命名空间可用的 Issuer:

yaml
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 的详细状态。

bash
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

预期输出

text
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 配置中最常见的“资源存在但控制器找不到凭据”问题。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

配置 Issuer 与 ClusterIssuer

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通