nginx/DEPLOYMENT-SUMMARY.md
huangzhiqiang e1c681bfe9
Some checks failed
Build NGINX on Ubuntu / build-nginx (push) Failing after 1m3s
fix action for k8s deploy
2025-06-07 17:50:51 +08:00

232 lines
5.5 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Kubernetes 自动部署优化总结
## 🎯 主要改进
### 1. kubectl 智能安装检查
**问题**: 原来的配置会无条件下载和安装 kubectl即使系统已经安装。
**解决方案**:
- 添加 `command -v kubectl` 检查
- 只在 kubectl 不存在时才安装
- 提供详细的版本信息反馈
- 添加备用安装方法apt 包管理器)
```bash
# 改进前
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
# 改进后
if ! command -v kubectl &> /dev/null; then
echo "kubectl 未安装,开始安装最新版本..."
# 安装逻辑...
else
echo "kubectl 已存在,当前版本: $(kubectl version --client)"
fi
```
### 2. 增强错误处理和验证
**改进内容**:
- KUBE_CONFIG base64 解码验证
- Kubernetes 集群连接测试
- 详细的错误提示和排查建议
- 安装失败时的备用方案
### 3. 完整的部署工具链
#### 📁 新增文件结构
```
k8s/
├── deploy.sh # Linux/macOS 自动部署脚本
├── deploy.bat # Windows 自动部署脚本
├── quickstart.sh # 交互式快速启动
├── nginx-deployment.yaml # K8s 部署配置
├── Makefile # 简化操作命令
├── .env.template # 环境变量模板
└── README.md # 详细部署文档
```
#### 🛠️ 多种部署方式
1. **快速启动(新手友好)**
```bash
./quickstart.sh # 交互式配置向导
```
2. **脚本自动化(运维推荐)**
```bash
./deploy.sh # 一键部署
```
3. **Make 命令(开发推荐)**
```bash
make deploy # 部署
make status # 查看状态
make logs # 查看日志
make scale REPLICAS=5 # 扩缩容
```
### 4. CI/CD 集成优化
#### GitHub Actions 改进
- **条件部署**: 仅在 main 分支推送时触发 K8s 部署
- **智能检查**: 验证所需 secrets 是否配置
- **详细日志**: 每个步骤都有清晰的状态输出
- **失败处理**: 提供具体的错误原因和解决建议
#### 环境变量和 Secrets
| Secret | 用途 | 必需性 |
|--------|------|--------|
| `HARBOR_REGISTRY` | Harbor 仓库地址 | 必需 |
| `HARBOR_USERNAME` | Harbor 用户名 | 必需 |
| `HARBOR_PASSWORD` | Harbor 密码 | 必需 |
| `KUBE_CONFIG` | base64 编码的 kubeconfig | K8s 部署时必需 |
| `K8S_NAMESPACE` | K8s 命名空间 | 可选,默认 default |
## 🚀 使用流程
### 首次设置
1. **配置 GitHub Secrets**
```bash
# 必需的 Harbor 配置
HARBOR_REGISTRY=harbor.example.com
HARBOR_USERNAME=admin
HARBOR_PASSWORD=your-password
# K8s 部署配置(可选)
KUBE_CONFIG=<base64-encoded-kubeconfig>
K8S_NAMESPACE=production
```
2. **生成 KUBE_CONFIG**
```bash
# 方法一:使用现有 kubeconfig
cat ~/.kube/config | base64 -w 0
# 方法二:创建服务账户
kubectl create serviceaccount github-actions
kubectl create clusterrolebinding github-actions \
--clusterrole=cluster-admin \
--serviceaccount=default:github-actions
```
### 自动化流程
1. **推送代码** → 触发 CI/CD
2. **构建 NGINX** → 编译和测试
3. **构建镜像** → Docker 镜像打包
4. **推送 Harbor** → 上传到私有仓库
5. **部署 K8s** → 自动部署到集群(仅 main 分支)
### 本地管理
```bash
cd k8s
# 快速开始
./quickstart.sh
# 查看状态
make status
# 查看日志
make logs
# 扩缩容
make scale REPLICAS=5
# 更新镜像
make update NGINX_IMAGE_TAG=v2.0.0
# 回滚
make rollback
# 清理
make clean
```
## 🔍 故障排除
### kubectl 相关问题
1. **安装失败**
- 网络问题:自动尝试 apt 安装
- 权限问题:检查 sudo 权限
2. **连接失败**
- 检查 KUBE_CONFIG 格式
- 验证集群网络访问
- 确认证书有效性
### Harbor 相关问题
1. **登录失败**
- 验证用户名密码
- 检查仓库访问权限
2. **推送失败**
- 确认项目存在
- 检查存储配额
### 部署相关问题
1. **镜像拉取失败**
- 验证 Harbor 凭据 Secret
- 检查镜像标签是否正确
2. **Pod 启动失败**
- 查看 Pod 日志:`make logs`
- 检查资源配额
- 验证配置文件
## 🔐 安全最佳实践
1. **最小权限原则**
- 为 CI/CD 创建专用服务账户
- 只授予必要的 K8s 权限
- 定期轮换访问凭据
2. **网络安全**
- Harbor 启用 HTTPS
- K8s 集群网络策略
- 防火墙规则配置
3. **镜像安全**
- 启用 Harbor 漏洞扫描
- 使用非 root 用户运行
- 定期更新基础镜像
## 📊 监控和维护
### 日常操作
```bash
# 查看部署状态
make status
# 监控日志
make logs
# 性能监控
kubectl top pods -l app=nginx
# 事件查看
kubectl get events --sort-by=.metadata.creationTimestamp
```
### 维护任务
- 定期更新镜像版本
- 监控资源使用情况
- 备份关键配置
- 更新安全证书
## 🎉 总结
通过这次优化,我们实现了:
1. **智能化**: kubectl 安装检查,避免重复操作
2. **自动化**: 完整的 CI/CD 到 K8s 部署流程
3. **用户友好**: 多种部署方式,适合不同技术水平
4. **健壮性**: 详细的错误处理和恢复机制
5. **可维护性**: 完善的工具链和监控机制
现在您可以:
- 推送代码自动触发构建和部署
- 本地快速管理 K8s 部署
- 灵活选择部署方式
- 轻松排查和解决问题
这套解决方案为 NGINX 项目提供了产品级的 CI/CD 和 K8s 部署能力!