目录

Homelab 证书管理实战:从私有 CA 到自动签发

基于 step-ca、cert-manager 与 Vault PKI 的内网证书实践

Homelab 里的服务一多,证书就会散落在 Nginx 配置、Kubernetes Secret、容器挂载目录和几台虚拟机上。公网证书有 Let’s Encrypt 和 Cloudflare 兜底,内网服务却没那么省心:用自签证书,浏览器和命令行工具到处报警告;把公网 CA 签发的证书用在 *.homelab.internal 上,又签不出来。

这篇文章记录我在 Homelab 里搭起来的一套证书管理链路:

  • step-ca 作为内网私有 CA,提供 ACME 接口和 step CLI;
  • cert-manager 在 Kubernetes 里申请、续期证书,并把结果写进 Secret;
  • Prometheus 采集证书过期时间、续期时间和就绪状态;
  • Vault PKI 作为需要审计和统一策略时的备选方案,这次也实际跑通了;
  • Cloudflare 继续负责公网域名,文中作为对比方案说明。

文中的实测部分运行在一台 Debian 12 + k3s 的虚拟机上,版本是 step-ca 0.30.2、step CLI 0.31.0、cert-manager 1.21.3、Vault 2.2.2。Vault PKI 已经在同一台 VM 上接入 cert-manager 并签发证书,Prometheus/Alertmanager 告警链路和 step-ca、Vault 的吊销流程也做了实测;Cloudflare API 只做方案说明,SPIFFE/SPIRE 和 cert-manager CSI Driver 属于后续方向,本文不展开。


先看整体结构。CA 层负责签发,cert-manager 负责把签发流程接到 Kubernetes,消费层是 Ingress、Pod 和虚拟机,监控层采集证书状态。

graph TB
    subgraph CA["CA 层"]
        StepCA["step-ca<br/>私有 CA"]
        Vault["Vault PKI<br/>可选"]
        CF["Cloudflare<br/>公网证书"]
    end

    subgraph Issue["签发层"]
        CM["cert-manager"]
        ACME["ACME / HTTP-01"]
    end

    subgraph Use["消费层"]
        Traefik["Traefik"]
        Ing["Ingress"]
        Pod["Pod"]
        VM["虚拟机 / 裸机服务"]
    end

    subgraph Monitor["监控层"]
        Prom["Prometheus"]
        Grafana["Grafana"]
        AM["Alertmanager"]
    end

    StepCA -->|ACME| CM
    Vault -->|Vault Issuer| CM
    CF -->|Origin CA| Traefik
    Traefik --> Ing
    CM -->|Secret| Ing
    CM -->|Secret / CSI| Pod
    StepCA -->|step CLI| VM
    CM -->|metrics| Prom
    Prom --> Grafana
    Prom --> AM

    style StepCA fill:#4f46e5,color:#fff
    style CM fill:#326ce5,color:#fff
    style Vault fill:#000,color:#fff
方案 适合的场景 优点 限制
step-ca 内网服务、开发环境、Kubernetes 单二进制部署,支持 ACME,短期证书 需要把 Root CA 分发到客户端
Vault PKI 需要审计、动态凭证、统一策略 权限模型和审计链路完整 部署和运维成本高
Cloudflare 公网暴露的服务 边缘证书自动管理,Origin CA 有效期长 只覆盖 Cloudflare 代理的流量

我的选择是 step-ca 做内网 CA,cert-manager 做 Kubernetes 侧的自动化。Vault 负责更敏感的服务,Cloudflare 继续管公网域名。三套方案不冲突,按域名和消费端拆分即可。

graph LR
    U["用户"] --> CF["Cloudflare"]
    CF -->|Full Strict| Traefik["Traefik<br/>Origin Certificate"]
    Traefik --> K8s["k3s / Kubernetes<br/>step-ca certificates"]
    K8s --> DB[("PostgreSQL<br/>可选 Vault 证书")]
    CA["step-ca<br/>ca.homelab.internal:8443"] --> K8s

    style CF fill:#f38020,color:#fff
    style Traefik fill:#24a1c1,color:#fff
    style K8s fill:#326ce5,color:#fff
    style CA fill:#4f46e5,color:#fff

实验环境里没有独立的内网 DNS,ca.homelab.internal 和测试域名通过 CoreDNS 的 homelab.internal server block 解析到实验室 VM。生产环境应该把这些记录放进自己的 DNS,而不是长期靠改 CoreDNS。


step-ca 是 Smallstep 开源的 CA 服务端,单个二进制就能跑,支持 ACME、JWK、OIDC 等 provisioner,适合 Homelab 这种规模。

我主要看中这几点:

  1. 部署轻,不需要数据库集群,BadgerDB 落地即可;
  2. cert-manager 可以直接走 ACME,不需要定制 Issuer;
  3. 默认证书有效期短,泄露后的影响窗口小;
  4. step CLI 能覆盖初始化、签发、检查和客户端信任配置。

创建目录和专用用户。下面的命令在 Debian 12 上执行,CA 监听 8443。

sudo useradd -r -s /bin/false step
sudo mkdir -p /opt/step-ca/{config,secrets,db,certs}
sudo chown -R step:step /opt/step-ca

# 生成 CA 私钥的加密口令,step-ca 启动时会读这个文件
sudo -u step sh -c 'openssl rand -base64 24 > /opt/step-ca/secrets/password.txt'
sudo chmod 600 /opt/step-ca/secrets/password.txt

export STEPPATH=/opt/step-ca
export CA_NAME="Homelab Root CA"
export CA_ADDRESS=":8443"
export CA_PROVISIONER="[email protected]"

CA_PROVISIONER 是第一个 JWK provisioner 的名字。后面用 step ca token 或 step ca certificate 手动签发时会用到它。

本文使用的版本是 step CLI 0.31.0、step-ca 0.30.2。下载地址和压缩包内的目录结构如下:

cd /tmp

curl -sLO https://github.com/smallstep/cli/releases/download/v0.31.0/step_linux_amd64.tar.gz
tar xzf step_linux_amd64.tar.gz
sudo install -m 755 step_linux_amd64/bin/step /usr/local/bin/step

curl -sLO https://github.com/smallstep/certificates/releases/download/v0.30.2/step-ca_linux_amd64.tar.gz
tar xzf step-ca_linux_amd64.tar.gz
sudo install -m 755 step-ca_linux_amd64/step-ca /usr/local/bin/step-ca

step version
step-ca version

step-ca 的压缩包里是 step-ca_linux_amd64/step-ca,不是直接在根目录。有些教程里的 mv step-ca /usr/local/bin/ 会找不到文件。

初始化时直接把 ACME provisioner 一起创建出来。step-ca 0.30 的 step ca init 支持 --acme,比先启动 CA、再调用 admin API 添加 provisioner 省事。

cd /opt/step-ca

sudo -u step env STEPPATH=/opt/step-ca step ca init \
  --name="$CA_NAME" \
  --dns=ca.homelab.internal \
  --dns=ca.plz.ac \
  --dns=10.31.0.141 \
  --address="$CA_ADDRESS" \
  --provisioner="$CA_PROVISIONER" \
  --acme \
  --deployment-type=standalone \
  --password-file=/opt/step-ca/secrets/password.txt

--dns 可以重复多次;不要写成逗号分隔的一整串,step-ca 不会帮你拆开。--deployment-type=standalone 表示不连接 Smallstep 的云服务,密钥完全本地管理。10.31.0.141 是实验环境 CA 的地址,实际部署时换成你的 CA IP,或者只在客户端通过域名访问时省略这个 SAN。

初始化完成后,目录结构是:

/opt/step-ca/
├── certs/
│   ├── root_ca.crt
│   └── intermediate_ca.crt
├── config/
│   ├── ca.json
│   └── defaults.json
├── db/
├── secrets/
│   ├── password.txt
│   ├── root_ca_key
│   └── intermediate_ca_key
└── ...

Root CA 证书在 certs/,私钥在 secrets/。有些示例把 root_ca.crt 写在 secrets/ 下,和 0.30 的实际布局不一致。

ca.json 里的 authority.claims 控制默认有效期。下面只列出需要修改的字段,不要整段覆盖原文件。为了让后面的续期测试能在几分钟内观察到,我把默认值改成了 10 分钟:

{
  "authority": {
    "claims": {
      "minTLSCertDuration": "5m",
      "maxTLSCertDuration": "2160h",
      "defaultTLSCertDuration": "10m",
      "disableRenewal": false,
      "allowRenewalAfterExpiry": true
    },
    "provisioners": [
      {
        "type": "ACME",
        "name": "acme",
        "claims": {
          "minTLSCertDuration": "5m",
          "maxTLSCertDuration": "2160h",
          "defaultTLSCertDuration": "10m"
        }
      }
    ]
  }
}

生产环境可以把 defaultTLSCertDuration 设为 24h 或 720h。ACME 客户端不能在订单里指定有效期,最终有效期由 CA 的 provisioner 配置决定;cert-manager 的 duration 字段在 ACME Issuer 下不会改变这个值。provisioners 数组里要保留初始化时生成的 JWK provisioner,只给 ACME 这一项加 claims。

修改后重启 CA,用 step ca provisioner list 可以看到 ACME provisioner 和 claims:

sudo systemctl restart step-ca
sudo step ca provisioner list \
  --ca-url=https://ca.homelab.internal:8443 \
  --root=/opt/step-ca/certs/root_ca.crt

把 CA 作为 systemd 服务运行,直接用专用用户 step,并限制它能写的目录:

# /etc/systemd/system/step-ca.service
[Unit]
Description=step-ca Certificate Authority
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=step
Group=step
Environment=STEPPATH=/opt/step-ca
ExecStart=/usr/local/bin/step-ca /opt/step-ca/config/ca.json --password-file=/opt/step-ca/secrets/password.txt
Restart=on-failure
RestartSec=10

NoNewPrivileges=yes
PrivateTmp=yes
ProtectSystem=strict
ProtectHome=yes
ReadWritePaths=/opt/step-ca/db

[Install]
WantedBy=multi-user.target

ProtectSystem=strict 会把大部分文件系统挂成只读,所以 ReadWritePaths 至少要包含 db。如果后面启用了其他会写文件的特性,要把对应目录加进去,否则 CA 会在启动或签发时因为权限失败。

启动并检查:

sudo systemctl daemon-reload
sudo systemctl enable --now step-ca
sudo systemctl status step-ca --lines=0 --no-pager

sudo step ca health \
  --ca-url=https://ca.homelab.internal:8443 \
  --root=/opt/step-ca/certs/root_ca.crt

step ca health 返回 ok 就说明 CA 的 HTTPS 和 ACME 端点已经起来了。下图是实际运行状态和 provisioner 列表:

step-ca 服务状态、健康检查和 provisioner 列表

step-ca 的 ACME directory 路径是 /acme/{provisioner}/directory。本文的 provisioner 名字是 acme,所以地址是:

https://ca.homelab.internal:8443/acme/acme/directory

可以直接验证:

sudo curl -s --cacert /opt/step-ca/certs/root_ca.crt \
  https://ca.homelab.internal:8443/acme/acme/directory | jq

输出包含 newNonce、newAccount、newOrder、revokeCert、keyChange。cert-manager 的 ACME Issuer 会先访问 newNonce 和 newAccount,然后创建订单。

私有 CA 绕不开的一步:把 Root CA 装进客户端信任库。Linux 下:

# 用指纹校验后再写入,避免从网络直接信任一个未知证书
step ca root root_ca.crt \
  --ca-url=https://ca.homelab.internal:8443 \
  --fingerprint <root-ca-fingerprint>

sudo cp root_ca.crt /usr/local/share/ca-certificates/homelab-ca.crt
sudo update-ca-certificates

# 验证
curl https://ca.homelab.internal:8443/health

macOS:

sudo security add-trusted-cert -d -r trustRoot \
  -k /Library/Keychains/System.keychain root_ca.crt

Windows(管理员 PowerShell):

Import-Certificate -FilePath "C:\temp\root_ca.crt" `
  -CertStoreLocation Cert:\LocalMachine\Root

容器镜像里没有系统信任库时,可以把 Root CA 复制进镜像:

FROM alpine:3.22
COPY root_ca.crt /usr/local/share/ca-certificates/homelab-ca.crt
RUN update-ca-certificates

或者在 Kubernetes 里用 ConfigMap 挂载,再用 SSL_CERT_FILE 指向它。不要在每个应用里重复写一套信任逻辑,能统一就统一。

如果不想在宿主机装二进制,官方镜像也可以直接跑。下面这份 compose 文件和 systemd 版本等价,适合把 CA 放到独立的 Docker 主机上:

services:
  step-ca:
    image: smallstep/step-ca:0.30.2
    container_name: step-ca
    restart: unless-stopped
    ports:
      - "8443:8443"
    volumes:
      - ./step:/home/step
    environment:
      - DOCKER_STEPCA_INIT_NAME=Homelab Root CA
      - DOCKER_STEPCA_INIT_DNS_NAMES=ca.homelab.internal,ca.plz.ac
      - DOCKER_STEPCA_INIT_REMOTE_MANAGEMENT=true
      - DOCKER_STEPCA_INIT_ACME=true
    healthcheck:
      test: ["CMD", "step", "ca", "health"]
      interval: 30s
      timeout: 10s
      retries: 3

这部分没有在本次实验里单独跑;镜像的初始化参数在不同版本间有变化,使用前先看对应版本的 README。


cert-manager 负责三件事:根据 Certificate 或 Ingress 注解创建 CertificateRequest,向 ACME 服务申请证书,把结果写进 Secret 并在到期前续期。

本文使用 cert-manager v1.21.3。新版 Helm chart 用 crds.enabled 安装 CRD,旧的 installCRDs 已经不再推荐。

helm repo add jetstack https://charts.jetstack.io
helm repo update

helm install cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --create-namespace \
  --version v1.21.3 \
  --set crds.enabled=true \
  --set prometheus.enabled=true

kubectl get pods -n cert-manager
kubectl wait --for=condition=Ready pods --all -n cert-manager --timeout=120s

prometheus.enabled=true 会给 cert-manager 的 Pod 加上 prometheus.io/scrape、prometheus.io/port 注解,同时暴露 9402 端口的 metrics。

先把 Root CA 转成 base64,写进 ClusterIssuer 的 caBundle。这一步不能省,否则 cert-manager 访问 https://ca.homelab.internal:8443 时会报 x509: certificate signed by unknown authority。

CA_B64=$(sudo base64 -w0 /opt/step-ca/certs/root_ca.crt)

cat <<EOF | kubectl apply -f -
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: step-ca-issuer
spec:
  acme:
    server: https://ca.homelab.internal:8443/acme/acme/directory
    email: [email protected]
    privateKeySecretRef:
      name: step-ca-account-key
    caBundle: ${CA_B64}
    solvers:
      - http01:
          ingress:
            ingressClassName: traefik
EOF

这里用 ingressClassName: traefik 指定 HTTP-01 solver 创建的 Ingress 由 Traefik 接管。早期示例里常见的是 class: traefik;新版本用 ingressClassName 更明确。

检查 Issuer 状态:

kubectl get clusterissuer step-ca-issuer
kubectl describe clusterissuer step-ca-issuer

READY=True 且消息是 The ACME account was registered with the ACME server,说明 cert-manager 已经用 caBundle 验证了 step-ca 的 TLS,并完成 ACME 账户注册。

先创建一个测试命名空间和 Certificate:

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: test-cert
  namespace: cert-test
spec:
  secretName: test-tls
  commonName: test.apps.homelab.internal
  dnsNames:
    - test.apps.homelab.internal
  renewBefore: 5m
  issuerRef:
    name: step-ca-issuer
    kind: ClusterIssuer

把上面的 YAML 保存为 test-cert.yaml,然后应用:

kubectl create namespace cert-test
kubectl apply -f test-cert.yaml
kubectl wait --for=condition=Ready certificate/test-cert -n cert-test --timeout=120s
kubectl get certificate -n cert-test

在本次实验里,从创建 Certificate 到 Ready=True 大约用了 20 秒。cert-manager 会创建一个 Order 和 HTTP-01 Challenge,step-ca 通过 Traefik 访问 http://test.apps.homelab.internal/.well-known/acme-challenge/...,验证通过后签发证书。

cert-manager 中的 ClusterIssuer、Certificate 和 ACME Order

一个常见的错误示例是直接申请 *.apps.homelab.internal,同时又用 HTTP-01 solver。这个组合跑不通:ACME 的 HTTP-01 只能验证具体主机名,wildcard 必须用 DNS-01。要签 wildcard,需要给 cert-manager 配一个 DNS-01 solver,例如 RFC2136、Cloudflare DNS 或 webhook。

另一个容易踩的点是 duration。ACME 协议里没有“请求有效期”这个字段,证书有效期由 CA 的 provisioner 决定。cert-manager 的 duration 在 ACME Issuer 下不会改变 step-ca 的签发结果。如果把 renewBefore 设得比实际有效期还长,cert-manager 会不停地续期。我的做法是:先看 step-ca 的 defaultTLSCertDuration,再把 renewBefore 设成它的一半左右。

更常见的用法是让 cert-manager 监听 Ingress 的 tls 配置,自动创建 Certificate:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: myapp
  namespace: cert-test
  annotations:
    cert-manager.io/cluster-issuer: step-ca-issuer
spec:
  ingressClassName: traefik
  tls:
    - hosts:
        - myapp.apps.homelab.internal
      secretName: tls-myapp
  rules:
    - host: myapp.apps.homelab.internal
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: myapp
                port:
                  number: 80

Ingress 创建后,cert-manager 会生成名为 tls-myapp 的 Certificate 和对应的 Secret。Traefik 从 Secret 读取证书,HTTPS 请求就能正常完成握手。Ingress 自动生成的证书通常只有 SAN,没有 Common Name,这是 cert-manager 的正常行为。

kubectl get certificate -n cert-test test-cert -o wide
kubectl describe certificate -n cert-test test-cert

kubectl get secret -n cert-test test-tls -o jsonpath='{.data.tls\.crt}' \
  | base64 -d \
  | openssl x509 -noout -subject -issuer -dates -ext subjectAltName

实际输出包含:

subject=CN = test.apps.homelab.internal
issuer=O = Homelab Root CA, CN = Homelab Root CA Intermediate CA
X509v3 Subject Alternative Name:
    DNS:test.apps.homelab.internal

证书主题、签发者、有效期和 SAN

证书链是“叶子证书 → step-ca Intermediate CA → Homelab Root CA”。客户端只要信任 Root CA,就能验证整条链。


Vault 的 PKI Secrets Engine 更适合需要审计、动态凭证和统一策略的环境。这一次我在同一台实验 VM 上把 Vault PKI 链路完整跑通了:Vault 2.2.2 使用 file backend,Vault 自己的 HTTPS 证书由 step-ca 签发,cert-manager 通过 Kubernetes auth 使用 Vault Issuer 签发证书。

Vault 的 HTTPS 证书先用 step-ca 签发,域名是 vault.homelab.internal:

sudo useradd -r -s /bin/false vault
sudo mkdir -p /opt/vault/{data,tls}

PROV=$(sudo step ca provisioner list \
  --ca-url=https://ca.homelab.internal:8443 \
  --root=/opt/step-ca/certs/root_ca.crt \
  | jq -r '.[] | select(.type=="JWK") | .name')

sudo STEPPATH=/opt/step-ca step ca certificate vault.homelab.internal \
  /opt/vault/tls/vault.crt /opt/vault/tls/vault.key \
  --ca-url=https://ca.homelab.internal:8443 \
  --root=/opt/step-ca/certs/root_ca.crt \
  --provisioner="$PROV" \
  --provisioner-password-file=/opt/step-ca/secrets/password.txt \
  --password-file=/opt/step-ca/secrets/password.txt \
  --not-after=720h

# 证书和私钥交给 vault 用户,Root CA 复制到 Vault 可读的位置
sudo chown -R vault:vault /opt/vault
sudo chmod 600 /opt/vault/tls/vault.key
sudo cp /opt/step-ca/certs/root_ca.crt /opt/vault/tls/root_ca.crt
sudo chmod 644 /opt/vault/tls/root_ca.crt

实验环境为了省事用了 disable_mlock = true;生产环境应启用 mlock 并关闭 swap,避免私钥被换出到磁盘。Vault 配置使用 file storage,并监听 8200:

# /etc/vault.d/vault.hcl
ui = true
disable_mlock = true
api_addr = "https://vault.homelab.internal:8200"
cluster_addr = "https://vault.homelab.internal:8201"

storage "file" {
  path = "/opt/vault/data"
}

listener "tcp" {
  address       = "0.0.0.0:8200"
  tls_cert_file = "/opt/vault/tls/vault.crt"
  tls_key_file  = "/opt/vault/tls/vault.key"
}

systemd 服务把 Vault 跑在专用用户下:

[Unit]
Description=HashiCorp Vault
After=network-online.target
Wants=network-online.target

[Service]
User=vault
Group=vault
ExecStart=/usr/local/bin/vault server -config=/etc/vault.d/vault.hcl
ExecReload=/bin/kill -HUP $MAINPID
KillSignal=SIGINT
Restart=on-failure
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

初始化时为了实验方便使用 1 个 share、阈值 1;生产环境不要这么配:

export VAULT_ADDR=https://vault.homelab.internal:8200
export VAULT_CACERT=/opt/vault/tls/root_ca.crt

vault operator init -key-shares=1 -key-threshold=1 -format=json \
  | sudo tee /opt/vault/init.json >/dev/null

UNSEAL=$(sudo jq -r '.unseal_keys_b64[0]' /opt/vault/init.json)
ROOT=$(sudo jq -r '.root_token' /opt/vault/init.json)

vault operator unseal "$UNSEAL"
vault login "$ROOT"
vault status

vault status 显示 Initialized true、Sealed false,服务就算起来了:

Vault 服务状态和 unseal 状态

vault secrets enable pki
vault secrets tune -max-lease-ttl=87600h pki

vault write -field=certificate pki/root/generate/internal \
  common_name="Homelab Vault Root CA" \
  issuer_name="homelab-root" \
  ttl=87600h > vault_root_ca.crt

vault write pki/config/urls \
  issuing_certificates="https://vault.homelab.internal:8200/v1/pki/ca" \
  crl_distribution_points="https://vault.homelab.internal:8200/v1/pki/crl"

vault secrets enable -path=pki_int pki
vault secrets tune -max-lease-ttl=43800h pki_int

vault write -format=json pki_int/intermediate/generate/internal \
  common_name="Homelab Vault Intermediate CA" \
  issuer_name="homelab-intermediate" \
  | jq -r '.data.csr' > pki_intermediate.csr

vault write -format=json pki/root/sign-intermediate \
  issuer_ref="homelab-root" \
  csr=@pki_intermediate.csr \
  format=pem_bundle \
  ttl="43800h" \
  | jq -r '.data.certificate' > intermediate.cert.pem

vault write pki_int/intermediate/set-signed certificate=@intermediate.cert.pem
vault write pki_int/roles/homelab-internal \
  allowed_domains="homelab.internal,svc.cluster.local" \
  allow_subdomains=true \
  allow_bare_domains=true \
  max_ttl="720h" \
  generate_lease=true \
  no_store=false

vault policy write cert-manager-policy - <<'EOF'
path "pki_int/sign/homelab-internal" {
  capabilities = ["create", "update"]
}
path "pki_int/issue/homelab-internal" {
  capabilities = ["create"]
}
EOF

no_store=false 让 Vault 保存签发记录,后面可以用 vault list pki_int/certs 查序列号。

Vault 跑在集群外,auth/kubernetes/config 需要 token reviewer 的 JWT 和 Kubernetes CA。先创建一个只用于 token review 的 ServiceAccount:

apiVersion: v1
kind: Namespace
metadata:
  name: vault
---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: vault-auth
  namespace: vault
---
apiVersion: v1
kind: Secret
metadata:
  name: vault-auth-token
  namespace: vault
  annotations:
    kubernetes.io/service-account.name: vault-auth
type: kubernetes.io/service-account-token
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: vault-auth-delegator
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: system:auth-delegator
subjects:
  - kind: ServiceAccount
    name: vault-auth
    namespace: vault
TOKEN=$(kubectl -n vault get secret vault-auth-token -o jsonpath='{.data.token}' | base64 -d)
CA=$(kubectl -n vault get secret vault-auth-token -o jsonpath='{.data.ca\.crt}' | base64 -d)

vault auth enable kubernetes

vault write auth/kubernetes/config \
  kubernetes_host="https://10.31.0.141:6443" \
  token_reviewer_jwt="$TOKEN" \
  kubernetes_ca_cert="$CA"

vault write auth/kubernetes/role/cert-manager \
  bound_service_account_names=cert-manager \
  bound_service_account_namespaces=cert-manager \
  policies=cert-manager-policy \
  ttl=1h

kubernetes_host 用 k3s API 的地址,不要写 https://kubernetes.default.svc,因为 Vault 不在 Pod 里。

cert-manager 原生支持 Vault Issuer,不需要额外插件。认证方式用 serviceAccountRef,让 cert-manager 用自己 Pod 里的 ServiceAccount token 去换 Vault token:

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: vault-issuer
spec:
  vault:
    server: https://vault.homelab.internal:8200
    path: pki_int/sign/homelab-internal
    caBundle: <base64-step-ca-root>
    auth:
      kubernetes:
        role: cert-manager
        mountPath: /v1/auth/kubernetes
        serviceAccountRef:
          name: cert-manager

这里的 caBundle 是 Vault HTTPS 证书的信任根,也就是 step-ca 的 Root CA,不是 Vault PKI 的 Root CA。两个 CA 在这一套里是分开的:step-ca 保护 Vault 的 API,Vault PKI 负责签发业务证书。

cert-manager 的 ServiceAccount 还需要 create serviceaccounts/token 权限,否则 Issuer 会报:

serviceaccounts "cert-manager" is forbidden:
User "system:serviceaccount:cert-manager:cert-manager"
cannot create resource "serviceaccounts/token"

补一个 Role 和 RoleBinding:

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: cert-manager-token-creator
  namespace: cert-manager
rules:
  - apiGroups: [""]
    resources: ["serviceaccounts/token"]
    verbs: ["create"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: cert-manager-token-creator
  namespace: cert-manager
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: cert-manager-token-creator
subjects:
  - kind: ServiceAccount
    name: cert-manager
    namespace: cert-manager

之后 Issuer 变成 Ready=True,消息是 Vault verified:

cert-manager 的 Vault ClusterIssuer 已通过认证

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: vault-test
  namespace: cert-test
spec:
  secretName: vault-test-tls
  commonName: vault-test.apps.homelab.internal
  dnsNames:
    - vault-test.apps.homelab.internal
  duration: 24h
  issuerRef:
    name: vault-issuer
    kind: ClusterIssuer

把上面的 YAML 保存为 vault-test.yaml,然后应用:

kubectl apply -f vault-test.yaml
kubectl wait --for=condition=Ready certificate/vault-test -n cert-test --timeout=120s
kubectl get certificate -n cert-test vault-test -o wide

实际结果是证书由 Homelab Vault Intermediate CA 签发,有效期 24 小时,SAN 正确:

subject=CN = vault-test.apps.homelab.internal
issuer=CN = Homelab Vault Intermediate CA
notBefore=Nov 13 17:25:51 2026 GMT
notAfter=Nov 14 17:26:21 2026 GMT
X509v3 Subject Alternative Name:
    DNS:vault-test.apps.homelab.internal

Vault PKI 签发的证书主题、签发者、有效期和 SAN

证书链是“叶子证书 → Homelab Vault Intermediate CA → Homelab Vault Root CA”。Vault 的 pki_int/certs 里也能查到这次签发的序列号,说明 no_store=false 和 generate_lease=true 都生效了:

vault list pki_int/certs
Keys
----
1f:2a:b8:9a:9b:68:ae:70:ff:31:66:ea:75:09:84:2e:24:e3:05:b9

证书签发只是开始。真正容易出事的是“证书过期了但没人知道”,所以监控要覆盖三件事:什么时候过期、什么时候续期、续期失败时能不能发现。

cert-manager 在 9402 端口暴露 Prometheus 指标。开启 prometheus.enabled=true 后,可以直接抓取这些指标:

指标 含义
certmanager_certificate_expiration_timestamp_seconds 证书过期时间戳
certmanager_certificate_ready_status 证书是否就绪,condition="True" 且值为 1 表示正常
certmanager_certificate_renewal_timestamp_seconds 计划续期时间戳
certmanager_controller_sync_call_count 控制器同步调用计数

如果集群里装了 Prometheus Operator,用 ServiceMonitor 最省事:

apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: cert-manager
  namespace: cert-manager
spec:
  selector:
    matchLabels:
      app.kubernetes.io/name: cert-manager
      app.kubernetes.io/component: controller
  endpoints:
    - port: http-metrics
      interval: 30s

没有 Prometheus Operator 时,可以在 Prometheus 的 scrape config 里直接抓 cert-manager.cert-manager.svc:9402,或者用 Pod 注解做服务发现。用注解方式时,relabel 要把 __address__ 改成 PodIP:9402,只写 keep 规则是不够的。

cert-manager 暴露的证书过期、就绪和续期指标

下面几条规则覆盖“即将过期”“已经过期”“未就绪”和“控制器消失”:

apiVersion: monitoring.coreos.com/v1
kind: PrometheusRule
metadata:
  name: cert-manager-alerts
  namespace: monitoring
spec:
  groups:
    - name: cert-manager
      rules:
        - alert: CertificateExpiringSoon
          expr: |
            (certmanager_certificate_expiration_timestamp_seconds - time()) < 7 * 24 * 3600
            and
            (certmanager_certificate_expiration_timestamp_seconds - time()) > 0
          for: 1h
          labels:
            severity: warning
          annotations:
            summary: "Certificate {{ $labels.name }} expires in 7 days"
            description: "Certificate {{ $labels.name }} in {{ $labels.namespace }} will expire soon."

        - alert: CertificateExpiringCritical
          expr: |
            (certmanager_certificate_expiration_timestamp_seconds - time()) < 24 * 3600
            and
            (certmanager_certificate_expiration_timestamp_seconds - time()) > 0
          for: 10m
          labels:
            severity: critical
          annotations:
            summary: "Certificate {{ $labels.name }} expires in 24 hours"
            description: "Certificate {{ $labels.name }} in {{ $labels.namespace }} needs immediate attention."

        - alert: CertificateExpired
          expr: |
            certmanager_certificate_expiration_timestamp_seconds - time() < 0
          for: 5m
          labels:
            severity: critical
          annotations:
            summary: "Certificate {{ $labels.name }} has expired"
            description: "Certificate {{ $labels.name }} in {{ $labels.namespace }} is past its expiry time."

        - alert: CertificateNotReady
          expr: |
            certmanager_certificate_ready_status{condition="True"} == 0
          for: 15m
          labels:
            severity: warning
          annotations:
            summary: "Certificate {{ $labels.name }} is not ready"
            description: "Certificate {{ $labels.name }} in {{ $labels.namespace }} has been not ready for 15 minutes."

        - alert: CertManagerAbsent
          expr: |
            absent(up{job="cert-manager"} == 1)
          for: 10m
          labels:
            severity: critical
          annotations:
            summary: "cert-manager is down"
            description: "cert-manager has been unavailable for more than 10 minutes."

CertManagerAbsent 里的 job 标签取决于你的抓取配置,用 ServiceMonitor 时通常不是字面上的 cert-manager。部署前先查一下 up{job=~".*cert-manager.*"} 的实际标签。

只看规则文本不够,我在实验环境里用最小化的 Prometheus 3.16.0 和 Alertmanager 0.35.0 跑了一遍,确认指标能从 cert-manager 抓取,规则能进入 firing,Alertmanager 能收到告警。实验里没有装完整的 kube-prometheus-stack,只用两个最小 Deployment 加 ConfigMap 验证链路;生产环境直接用 Prometheus Operator 的 ServiceMonitor 和 PrometheusRule 即可。

Prometheus 的抓取配置直接指向 cert-manager 的 Service:

scrape_configs:
  - job_name: cert-manager
    static_configs:
      - targets: ["cert-manager.cert-manager.svc:9402"]

规则文件里先用一条 CertificateNotReady,for 缩短到 30 秒方便观察:

groups:
  - name: cert-manager
    rules:
      - alert: CertificateNotReady
        expr: certmanager_certificate_ready_status{condition="True"} == 0
        for: 30s
        labels:
          severity: warning
        annotations:
          summary: "Certificate {{ $labels.name }} is not ready"

然后创建一个引用不存在 Issuer 的 Certificate,让它保持 Ready=False:

kubectl apply -f - <<'EOF'
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: alert-test
  namespace: cert-test
spec:
  secretName: alert-test-tls
  commonName: alert-test.apps.homelab.internal
  dnsNames:
    - alert-test.apps.homelab.internal
  issuerRef:
    name: does-not-exist
    kind: ClusterIssuer
EOF

大约一轮抓取加 30 秒之后,Prometheus 和 Alertmanager 都能看到这条告警:

kubectl get certificate -n cert-test alert-test
curl -s localhost:9090/api/v1/alerts | jq -r '.data.alerts[] | [.labels.alertname, .state, .labels.name] | @tsv'
curl -s localhost:9093/api/v2/alerts | jq -r '.[] | [.labels.alertname, .status.state, .labels.name] | @tsv'

实际输出是 CertificateNotReady firing alert-test 和 CertificateNotReady active alert-test:

Prometheus 告警进入 firing,Alertmanager 收到 active 告警

实验里的 Alertmanager 只配置了空 receiver,所以这里用 API 验证链路。生产环境把 receiver 换成 Slack、邮件或 webhook,并保留 for: 15m 之类的持续时间,避免瞬时抖动触发告警。

不在 Kubernetes 里的服务,可以用 blackbox-exporter 的 TLS probe 检查:

modules:
  tls_connect:
    prober: tcp
    timeout: 5s
    tcp:
      tls: true
      tls_config:
        insecure_skip_verify: false

Prometheus 抓取配置:

scrape_configs:
  - job_name: blackbox-tls
    metrics_path: /probe
    params:
      module: [tls_connect]
    static_configs:
      - targets:
          - ca.homelab.internal:8443
          - vault.homelab.internal:8200
    relabel_configs:
      - source_labels: [__address__]
        target_label: __param_target
      - source_labels: [__param_target]
        target_label: instance
      - target_label: __address__
        replacement: blackbox-exporter:9115

对应的告警:

- alert: TLSCertExpiringSoon
  expr: |
    probe_ssl_earliest_cert_expiry - time() < 7 * 24 * 3600
  for: 1h
  labels:
    severity: warning
  annotations:
    summary: "TLS certificate for {{ $labels.instance }} expires soon"

如果域名托管在 Cloudflare,证书分两层:

  • Edge Certificate:Cloudflare 到访客,Universal SSL 自动管理,通常不需要手工续期;
  • Origin Certificate:Cloudflare 到源站,最长 15 年,适合放在 Traefik 或 Nginx 上。

用 API 查看边缘证书包和 Origin CA 证书:

export CF_API_TOKEN="..."
export CF_ZONE_ID="..."

curl -s "https://api.cloudflare.com/client/v4/zones/${CF_ZONE_ID}/ssl/certificate_packs" \
  -H "Authorization: Bearer ${CF_API_TOKEN}" \
  | jq '.result[] | {id, type, status, hosts, expires_on: .certificates[0].expires_on}'

curl -s "https://api.cloudflare.com/client/v4/certificates?zone_id=${CF_ZONE_ID}" \
  -H "Authorization: Bearer ${CF_API_TOKEN}" \
  | jq '.result[] | {id, hostnames, expires_on, request_type}'

这部分没有在实验环境里调用真实 API。Cloudflare 的 API token 权限和返回字段会随产品调整,脚本上线前先用一个只读 token 验证。


项目 配置
操作系统 Debian 12 (bookworm)
虚拟化 Proxmox VE 虚拟机,4 vCPU / 5.8 GiB
Kubernetes k3s v1.32.3+k3s1,单节点
Ingress Traefik 3.3.2(k3s 自带)
私有 CA step-ca 0.30.2 / step CLI 0.31.0
cert-manager v1.21.3
Vault 2.2.2,file backend
监控 Prometheus 3.16.0 / Alertmanager 0.35.0
证书默认有效期 10 分钟(仅为测试续期;Vault 测试用 24 小时)

测试域名是 test.apps.homelab.internal、renew.apps.homelab.internal 和 myapp.apps.homelab.internal。step-ca 运行在同一个 VM 上,监听 8443;Traefik 监听 80/443。

创建 Certificate 并等待就绪:

kubectl create namespace cert-test

kubectl apply -f - <<'EOF'
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: test-cert
  namespace: cert-test
spec:
  secretName: test-tls
  commonName: test.apps.homelab.internal
  dnsNames:
    - test.apps.homelab.internal
  renewBefore: 5m
  issuerRef:
    name: step-ca-issuer
    kind: ClusterIssuer
EOF

kubectl wait --for=condition=Ready certificate/test-cert -n cert-test --timeout=120s
kubectl get certificate -n cert-test

实际结果是 READY=True,状态为 Certificate is up to date and has not expired,从创建到就绪大约 20 秒。

检查证书细节:

kubectl get secret -n cert-test test-tls -o jsonpath='{.data.tls\.crt}' \
  | base64 -d \
  | openssl x509 -noout -subject -issuer -dates -ext subjectAltName

输出确认了主题、签发者和 SAN:

subject=CN = test.apps.homelab.internal
issuer=O = Homelab Root CA, CN = Homelab Root CA Intermediate CA
X509v3 Subject Alternative Name:
    DNS:test.apps.homelab.internal

这一步同时验证了 CA 信任链:客户端信任 Root CA,叶子证书由 Intermediate CA 签发,中间证书由 Root CA 签发。

为了在几分钟内看到续期,我把 step-ca 的 ACME 默认有效期设为 10 分钟,并给 Certificate 设置 renewBefore: 5m:

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: renew-test
  namespace: cert-test
spec:
  secretName: renew-test-tls
  commonName: renew.apps.homelab.internal
  dnsNames:
    - renew.apps.homelab.internal
  renewBefore: 5m
  issuerRef:
    name: step-ca-issuer
    kind: ClusterIssuer

把上面的 YAML 保存为 renew-cert.yaml,然后应用:

kubectl apply -f renew-cert.yaml
kubectl wait --for=condition=Ready certificate/renew-test -n cert-test --timeout=120s
kubectl get certificate -n cert-test renew-test -o wide

第一次签发后,证书有效期是 16:48:22 到 16:59:22,renewalTime 是 16:54:22,正好提前 5 分钟。到了续期时间,cert-manager 创建了 renew-test-2,随后又因为同样的 10 分钟有效期产生了 renew-test-3。截图中 revision=3,序列号和 notBefore/notAfter 都已经更新:

cert-manager 自动续期后的 revision、序列号和有效期

这说明续期链路是通的,不是只在第一次签发时成功。生产环境不会用 10 分钟有效期,改成 24 小时、renewBefore: 8h 更合适。

部署一个 nginx 和一个带 cert-manager 注解的 Ingress:

kubectl apply -f - <<'EOF'
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
  namespace: cert-test
spec:
  replicas: 1
  selector:
    matchLabels:
      app: myapp
  template:
    metadata:
      labels:
        app: myapp
    spec:
      containers:
        - name: nginx
          image: nginx:1.27-alpine
          ports:
            - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: myapp
  namespace: cert-test
spec:
  selector:
    app: myapp
  ports:
    - port: 80
      targetPort: 80
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: myapp
  namespace: cert-test
  annotations:
    cert-manager.io/cluster-issuer: step-ca-issuer
spec:
  ingressClassName: traefik
  tls:
    - hosts:
        - myapp.apps.homelab.internal
      secretName: tls-myapp
  rules:
    - host: myapp.apps.homelab.internal
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: myapp
                port:
                  number: 80
EOF

kubectl wait --for=condition=Ready certificate/tls-myapp -n cert-test --timeout=120s
kubectl get ingress,certificate -n cert-test

tls-myapp 变成 Ready=True 后,用 curl 验证 HTTPS:

sudo curl -sSI \
  --cacert /opt/step-ca/certs/root_ca.crt \
  --resolve myapp.apps.homelab.internal:443:10.31.0.141 \
  https://myapp.apps.homelab.internal/

实际返回 HTTP/2 200,说明 Traefik 已经加载了 cert-manager 生成的 Secret,TLS 握手和证书校验都通过:

Ingress 自动申请证书并通过 HTTPS 访问

把 cert-manager 的 metrics 端口转到本地,查三个关键指标:

kubectl -n cert-manager port-forward svc/cert-manager 9402:9402 >/dev/null 2>&1 &
sleep 2

curl -s localhost:9402/metrics \
  | grep -E '^certmanager_certificate_(expiration_timestamp_seconds|ready_status|renewal_timestamp_seconds)'

实际输出里能看到 test-cert、renew-test 和 tls-myapp 的过期时间、就绪状态和续期时间。ready_status{condition="True"} 为 1,condition="False" 为 0,和资源状态一致,指标截图见上一节。

项目 结果
step-ca 服务 systemd active (running),step ca health 返回 ok
ACME 账户 ClusterIssuer Ready=True,账户注册成功
首次签发 Certificate Ready=True,约 20 秒
证书链 Leaf → Intermediate CA → Root CA,SAN 正确
自动续期 revision 从 1 升到 3,序列号和有效期更新
Ingress 自动签发 tls-myapp Ready,HTTPS 返回 HTTP/2 200
Vault PKI vault-issuer Ready,vault-test 由 Vault Intermediate CA 签发,24 小时有效
监控指标 过期、就绪、续期三类指标均可抓取
告警链路 CertificateNotReady 进入 firing,Alertmanager 收到 active 告警
step-ca 吊销 mTLS 和 JWK token 两种方式均成功,序列号出现在 /1.0/crl
Vault 吊销 revocation_time 已写入,序列号出现在 Vault CRL

下面这些内容在本文里只作为方案说明,没有在这台 k3s VM 上完整部署:

  • Cloudflare API 的真实调用(需要域名和 API token);
  • SPIFFE/SPIRE 工作负载身份;
  • cert-manager CSI Driver 的证书挂载和轮换;
  • wildcard 证书的 DNS-01 流程(需要可编程 DNS)。

文中没有说明实测的部分按方案示例看待,不要直接当成已经在生产验证过的配置。


cert-manager 访问 step-ca 时最常见的错误。原因是 ClusterIssuer 没有配置 caBundle,或者 base64 内容不对。

# 确认 Root CA 路径
sudo ls -l /opt/step-ca/certs/root_ca.crt

# 重新生成 base64,注意不要带换行
CA_B64=$(sudo base64 -w0 /opt/step-ca/certs/root_ca.crt)
echo "$CA_B64" | head -c 80; echo

kubectl describe clusterissuer step-ca-issuer

ACME 的 HTTP-01 challenge 需要访问具体域名的 /.well-known/acme-challenge/<token>,wildcard 没有对应的主机名,所以只能走 DNS-01。cert-manager 的报错通常会出现在 Order 或 Challenge 的 message 里:

kubectl get order,challenge -n cert-test
kubectl describe challenge -n cert-test <challenge-name>

如果 renewBefore 大于等于证书的实际有效期,cert-manager 会认为证书一直处于“需要续期”的状态。先看证书的真实有效期:

kubectl get certificate -n cert-test renew-test -o jsonpath='{.status.notAfter}{"\n"}'

再对照 step-ca 的 provisioner 配置:

sudo step ca provisioner list \
  --ca-url=https://ca.homelab.internal:8443 \
  --root=/opt/step-ca/certs/root_ca.crt

把 renewBefore 调到实际有效期的一半左右,或者把 CA 的 defaultTLSCertDuration 调大。

如果直接在 CoreDNS 的 .override 文件里再写一个 hosts 块,CoreDNS 会报:

plugin/hosts: this plugin can only be used once per Server Block

因为 k3s 默认的 Corefile 里已经有一个 hosts /etc/coredns/NodeHosts。正确做法是给 homelab.internal 单独建一个 server block,放在 coredns-custom 的 .server 文件里:

apiVersion: v1
kind: ConfigMap
metadata:
  name: coredns-custom
  namespace: kube-system
data:
  homelab.server: |
    homelab.internal:53 {
      errors
      hosts {
        10.31.0.141 ca.homelab.internal test.apps.homelab.internal myapp.apps.homelab.internal
        fallthrough
      }
      forward . /etc/resolv.conf
    }

改完后重启 CoreDNS:

kubectl -n kube-system rollout restart deployment coredns

另外,k3s 会周期性地 reconcile coredns ConfigMap 的 NodeHosts,手工往里加记录可能过一会就消失。生产环境应该把记录放到自己的 DNS,而不是长期改 CoreDNS。

step ca root 需要验证 Root CA 的指纹。没有指纹时,它可能拒绝下载或者依赖系统信任库:

step ca root root_ca.crt \
  --ca-url=https://ca.homelab.internal:8443 \
  --fingerprint <root-ca-fingerprint>

指纹可以在 CA 初始化输出里找到,也可以在 CA 主机上执行:

step certificate fingerprint /opt/step-ca/certs/root_ca.crt

如果看到 permission denied 或 BadgerDB 打不开,检查 ProtectSystem=strict 下的 ReadWritePaths 是否包含 /opt/step-ca/db,以及目录属主是不是 step:step:

sudo systemctl status step-ca --no-pager
sudo journalctl -u step-ca -n 50 --no-pager
sudo ls -ld /opt/step-ca/db

删除 Certificate 或删除 Secret 不等于吊销。删除只是让 cert-manager 不再管理这个对象,已经签发的证书在有效期内仍然可以使用。真正的安全事故响应要在签发它的 CA 上吊销,并确认客户端会检查吊销状态。

step-ca 的 CRL 默认关闭。配置要放在 ca.json 的顶层,不要放进 authority:

{
  "crl": {
    "enabled": true,
    "generateOnRevoke": true,
    "cacheDuration": "24h"
  }
}

step-ca 文档里这个 CRL 功能仍标注为 experimental,上线前要在自己的客户端上验证兼容性。我第一次把 crl 写在 authority 下面,/1.0/crl 一直返回 404,日志里是 Certificate Revocation Lists are not enabled。移到顶层并重启 step-ca 后,CRL 端点才正常:

sudo systemctl restart step-ca

sudo curl -s --cacert /opt/step-ca/certs/root_ca.crt \
  https://ca.homelab.internal:8443/1.0/crl \
  -o /tmp/ca.crl

吊销时可以从 Secret 取出证书和私钥,用 mTLS 授权:

kubectl get secret -n cert-test revoke-test-tls -o jsonpath='{.data.tls\.crt}' \
  | base64 -d > /tmp/revoke-test.crt
kubectl get secret -n cert-test revoke-test-tls -o jsonpath='{.data.tls\.key}' \
  | base64 -d > /tmp/revoke-test.key

sudo step ca revoke \
  --cert=/tmp/revoke-test.crt \
  --key=/tmp/revoke-test.key \
  --ca-url=https://ca.homelab.internal:8443 \
  --root=/opt/step-ca/certs/root_ca.crt \
  --reason=KeyCompromise

也可以按序列号加 JWK token 吊销:

PROV=$(sudo step ca provisioner list \
  --ca-url=https://ca.homelab.internal:8443 \
  --root=/opt/step-ca/certs/root_ca.crt \
  | jq -r '.[] | select(.type=="JWK") | .name')

# step ca token --revoke 使用十进制序列号;openssl x509 -serial 输出的是十六进制
TOKEN=$(sudo step ca token <serial-number> --revoke \
  --ca-url=https://ca.homelab.internal:8443 \
  --root=/opt/step-ca/certs/root_ca.crt \
  --provisioner="$PROV" \
  --provisioner-password-file=/opt/step-ca/secrets/password.txt)

sudo step ca revoke <serial-number> \
  --token="$TOKEN" \
  --ca-url=https://ca.homelab.internal:8443 \
  --root=/opt/step-ca/certs/root_ca.crt \
  --reason=KeyCompromise

CRL 里能看到被吊销的序列号:

sudo openssl crl -inform DER -in /tmp/ca.crl -noout -text \
  | sed -n '/Revoked Certificates/,+6p'

step-ca 证书序列号出现在 /1.0/crl 的吊销列表里

这里有个容易忽略的限制:打开 CRL 服务不会自动把 CRL 分发地址写进新签发的证书。客户端必须显式配置 CRL URL,或者由应用自己检查;否则吊销只能阻止证书续期,不能阻止已签发证书在剩余有效期内继续使用。证书有效期越短,这个窗口越小。

Vault 的吊销更直接,按序列号写入 pki_int/revoke:

export VAULT_ADDR=https://vault.homelab.internal:8200
export VAULT_CACERT=/opt/vault/tls/root_ca.crt

SERIAL=$(vault list -format=json pki_int/certs | jq -r '.[0]')

vault write pki_int/revoke serial_number="$SERIAL"
vault read pki_int/cert/$SERIAL | grep -E 'revocation_time|state'

再拉 Vault 的 CRL 确认序列号已经进入吊销列表:

curl -s --cacert /opt/vault/tls/root_ca.crt \
  https://vault.homelab.internal:8200/v1/pki_int/crl/pem \
  | openssl crl -in /dev/stdin -noout -text \
  | sed -n '/Revoked Certificates/,+3p'

Vault PKI 的 revocation_time 和 CRL 记录

证书私钥泄露、主机被入侵或者 CA 私钥泄露,处理顺序不一样,但大方向一致:

  1. 确认范围:拿到证书序列号、私钥所在的 Secret 或主机、签发者和到期时间。openssl x509 -serial 和 CA 的签发日志都要看。
  2. 隔离:先停止使用这张证书的服务,删除对应的 Secret 或挂载,必要时在入口层阻断流量。不要一边吊销一边继续让旧私钥提供服务。
  3. 吊销:在签发 CA 上执行 revoke,记录 reason(私钥泄露用 KeyCompromise)和操作人。step-ca 和 Vault 都要保留吊销记录。
  4. 轮换:删除旧 Secret,让 cert-manager 重新签发;rotationPolicy: Always 可以保证每次续期都换私钥。如果怀疑签发 CA 本身泄露,就不只是换叶子证书,要轮换 Intermediate CA 甚至 Root CA,并重新分发信任链。
  5. 验证:确认 CRL 或 OCSP 里能查到旧序列号,确认客户端会拒绝旧证书,检查日志里是否还有旧序列号在活动。
  6. 复盘:检查 CA 日志、cert-manager Event、Kubernetes audit log,缩短证书有效期和 renewBefore,把同类告警补上。

几个配置上的注意事项:

  • allowRenewalAfterExpiry 生产环境应该设为 false,避免已过期证书继续续期;
  • 删除 Certificate 不会自动吊销,必须显式调用 CA 的 revoke;
  • 短期证书能缩小泄露窗口,但不能替代吊销流程;
  • Root CA 私钥尽量离线保存,日常签发只用 Intermediate CA;
  • 如果客户端完全不检查 CRL,吊销的效果有限,这时短期证书和快速轮换更重要。

阶段 建议
签发 内网服务用 24h 到 7d 的短期证书,减少泄露影响
存储 Kubernetes Secret 开启 etcd 加密;CA 私钥离线保存
分发 cert-manager 写 Secret,Ingress/Pod 自动挂载
续期 renewBefore 设为有效期的 1/3 到 1/2
监控 7 天预警,24 小时严重告警
轮换 需要换私钥时用 rotationPolicy: Always
  • Root CA 私钥离线保存,日常签发只用 Intermediate CA;
  • CA 服务只监听内网,ACME 端点不要直接暴露到公网;
  • 每个 Issuer 只允许必要的域名,Vault 的 role 用 allowed_domains 限制;
  • 打开 CA 和 cert-manager 的审计日志,至少保留签发、续期、失败记录;
  • 备份 Root CA、Intermediate CA、ca.json 和 db,恢复演练比备份本身更重要。
# 备份前先停服务,避免 BadgerDB 在写入过程中被打包
sudo systemctl stop step-ca

# 备份 step-ca 的证书、密钥、配置和数据库
sudo tar czf step-ca-backup.tar.gz \
  -C /opt step-ca/certs step-ca/secrets step-ca/config step-ca/db

sudo systemctl start step-ca

# 备份 cert-manager 的资源
kubectl get certificate,certificaterequest,issuer,clusterissuer -A -o yaml \
  > cert-manager-backup.yaml

# 备份 cert-manager 生成的 TLS Secret
kubectl get secrets -A -l cert-manager.io/certificate-name \
  -o yaml > tls-secrets-backup.yaml

恢复时先恢复 CA,再恢复 cert-manager 的 CRD 和资源,最后让 cert-manager 重新签发或续期。不要只备份 Secret 而不备份 CA 私钥,否则证书过期后无法续期。


这套链路现在跑在一台 4 vCPU 的 k3s 虚拟机上:step-ca 负责内网 CA,cert-manager 负责申请和续期,Vault PKI 负责需要独立审计和策略的证书,Traefik 从 Secret 加载证书,Prometheus/Alertmanager 负责指标和告警。实测覆盖了首次签发、自动续期、Ingress 注解签发、Vault 签发、告警链路,以及两套 CA 的吊销和 CRL 查询。

还有几件事值得继续做:

  • 给 wildcard 域名配 DNS-01,避免 HTTP-01 的限制;
  • 把 Vault 的审计和租期策略继续补全;
  • 在规模更大时引入 SPIFFE/SPIRE 或 cert-manager CSI Driver,减少对 Secret 的依赖。

证书管理不需要一开始就上最复杂的方案。先把 CA、Issuer、续期和告警跑通,再按服务的重要程度逐步加策略,维护成本会低很多。

参考资料