gao/ljwx-k8s

Fork 0

Files

T

bruno 2a56d7fd6c first commit

2026-02-20 22:50:45 +08:00

13 KiB

Raw Permalink Blame History

Kubernetes 证书管理完善方案

📋 方案概览

已完成基于 cert-manager + DNSPod DNS-01 的自动化证书管理方案部署配置。

✨ 核心特性

特性	说明
🤖 全自动化	证书自动签发、自动续期，无需人工干预
💰 零成本	Let's Encrypt 免费 SSL/TLS 证书
🔒 高安全	DNS-01 验证，支持通配符证书
⏰ 智能续期	证书有效期 90 天，提前 30 天自动续期
🌐 灵活配置	支持单域名、多域名、通配符域名

🏗️ 技术架构

┌───────────────────────────────────────────────────────────────────────┐
│                      Kubernetes Cluster                                │
│                                                                         │
│  ┌──────────────┐          ┌─────────────────────┐                   │
│  │   Ingress    │──────────▶│   Certificate       │                   │
│  │  Resources   │          │   (证书资源)         │                   │
│  └──────────────┘          └──────────┬──────────┘                   │
│                                        │                               │
│                          ┌─────────────▼─────────────┐                │
│                          │   cert-manager Controller │                │
│                          │   (核心控制器)             │                │
│                          └─────────────┬─────────────┘                │
│                                        │                               │
│              ┌─────────────────────────┼─────────────────────┐        │
│              │                         │                     │        │
│    ┌─────────▼────────┐   ┌──────────▼────────┐   ┌───────▼───────┐│
│    │ ClusterIssuers   │   │  DNSPod Webhook   │   │    Secrets    ││
│    │ - dnspod-le      │   │  (DNS-01 验证)     │   │ - API Token   ││
│    │ - letsencrypt-*  │   │                   │   │ - 证书存储    ││
│    └─────────┬────────┘   └──────────┬────────┘   └───────────────┘│
│              │                        │                               │
└──────────────┼────────────────────────┼───────────────────────────────┘
               │                        │
               │                        │
      ┌────────▼──────────┐    ┌───────▼──────────────┐
      │  Let's Encrypt    │    │    DNSPod API        │
      │  ACME Server      │    │  (腾讯云 DNS 服务)    │
      │  (证书颁发机构)    │    │                      │
      └───────────────────┘    └──────────────────────┘

📂 文件结构

infra/cert-manager/
├── README.md                          # 完整技术文档（13KB）
│   ├── 架构说明
│   ├── 配置参数详解
│   ├── 监控和维护指南
│   ├── 故障排查手册
│   └── 安全最佳实践
│
├── DEPLOY-GUIDE.md                   # 快速部署指南（10KB）
│   ├── 3 分钟快速开始
│   ├── 部署步骤详解
│   ├── 使用示例
│   ├── 监控命令
│   └── 故障排查
│
├── deploy.sh                         # 一键部署脚本（5KB）
│   ├── 自动检查环境
│   ├── 配置 DNSPod Token
│   ├── 部署所有组件
│   └── 交互式引导
│
├── verify.sh                         # 部署验证脚本（7KB）
│   ├── 检查 cert-manager 组件
│   ├── 验证 DNSPod 集成
│   ├── 测试 ClusterIssuers
│   └── 生成验证报告
│
├── update-existing-ingress.sh       # Ingress 更新工具（2KB）
│   ├── 批量更新现有 Ingress
│   └── 自动触发证书重新签发
│
├── dnspod-secret.yaml               # DNSPod API Token 模板
├── dnspod-webhook-deployment.yaml   # DNSPod Webhook 部署配置（5KB）
├── clusterissuer-dnspod.yaml        # ClusterIssuer 配置（2KB）
└── test-certificate.yaml            # 测试证书示例

🚀 快速部署（3 步完成）

第 1 步：准备 DNSPod API Token

访问 DNSPod 控制台
创建 API Token（需要 DNS 记录管理权限）
保存格式：ID,Token

第 2 步：执行部署

cd /Users/brunogao/work/codes/tools/macos/k8s/infra/cert-manager
./deploy.sh

脚本会自动完成：

✅ 检查 cert-manager 安装状态
✅ 配置 DNSPod API Token Secret
✅ 部署 DNSPod Webhook
✅ 创建 3 个 ClusterIssuers
✅ 可选：测试证书签发

第 3 步：验证部署

./verify.sh

预期输出：

✓ 通过: 16
✗ 失败: 0

✓ 所有检查通过！cert-manager + DNSPod 部署正常

📝 使用方法

方式 1: Ingress 自动签发（推荐）

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: myapp
  annotations:
    # 关键：指定 ClusterIssuer
    cert-manager.io/cluster-issuer: dnspod-letsencrypt
spec:
  tls:
  - hosts:
    - myapp.example.com
    secretName: myapp-tls  # 自动创建
  rules:
  - host: myapp.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: myapp-service
            port:
              number: 80

方式 2: 手动创建证书

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: wildcard-cert
  namespace: default
spec:
  secretName: wildcard-tls
  issuerRef:
    name: dnspod-letsencrypt
    kind: ClusterIssuer
  commonName: "*.example.com"
  dnsNames:
  - "*.example.com"
  - example.com

方式 3: 更新现有 Ingress

./update-existing-ingress.sh

🎯 ClusterIssuers 说明

ClusterIssuer 名称	环境	ACME 服务器	使用场景
`dnspod-letsencrypt`	生产	Production	正式环境（主推荐）
`letsencrypt-prod`	生产	Production	兼容旧配置
`letsencrypt-staging`	测试	Staging	开发测试，避免速率限制

🔍 监控和管理

查看证书状态

# 所有命名空间的证书
kubectl get certificates --all-namespaces

# 证书详情
kubectl describe certificate <name> -n <namespace>

# 实时监控
kubectl get certificates --all-namespaces -w

查看签发进度

# 证书请求
kubectl get certificaterequest -n <namespace>

# DNS 验证挑战
kubectl get challenges -n <namespace>

# 查看日志
kubectl logs -n cert-manager -l app=cert-manager -f
kubectl logs -n cert-manager -l app=cert-manager-webhook-dnspod -f

证书状态解读

Ready	Issuing	状态说明	预计时间
True	-	✅ 证书已签发	-
False	True	🔄 正在签发中	1-5 分钟
False	False	❌ 签发失败	需要排查

🛠️ 证书自动续期机制

续期策略

证书有效期: 90 天（Let's Encrypt 标准）
续期触发时间: 到期前 30 天
检查频率: 每 24 小时
自动化程度: 100%，无需人工干预

续期流程

Day 0                Day 60               Day 90
  │                    │                    │
  ├─ 证书签发          ├─ 自动续期触发      ├─ 旧证书过期
  │                    │                    │
  │                    ├─ 创建新请求        │
  │                    ├─ DNS-01 验证       │
  │                    ├─ 获取新证书        │
  │                    └─ 更新 Secret      │
  │                                         │
  └────────────────────┴─────────────────────┘
       正常使用期          自动续期窗口

⚠️ 常见问题和解决方案

问题 1: 证书一直处于 Issuing 状态

原因: DNS 记录传播延迟或 DNSPod API 问题

解决:

# 检查挑战状态
kubectl describe challenge <challenge-name> -n <namespace>

# 检查 DNSPod Webhook 日志
kubectl logs -n cert-manager -l app=cert-manager-webhook-dnspod --tail=50

# 手动验证 DNS TXT 记录
dig TXT _acme-challenge.example.com

问题 2: Let's Encrypt 速率限制

限制说明:

每个域名: 50 个证书/周
每个账户: 300 个新订单/3 小时

解决:

# 使用 staging 环境测试
kubectl annotate certificate <name> \
  cert-manager.io/cluster-issuer=letsencrypt-staging \
  --overwrite -n <namespace>

问题 3: DNSPod API Token 失效

解决:

# 更新 Secret
kubectl delete secret dnspod-api-token -n cert-manager
kubectl create secret generic dnspod-api-token \
  --from-literal=api-token="NEW_ID,NEW_TOKEN" \
  -n cert-manager

# 重启 Webhook
kubectl rollout restart deployment cert-manager-webhook-dnspod -n cert-manager

📊 当前环境状态

已发现的配置

# cert-manager 组件状态
NAME                                       READY   STATUS    RESTARTS   AGE
cert-manager-776494b6cf-j9fst              1/1     Running   1          2d18h
cert-manager-cainjector-6cf76fc759-wlhpl   1/1     Running   1          2d18h
cert-manager-webhook-7bfbfdc97c-mcr4q      1/1     Running   1          2d18h

# 现有证书
NAMESPACE       NAME          READY   SECRET        AGE
observability   monitor-tls   False   monitor-tls   2d18h

待处理

⏳ ClusterIssuers 未创建: 需要运行 ./deploy.sh 创建
⏳ DNSPod Webhook 未部署: 需要部署 webhook 组件
⏳ monitor-tls 证书未签发: 当前引用不存在的 letsencrypt-prod

🎯 下一步操作

立即执行

# 1. 部署方案
cd /Users/brunogao/work/codes/tools/macos/k8s/infra/cert-manager
./deploy.sh

# 2. 验证部署
./verify.sh

# 3. 更新现有 Ingress（可选）
./update-existing-ingress.sh

验证成功后

监控首次签发

kubectl get certificate monitor-tls -n observability -w

检查证书详情

kubectl describe certificate monitor-tls -n observability

验证 HTTPS 访问

curl -I https://monitor.omniverseai.net

📚 文档导航

文档	用途	适用场景
`README.md`	完整技术文档	深入了解、故障排查、最佳实践
`DEPLOY-GUIDE.md`	快速部署指南	首次部署、日常操作、命令速查
`CERT-MANAGER-SOLUTION.md`	方案总览（本文档）	架构理解、整体把握

🔐 安全建议

保护 DNSPod API Token
- ✅ 使用 Kubernetes Secret 存储
- ✅ 限制 RBAC 权限
- ✅ 定期轮换 Token
证书访问控制
- ✅ 使用 NetworkPolicy 限制访问
- ✅ 分离不同环境的证书
监控和告警
- ✅ 证书即将过期告警（< 30 天）
- ✅ 证书续期失败告警
- ✅ cert-manager 组件健康检查

📞 技术支持

部署问题: 查看 DEPLOY-GUIDE.md 故障排查章节
配置问题: 参考 README.md 配置说明
日志查看: kubectl logs -n cert-manager -l app=cert-manager
官方文档: https://cert-manager.io/docs/

✅ 方案优势总结

维度	传统方式	本方案
自动化	手动申请和更新	100% 自动化
成本	需购买证书	免费
续期	人工介入	自动提前 30 天
安全性	依赖人工流程	DNS-01 验证，支持通配符
维护成本	高（定期人工操作）	低（仅监控）
灵活性	受限	支持多域名、通配符

方案完成时间: 2025-12-20 技术栈: cert-manager v1.13+ / Let's Encrypt / DNSPod / Kubernetes 文档版本: v1.0.0

13 KiB Raw Permalink Blame History Unescape Escape