nginx/k8s/README.md

# Kubernetes 部署指南

本指南详细说明了如何将构建好的 NGINX Docker 镜像从私有 Harbor 仓库部署到 Kubernetes 集群。

## 📋 目录结构

```
k8s/
├── deploy.sh                    # Linux/macOS 自动部署脚本
├── deploy.bat                   # Windows 自动部署脚本
├── nginx-deployment.yaml        # Kubernetes 部署配置
├── .env.template                # 环境变量模板
└── README.md                   # 本文档
```

## 🚀 快速开始

### 方法一：使用自动部署脚本（推荐）

1. **设置环境变量**
   ```bash
   # Linux/macOS
   export HARBOR_REGISTRY=harbor.example.com
   export HARBOR_USERNAME=your-username
   export HARBOR_PASSWORD=your-password
   export NGINX_IMAGE_TAG=latest  # 或使用 ${GITHUB_SHA}
   ```
   
   ```cmd
   REM Windows
   set HARBOR_REGISTRY=harbor.example.com
   set HARBOR_USERNAME=your-username
   set HARBOR_PASSWORD=your-password
   set NGINX_IMAGE_TAG=latest
   ```

2. **运行部署脚本**
   ```bash
   # Linux/macOS
   chmod +x deploy.sh
   ./deploy.sh
   
   # Windows
   deploy.bat
   ```

### 方法二：使用环境变量文件

1. **创建环境变量文件**
   ```bash
   cp .env.template .env
   # 编辑 .env 文件，填入实际的配置值
   ```

2. **运行部署脚本**
   ```bash
   # 脚本会自动加载 .env 文件
   ./deploy.sh
   ```

### 方法三：手动部署

1. **创建 Harbor 仓库访问凭据**
   ```bash
   kubectl create secret docker-registry harbor-registry-secret \
     --docker-server=harbor.example.com \
     --docker-username=your-username \
     --docker-password=your-password \
     --namespace=default
   ```

2. **更新部署文件中的镜像标签**
   ```bash
   # 编辑 nginx-deployment.yaml，替换镜像标签
   # 将 harbor.example.com/test/nginx:latest 替换为实际的镜像地址
   ```

3. **应用 Kubernetes 配置**
   ```bash
   kubectl apply -f nginx-deployment.yaml
   ```

4. **检查部署状态**
   ```bash
   kubectl get pods -l app=nginx
   kubectl get services -l app=nginx
   ```

## 🔧 配置说明

### 环境变量

| 变量名 | 描述 | 必需 | 默认值 |
|--------|------|------|--------|
| `HARBOR_REGISTRY` | Harbor 仓库地址 | 是 | - |
| `HARBOR_USERNAME` | Harbor 用户名 | 是 | - |
| `HARBOR_PASSWORD` | Harbor 密码 | 是 | - |
| `NGINX_IMAGE_TAG` | NGINX 镜像标签 | 是 | - |
| `NAMESPACE` | Kubernetes 命名空间 | 否 | `default` |
| `DEPLOYMENT_FILE` | 部署配置文件路径 | 否 | `./nginx-deployment.yaml` |

### Kubernetes 资源

部署文件包含以下 Kubernetes 资源：

1. **ConfigMap** (`nginx-config`)
   - 包含 NGINX 配置文件
   - 自定义日志格式和访问控制

2. **Deployment** (`nginx-deployment`)
   - 3 个副本的 NGINX Pod
   - 从私有 Harbor 仓库拉取镜像
   - 包含健康检查和资源限制

3. **Service** (`nginx-service`)
   - NodePort 类型（端口 30080）
   - 可以改为 LoadBalancer 或 ClusterIP

4. **HPA** (`nginx-hpa`)
   - 水平自动伸缩
   - 基于 CPU 使用率（目标 70%）
   - 副本数范围：3-10

5. **PodDisruptionBudget** (`nginx-pdb`)
   - 确保更新期间的可用性
   - 最小可用副本数：2

## 🔍 验证部署

### 检查 Pod 状态
```bash
kubectl get pods -l app=nginx -o wide
```

### 检查服务状态
```bash
kubectl get services -l app=nginx
```

### 查看日志
```bash
# 查看特定 Pod 的日志
kubectl logs -l app=nginx -f

# 查看所有 NGINX Pod 的日志
kubectl logs -l app=nginx --all-containers=true -f
```

### 访问应用

根据服务类型不同，访问方式如下：

1. **NodePort**（默认）
   ```bash
   # 获取节点 IP 和端口
   kubectl get nodes -o wide
   kubectl get service nginx-service
   # 访问 http://<node-ip>:30080
   ```

2. **LoadBalancer**
   ```bash
   # 等待外部 IP 分配
   kubectl get service nginx-service -w
   # 访问 http://<external-ip>
   ```

3. **ClusterIP**
   ```bash
   # 使用端口转发进行测试
   kubectl port-forward service/nginx-service 8080:80
   # 访问 http://localhost:8080
   ```

## 🔧 故障排除

### 常见问题

1. **镜像拉取失败**
   ```bash
   # 检查 Secret 是否正确创建
   kubectl get secret harbor-registry-secret -o yaml
   
   # 检查镜像地址是否正确
   kubectl describe pod <pod-name>
   ```

2. **Pod 启动失败**
   ```bash
   # 查看 Pod 详细信息
   kubectl describe pod <pod-name>
   
   # 查看 Pod 日志
   kubectl logs <pod-name>
   ```

3. **服务无法访问**
   ```bash
   # 检查服务端点
   kubectl get endpoints nginx-service
   
   # 检查网络策略（如果启用）
   kubectl get networkpolicy
   ```

### 日志查看

```bash
# 查看部署事件
kubectl get events --sort-by=.metadata.creationTimestamp

# 查看特定资源的事件
kubectl describe deployment nginx-deployment
kubectl describe service nginx-service
```

## 🔄 更新部署

### 更新镜像版本

1. **使用脚本更新**
   ```bash
   export NGINX_IMAGE_TAG=new-version
   ./deploy.sh
   ```

2. **手动更新**
   ```bash
   kubectl set image deployment/nginx-deployment \
     nginx=harbor.example.com/test/nginx:new-version
   ```

3. **滚动更新策略**
   ```bash
   # 查看滚动更新状态
   kubectl rollout status deployment/nginx-deployment
   
   # 回滚到上一个版本
   kubectl rollout undo deployment/nginx-deployment
   ```

## 🗑️ 清理资源

### 删除部署
```bash
kubectl delete -f nginx-deployment.yaml
kubectl delete secret harbor-registry-secret
```

### 删除命名空间（如果使用专用命名空间）
```bash
kubectl delete namespace <namespace-name>
```

## 🔐 安全注意事项

1. **敏感信息管理**
   - 不要将 Harbor 凭据提交到代码仓库
   - 使用 Kubernetes Secrets 存储敏感信息
   - 考虑使用外部密钥管理系统

2. **网络安全**
   - 配置网络策略限制 Pod 间通信
   - 使用 HTTPS 和 TLS 证书
   - 配置防火墙规则

3. **镜像安全**
   - 定期扫描镜像漏洞
   - 使用最小权限运行容器
   - 启用镜像签名验证

## 📚 参考资料

- [Kubernetes 官方文档](https://kubernetes.io/docs/)
- [Harbor 官方文档](https://goharbor.io/docs/)
- [NGINX 官方文档](https://nginx.org/en/docs/)
- [Docker 私有仓库配置](https://docs.docker.com/registry/deploying/)

## 💡 提示

1. **性能优化**
   - 根据实际负载调整副本数和资源限制
   - 配置 NGINX 缓存策略
   - 使用持久化存储保存日志

2. **监控配置**
   - 集成 Prometheus 监控
   - 配置 Grafana 仪表板
   - 设置告警规则

3. **自动化**
   - 集成到 CI/CD 流水线
   - 使用 Helm 管理复杂部署
   - 配置自动化测试

## `${{ github.sha }}` 变量说明

`${{ github.sha }}` 是 GitHub Actions 中的一个内置环境变量，代表：

- **含义**: 当前提交的完整 SHA-1 哈希值（40 字符）
- **格式**: 例如 `a1b2c3d4e5f6789012345678901234567890abcd`
- **用途**: 作为 Docker 镜像的唯一标签，确保每次构建的镜像都有唯一标识
- **优势**: 
  - 可追溯性：能够准确对应到具体的代码提交
  - 唯一性：避免镜像标签冲突
  - 版本控制：便于回滚和版本管理

在 CI/CD 中使用 `${{ github.sha }}` 作为镜像标签是最佳实践，可以实现精确的版本控制和部署追踪。