fix: 将 k3s-ansible 作为普通目录添加
This commit is contained in:
fei
461
DEPLOYMENT-GUIDE.md
Normal file
461
DEPLOYMENT-GUIDE.md
Normal file
@@ -0,0 +1,461 @@
|
||||
# K3s + GitOps 全自动化部署指南
|
||||
|
||||
面对一个新的集群，如何从零开始一步步搭建完整的K3s + GitOps自动化环境。
|
||||
|
||||
## 📋 目录
|
||||
|
||||
- [概述](#概述)
|
||||
- [前置准备](#前置准备)
|
||||
- [快速开始](#快速开始)
|
||||
- [详细步骤](#详细步骤)
|
||||
- [验证部署](#验证部署)
|
||||
- [故障排查](#故障排查)
|
||||
|
||||
---
|
||||
|
||||
## 概述
|
||||
|
||||
本项目提供了一套完整的K3s + GitOps自动化部署方案，适用于从零开始搭建新集群。
|
||||
|
||||
### 部署内容
|
||||
|
||||
- **K3s集群**: 轻量级Kubernetes集群（1 master + N worker）
|
||||
- **Gitea**: 私有Git服务器
|
||||
- **ArgoCD**: GitOps持续部署工具
|
||||
- **cert-manager**: 自动SSL证书管理
|
||||
- **Traefik**: Ingress控制器（K3s内置）
|
||||
|
||||
### 特点
|
||||
|
||||
- ✅ 完全自动化部署
|
||||
- ✅ 支持幂等性（可重复执行）
|
||||
- ✅ GitOps工作流
|
||||
- ✅ HTTPS自动配置
|
||||
- ✅ 配置参数化
|
||||
|
||||
---
|
||||
|
||||
## 前置准备
|
||||
|
||||
### 1. 硬件要求
|
||||
|
||||
| 角色 | 最低配置 | 推荐配置 |
|
||||
|------|---------|---------|
|
||||
| Master节点 | 2核4G | 4核8G |
|
||||
| Worker节点 | 2核4G | 4核8G |
|
||||
|
||||
### 2. 软件要求
|
||||
|
||||
**控制机（本地机器）**:
|
||||
```bash
|
||||
# Ubuntu/Debian
|
||||
sudo apt update
|
||||
sudo apt install -y python3 python3-pip git ansible sshpass
|
||||
|
||||
# macOS
|
||||
brew install python3 ansible git
|
||||
```
|
||||
|
||||
**目标节点（K3s集群）**:
|
||||
- Ubuntu 20.04+ / Debian 11+
|
||||
- SSH访问权限
|
||||
- sudo权限
|
||||
|
||||
### 3. 准备配置信息
|
||||
|
||||
需要收集以下信息：
|
||||
|
||||
```yaml
|
||||
# 节点信息
|
||||
- Master节点: 公网IP、内网IP、SSH用户、SSH密码
|
||||
- Worker节点: 公网IP、内网IP、SSH用户、SSH密码
|
||||
|
||||
# 域名（可选，用于HTTPS）
|
||||
- 主域名: example.com
|
||||
- ArgoCD域名: argocd.example.com
|
||||
- Gitea域名: git.example.com
|
||||
|
||||
# 密码
|
||||
- ArgoCD管理员密码
|
||||
- Gitea管理员密码
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 一键部署（推荐）
|
||||
|
||||
```bash
|
||||
# 1. 克隆项目
|
||||
git clone <your-repo-url>
|
||||
cd k3s自动化部署
|
||||
|
||||
# 2. 配置集群信息
|
||||
cp config/cluster-vars.yml.example config/cluster-vars.yml
|
||||
vim config/cluster-vars.yml # 填写实际配置
|
||||
|
||||
# 3. 执行部署
|
||||
chmod +x scripts/*.sh
|
||||
./scripts/deploy-all.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 详细步骤
|
||||
|
||||
### 步骤1: 配置集群参数
|
||||
|
||||
#### 1.1 创建配置文件
|
||||
|
||||
```bash
|
||||
cd k3s自动化部署
|
||||
cp config/cluster-vars.yml.example config/cluster-vars.yml
|
||||
vim config/cluster-vars.yml
|
||||
```
|
||||
|
||||
#### 1.2 配置示例
|
||||
|
||||
```yaml
|
||||
# 节点配置
|
||||
master_nodes:
|
||||
- hostname: k3s-master-01
|
||||
public_ip: "8.216.38.248" # 改为你的公网IP
|
||||
private_ip: "172.23.96.138" # 改为你的内网IP
|
||||
ssh_user: "root" # 改为你的SSH用户
|
||||
ssh_password: "your-password" # 改为你的SSH密码
|
||||
|
||||
worker_nodes:
|
||||
- hostname: k3s-worker-01
|
||||
public_ip: "8.216.41.97"
|
||||
private_ip: "172.23.96.139"
|
||||
ssh_user: "root"
|
||||
ssh_password: "your-password"
|
||||
|
||||
# K3s配置
|
||||
k3s_version: "v1.28.5+k3s1"
|
||||
flannel_iface: "eth0"
|
||||
target_dir: "/home/fei/k3s"
|
||||
|
||||
# 域名配置（可选）
|
||||
domain_name: "example.com"
|
||||
argocd_domain: "argocd.example.com"
|
||||
gitea_domain: "git.example.com"
|
||||
|
||||
# 密码配置
|
||||
argocd_admin_password: "YourStrongPassword123!"
|
||||
gitea_admin_password: "YourStrongPassword123!"
|
||||
```
|
||||
|
||||
### 步骤2: 部署K3s集群
|
||||
|
||||
```bash
|
||||
# 生成inventory
|
||||
python3 scripts/generate-inventory.py
|
||||
|
||||
# 部署K3s
|
||||
cd k3s-ansible
|
||||
ansible-playbook site.yml -i inventory/hosts.ini
|
||||
|
||||
# 验证集群
|
||||
ssh user@master-ip
|
||||
kubectl get nodes
|
||||
```
|
||||
|
||||
**预期输出**:
|
||||
```
|
||||
NAME STATUS ROLES AGE VERSION
|
||||
k3s-master-01 Ready control-plane,master 5m v1.28.5+k3s1
|
||||
k3s-worker-01 Ready <none> 4m v1.28.5+k3s1
|
||||
```
|
||||
|
||||
### 步骤3: 部署Gitea
|
||||
|
||||
```bash
|
||||
# 部署Gitea
|
||||
./scripts/deploy-gitea.sh
|
||||
|
||||
# 初始化Gitea
|
||||
./scripts/setup-gitea.sh
|
||||
|
||||
# 获取访问地址
|
||||
kubectl get svc -n gitea gitea-http
|
||||
```
|
||||
|
||||
**访问**: `http://<MASTER_IP>:<NODEPORT>`
|
||||
|
||||
### 步骤4: 部署ArgoCD
|
||||
|
||||
```bash
|
||||
# 部署ArgoCD
|
||||
./scripts/deploy-argocd.sh
|
||||
|
||||
# 获取访问地址
|
||||
kubectl get svc -n argocd argocd-server
|
||||
```
|
||||
|
||||
**访问**: `https://<MASTER_IP>:<NODEPORT>`
|
||||
|
||||
### 步骤5: 配置HTTPS（可选）
|
||||
|
||||
#### 5.1 前置条件
|
||||
|
||||
- DNS已解析到master节点公网IP
|
||||
- 云服务器安全组已开放80和443端口
|
||||
|
||||
#### 5.2 部署cert-manager
|
||||
|
||||
```bash
|
||||
# 在master节点上执行
|
||||
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.13.3/cert-manager.yaml
|
||||
|
||||
# 等待就绪
|
||||
kubectl wait --for=condition=ready pod -l app.kubernetes.io/instance=cert-manager -n cert-manager --timeout=300s
|
||||
```
|
||||
|
||||
#### 5.3 创建ClusterIssuer
|
||||
|
||||
```bash
|
||||
kubectl apply -f - <<EOF
|
||||
apiVersion: cert-manager.io/v1
|
||||
kind: ClusterIssuer
|
||||
metadata:
|
||||
name: letsencrypt-prod
|
||||
spec:
|
||||
acme:
|
||||
server: https://acme-v02.api.letsencrypt.org/directory
|
||||
email: admin@example.com
|
||||
privateKeySecretRef:
|
||||
name: letsencrypt-prod
|
||||
solvers:
|
||||
- http01:
|
||||
ingress:
|
||||
class: traefik
|
||||
EOF
|
||||
```
|
||||
|
||||
#### 5.4 配置ArgoCD HTTPS
|
||||
|
||||
```bash
|
||||
# 配置ArgoCD insecure模式
|
||||
kubectl patch configmap argocd-cmd-params-cm -n argocd --type merge -p '{"data":{"server.insecure":"true"}}'
|
||||
|
||||
# 重启ArgoCD
|
||||
kubectl rollout restart deployment argocd-server -n argocd
|
||||
|
||||
# 创建HTTPS Ingress
|
||||
kubectl apply -f - <<EOF
|
||||
apiVersion: networking.k8s.io/v1
|
||||
kind: Ingress
|
||||
metadata:
|
||||
name: argocd-server-tls
|
||||
namespace: argocd
|
||||
annotations:
|
||||
traefik.ingress.kubernetes.io/router.entrypoints: websecure
|
||||
traefik.ingress.kubernetes.io/router.tls: "true"
|
||||
cert-manager.io/cluster-issuer: letsencrypt-prod
|
||||
spec:
|
||||
tls:
|
||||
- hosts:
|
||||
- argocd.example.com
|
||||
secretName: argocd-tls-cert
|
||||
rules:
|
||||
- host: argocd.example.com
|
||||
http:
|
||||
paths:
|
||||
- path: /
|
||||
pathType: Prefix
|
||||
backend:
|
||||
service:
|
||||
name: argocd-server
|
||||
port:
|
||||
number: 80
|
||||
EOF
|
||||
```
|
||||
|
||||
### 步骤6: 创建示例应用
|
||||
|
||||
```bash
|
||||
# 在master节点上执行
|
||||
cd /home/fei/k3s
|
||||
mkdir -p demo-app/manifests
|
||||
|
||||
# 创建Deployment
|
||||
cat > demo-app/manifes/deployment.yaml <<EOF
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: demo-nginx
|
||||
spec:
|
||||
replicas: 2
|
||||
selector:
|
||||
matchLabels:
|
||||
app: demo-nginx
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
app: demo-nginx
|
||||
spec:
|
||||
containers:
|
||||
- name: nginx
|
||||
image: nginx:1.25-alpine
|
||||
ports:
|
||||
- containerPort: 80
|
||||
EOF
|
||||
|
||||
# 推送到Gitea
|
||||
cd demo-app
|
||||
git init -b main
|
||||
git add .
|
||||
git commit -m "Initial commit"
|
||||
GITEA_PORT=$(kubectl get svc gitea-http -n gitea -o jsonpath='{.spec.ports[0].nodePort}')
|
||||
git remote add origin http://argocd:ArgoCD%402026@localhost:$3s-apps/demo-app.git
|
||||
git push -u origin main
|
||||
|
||||
# 创建ArgoCD应用
|
||||
kubectl apply -f - <<EOF
|
||||
apiVersion: argoproj.io/v1alpha1
|
||||
kind: Application
|
||||
metadata:
|
||||
name: demo-app
|
||||
namespace: argocd
|
||||
spec:
|
||||
project: default
|
||||
source:
|
||||
repoURL: http://gitea-http.gitea.svc.cluster.local:3000/k3s-apps/demo-app.git
|
||||
targetRevision: main
|
||||
path: manifests
|
||||
destination:
|
||||
server: https://kubernetes.default.svc
|
||||
namespace: default
|
||||
syncPolicy:
|
||||
automated:
|
||||
prune: true
|
||||
selfHeal: true
|
||||
EOF
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 验证部署
|
||||
|
||||
### 完整验证清单
|
||||
|
||||
```bash
|
||||
# 1. 验证K3s集群
|
||||
kubectl get nodes # 所有节点应为Ready
|
||||
kubectl get pods -A # 所有Pod应为Running
|
||||
|
||||
# 2. 验证Gitea
|
||||
kubectl get pods -n gitea # Gitea Pod应为Running
|
||||
|
||||
# 3. 验证ArgoCD
|
||||
kubectl get pods -n argocd # 所有ArgoCD Pod应为Running
|
||||
kubectl get application -n argocd # 应用应为Synced和Healthy
|
||||
|
||||
# 4. 验证HTTPS（如果已配置）
|
||||
kubectl get certificate -A # 证书应为Ready
|
||||
|
||||
# 5. 验证GitOps工作流
|
||||
# 修改应用配置 → 提交Git → 等待3分钟 → 自动部署
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 故障排查
|
||||
|
||||
### 问题1: 节点无法加入集群
|
||||
|
||||
```bash
|
||||
# 检查网络连通性
|
||||
ping <master-private-ip>
|
||||
|
||||
# 检查K3s服务
|
||||
sudo systemctl status k3s-agent
|
||||
sudo journalctl -u k3s-agent -f
|
||||
```
|
||||
|
||||
### 问题2: 外部无法访问服务
|
||||
|
||||
```bash
|
||||
# 检查云服务器安全组
|
||||
# 开放端口: 80, 443, 30000-32767
|
||||
|
||||
# 从master节点内部测试
|
||||
curl http://localhost:30080
|
||||
```
|
||||
|
||||
### 问题3: HTTPS证书申请失败
|
||||
|
||||
```bash
|
||||
# 检查DNS解析
|
||||
nslookup argocd.example.com
|
||||
|
||||
# 检查cert-manager日志
|
||||
kubectl logs -n cert-manager deployment/cert-manager
|
||||
|
||||
# 查看证书详情
|
||||
kubectl describe certificate <cert-name> -n <namespace>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 架构说明
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ K3s Cluster │
|
||||
│ │
|
||||
│ Master + Workers │
|
||||
│ ↓ │
|
||||
│ Gitea (Git Server) │
|
||||
│ ↓ │
|
||||
│ ArgoCD (GitOps) │
|
||||
│ ↓ │
|
||||
│ cert-manager (SSL) │
|
||||
│ ↓ │
|
||||
│ Traefik (Ingress) │
|
||||
│ ↓ │
|
||||
│ Applications │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### GitOps工作流
|
||||
|
||||
```
|
||||
开发者修改代码
|
||||
↓
|
||||
提交到Git (Gitea)
|
||||
↓
|
||||
ArgoCD检测变化 (3分钟内)
|
||||
↓
|
||||
自动同步到集群
|
||||
↓
|
||||
应用自动更新
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 总结
|
||||
|
||||
按照本指南，您可以在30-60分钟内完成：
|
||||
|
||||
- ✅ K3s集群部署
|
||||
- ✅ Gitea私有Git服务器
|
||||
- ✅ ArgoCD GitOps引擎
|
||||
- ✅ HTTPS自动证书
|
||||
- ✅ 示例应用
|
||||
|
||||
所有配置都支持幂等性，可以安全重复执行。
|
||||
|
||||
**祝您部署顺利！** 🚀
|
||||
|
||||
---
|
||||
|
||||
## 参考文档
|
||||
|
||||
- [README-DEPLOYMENT.md](README-DEPLOYMENT.md) - 详细部署文档
|
||||
- [USAGE-GUIDE.md](USAGE-GUIDE.md) - 使用指南
|
||||
- [SUMMARY.md](SUMMARY.md) - 完整总结
|
||||
- [QUICK-REFERENCE.md](QUICK-REFERENCE.md) - 快速参考
|
||||
- [TROUBLESHOOTING-ACCESS.md](TROUBLESHOOTING-ACCESS.md) - 访问问题排查
|
||||
Reference in New Issue
Block a user