zetaloop
416 lines
24 KiB
Markdown
416 lines
24 KiB
Markdown
# 部署流程图和时间线
|
||
|
||
## 部署架构流程图
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────────────┐
|
||
│ JWT 认证系统部署流程 │
|
||
└──────────────────────────────────────────────────────────────────┘
|
||
|
||
┌─────────────────────────────────────────────────────────────────────┐
|
||
│ Phase 1: 前置检查 (5分钟) │
|
||
├─────────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ ✓ Kubernetes 集群版本 >= 1.24 │
|
||
│ ✓ kubectl 已配置，可访问集群 │
|
||
│ ✓ juwan namespace 已存在 │
|
||
│ ✓ redis-operator CRD 已安装 │
|
||
│ ✓ 集群管理员权限（用于 ETCD 加密） │
|
||
│ │
|
||
│ 命令检查: │
|
||
│ $ kubectl cluster-info │
|
||
│ $ kubectl get ns juwan │
|
||
│ $ kubectl get crd redisclusters.redis.redis.opstreelabs.in │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────────────┐
|
||
│ Phase 2: 创建 Secret 和 RBAC (5分钟) ⚡ 必需 │
|
||
├─────────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ 执行: │
|
||
│ $ kubectl apply -f deploy/k8s/secrets/jwt-secret.yaml │
|
||
│ │
|
||
│ 创建的资源: │
|
||
│ ✓ Secret: jwt-secret (包含 JWT 秘钥) │
|
||
│ ✓ ServiceAccount: user-rpc │
|
||
│ ✓ ServiceAccount: envoy-gateway │
|
||
│ ✓ Role: jwt-secret-reader (只读权限) │
|
||
│ ✓ RoleBinding: jwt-secret-reader-user-rpc │
|
||
│ ✓ RoleBinding: jwt-secret-reader-envoy-gateway │
|
||
│ │
|
||
│ 验证: │
|
||
│ $ kubectl get secret jwt-secret -n juwan │
|
||
│ $ kubectl get sa -n juwan | grep -E "user-rpc|envoy" │
|
||
│ $ kubectl get role -n juwan │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────────────┐
|
||
│ Phase 3: 更新 Deployments (10分钟) ⚡ 必需 │
|
||
├─────────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ Step 3a: 更新 user-rpc Deployment │
|
||
│ 执行: │
|
||
│ $ kubectl apply -f deploy/k8s/service/user/user-rpc.yaml │
|
||
│ │
|
||
│ 变更: │
|
||
│ - serviceAccountName: user-rpc (绑定权限) │
|
||
│ - env.JWT_SECRET_KEY (从 Secret 挂载) │
|
||
│ - 保持 Redis Cluster 配置 │
|
||
│ │
|
||
│ 等待 Pods 启动: │
|
||
│ $ kubectl rollout status deployment/user-rpc -n juwan │
|
||
│ │
|
||
│ --- │
|
||
│ │
|
||
│ Step 3b: 更新 Envoy Gateway Deployment │
|
||
│ 执行: │
|
||
│ $ kubectl apply -f deploy/k8s/envoy/envoy.yaml │
|
||
│ │
|
||
│ 变更: │
|
||
│ - serviceAccountName: envoy-gateway (绑定权限) │
|
||
│ - 保持 CSRF Lua 防护配置 │
|
||
│ │
|
||
│ 等待 Pods 启动: │
|
||
│ $ kubectl rollout status deployment/envoy-gateway -n juwan │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────────────┐
|
||
│ Phase 4: 验证部署 (15分钟) ⚡ 必需 │
|
||
├─────────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ 检查清单: │
|
||
│ │
|
||
│ 1️⃣ Secret 和权限验证 │
|
||
│ $ kubectl get secret jwt-secret -n juwan │
|
||
│ $ kubectl get role jwt-secret-reader -n juwan │
|
||
│ $ kubectl get rolebinding -n juwan | grep jwt-secret │
|
||
│ │
|
||
│ 2️⃣ 权限测试 │
|
||
│ $ kubectl auth can-i get secrets \ │
|
||
│ --as=system:serviceaccount:juwan:user-rpc \ │
|
||
│ --resource-name=jwt-secret -n juwan │
|
||
│ 预期: yes │
|
||
│ │
|
||
│ 3️⃣ Pods 运行状态 │
|
||
│ $ kubectl get pods -n juwan -l app=user-rpc │
|
||
│ $ kubectl get pods -n juwan -l app=envoy-gateway │
|
||
│ 预期: 3 个 user-rpc Pods + 1 个 envoy-gateway Pod 都在 Running │
|
||
│ │
|
||
│ 4️⃣ 环境变量验证 │
|
||
│ $ kubectl exec -it <user-rpc-pod> -n juwan -- env | grep JWT │
|
||
│ 预期: JWT_SECRET_KEY=... │
|
||
│ │
|
||
│ 5️⃣ Redis 连接验证 │
|
||
│ $ kubectl run redis-cli --image=redis:latest --rm -it \ │
|
||
│ -- redis-cli -h user-redis.juwan:6379 PING │
|
||
│ 预期: PONG │
|
||
│ │
|
||
│ 详见: VERIFICATION.md 第1-8部分 │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────────────────┘
|
||
│
|
||
├─────────── 生产环境额外步骤 ──────────────┐
|
||
│ │
|
||
▼ ▼
|
||
┌──────────────────────────┐ ┌─────────────────────────────────────┐
|
||
│ Phase 5a: 应用集成 │ │ Phase 5b: 启用 ETCD 加密 (30分钟) │
|
||
│ (2-3 小时) ⚠️ 推荐 │ │ ⚠️ 生产推荐，需集群管理员权限 │
|
||
├──────────────────────────┤ ├─────────────────────────────────────┤
|
||
│ │ │ │
|
||
│ 实施内容: │ │ 前提条件: │
|
||
│ ✓ gRPC Interceptor │ │ ✓ Control Plane 节点访问权限 │
|
||
│ ✓ Login/Logout Handler │ │ ✓ ETCD 备份已创建 │
|
||
│ ✓ JWT Middleware │ │ ✓ 加密密钥已生成 │
|
||
│ ✓ Token Refresh Logic │ │ │
|
||
│ ✓ Error Handling │ │ 步骤: │
|
||
│ ✓ Unit Tests │ │ 1. 生成 32 字节密钥 │
|
||
│ │ │ $ head -c 32 /dev/urandom | base64
|
||
│ 参考: │ │ │
|
||
│ INTEGRATION.md │ │ 2. 创建加密配置文件 │
|
||
│ │ │ /etc/kubernetes/encryption-config.yaml
|
||
│ 时间估计: │ │ │
|
||
│ - gRPC 拦截器: 30分钟 │ │ 3. 修改 kube-apiserver manifest │
|
||
│ - Handlers: 60分钟 │ │ 添加密钥路径和卷挂载 │
|
||
│ - Middleware: 30分钟 │ │ │
|
||
│ - 测试: 60分钟 │ │ 4. 重启 kube-apiserver │
|
||
│ │ │ kubelet 自动重启 │
|
||
│ │ │ │
|
||
│ │ │ 5. 验证加密已启用 │
|
||
│ │ │ kubectl create secret generic ... │
|
||
│ │ │ 检查 ETCD 中的数据是否加密 │
|
||
│ │ │ │
|
||
│ │ │ 详见: ENCRYPTION.md (8个部分) │
|
||
│ │ │ 验证: VERIFICATION.md 第9部分 │
|
||
│ │ │ │
|
||
└──────────────────────────┘ └─────────────────────────────────────┘
|
||
│ │
|
||
└───────────────────┬─────────────────────┘
|
||
│
|
||
▼
|
||
┌──────────────────────────────────────────┐
|
||
│ Phase 6: 完成 ✅ │
|
||
├──────────────────────────────────────────┤
|
||
│ │
|
||
│ 最终检查: │
|
||
│ ✓ 所有 Pods 运行正常 │
|
||
│ ✓ RBAC 权限已验证 │
|
||
│ ✓ JWT 功能已集成 │
|
||
│ ✓ 日志和监控已配置 │
|
||
│ ✓ (可选) ETCD 加密已启用 │
|
||
│ │
|
||
│ 生产推荐: │
|
||
│ ✓ 启用审计日志 │
|
||
│ ✓ 配置密钥轮换计划（季度） │
|
||
│ ✓ 备份密钥到安全位置 │
|
||
│ ✓ 配置告警和监控 │
|
||
│ │
|
||
└──────────────────────────────────────────┘
|
||
```
|
||
|
||
## 时间估计和路径
|
||
|
||
```
|
||
推荐部署路径
|
||
═════════════════════════════════════════════════════════════════
|
||
|
||
🚀 最快路径 (30 分钟) - 开发环境
|
||
────────────────────────────────────────────────────────────────
|
||
Phase 1: 前置检查 ⏱️ 5 分钟
|
||
Phase 2: 创建 Secret 和 RBAC ⏱️ 5 分钟
|
||
Phase 3: 更新 Deployments ⏱️ 10 分钟
|
||
Phase 4: 验证部署 ⏱️ 10 分钟
|
||
────────────────────────────────────────────────────────────────
|
||
总计: 30 分钟
|
||
|
||
|
||
📊 默认路径 (75 分钟) - 测试环境
|
||
────────────────────────────────────────────────────────────────
|
||
Phase 1-4: 如上 ⏱️ 30 分钟
|
||
Phase 5a: 应用集成（简单版） ⏱️ 45 分钟
|
||
────────────────────────────────────────────────────────────────
|
||
总计: 75 分钟
|
||
|
||
|
||
🏆 完整路径 (3.5-4 小时) - 生产环境
|
||
────────────────────────────────────────────────────────────────
|
||
Phase 1-4: 如上 ⏱️ 30 分钟
|
||
Phase 5a: 应用集成（完整版） ⏱️ 2-3 小时
|
||
Phase 5b: ETCD 加密配置 ⏱️ 30 分钟
|
||
────────────────────────────────────────────────────────────────
|
||
总计: 3.5-4 小时
|
||
|
||
|
||
📚 学习路径 (6-8 小时) - 从零开始理解
|
||
────────────────────────────────────────────────────────────────
|
||
文档阅读 (SUMMARY + DEPLOYMENT + INTEGRATION) ⏱️ 1-2 小时
|
||
完整路径部署 ⏱️ 3.5-4 小时
|
||
验证和测试 ⏱️ 1-2 小时
|
||
────────────────────────────────────────────────────────────────
|
||
总计: 6-8 小时
|
||
```
|
||
|
||
## 并行和串行步骤
|
||
|
||
```
|
||
可以并行执行的任务
|
||
═════════════════════════════════════════════════════════════════
|
||
|
||
┌─────────────────────────────────┐
|
||
│ 应用集成 (Phase 5a) │ ────┐
|
||
├─────────────────────────────────┤ │ 可选，独立
|
||
│ • gRPC interceptor │ │ 进行
|
||
│ • REST middleware │ │
|
||
│ • Handler 实现 │ │
|
||
│ • 单元测试 │ │
|
||
└─────────────────────────────────┘ │
|
||
├─ 与 Phase 2-4 并行
|
||
│
|
||
┌─────────────────────────────────┐ │
|
||
│ ETCD 加密 (Phase 5b) │ ────┘
|
||
├─────────────────────────────────┤ │ 需要集群管理员
|
||
│ • 生成密钥（可单独进行） │ │ 权限，在
|
||
│ • 创建配置文件 │ │ Control Plane
|
||
│ • 修改 kube-apiserver │ │ 节点执行
|
||
│ • 重启 API server │ │
|
||
└─────────────────────────────────┘────┘
|
||
|
||
|
||
必须串行执行的步骤
|
||
═════════════════════════════════════════════════════════════════
|
||
|
||
Phase 1 → Phase 2 → Phase 3 → Phase 4 → (Phase 5a + Phase 5b)
|
||
|
||
↓ ↓ ↓ ↓
|
||
前置检查 创建资源 部署应用 验证完整 可选扩展功能
|
||
|
||
• Phase 2 必须在 Phase 1 之后（需要 namespace）
|
||
• Phase 3 必须在 Phase 2 之后（需要 RoleBinding）
|
||
• Phase 4 必须在 Phase 3 之后（需要 Pods 启动）
|
||
• Phase 5a/5b 可在 Phase 4 完成后并行进行
|
||
```
|
||
|
||
## 关键时间点
|
||
|
||
```
|
||
事件时间线
|
||
═════════════════════════════════════════════════════════════════
|
||
|
||
T+0 Phase 1: 验证前置条件
|
||
└─ 预计 5 分钟
|
||
|
||
T+5 Phase 2: kubectl apply jwt-secret.yaml
|
||
└─ 预计 1 分钟执行，5 分钟验证
|
||
|
||
T+11 Phase 3a: kubectl apply user-rpc.yaml
|
||
└─ 3 个 Pods 启动（滚动更新）
|
||
└─ 预计 ~3 分钟（取决于镜像拉取）
|
||
|
||
T+14 Phase 3b: kubectl apply envoy.yaml
|
||
└─ 1 个 Pod 启动
|
||
└─ 预计 ~2 分钟
|
||
|
||
T+16 Phase 4: 执行完整验证检查
|
||
└─ 12 个验证部分，共 ~15 分钟
|
||
|
||
T+31 ✅ 基础部署完成
|
||
|
||
T+31 (可选) Phase 5a: 应用代码集成
|
||
到 └─ 2-3 小时编码和测试
|
||
T+211
|
||
|
||
T+31 (可选) Phase 5b: ETCD 加密
|
||
到 └─ 30 分钟配置
|
||
T+61
|
||
|
||
T+211 或 T+61 🎉 全部完成
|
||
(取决于是否执行 Phase 5)
|
||
```
|
||
|
||
## 推荐的部署顺序
|
||
|
||
### 对于 DevOps/SRE
|
||
|
||
```
|
||
优先级顺序:
|
||
|
||
1️⃣ Phase 1-4 (核心部署) [必需]
|
||
└─ 时间: 30 分钟
|
||
|
||
2️⃣ Phase 5b (ETCD 加密) [生产强烈推荐]
|
||
└─ 时间: 30 分钟
|
||
└─ 开始时间: T+16 之前 (与 Phase 4 并行)
|
||
|
||
3️⃣ 密钥备份和恢复计划 [重要]
|
||
└─ 时间: 15 分钟
|
||
└─ 参考: DEPLOYMENT.md 灾难恢复
|
||
|
||
4️⃣ Phase 5a 支持 [当开发完成时]
|
||
└─ 协助开发团队集成 JWT
|
||
└─ 参考: INTEGRATION.md
|
||
```
|
||
|
||
### 对于应用开发者
|
||
|
||
```
|
||
优先级顺序:
|
||
|
||
1️⃣ 了解系统架构 [了解背景]
|
||
└─ 文档: SUMMARY.md
|
||
└─ 时间: 10 分钟
|
||
|
||
2️⃣ Phase 5a: 代码集成 [并行进行]
|
||
└─ 参考: INTEGRATION.md
|
||
└─ 时间: 2-3 小时
|
||
|
||
3️⃣ 单元测试 [在开发中]
|
||
└─ 参考: INTEGRATION.md 第 9 部分
|
||
└─ 时间: 1 小时
|
||
|
||
4️⃣ 集成测试 [与运维协调]
|
||
└─ 测试完整流程
|
||
└─ 时间: 1-2 小时
|
||
```
|
||
|
||
## 回滚应急步骤
|
||
|
||
如果部署失败，可以快速回滚：
|
||
|
||
```
|
||
紧急回滚
|
||
═════════════════════════════════════════════════════════════════
|
||
|
||
如果 Phase 2 (Secret) 失败:
|
||
→ kubectl delete secret jwt-secret -n juwan
|
||
→ kubectl delete sa user-rpc envoy-gateway -n juwan
|
||
→ kubectl delete role jwt-secret-reader -n juwan
|
||
→ 修正配置后重新应用
|
||
|
||
如果 Phase 3 (Deployment) 失败:
|
||
→ kubectl rollout undo deployment/user-rpc -n juwan
|
||
→ kubectl rollout undo deployment/envoy-gateway -n juwan
|
||
→ 或删除部署并使用稳定的旧版本重新部署
|
||
|
||
如果 Phase 5b (ETCD 加密) 失败:
|
||
→ 从 kube-apiserver 清单中移除加密参数
|
||
→ 重启 kube-apiserver
|
||
→ 删除 /etc/kubernetes/encryption-config.yaml
|
||
→ 从最近的 ETCD 备份恢复（如果需要）
|
||
|
||
注意: 备份是关键！每次重大操作前都应备份。
|
||
```
|
||
|
||
## 部署检查点 (Go/No-Go)
|
||
|
||
```
|
||
关键检查点
|
||
═════════════════════════════════════════════════════════════════
|
||
|
||
✅ Checkpoint 1 (Phase 2 后)
|
||
- Secret 已创建
|
||
- ServiceAccounts 已创建
|
||
- Go → 继续 Phase 3
|
||
- No-Go → 检查 kubectl 权限
|
||
|
||
✅ Checkpoint 2 (Phase 3 后)
|
||
- Pods 已启动 (Running)
|
||
- No PodSchedulingFailure
|
||
- Go → 继续 Phase 4
|
||
- No-Go → 检查资源限制和镜像拉取
|
||
|
||
✅ Checkpoint 3 (Phase 4 权限测试)
|
||
- user-rpc 可以读 jwt-secret
|
||
- envoy-gateway 可以读 jwt-secret
|
||
- 其他 SA 无法读取
|
||
- Go → 继续 Phase 5
|
||
- No-Go → 检查 RBAC 配置
|
||
|
||
✅ Checkpoint 4 (Phase 4 Redis 连接)
|
||
- Redis Cluster 健康 (3/3 nodes)
|
||
- PING 返回 PONG
|
||
- Go → 继续应用集成
|
||
- No-Go → 检查 Redis Pods 和网络
|
||
|
||
✅ Checkpoint 5 (Phase 5b - ETCD 加密)
|
||
- 新创建的 Secret 在 ETCD 中已加密
|
||
- Go → 生产就绪
|
||
- No-Go → 检查 kube-apiserver 配置参数
|
||
```
|
||
|
||
---
|
||
|
||
## 使用这个流程图
|
||
|
||
1. **首次部署** → 从 "推荐部署路径" 选择合适的版本
|
||
2. **卡在某一步** → 查看对应的 Phase 描述和命令
|
||
3. **估算时间** → 查看 "时间估计和路径" 部分
|
||
4. **需要回滚** → 参考 "回滚应急步骤"
|
||
5. **检查进度** → 使用 "部署检查点"
|
||
|
||
详细的部署步骤见：[DEPLOYMENT.md](./DEPLOYMENT.md)
|