# 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 1. 访问 [DNSPod 控制台](https://console.dnspod.cn/account/token/token) 2. 创建 API Token（需要 DNS 记录管理权限） 3. 保存格式：`ID,Token` ### 第 2 步：执行部署 ```bash cd /Users/brunogao/work/codes/tools/macos/k8s/infra/cert-manager ./deploy.sh ``` 脚本会自动完成： - ✅ 检查 cert-manager 安装状态 - ✅ 配置 DNSPod API Token Secret - ✅ 部署 DNSPod Webhook - ✅ 创建 3 个 ClusterIssuers - ✅ 可选：测试证书签发 ### 第 3 步：验证部署 ```bash ./verify.sh ``` 预期输出： ``` ✓ 通过: 16 ✗ 失败: 0 ✓ 所有检查通过！cert-manager + DNSPod 部署正常 ``` ## 📝 使用方法 ### 方式 1: Ingress 自动签发（推荐） ```yaml 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: 手动创建证书 ```yaml 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 ```bash ./update-existing-ingress.sh ``` ## 🎯 ClusterIssuers 说明 | ClusterIssuer 名称 | 环境 | ACME 服务器 | 使用场景 | |-------------------|------|-------------|---------| | `dnspod-letsencrypt` | 生产 | Production | 正式环境（主推荐） | | `letsencrypt-prod` | 生产 | Production | 兼容旧配置 | | `letsencrypt-staging` | 测试 | Staging | 开发测试，避免速率限制 | ## 🔍 监控和管理 ### 查看证书状态 ```bash # 所有命名空间的证书 kubectl get certificates --all-namespaces # 证书详情 kubectl describe certificate -n # 实时监控 kubectl get certificates --all-namespaces -w ``` ### 查看签发进度 ```bash # 证书请求 kubectl get certificaterequest -n # DNS 验证挑战 kubectl get challenges -n # 查看日志 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 问题 **解决**: ```bash # 检查挑战状态 kubectl describe challenge -n # 检查 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 小时 **解决**: ```bash # 使用 staging 环境测试 kubectl annotate certificate \ cert-manager.io/cluster-issuer=letsencrypt-staging \ --overwrite -n ``` ### 问题 3: DNSPod API Token 失效 **解决**: ```bash # 更新 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 ``` ## 📊 当前环境状态 ### 已发现的配置 ```bash # 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` ## 🎯 下一步操作 ### 立即执行 ```bash # 1. 部署方案 cd /Users/brunogao/work/codes/tools/macos/k8s/infra/cert-manager ./deploy.sh # 2. 验证部署 ./verify.sh # 3. 更新现有 Ingress（可选） ./update-existing-ingress.sh ``` ### 验证成功后 1. **监控首次签发** ```bash kubectl get certificate monitor-tls -n observability -w ``` 2. **检查证书详情** ```bash kubectl describe certificate monitor-tls -n observability ``` 3. **验证 HTTPS 访问** ```bash curl -I https://monitor.omniverseai.net ``` ## 📚 文档导航 | 文档 | 用途 | 适用场景 | |------|------|---------| | `README.md` | 完整技术文档 | 深入了解、故障排查、最佳实践 | | `DEPLOY-GUIDE.md` | 快速部署指南 | 首次部署、日常操作、命令速查 | | `CERT-MANAGER-SOLUTION.md` | 方案总览（本文档） | 架构理解、整体把握 | ## 🔐 安全建议 1. **保护 DNSPod API Token** - ✅ 使用 Kubernetes Secret 存储 - ✅ 限制 RBAC 权限 - ✅ 定期轮换 Token 2. **证书访问控制** - ✅ 使用 NetworkPolicy 限制访问 - ✅ 分离不同环境的证书 3. **监控和告警** - ✅ 证书即将过期告警（< 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