fix: 将 k3s-ansible 作为普通目录添加
This commit is contained in:
fei
426
USAGE-GUIDE.md
Normal file
426
USAGE-GUIDE.md
Normal file
@@ -0,0 +1,426 @@
|
||||
# K3s + GitOps 使用指南
|
||||
|
||||
## 📊 当前部署状态总结
|
||||
|
||||
### ✅ 1. 幂等性配置已修复
|
||||
|
||||
所有配置文件已经修复，支持完全幂等性部署：
|
||||
|
||||
- ✅ **inventory/hosts.ini**: 使用正确的组名 `server` 和 `agent`
|
||||
- ✅ **api_endpoint**: 配置为内网IP `172.23.96.138`
|
||||
- ✅ **worker节点**: 使用内网IP连接master，配置正确的token
|
||||
- ✅ **验证**: 最后一次Ansible运行显示 `changed=0`，配置稳定
|
||||
|
||||
**可以安全地重复运行部署脚本，不会出错！**
|
||||
|
||||
### ✅ 2. 测试项目已创建
|
||||
|
||||
已创建完整的测试应用 `test-app`，包含：
|
||||
|
||||
- **应用**: 2个nginx副本，带自定义HTML页面
|
||||
- **Service**: NodePort 30081
|
||||
- **Ingress**: 域名访问 `test.jpc.net3w.com`
|
||||
- **Git仓库**: http://8.216.38.248:32158/k3s-apps/test-app
|
||||
- **ArgoCD应用**: 自动同步部署
|
||||
|
||||
## 🌐 访问方式
|
||||
|
||||
### 1. NodePort访问（直接可用）
|
||||
```bash
|
||||
# 通过任意节点访问
|
||||
curl http://8.216.38.248:30081
|
||||
curl http://8.216.41.97:30081
|
||||
curl http://8.216.33.69:30081
|
||||
```
|
||||
|
||||
### 2. 域名访问（需要DNS配置）
|
||||
|
||||
**方式A: 配置本地hosts文件（测试用）**
|
||||
```bash
|
||||
# Linux/Mac
|
||||
sudo echo "8.216.38.248 test.jpc.net3w.com" >> /etc/hosts
|
||||
|
||||
# Windows (管理员权限)
|
||||
# 编辑 C:\Windows\System32\drivers\etc\hosts
|
||||
# 添加: 8.216.38.248 test.jpc.net3w.com
|
||||
```
|
||||
|
||||
**方式B: 配置DNS解析（生产用）**
|
||||
在你的域名DNS管理面板添加A记录：
|
||||
```
|
||||
test.jpc.net3w.com → 8.216.38.248
|
||||
```
|
||||
|
||||
配置后访问：
|
||||
```bash
|
||||
curl http://test.jpc.net3w.com
|
||||
# 或在浏览器打开: http://test.jpc.net3w.com
|
||||
```
|
||||
|
||||
## 🔄 更新应用演示
|
||||
|
||||
### 方式1: 使用更新脚本（推荐）
|
||||
|
||||
在master节点上执行：
|
||||
```bash
|
||||
ssh fei@8.216.38.248
|
||||
cd /home/fei/k3s/test-app
|
||||
|
||||
# 更新到v2.0（粉红色背景）
|
||||
./update-app.sh v2.0
|
||||
|
||||
# 更新到v3.0（蓝色背景）
|
||||
./update-app.sh v3.0
|
||||
|
||||
# 更新到v4.0（绿色背景）
|
||||
./update-app.sh v4.0
|
||||
```
|
||||
|
||||
### 方式2: 手动修改并提交
|
||||
|
||||
```bash
|
||||
ssh fei@8.216.38.248
|
||||
cd /home/fei/k3s/test-app
|
||||
|
||||
# 1. 修改配置
|
||||
vim manifests/deployment.yaml
|
||||
# 修改 ConfigMap 中的内容，比如版本号、颜色等
|
||||
|
||||
# 2. 提交到Git
|
||||
git add .
|
||||
git commit -m "Update to v2.0"
|
||||
git push
|
||||
|
||||
# 3. 等待ArgoCD自动同步（3分钟内）
|
||||
kubectl get application test-app -n argocd -w
|
||||
```
|
||||
|
||||
### 查看更新状态
|
||||
|
||||
```bash
|
||||
# 查看ArgoCD应用状态
|
||||
kubectl get application test-app -n argocd
|
||||
|
||||
# 查看Pod状态
|
||||
kubectl get pods -l app=test-app
|
||||
|
||||
# 查看实时日志
|
||||
kubectl logs -f -l app=test-app
|
||||
|
||||
# 访问应用验证更新
|
||||
curl http://8.216.38.248:30081 | grep Version
|
||||
```
|
||||
|
||||
## 📦 将部署配置存入Git
|
||||
|
||||
### 1. 初始化Git仓库
|
||||
|
||||
```bash
|
||||
cd /home/fei/opk3s/k3s自动化部署
|
||||
|
||||
# 初始化Git
|
||||
git init -b main
|
||||
|
||||
# 添加文件
|
||||
git add .gitignore
|
||||
git add README-DEPLOYMENT.md
|
||||
git add USAGE-GUIDE.md
|
||||
git add config/cluster-vars.yml.example
|
||||
git add scripts/
|
||||
git add k3s-ansible/inventory/hosts.ini
|
||||
|
||||
# 提交
|
||||
git commit -m "Initial commit: K3s deployment configuration"
|
||||
```
|
||||
|
||||
### 2. 推送到远程仓库
|
||||
|
||||
**选项A: 推送到Gitea（内部）**
|
||||
```bash
|
||||
# 在Gitea创建仓库 k3s-deployment
|
||||
# 然后推送
|
||||
git remote add origin http://8.216.38.248:32158/k3s-apps/k3s-deployment.git
|
||||
git push -u origin main
|
||||
```
|
||||
|
||||
**选项B: 推送到GitHub/GitLab（外部）**
|
||||
```bash
|
||||
# 创建GitHub仓库后
|
||||
git remote add origin https://github.com/YOUR_USERNAME/k3s-deployment.git
|
||||
git push -u origin main
|
||||
```
|
||||
|
||||
### 3. 下次更新配置
|
||||
|
||||
```bash
|
||||
# 修改配置文 config/cluster-vars.yml
|
||||
|
||||
# 重新生成inventory
|
||||
python3 scripts/generate-inventory.py
|
||||
|
||||
# 提交更改
|
||||
git add k3s-ansible/inventory/hosts.ini
|
||||
git commit -m "Update cluster configuration"
|
||||
git push
|
||||
|
||||
# 重新部署（幂等操作）
|
||||
cd k3s-ansible
|
||||
ansible-playbook site.yml -i inventory/hosts.ini -e "@../config/cluster-vars.yml"
|
||||
```
|
||||
|
||||
## 🚀 创建新的应用
|
||||
|
||||
### 1. 在Gitea创建新仓库
|
||||
|
||||
```bash
|
||||
ssh fei@8.216.38.248
|
||||
cd /home/fei/k3s
|
||||
|
||||
# 创建新应用目录
|
||||
mkdir -p my-new-app/manifests
|
||||
|
||||
# 创建Kubernetes清单
|
||||
cat > my-new-app/manifests/deployment.yaml << 'EOF'
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: my-new-app
|
||||
namespace: default
|
||||
spec:
|
||||
replicas: 2
|
||||
selector:
|
||||
matchLabels:
|
||||
app: my-new-app
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
app: my-new-app
|
||||
spec:
|
||||
containers:
|
||||
- name: app
|
||||
image: nginx:alpine
|
||||
ports:
|
||||
- containerPort: 80
|
||||
EOF
|
||||
|
||||
# 创建Service
|
||||
cat > my-new-app/manifests/service.yaml << 'EOF'
|
||||
apiVersion: v1
|
||||
kind: Service
|
||||
metadata:
|
||||
name: my-new-app
|
||||
namespace: default
|
||||
spec:
|
||||
type: NodePort
|
||||
selector:
|
||||
app: my-new-app
|
||||
ports:
|
||||
- port: 80
|
||||
targetPort: 80
|
||||
nodePort: 30082
|
||||
EOF
|
||||
|
||||
# 初始化Git并推送
|
||||
cd my-new-app
|
||||
git init -b main
|
||||
git add .
|
||||
git commit -m "Initial commit"
|
||||
|
||||
# 推送到Gitea（需要先在Gitea创建仓库）
|
||||
git remote add origin http://argocd:ArgoCD%402026@localhost:32158/k3s-apps/my-new-app.git
|
||||
git push -u origin main
|
||||
```
|
||||
|
||||
### 2. 创建ArgoCD应用
|
||||
|
||||
```bash
|
||||
kubectl apply -f - << 'EOF'
|
||||
apiVersion: argoproj.io/v1alpha1
|
||||
kind: Application
|
||||
metadata:
|
||||
name: my-new-app
|
||||
namespace: argocd
|
||||
spec:
|
||||
project: default
|
||||
source:
|
||||
repoURL: http://gitea-http.gitea.svc.cluster.local:3000/k3s-apps/my-new-app.git
|
||||
targetRevision: main
|
||||
path: manifests
|
||||
destination:
|
||||
server: https://kubernetes.default.svc
|
||||
namespace: default
|
||||
syncPolicy:
|
||||
automated:
|
||||
prune: true
|
||||
selfHeal: true
|
||||
EOF
|
||||
```
|
||||
|
||||
## 📊 监控和管理
|
||||
|
||||
### ArgoCD Web UI
|
||||
- **URL**: https://8.216.38.248:31875
|
||||
- **用户名**: admin
|
||||
- **密码**: ArgoAdmin@2026
|
||||
|
||||
功能：
|
||||
- 查看所有应用的同步状态
|
||||
- 手动触发同步
|
||||
- 查看部署历史
|
||||
- 回滚到之前的版本
|
||||
|
||||
### Gitea Web UI
|
||||
- **URL**: http://8.216.38.248:32158
|
||||
- **管理员**: gitea_admin / GitAdmin@2026
|
||||
- **ArgoCD用户**: argocd / ArgoCD@2026
|
||||
|
||||
功能：
|
||||
- 管理Git仓库
|
||||
- 查看提交历史
|
||||
- 创建新仓库
|
||||
- 管理用户和权限
|
||||
|
||||
### 命令行管理
|
||||
|
||||
```bash
|
||||
# 查看所有ArgoCD应用
|
||||
kubectl get application -n argocd
|
||||
|
||||
# 查看应用详情
|
||||
kubectl describe application test-app -n argocd
|
||||
|
||||
# 手动触发同步
|
||||
kubectl patch application test-app -n --type merge -p '{"metadotations":{"argocd.argoproj.io/refresh":"hard"}}}'
|
||||
|
||||
# 查看所有Pod
|
||||
kubectl get pods -A
|
||||
|
||||
# 查看特定应用的Pod
|
||||
kubectl get pods -l app=test-app
|
||||
|
||||
# 查看Ingress
|
||||
kubectl get ingress -A
|
||||
```
|
||||
|
||||
## 🔧 故障排查
|
||||
|
||||
### 应用无法访问
|
||||
|
||||
1. **检查Pod状态**
|
||||
```bash
|
||||
kubectl get pods -l app=test-app
|
||||
kubectl describe pod <pod-name>
|
||||
kubectl logs <pod-name>
|
||||
```
|
||||
|
||||
2. **检查Service**
|
||||
```bash
|
||||
kubectl get svc test-app
|
||||
kubectl describe svc test-app
|
||||
```
|
||||
|
||||
3. **检查Ingress**
|
||||
```bash
|
||||
kubectl get ingress test-app
|
||||
kubectl describe ingress test-app
|
||||
```
|
||||
|
||||
### ArgoCD同步失败
|
||||
|
||||
1. **查看应用状态**
|
||||
```bash
|
||||
kubectl get application test-app -n argocd
|
||||
kubectl describe application test-app -n argocd
|
||||
```
|
||||
|
||||
2. **查看ArgoCD日志**
|
||||
```bash
|
||||
kubectl logs -n argocd deployment/argocd-application-controller
|
||||
kubectl logs -n argocd deployment/argocd-repo-server
|
||||
```
|
||||
|
||||
3. **检查Git仓库连接**
|
||||
```bash
|
||||
# 在master节点测试
|
||||
curl http://gitea-http.gitea.svc.cluster.local:3000/k3s-apps/test-app.git
|
||||
```
|
||||
|
||||
### 域名无法访问
|
||||
|
||||
1. **检查DNS解析**
|
||||
```bash
|
||||
nslookup test.jpc.net3w.com
|
||||
# 或
|
||||
dig test.jpc.net3w.com
|
||||
```
|
||||
|
||||
2. **检查Traefik Ingress Controller**
|
||||
```bash
|
||||
kubectl get pods -n kube-system -l app.kubernetes.io/name=traefik
|
||||
kubectl logs -n kube-system -l app.kubernetes.io/name=traefik
|
||||
```
|
||||
|
||||
3. **临时使用hosts文件**
|
||||
```bash
|
||||
# 添加到 /etc/hosts
|
||||
8.216.38.248 test.jpc.net3w.com
|
||||
```
|
||||
|
||||
## 📝 最佳实践
|
||||
|
||||
1. **使用Git管理所有配置**
|
||||
- 所有Kubernetes清单文件都应该在Git中
|
||||
- 使用分支管理不同环境（dev/staging/prod）
|
||||
|
||||
2. **定期备份**
|
||||
- 备份Gitea数据：`kubectl exec -n gitea <pod> -- tar czf /tmp/backup.tar.gz /data`
|
||||
- 备份ArgoCD配置：`kubectl get application -n argocd -o yaml > argocd-apps-backup.yaml`
|
||||
|
||||
3. **监控资源使用**
|
||||
```bash
|
||||
kubectl top nodes
|
||||
kubectl top pods -A
|
||||
```
|
||||
|
||||
4. **使用命名空间隔离应用**
|
||||
```bash
|
||||
kubectl create namespace production
|
||||
kubectl create namespace staging
|
||||
```
|
||||
|
||||
5. **配置资源限制**
|
||||
在Deployment中添加：
|
||||
```yaml
|
||||
resources:
|
||||
requests:
|
||||
memory: "64Mi"
|
||||
cpu: "100m"
|
||||
limits:
|
||||
memory: "128Mi"
|
||||
cpu: "200m"
|
||||
```
|
||||
|
||||
## 🎯 下一步
|
||||
|
||||
1. **配置HTTPS**
|
||||
- 安装cert-manager
|
||||
- 配置Let's Encrypt自动证书
|
||||
|
||||
2. **添加监控**
|
||||
- 部署Prometheus + Grafana
|
||||
- 配置告警规则
|
||||
|
||||
3. **配置CI/CD**
|
||||
- 集成Gitea Actions或Jenkins
|
||||
- 自动构建Docker镜像
|
||||
|
||||
4. **多环境管理**
|
||||
- 使用ArgoCD ApplicationSet
|
||||
- 管理dev/staging/prod环境
|
||||
|
||||
## 📞 获取帮助
|
||||
|
||||
- **ArgoCD文档**: https://argo-cd.readthedocs.io/
|
||||
- **K3s文档**: https://docs.k3s.io/
|
||||
- **Gitea文档**: https://docs.gitea.io/
|
||||
- **Kubernetes文档**: https://kubernetes.io/docs/
|
||||
Reference in New Issue
Block a user