654 lines
13 KiB
Markdown
654 lines
13 KiB
Markdown
# K3s集群迁移指导文档
|
||
|
||
本文档提供K3s集群完整迁移的详细步骤，包括备份、迁移和恢复全流程。
|
||
|
||
## 目录
|
||
|
||
1. [迁移概述](#迁移概述)
|
||
2. [迁移前准备](#迁移前准备)
|
||
3. [备份现有集群](#备份现有集群)
|
||
4. [准备新环境](#准备新环境)
|
||
5. [部署新集群](#部署新集群)
|
||
6. [恢复数据和应用](#恢复数据和应用)
|
||
7. [验证和测试](#验证和测试)
|
||
8. [切换流量](#切换流量)
|
||
9. [故障回滚](#故障回滚)
|
||
10. [清理旧集群](#清理旧集群)
|
||
|
||
---
|
||
|
||
## 迁移概述
|
||
|
||
### 迁移场景
|
||
|
||
- **云服务商迁移**: 从一个云平台迁移到另一个云平台
|
||
- **区域迁移**: 在同一云平台的不同区域间迁移
|
||
- **硬件升级**: 迁移到更高配置的服务器
|
||
- **架构调整**: 改变集群节点数量或配置
|
||
- **灾难恢复**: 从备份恢复整个集群
|
||
|
||
### 迁移策略
|
||
|
||
**蓝绿部署（推荐）**:
|
||
- 保持旧集群运行
|
||
- 部署新集群并验证
|
||
- 切换流量到新集群
|
||
- 验证后清理旧集群
|
||
|
||
**优点**: 风险低，可快速回滚
|
||
**缺点**: 需要双倍资源
|
||
|
||
---
|
||
|
||
## 迁移前准备
|
||
|
||
### 1. 评估现有集群
|
||
|
||
```bash
|
||
# 记录集群信息
|
||
kubectl get nodes -o wide > cluster-info.txt
|
||
kubectl version >> cluster-info.txt
|
||
|
||
# 记录所有命名空间
|
||
kubectl get namespaces -o yaml > namespaces-backup.yaml
|
||
|
||
# 记录所有资源
|
||
kubectl get all --all-namespaces -o wide > all-resources.txt
|
||
|
||
# 记录持久化存储
|
||
kubectl get pv,pvc --all-namespaces -o yaml > storage-backup.yaml
|
||
|
||
# 记录ConfigMaps和Secrets
|
||
kubectl get configmaps,secrets --all-namespaces -o yaml > configs-secrets-backup.yaml
|
||
```
|
||
|
||
### 2. 创建迁移清单
|
||
|
||
创建迁移检查清单，确保不遗漏任何步骤。
|
||
|
||
### 3. 准备迁移工具
|
||
|
||
```bash
|
||
# 安装必要工具
|
||
sudo apt-get update
|
||
sudo apt-get install -y rsync tar gzip
|
||
|
||
# 安装velero（Kubernetes备份工具）
|
||
wget https://github.com/vmware-tanzu/velero/releases/download/v1.12.0/velero-v1.12.0-linux-amd64.tar.gz
|
||
tar -xvf velero-v1.12.0-linux-amd64.tar.gz
|
||
sudo mv velero-v1.12.0-linux-amd64/velero /usr/local/bin/
|
||
```
|
||
|
||
---
|
||
|
||
## 备份现有集群
|
||
|
||
### 1. 备份etcd数据
|
||
|
||
```bash
|
||
# 在master节点执行
|
||
sudo mkdir -p /backup/etcd
|
||
|
||
# 备份etcd数据
|
||
sudo k3s etcd-snapshot save --name migration-backup
|
||
|
||
# 查找备份文件
|
||
sudo ls -lh /var/lib/rancher/k3s/server/db/snapshots/
|
||
|
||
# 复制备份到安全位置
|
||
sudo cp /var/lib/rancher/k3s/server/db/snapshots/migration-backup* /backup/etcd/
|
||
|
||
# 下载到本地
|
||
scp fei@8.216.38.248:/backup/etcd/migration-backup* ./backups/
|
||
```
|
||
|
||
### 2. 备份Kubernetes资源
|
||
|
||
```bash
|
||
# 创建备份目录
|
||
mkdir -p backups/k8s-resources
|
||
cd backups/k8s-resources
|
||
|
||
# 备份所有命名空间的资源
|
||
for ns in $(kubectl get ns -o jsonpath='{.items[*].metadata.name}'); do
|
||
echo "Backing up namespace: $ns"
|
||
mkdir -p $ns
|
||
|
||
# 备份各类资源
|
||
kubectl get deployments -n $ns -o yaml > $ns/deployments.yaml
|
||
kubectl get services -n $ns -o yaml > $ns/services.yaml
|
||
kubectl get ingress -n $ns -o yaml > $ns/ingress.yaml
|
||
kubectl get configmaps -n $ns -o yaml > $ns/configmaps.yaml
|
||
kubectl get secrets -n $ns -o yaml > $ns/secrets.yaml
|
||
kubectl get pvc -n $ns -o yaml > $ns/pvc.yaml
|
||
done
|
||
|
||
# 备份CRDs和全局资源
|
||
kubectl get crd -o yaml > crds.yaml
|
||
kubectl get pv -o yaml > persistent-volumes.yaml
|
||
kubectl get storageclass -o yaml > storageclasses.yaml
|
||
|
||
# 打包备份
|
||
cd ..
|
||
tar -czf k8s-resources-$(date +%Y%m%d-%H%M%S).tar.gz k8s-resources/
|
||
```
|
||
|
||
### 3. 备份Gitea数据
|
||
|
||
```bash
|
||
# 备份Gitea PostgreSQL数据库
|
||
kubectl exec -n gitea gitea-postgresql-ha-postgresql-0 -- \
|
||
pg_dump -U postgres gitea > backups/gitea-db-backup.sql
|
||
|
||
# 备份Gitea数据目录
|
||
ssh fei@8.216.38.248 "sudo tar -czf /backup/gitea-data.tar.gz /var/lib/rancher/k3s/storage/gitea-data"
|
||
scp fei@8.216.38.248:/backup/gitea-data.tar.gz ./backups/
|
||
```
|
||
|
||
### 4. 备份ArgoCD数据
|
||
|
||
```bash
|
||
# 备份ArgoCD配置
|
||
kubectl get configmaps -n argocd -o yaml > backups/argocd-configmaps.yaml
|
||
kubectl get secrets -n argocd -o yaml > backups/argocd-secrets.yaml
|
||
|
||
# 备份ArgoCD Applications
|
||
kubectl get applications -n argocd -o yaml > backups/argocd-applications.yaml
|
||
```
|
||
|
||
### 5. 备份配置文件
|
||
|
||
```bash
|
||
# 备份部署脚本和配置
|
||
cd /home/fei/opk3s/k3s自动化部署
|
||
tar -czf ~/backups/deployment-scripts-$(date +%Y%m%d).tar.gz \
|
||
config/ scripts/ *.md *.sh
|
||
|
||
# 备份K3s配置
|
||
ssh fei@8.216.38.248 "sudo tar -czf /backup/k3s-config.tar.gz \
|
||
/etc/rancher/k3s/ \
|
||
/var/lib/rancher/k3s/server/manifests/"
|
||
|
||
scp fei@8.216.38.248:/backup/k3s-config.tar.gz ./backups/
|
||
```
|
||
|
||
---
|
||
|
||
## 准备新环境
|
||
|
||
### 1. 准备新服务器
|
||
|
||
**服务器要求**:
|
||
- 操作系统: Debian 12 / Ubuntu 22.04
|
||
- CPU: 2核以上（推荐4核）
|
||
- 内存: 4GB以上（推荐8GB）
|
||
- 磁盘: 50GB以上
|
||
- 网络: 公网IP，开放必要端口
|
||
|
||
**端口要求**:
|
||
- 6443: Kubernetes API
|
||
- 80: HTTP
|
||
- 443: HTTPS
|
||
- 10250: Kubelet
|
||
- 2379-2380: etcd（仅master节点间）
|
||
|
||
### 2. 配置服务器
|
||
|
||
```bash
|
||
# 在所有新节点上执行
|
||
|
||
# 更新系统
|
||
sudo apt-get update && sudo apt-get upgrade -y
|
||
|
||
# 设置主机名
|
||
sudo hostnamectl set-hostname k3s-master-new-01
|
||
|
||
# 配置hosts
|
||
sudo tee -a /etc/hosts <<EOF
|
||
<NEW_MASTER_IP> k3s-master-new-01
|
||
<NEW_WORKER1_IP> k3s-worker-new-01
|
||
<NEW_WORKER2_IP> k3s-worker-new-02
|
||
EOF
|
||
|
||
# 禁用swap
|
||
sudo swapoff -a
|
||
sudo sed -i '/ swap / s/^/#/' /etc/fstab
|
||
|
||
# 配置防火墙
|
||
sudo ufw allow 6443/tcp
|
||
sudo ufw allow 80/tcp
|
||
sudo ufw allow 443/tcp
|
||
sudo ufw allow 10250/tcp
|
||
sudo ufw enable
|
||
```
|
||
|
||
### 3. 准备域名和DNS
|
||
|
||
```bash
|
||
# 更新DNS记录（在域名服务商控制台）
|
||
# 方式1: 先添加新记录，保留旧记录
|
||
new-cluster.jpc.net3w.com A <NEW_MASTER_IP>
|
||
|
||
# 方式2: 准备好，切换时修改
|
||
# git.jpc.net3w.com A <NEW_MASTER_IP>
|
||
# argocd.jpc.net3w.com A <NEW_MASTER_IP>
|
||
```
|
||
|
||
---
|
||
|
||
## 部署新集群
|
||
|
||
### 1. 上传部署脚本
|
||
|
||
```bash
|
||
# 解压备份的部署脚本
|
||
tar -xzf backups/deployment-scripts-*.tar.gz -C /tmp/
|
||
|
||
# 上传到新master节点
|
||
scp -r /tmp/k3s自动化部署 fei@<NEW_MASTER_IP>:/home/fei/
|
||
|
||
# SSH到新master节点
|
||
ssh fei@<NEW_MASTER_IP>
|
||
cd /home/fei/k3s自动化部署
|
||
```
|
||
|
||
### 2. 修改配置文件
|
||
|
||
```bash
|
||
# 编辑配置文件
|
||
vi config/cluster-vars.yml
|
||
|
||
# 更新以下内容:
|
||
# - master_nodes: 新master节点IP
|
||
# - worker_nodes: 新worker节点IP列表
|
||
# - 域名配置（如果更改）
|
||
```
|
||
|
||
### 3. 部署K3s集群
|
||
|
||
```bash
|
||
# 使用自动化脚本部署
|
||
./scripts/deploy-all.sh
|
||
|
||
# 或分步部署
|
||
# 1. 生成inventory
|
||
python3 scripts/generate-inventory.py
|
||
|
||
# 2. 部署K3s
|
||
cd k3s-ansible
|
||
ansible-playbook playbooks/site.yml -i inventory.yml
|
||
|
||
# 3. 配置kubectl
|
||
mkdir -p ~/.kube
|
||
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
|
||
sudo chown $USER:$USER ~/.kube/config
|
||
|
||
# 验证集群
|
||
kubectl get nodes -o wide
|
||
```
|
||
|
||
### 4. 部署基础组件
|
||
|
||
```bash
|
||
# 部署Gitea
|
||
./scripts/deploy-gitea.sh
|
||
|
||
# 部署ArgoCD
|
||
./scripts/deploy-argocd.sh
|
||
|
||
# 部署HTTPS支持
|
||
./scripts/deploy-https.sh
|
||
|
||
# 验证所有组件
|
||
kubectl get pods --all-namespaces
|
||
```
|
||
|
||
---
|
||
|
||
## 恢复数据和应用
|
||
|
||
### 1. 恢复Gitea数据
|
||
|
||
```bash
|
||
# 上传数据库备份
|
||
scp backups/gitea-db-backup.sql fei@<NEW_MASTER_IP>:/tmp/
|
||
|
||
# 恢复数据库
|
||
kubectl cp /tmp/gitea-db-backup.sql gitea/gitea-postgresql-ha-postgresql-0:/tmp/
|
||
kubectl exec -n gitea gitea-postgresql-ha-postgresql-0 -- \
|
||
psql -U postgres gitea < /tmp/gitea-db-backup.sql
|
||
|
||
# 重启Gitea
|
||
kubectl rollout restart deployment/gitea -n gitea
|
||
```
|
||
|
||
### 2. 恢复ArgoCD配置
|
||
|
||
```bash
|
||
# 恢复ArgoCD Secrets
|
||
kubectl apply -f backups/argocd-secrets.yaml
|
||
|
||
# 恢复ArgoCD Applications
|
||
kubectl apply -f backups/argocd-applications.yaml
|
||
|
||
# 验证
|
||
kubectl get applications -n argocd
|
||
```
|
||
|
||
### 3. 恢复应用
|
||
|
||
**方式1: 通过ArgoCD自动同步**
|
||
|
||
```bash
|
||
# 如果Git仓库已恢复，ArgoCD会自动同步应用
|
||
kubectl get applications -n argocd
|
||
|
||
# 手动触发同步
|
||
kubectl patch application <app-name> -n argocd \
|
||
--type merge \
|
||
-p '{"operation":{"initiatedBy":{"username":"admin"},"sync":{"revision":"HEAD"}}}'
|
||
```
|
||
|
||
**方式2: 手动恢复资源**
|
||
|
||
```bash
|
||
# 解压资源备份
|
||
tar -xzf backups/k8s-resources-*.tar.gz
|
||
|
||
# 恢复各命名空间资源
|
||
kubectl apply -f k8s-resources/default/
|
||
kubectl apply -f k8s-resources/gitea/
|
||
kubectl apply -f k8s-resources/argocd/
|
||
```
|
||
|
||
---
|
||
|
||
## 验证和测试
|
||
|
||
### 1. 验证集群状态
|
||
|
||
```bash
|
||
# 检查节点状态
|
||
kubectl get nodes -o wide
|
||
|
||
# 检查所有Pod
|
||
kubectl get pods --all-namespaces
|
||
|
||
# 检查资源使用
|
||
kubectl top nodes
|
||
kubectl top pods --all-namespaces
|
||
```
|
||
|
||
### 2. 验证网络连通性
|
||
|
||
```bash
|
||
# 测试Service访问
|
||
kubectl run test-pod --rm -it --image=curlimages/curl -- \
|
||
curl http://<service-name>.<namespace>.svc.cluster.local
|
||
|
||
# 测试外部访问
|
||
curl http://<domain>
|
||
curl https://<domain>
|
||
```
|
||
|
||
### 3. 验证应用功能
|
||
|
||
```bash
|
||
# 测试Gitea
|
||
curl http://git.jpc.net3w.com
|
||
|
||
# 测试ArgoCD
|
||
curl https://argocd.jpc.net3w.com
|
||
|
||
# 测试应用
|
||
curl http://ng.jpc.net3w.com
|
||
curl http://test.jpc.net3w.com
|
||
```
|
||
|
||
### 4. 性能测试
|
||
|
||
```bash
|
||
# 压力测试
|
||
kubectl run load-test --rm -it --image=williamyeh/hey -- \
|
||
-z 30s -c 10 http://<app-url>
|
||
|
||
# 监控资源使用
|
||
watch kubectl top pods --all-namespaces
|
||
```
|
||
|
||
---
|
||
|
||
## 切换流量
|
||
|
||
### 1. 准备切换
|
||
|
||
```bash
|
||
# 降低DNS TTL（提前24小时）
|
||
# 在域名服务商控制台将TTL设置为300秒（5分钟）
|
||
|
||
# 准备回滚方案
|
||
# 记录旧集群IP，准备快速回滚
|
||
```
|
||
|
||
### 2. 灰度切换（推荐）
|
||
|
||
```bash
|
||
# 使用权重DNS或负载均衡器
|
||
# 逐步增加新集群流量比例
|
||
# 30% -> 50% -> 70% -> 100%
|
||
|
||
# 监控新集群
|
||
watch kubectl top pods --all-namespaces
|
||
```
|
||
|
||
### 3. 完全切换
|
||
|
||
```bash
|
||
# 更新DNS记录
|
||
# 在域名服务商控制台修改A记录：
|
||
# git.jpc.net3w.com A <NEW_MASTER_IP>
|
||
# argocd.jpc.net3w.com A <NEW_MASTER_IP>
|
||
# *.jpc.net3w.com A <NEW_MASTER_IP>
|
||
|
||
# 验证DNS生效
|
||
nslookup git.jpc.net3w.com
|
||
dig git.jpc.net3w.com
|
||
|
||
# 等待DNS传播（5-30分钟）
|
||
```
|
||
|
||
### 4. 切换后监控
|
||
|
||
```bash
|
||
# 监控应用状态
|
||
watch kubectl get pods --all-namespaces
|
||
|
||
# 监控日志
|
||
kubectl logs -n <namespace> -l app=<app-name> -f
|
||
|
||
# 检查错误
|
||
kubectl get events --all-namespaces --sort-by='.lastTimestamp'
|
||
```
|
||
|
||
---
|
||
|
||
## 故障回滚
|
||
|
||
### 1. 快速回滚DNS
|
||
|
||
```bash
|
||
# 如果新集群出现问题，立即回滚DNS
|
||
# 在域名服务商控制台修改A记录回旧IP
|
||
|
||
# 清除本地DNS缓存
|
||
sudo systemd-resolve --flush-caches
|
||
|
||
# 验证回滚
|
||
nslookup git.jpc.net3w.com
|
||
```
|
||
|
||
### 2. 回滚应用
|
||
|
||
```bash
|
||
# 在旧集群重新启动应用
|
||
kubectl rollout restart deployment/<app-name> -n <namespace>
|
||
|
||
# 或在新集群回滚到旧版本
|
||
kubectl rollout undo deployment/<app-name> -n <namespace>
|
||
```
|
||
|
||
---
|
||
|
||
## 清理旧集群
|
||
|
||
### 1. 确认新集群稳定
|
||
|
||
```bash
|
||
# 运行至少7天，确保：
|
||
# - 所有功能正常
|
||
# - 性能满足要求
|
||
# - 没有数据丢失
|
||
# - 用户反馈良好
|
||
```
|
||
|
||
### 2. 最后备份旧集群
|
||
|
||
```bash
|
||
# 再次备份旧集群（以防万一）
|
||
ssh fei@<OLD_MASTER_IP>
|
||
sudo k3s etcd-snapshot save --name final-backup
|
||
sudo cp /var/lib/rancher/k3s/server/db/snapshots/final-backup* /backup/
|
||
```
|
||
|
||
### 3. 停止旧集群服务
|
||
|
||
```bash
|
||
# 在旧集群所有节点执行
|
||
|
||
# 停止K3s服务
|
||
sudo systemctl stop k3s
|
||
sudo systemctl stop k3s-agent
|
||
|
||
# 禁用自动启动
|
||
sudo systemctl disable k3s
|
||
sudo systemctl disable k3s-agent
|
||
```
|
||
|
||
### 4. 清理旧集群数据
|
||
|
||
```bash
|
||
# 在旧集群所有节点执行
|
||
|
||
# 卸载K3s
|
||
/usr/local/bin/k3s-uninstall.sh # master节点
|
||
/usr/local/bin/k3s-agent-uninstall.sh # worker节点
|
||
|
||
# 清理残留数据
|
||
sudo rm -rf /var/lib/rancher/k3s
|
||
sudo rm -rf /etc/rancher/k3s
|
||
```
|
||
|
||
---
|
||
|
||
## 迁移检查清单
|
||
|
||
### 迁移前
|
||
- [ ] 完整备份已创建
|
||
- [ ] 备份已验证可用
|
||
- [ ] 新环境已准备
|
||
- [ ] 迁移计划已制定
|
||
- [ ] 回滚方案已准备
|
||
|
||
### 迁移中
|
||
- [ ] 新集群已部署
|
||
- [ ] 基础组件已安装
|
||
- [ ] 数据已恢复
|
||
- [ ] 应用已部署
|
||
- [ ] 功能已验证
|
||
|
||
### 迁移后
|
||
- [ ] DNS已切换
|
||
- [ ] 流量已迁移
|
||
- [ ] 监控已配置
|
||
- [ ] 文档已更新
|
||
|
||
### 清理阶段
|
||
- [ ] 新集群运行稳定（7天+）
|
||
- [ ] 旧集群已最终备份
|
||
- [ ] 旧集群已停止
|
||
- [ ] 旧数据已清理
|
||
|
||
---
|
||
|
||
## 最佳实践
|
||
|
||
### 1. 迁移时机
|
||
- 选择业务低峰期
|
||
- 避开节假日
|
||
- 预留充足时间
|
||
|
||
### 2. 风险控制
|
||
- 保持旧集群运行
|
||
- 使用灰度切换
|
||
- 准备快速回滚
|
||
- 实时监控告警
|
||
|
||
### 3. 数据安全
|
||
- 多重备份
|
||
- 异地存储
|
||
- 加密传输
|
||
- 验证完整性
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
### Q1: 迁移需要多长时间？
|
||
|
||
**A**: 取决于集群规模和数据量：
|
||
- 小型集群（<10个应用）: 4-8小时
|
||
- 中型集群（10-50个应用）: 1-2天
|
||
- 大型集群（>50个应用）: 3-7天
|
||
|
||
### Q2: 迁移期间服务会中断吗？
|
||
|
||
**A**: 使用蓝绿部署策略，可以实现零停机迁移。DNS切换时可能有短暂的缓存延迟（5-30分钟）。
|
||
|
||
### Q3: 如何处理有状态应用？
|
||
|
||
**A**: 有状态应用需要特别注意：
|
||
- 提前停止写入，确保数据一致性
|
||
- 使用数据库复制或备份恢复
|
||
- 验证数据完整性后再切换
|
||
|
||
### Q4: 如何验证迁移成功？
|
||
|
||
**A**: 多维度验证：
|
||
- 功能测试：所有功能正常工作
|
||
- 性能测试：响应时间和吞吐量符合预期
|
||
- 数据验证：数据完整且一致
|
||
- 监控指标：CPU、内存、网络正常
|
||
|
||
### Q5: 迁移失败如何回滚？
|
||
|
||
**A**: 快速回滚步骤：
|
||
1. 立即切换DNS回旧集群
|
||
2. 清除DNS缓存
|
||
3. 验证旧集群服务正常
|
||
4. 分析失败原因
|
||
5. 修复问题后重新迁移
|
||
|
||
---
|
||
|
||
## 相关文档
|
||
|
||
- [K3s部署指南](./DEPLOYMENT-GUIDE.md)
|
||
- [手动部署指南](./MANUAL-DEPLOYMENT-GUIDE.md)
|
||
- [故障排查指南](./TROUBLESHOOTING-ACCESS.md)
|
||
- [K3s官方文档](https://docs.k3s.io/)
|
||
|
||
---
|
||
|
||
**最后更新**: 2026-02-04
|
||
**文档版本**: 1.0
|