fix: 将 k3s-ansible 作为普通目录添加
This commit is contained in:
fei
585
README.md
Normal file
585
README.md
Normal file
@@ -0,0 +1,585 @@
|
||||
# K3s集群自动化部署与GitOps方案（含Gitea私有Git服务）
|
||||
|
||||
## 概述
|
||||
|
||||
本项目提供完整的K3s集群自动化部署方案，集成Gitea私有Git服务器和ArgoCD实现完整的GitOps工作流。所有配置参数化，**完全支持幂等部署**，可在重装系统后无需手动调试即可自动化部署。
|
||||
|
||||
### 🎯 核心特性
|
||||
|
||||
- ✅ **完全幂等**: 所有脚本可重复执行，不会破坏现有配置
|
||||
- ✅ **一键部署**: 使用 `deploy-all.sh` 统一编排所有步骤
|
||||
- ✅ **断点续传**: 部署失败后可从中断处继续
|
||||
- ✅ **自动重试**: 网络失败自动重试，提高可靠性
|
||||
- ✅ **工具检查**: 自动检查和安装所有依赖工具
|
||||
- ✅ **状态管理**: 记录已完成步骤，避免重复执行
|
||||
- ✅ **详细日志**: 完整的部署日志便于问题排查
|
||||
- ✅ **验证脚本**: 自动验证部署状态和服务健康
|
||||
|
||||
## 实际环境信息
|
||||
|
||||
- **集群规模**: 1 master + 2 worker节点
|
||||
- **主节点**: 8.216.38.248 (内网: 172.23.96.138) - *.jpc.net3w.com
|
||||
- **从节点1**: 8.216.41.97 (内网: 172.23.96.139) - *.jpc2.net3w.com
|
||||
- **从节点2**: 8.216.33.69 (内网: 172.23.96.140) - *.jpc3.net3w.com
|
||||
- **SSH用户**: fei / 密码: 1
|
||||
- **目标目录**: /home/fei/k3s
|
||||
|
||||
## 特性
|
||||
|
||||
### 部署特性
|
||||
- ✅ 基于k3s-ansible的幂等部署
|
||||
- ✅ 统一部署脚本 `deploy-all.sh` 编排所有步骤
|
||||
- ✅ 自动检查和安装依赖工具（yq, htpasswd, helm等）
|
||||
- ✅ 网络下载自动重试机制
|
||||
- ✅ 部署状态持久化，支持断点续传
|
||||
- ✅ 详细的日志记录和错误处理
|
||||
|
||||
### 功能特性
|
||||
- ✅ 所有敏感信息变量化配置
|
||||
- ✅ 一键部署K3s集群
|
||||
- ✅ 自动部署Gitea私有Git服务器
|
||||
- ✅ 自动创建Gitea组织、仓库和用户
|
||||
- ✅ 自动安装和配置ArgoCD
|
||||
- ✅ ArgoCD连接Gitea实现GitOps自动同步部署
|
||||
- ✅ 自动配置HTTPS证书（cert-manager + Let's Encrypt）
|
||||
- ✅ 部署验证脚本自动检查所有服务
|
||||
|
||||
### 认证方式
|
||||
- ✅ 支持密码认证和SSH密钥认证
|
||||
- ✅ 支持Ansible Vault加密
|
||||
|
||||
## 目录结构
|
||||
|
||||
```
|
||||
.
|
||||
├── config/
|
||||
│ ├── cluster-vars.yml.example # 配置模板
|
||||
│ └── cluster-vars.yml # 实际配置（已创建）
|
||||
├── scripts/
|
||||
│ ├── lib/
|
||||
│ │ └── common.sh # 通用函数库（新增）
|
||||
│ ├── deploy-all.sh # 统一部署脚本（新增）
|
||||
│ ├── verify-deployment.sh # 部署验证脚本（新增）
|
||||
│ ├── generate-inventory.py # 生成Ansible inventory（支持密码认证）
|
||||
│ ├── deploy.sh # K3s部署脚本
|
||||
│ ├── deploy-gitea.sh # Gitea部署脚本
|
||||
│ ├── setup-gitea.sh # Gitea初始化脚本
|
||||
│ ├── deploy-argocd.sh # ArgoCD部署脚本（已改进）
|
||||
│ ├── deploy-https.sh # HTTPS证书配置脚本（新增）
|
||||
│ ├── create-argocd-app.sh # 创建ArgoCD应用
|
||||
│ └── push-demo-app.sh # 推送示例应用
|
||||
├── templates/ # 模板文件
|
||||
├── k3s-ansible/ # k3s-ansible项目（需克隆）
|
||||
├── .deployment-state # 部署状态文件（自动生成）
|
||||
└── deployment.log # 部署日志（自动生成）
|
||||
```
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 方式一：一键部署（推荐）
|
||||
|
||||
使用统一部署脚本自动完成所有步骤：
|
||||
|
||||
```bash
|
||||
cd /home/fei/opk3s/k3s自动化部署
|
||||
|
||||
# 克隆k3s-ansible（首次需要）
|
||||
git clone https://github.com/k3s-io/k3s-ansible.git
|
||||
|
||||
# 设置脚本执行权限
|
||||
chmod +x scripts/*.sh scripts/*.py
|
||||
|
||||
# 一键部署所有组件
|
||||
./scripts/deploy-all.sh
|
||||
```
|
||||
|
||||
**特性**:
|
||||
- ✅ 自动检查所有前置条件
|
||||
- ✅ 自动安装缺失的工具
|
||||
- ✅ 按正确顺序执行所有步骤
|
||||
- ✅ 失败后可断点续传
|
||||
- ✅ 详细的进度显示和日志
|
||||
|
||||
**断点续传**:
|
||||
如果部署中途失败，修复问题后直接重新运行即可从中断处继续：
|
||||
```bash
|
||||
./scripts/deploy-all.sh
|
||||
```
|
||||
|
||||
**重置状态**:
|
||||
如果需要从头开始部署：
|
||||
```bash
|
||||
./scripts/deploy-all.sh --reset
|
||||
```
|
||||
|
||||
### 方式二：分步部署
|
||||
|
||||
如果需要更细粒度的控制，可以手动执行各个步骤：
|
||||
|
||||
#### 1. 克隆k3s-ansible项目
|
||||
```bash
|
||||
cd /home/fei/opk3s/k3s自动化部署
|
||||
git clone https://github.com/k3s-io/k3s-ansible.git
|
||||
```
|
||||
|
||||
#### 2. 设置脚本执行权限
|
||||
```bash
|
||||
chmod +x scripts/*.sh scripts/*.py
|
||||
```
|
||||
|
||||
#### 3. 部署K3s集群
|
||||
```bash
|
||||
./scripts/deploy.sh
|
||||
```
|
||||
|
||||
#### 4. 部署Gitea私有Git服务器
|
||||
```bash
|
||||
./scripts/deploy-gitea.sh
|
||||
```
|
||||
|
||||
#### 5. 初始化Gitea
|
||||
```bash
|
||||
./scripts/setup-gitea.sh
|
||||
```
|
||||
|
||||
#### 6. 部署ArgoCD
|
||||
```bash
|
||||
./scripts/deploy-argocd.sh
|
||||
```
|
||||
|
||||
#### 7. 配置HTTPS证书
|
||||
```bash
|
||||
./scripts/deploy-https.sh
|
||||
```
|
||||
|
||||
#### 8. 创建ArgoCD应用
|
||||
```bash
|
||||
./scripts/create-argocd-app.sh
|
||||
```
|
||||
|
||||
#### 9. 推送示例应用
|
||||
```bash
|
||||
./scripts/push-demo-app.sh
|
||||
```
|
||||
|
||||
### 验证部署
|
||||
|
||||
部署完成后，运行验证脚本检查所有服务：
|
||||
|
||||
```bash
|
||||
./scripts/verify-deployment.sh
|
||||
```
|
||||
|
||||
验证脚本会检查：
|
||||
- K3s集群状态
|
||||
- Gitea服务
|
||||
- ArgoCD服务
|
||||
- HTTPS证书
|
||||
- GitOps工作流
|
||||
- 存储卷状态
|
||||
|
||||
## 配置说明
|
||||
|
||||
### 节点配置（实际配置）
|
||||
|
||||
```yaml
|
||||
master_nodes:
|
||||
- hostname: k3s-master-01
|
||||
public_ip: "8.216.38.248"
|
||||
private_ip: "172.23.96.138"
|
||||
ssh_user: "fei"
|
||||
ssh_password: "1" # 使用密码认证
|
||||
|
||||
worker_nodes:
|
||||
- hostname: k3s-worker-01
|
||||
public_ip: "8.216.41.97"
|
||||
private_ip: "172.23.96.139"
|
||||
ssh_user: "fei"
|
||||
ssh_password: "1"
|
||||
- hostname: k3s-worker-02
|
||||
public_ip: "8.216.33.69"
|
||||
private_ip: "172.23.96.140"
|
||||
ssh_user: "fei"
|
||||
ssh_password: "1"
|
||||
```
|
||||
|
||||
### K3s配置
|
||||
|
||||
```yaml
|
||||
k3s_version: "v1.28.5+k3s1"
|
||||
k3s_token: "" # 留空自动生成
|
||||
flannel_iface: "eth0"
|
||||
target_dir: "/home/fei/k3s"
|
||||
```
|
||||
|
||||
### 域名配置
|
||||
|
||||
```yaml
|
||||
domain_name: "jpc.net3w.com"
|
||||
master_domain: "jpc1.net3w.com"
|
||||
worker1_domain: "jpc2.net3w.com"
|
||||
worker2_domain: "jpc3.net3w.com"
|
||||
gitea_domain: "git.jpc.net3w.com"
|
||||
argocd_domain: "argocd.jpc.net3w.com"
|
||||
```
|
||||
|
||||
### Gitea配置（私有Git服务器）
|
||||
|
||||
```yaml
|
||||
gitea_enabled: true
|
||||
gitea_admin_user: "gitea_admin"
|
||||
gitea_admin_password: "GitAdmin@2026"
|
||||
gitea_org_name: "k3s-apps"
|
||||
gitea_repo_name: "demo-app"
|
||||
gitea_user_name: "argocd" # ArgoCD使用的用户
|
||||
gitea_user_password: "ArgoCD@2026"
|
||||
```
|
||||
|
||||
### ArgoCD配置
|
||||
|
||||
```yaml
|
||||
argocd_admin_password: "ArgoAdmin@2026"
|
||||
git_repo_url: "http://gitea-http.gitea.svc.cluster.local:3000/k3s-apps/demo-app.git"
|
||||
```
|
||||
|
||||
## 验证部署
|
||||
|
||||
### 自动验证（推荐）
|
||||
|
||||
使用验证脚本自动检查所有服务：
|
||||
|
||||
```bash
|
||||
./scripts/verify-deployment.sh
|
||||
```
|
||||
|
||||
验证脚本会检查：
|
||||
- ✅ K3s集群状态（节点、系统Pod）
|
||||
- ✅ Gitea服务（部署、Pod、访问地址）
|
||||
- ✅ ArgoCD服务（Server、Controller、Repo Server）
|
||||
- ✅ HTTPS证书（cert-manager、ClusterIssuer、Certificate）
|
||||
- ✅ GitOps工作流（ArgoCD Application状态）
|
||||
- ✅ 存储卷状态（PV、PVC）
|
||||
|
||||
### 手动验证
|
||||
|
||||
#### 验证K3s集群
|
||||
|
||||
```bash
|
||||
# 查看节点状态
|
||||
kubectl get nodes
|
||||
|
||||
# 查看所有Pod
|
||||
kubectl get pods -A
|
||||
|
||||
# 创建测试Pod
|
||||
kubectl run test --image=nginx
|
||||
```
|
||||
|
||||
### 验证Gitea
|
||||
|
||||
```bash
|
||||
# 查看Gitea Pod状态
|
||||
kubectl get pods -n gitea
|
||||
|
||||
# 查看Gitea服务
|
||||
kubectl get svc -n gitea
|
||||
|
||||
# 获取Gitea访问地址
|
||||
GITEA_NODEPORT=$(kubectl get svc gitea-http -n gitea -o jsonpath='{.spec.ports[0].nodePort}')
|
||||
echo "Gitea访问地址: http://8.216.38.248:$GITEA_NODEPORT"
|
||||
```
|
||||
|
||||
### 验证ArgoCD
|
||||
|
||||
```bash
|
||||
# 查看ArgoCD Pod状态
|
||||
kubectl get pods -n argocd
|
||||
|
||||
# 查看ArgoCD服务
|
||||
kubectl get svc -n argocd
|
||||
|
||||
# 获取ArgoCD访问地址
|
||||
ARGOCD_NODEPORT=$(kubectl get svc argocd-server -n argocd -o jsonpath='{.spec.ports[0].nodePort}')
|
||||
echo "ArgoCD访问地址: https://8.216.38.248:$ARGOCD_NODEPORT"
|
||||
echo "用户名: admin"
|
||||
echo "密码: ArgoAdmin@2026"
|
||||
|
||||
# 查看Application状态
|
||||
kubectl get application -n argocd
|
||||
```
|
||||
|
||||
### 验证GitOps
|
||||
|
||||
```bash
|
||||
# 查看应用同步状态
|
||||
kubectl describe application demo-app -n argocd
|
||||
|
||||
# 查看示例应用
|
||||
kubectl get pods -n default
|
||||
kubectl get svc demo-nginx -n default
|
||||
|
||||
# 访问示例应用
|
||||
curl http://8.216.38.248:30080
|
||||
|
||||
# 测试自动同步：修改Gitea仓库内容，等待3分钟观察自动部署
|
||||
```
|
||||
|
||||
## 安全建议
|
||||
|
||||
### 1. 使用Ansible Vault加密配置
|
||||
|
||||
```bash
|
||||
# 加密配置文件
|
||||
ansible-vault encrypt config/cluster-vars.yml
|
||||
|
||||
# 编辑加密文件
|
||||
ansible-vault edit config/cluster-vars.yml
|
||||
|
||||
# 部署时使用加密文件
|
||||
cd k3s-ansible
|
||||
ansible-playbook site.yml -i inventory/hosts.ini -e "@../config/cluster-vars.yml" --ask-vault-pass
|
||||
```
|
||||
|
||||
### 2. 限制文件权限
|
||||
|
||||
```bash
|
||||
chmod 600 config/cluster-vars.yml
|
||||
```
|
||||
|
||||
### 3. 不要提交敏感信息到Git
|
||||
|
||||
`.gitignore`已配置忽略敏感文件：
|
||||
- `config/cluster-vars.yml`
|
||||
- `config/*-vars.yml`
|
||||
- `*.vault`
|
||||
|
||||
## 故障排查
|
||||
|
||||
### K3s部署失败
|
||||
|
||||
```bash
|
||||
# 测试SSH连接
|
||||
ansible all -i k3s-ansible/inventory/hosts.ini -m ping
|
||||
|
||||
# 查看详细日志
|
||||
cd k3s-ansible
|
||||
ansible-playbook site.yml -i inventory/hosts.ini -e "@../config/cluster-vars.yml" -vvv
|
||||
```
|
||||
|
||||
### Gitea无法访问
|
||||
|
||||
```bash
|
||||
# 检查Pod状态
|
||||
kubectl get pods -n gitea
|
||||
|
||||
# 查看日志
|
||||
kubectl logs -n gitea -l app.kubernetes.io/name=gitea
|
||||
|
||||
# 检查Service
|
||||
kubectl get svc -n gitea
|
||||
|
||||
# 检查持久化存储
|
||||
kubectl get pvc -n gitea
|
||||
```
|
||||
|
||||
### ArgoCD无法访问
|
||||
|
||||
```bash
|
||||
# 检查Pod状态
|
||||
kubectl get pods -n argocd
|
||||
|
||||
# 查看日志
|
||||
kubectl logs -n argocd deployment/argocd-server
|
||||
|
||||
# 检查Service
|
||||
kubectl get svc -n argocd
|
||||
```
|
||||
|
||||
### GitOps同步失败
|
||||
|
||||
```bash
|
||||
# 查看Application详情
|
||||
kubectl describe application demo-app -n argocd
|
||||
|
||||
# 查看ArgoCD控制器日志
|
||||
kubectl logs -n argocd deployment/argocd-application-controller
|
||||
|
||||
# 测试ArgoCD到Gitea的连接
|
||||
kubectl exec -n argocd deployment/argocd-server -- curl -v http://gitea-http.gitea.svc.cluster.local:3000
|
||||
|
||||
# 检查Gitea仓库凭证
|
||||
kubectl get secret gitea-creds -n argocd -o yaml
|
||||
```
|
||||
|
||||
## 幂等性保证
|
||||
|
||||
### 什么是幂等性？
|
||||
|
||||
幂等性意味着脚本可以重复执行多次，每次都会产生相同的结果，不会破坏现有配置或产生错误。
|
||||
|
||||
### 本项目的幂等性实现
|
||||
|
||||
#### 1. 统一部署脚本 (`deploy-all.sh`)
|
||||
- ✅ **状态持久化**: 记录已完成的步骤到 `.deployment-state` 文件
|
||||
- ✅ **断点续传**: 失败后重新运行会跳过已完成的步骤
|
||||
- ✅ **重复执行安全**: 已完成的步骤会被自动跳过
|
||||
|
||||
#### 2. 工具依赖检查
|
||||
- ✅ **自动检测**: 检查工具是否已安装
|
||||
- ✅ **自动安装**: 缺失的工具自动安装
|
||||
- ✅ **重试机制**: 网络下载失败自动重试（最多3次）
|
||||
|
||||
#### 3. K3s部署 (`deploy.sh`)
|
||||
- ✅ 使用Ansible的幂等特性
|
||||
- ✅ 重复执行不会重新安装已存在的组件
|
||||
- ✅ kubectl配置自动检测和更新
|
||||
|
||||
#### 4. Gitea部署 (`deploy-gitea.sh`)
|
||||
- ✅ 使用Helm的幂等特性
|
||||
- ✅ 命名空间已存在时自动跳过创建
|
||||
- ✅ 重复执行会更新配置而不是重新安装
|
||||
|
||||
#### 5. ArgoCD部署 (`deploy-argocd.sh`)
|
||||
- ✅ 使用 `kubectl apply` 声明式部署
|
||||
- ✅ 自动检测htpasswd和yq工具
|
||||
- ✅ 密码更新使用patch操作，安全幂等
|
||||
|
||||
#### 6. HTTPS配置 (`deploy-https.sh`)
|
||||
- ✅ cert-manager CRDs和组件使用 `kubectl apply`
|
||||
- ✅ ClusterIssuer和Ingress可重复应用
|
||||
- ✅ 证书自动续期，无需手动干预
|
||||
|
||||
### 测试幂等性
|
||||
|
||||
重复执行部署脚本验证幂等性：
|
||||
|
||||
```bash
|
||||
# 第一次部署
|
||||
./scripts/deploy-all.sh
|
||||
|
||||
# 验证部署
|
||||
./scripts/verify-deployment.sh
|
||||
|
||||
# 重复执行（应该跳过所有已完成步骤）
|
||||
./scripts/deploy-all.sh
|
||||
|
||||
# 再次验证（状态应该不变）
|
||||
./scripts/verify-deployment.sh
|
||||
```
|
||||
|
||||
### 重装系统后的部署流程
|
||||
|
||||
1. **准备环境**:
|
||||
```bash
|
||||
# 创建fei用户（如果不存在）
|
||||
sudo useradd -m -s /bin/bash fei
|
||||
sudo passwd fei
|
||||
|
||||
# 配置sudo权限
|
||||
echo "fei ALL=(ALL) NOPASSWD:ALL" | sudo tee /etc/sudoers.d/fei
|
||||
```
|
||||
|
||||
2. **复制配置文件**:
|
||||
```bash
|
||||
# 备份配置文件
|
||||
cp config/cluster-vars.yml ~/cluster-vars.yml.backup
|
||||
|
||||
# 重装系统后恢复
|
||||
cp ~/cluster-vars.yml.backup config/cluster-vars.yml
|
||||
```
|
||||
|
||||
3. **一键部署**:
|
||||
```bash
|
||||
./scripts/deploy-all.sh
|
||||
```
|
||||
|
||||
4. **验证部署**:
|
||||
```bash
|
||||
./scripts/verify-deployment.sh
|
||||
```
|
||||
|
||||
### 常见问题
|
||||
|
||||
**Q: 部署失败后如何继续？**
|
||||
A: 直接重新运行 `./scripts/deploy-all.sh`，脚本会自动跳过已完成的步骤。
|
||||
|
||||
**Q: 如何从头开始部署？**
|
||||
A: 运行 `./scripts/deploy-all.sh --reset` 清除状态后重新部署。
|
||||
|
||||
**Q: 网络下载失败怎么办？**
|
||||
A: 脚本会自动重试3次，如果仍然失败，检查网络连接后重新运行。
|
||||
|
||||
**Q: 如何查看部署日志？**
|
||||
A: 查看 `deployment.log` 文件获取详细日志。
|
||||
|
||||
## 部署架构
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ K3s Cluster (3 nodes) │
|
||||
│ │
|
||||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ │ Master │ │ Worker 1 │ │ Worker 2 │ │
|
||||
│ │ 8.216.38.248 │ │ 8.216.41.97 │ │ 8.216.33.69 │ │
|
||||
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────┐ │
|
||||
│ │ Gitea (Private Git Server) │ │
|
||||
│ │ git.jpc.net3w.com (NodePort) │ │
|
||||
│ │ - Organization: k3s-apps │ │
|
||||
│ │ - Repository: demo-app │ │
|
||||
│ │ - User: argocd (for ArgoCD access) │ │
|
||||
│ └─────────────────────────────────────────────────────┘ │
|
||||
│ ↓ │
|
||||
│ (Git Sync) │
|
||||
│ ↓ │
|
||||
│ ┌─────────────────────────────────────────────────────┐ │
|
||||
│ │ ArgoCD (GitOps Engine) │ │
|
||||
│ │ argocd.jpc.net3w.com (NodePort) │ │
|
||||
│ │ - Monitors Gitea repository │ │
|
||||
│ │ - Auto-sync on Git push │ │
|
||||
│ │ - Deploys to K3s cluster │ │
|
||||
│ └─────────────────────────────────────────────────────┘ │
|
||||
│ ↓ │
|
||||
│ (Auto Deploy) │
|
||||
│ ↓ │
|
||||
│ ┌─────────────────────────────────────────────────────┐ │
|
||||
│ │ Application Workloads │ │
|
||||
│ │ - demo-nginx (example app) │ │
|
||||
│ │ - Managed by ArgoCD from Gitea │ │
|
||||
│ └─────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
|
||||
Developer Workflow:
|
||||
1. Developer pushes code to Gitea (git.jpc.net3w.com)
|
||||
2. ArgoCD detects changes (polling every 3 minutes)
|
||||
3. ArgoCD syncs and deploys to K3s cluster
|
||||
4. Application updates automatically
|
||||
```
|
||||
|
||||
## 后续优化
|
||||
|
||||
1. **配置Ingress**: 使用Traefik Ingress暴露服务
|
||||
- ArgoCD: argocd.jpc.net3w.com
|
||||
- Gitea: git.jpc.net3w.com
|
||||
2. **HTTPS证书**: 集成cert-manager + Let's Encrypt自动管理证书
|
||||
3. **RBAC配置**: 为不同团队配置Gitea和ArgoCD权限
|
||||
4. **多环境管理**: 使用ArgoCD ApplicationSet管理dev/staging/prod
|
||||
5. **监控告警**: 集成Prometheus和Grafana
|
||||
6. **备份方案**:
|
||||
- K3s etcd自动备份
|
||||
- Gitea数据持久化和备份
|
||||
7. **CI/CD集成**: 集成Gitea Actions或Jenkins
|
||||
8. **镜像仓库**: 部署Harbor私有镜像仓库
|
||||
9. **SSH密钥认证**: 替换密码认证提高安全性
|
||||
|
||||
## 参考资源
|
||||
|
||||
- [k3s-ansible项目](https://github.com/k3s-io/k3s-ansible)
|
||||
- [ArgoCD文档](https://argo-cd.readthedocs.io/)
|
||||
- [Gitea文档](https://docs.gitea.com/)
|
||||
- [K3s官方文档](https://docs.k3s.io/)
|
||||
|
||||
## 许可证
|
||||
|
||||
本项目使用MIT许可证。
|
||||
Reference in New Issue
Block a user