Cert-Manager K8S SSL 证书管理教程

Cert-Manager 是 Kubernetes 集群中最流行的证书管理控制器，能够自动从 Let's Encrypt、HashiCorp Vault 等多种来源申请和续期 SSL/TLS 证书。它将证书管理完全融入 Kubernetes 的声明式工作流，让 SSL 证书的生命周期管理变得自动化和透明。本文将介绍如何在搬瓦工 VPS 上的 K8S 集群中部署和使用 Cert-Manager。

一、前置条件

Kubernetes 集群：已部署的 K8S 集群（可以是 K3s、MicroK8s 等轻量方案）。
kubectl：已配置并可以访问集群。
Helm 3：推荐使用 Helm 安装 Cert-Manager。
Ingress Controller：如 Nginx Ingress 或 Traefik。
域名：已指向搬瓦工 VPS IP 的域名。

如果尚未购买 VPS，可以参考搬瓦工全部方案选购，使用优惠码 NODESEEK2026 享受 6.77% 折扣。

二、安装 Cert-Manager

2.1 使用 Helm 安装

# 添加 Jetstack Helm 仓库
helm repo add jetstack https://charts.jetstack.io
helm repo update

# 安装 Cert-Manager
helm install cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --create-namespace \
  --set crds.enabled=true

2.2 使用 kubectl 安装

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/latest/download/cert-manager.yaml

2.3 验证安装

kubectl get pods -n cert-manager
kubectl get crd | grep cert-manager

确认三个 Pod（cert-manager、cert-manager-cainjector、cert-manager-webhook）都处于 Running 状态。

三、配置 Issuer

Issuer 定义了证书的来源和验证方式。有两种类型：Issuer（命名空间级别）和 ClusterIssuer（集群级别）。

3.1 Let's Encrypt Staging Issuer（测试用）

cat << 'EOF' | kubectl apply -f -
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-staging
spec:
  acme:
    server: https://acme-staging-v02.api.letsencrypt.org/directory
    email: your@email.com
    privateKeySecretRef:
      name: letsencrypt-staging-key
    solvers:
    - http01:
        ingress:
          class: nginx
EOF

3.2 Let's Encrypt Production Issuer

cat << 'EOF' | kubectl apply -f -
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: your@email.com
    privateKeySecretRef:
      name: letsencrypt-prod-key
    solvers:
    - http01:
        ingress:
          class: nginx
EOF

3.3 DNS01 验证（支持通配符证书）

# 先创建 Cloudflare API Token Secret
kubectl create secret generic cloudflare-api-token \
  --namespace cert-manager \
  --from-literal=api-token=YOUR_CF_API_TOKEN

cat << 'EOF' | kubectl apply -f -
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-dns
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: your@email.com
    privateKeySecretRef:
      name: letsencrypt-dns-key
    solvers:
    - dns01:
        cloudflare:
          apiTokenSecretRef:
            name: cloudflare-api-token
            key: api-token
EOF

3.4 检查 Issuer 状态

kubectl get clusterissuer
kubectl describe clusterissuer letsencrypt-prod

四、申请证书

4.1 通过 Certificate 资源申请

cat << 'EOF' | kubectl apply -f -
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: example-com-tls
  namespace: default
spec:
  secretName: example-com-tls-secret
  issuerRef:
    name: letsencrypt-prod
    kind: ClusterIssuer
  dnsNames:
  - example.com
  - www.example.com
EOF

4.2 通过 Ingress 注解自动申请

cat << 'EOF' | kubectl apply -f -
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ingress
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
spec:
  tls:
  - hosts:
    - example.com
    - www.example.com
    secretName: example-com-tls-secret
  rules:
  - host: example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: my-service
            port:
              number: 80
EOF

4.3 申请通配符证书

cat << 'EOF' | kubectl apply -f -
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: wildcard-example-com
  namespace: default
spec:
  secretName: wildcard-example-com-tls
  issuerRef:
    name: letsencrypt-dns
    kind: ClusterIssuer
  dnsNames:
  - example.com
  - "*.example.com"
EOF

五、查看证书状态

# 查看证书列表
kubectl get certificates

# 查看证书详情
kubectl describe certificate example-com-tls

# 查看证书签发请求
kubectl get certificaterequests

# 查看 ACME 验证状态
kubectl get challenges
kubectl get orders

# 查看证书 Secret
kubectl get secret example-com-tls-secret -o yaml

六、自动续期

Cert-Manager 默认在证书到期前 30 天自动续期。可以通过 Certificate 资源自定义续期策略：

spec:
  renewBefore: 720h  # 到期前 30 天续期
  duration: 2160h    # 证书有效期 90 天

七、故障排查

# 查看 Cert-Manager 日志
kubectl logs -n cert-manager deployment/cert-manager -f

# 查看证书事件
kubectl describe certificate example-com-tls

# 查看 Challenge 状态
kubectl describe challenge -l cert-manager.io/certificate-name=example-com-tls

# 常见问题检查清单
kubectl get clusterissuer -o wide
kubectl get certificate -o wide
kubectl get certificaterequest -o wide
kubectl get order -o wide
kubectl get challenge -o wide

八、常见问题

证书一直处于 Pending 状态

检查 Issuer 配置和 Challenge 状态，确保 HTTP01 验证可以从外网访问到 Ingress 控制器。

DNS01 验证失败

确认 DNS API 凭据正确，并且 API Token 有修改 DNS 记录的权限。

速率限制

先使用 staging Issuer 测试，确认无误后再切换到 production。Let's Encrypt 的 production 环境有严格的速率限制。

总结

Cert-Manager 让 Kubernetes 环境中的 SSL 证书管理变得完全自动化，通过声明式配置即可实现证书的申请、安装和续期。对于非 K8S 环境，可以使用 acme.sh 管理 SSL 证书。选购搬瓦工 VPS 请查看全部方案，使用优惠码 NODESEEK2026 可享受折扣。相关问题可通过搬瓦工官网提交工单咨询。