nginx/k8s

Kubernetes 部署指南

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

📋 目录结构

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

🚀 快速开始

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

1. 设置环境变量

   # 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}
   

   REM Windows
   set HARBOR_REGISTRY=harbor.example.com
   set HARBOR_USERNAME=your-username
   set HARBOR_PASSWORD=your-password
   set NGINX_IMAGE_TAG=latest
   

2. 运行部署脚本

   # Linux/macOS
   chmod +x deploy.sh
   ./deploy.sh
   
   # Windows
   deploy.bat
   

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

1. 创建环境变量文件

   cp .env.template .env
   # 编辑 .env 文件，填入实际的配置值
   

2. 运行部署脚本

   # 脚本会自动加载 .env 文件
   ./deploy.sh
   

方法三：手动部署

1. 创建 Harbor 仓库访问凭据

   kubectl create secret docker-registry harbor-registry-secret \
     --docker-server=harbor.example.com \
     --docker-username=your-username \
     --docker-password=your-password \
     --namespace=default
   

2. 更新部署文件中的镜像标签

   # 编辑 nginx-deployment.yaml，替换镜像标签
   # 将 harbor.example.com/test/nginx:latest 替换为实际的镜像地址
   

3. 应用 Kubernetes 配置

   kubectl apply -f nginx-deployment.yaml
   

4. 检查部署状态

   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 状态

kubectl get pods -l app=nginx -o wide

检查服务状态

kubectl get services -l app=nginx

查看日志

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

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

访问应用

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

1. NodePort（默认）

   # 获取节点 IP 和端口
   kubectl get nodes -o wide
   kubectl get service nginx-service
   # 访问 http://<node-ip>:30080
   

2. LoadBalancer

   # 等待外部 IP 分配
   kubectl get service nginx-service -w
   # 访问 http://<external-ip>
   

3. ClusterIP

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

🔧 故障排除

常见问题

1. 镜像拉取失败

   # 检查 Secret 是否正确创建
   kubectl get secret harbor-registry-secret -o yaml
   
   # 检查镜像地址是否正确
   kubectl describe pod <pod-name>
   

2. Pod 启动失败

   # 查看 Pod 详细信息
   kubectl describe pod <pod-name>
   
   # 查看 Pod 日志
   kubectl logs <pod-name>
   

3. 服务无法访问

   # 检查服务端点
   kubectl get endpoints nginx-service
   
   # 检查网络策略（如果启用）
   kubectl get networkpolicy
   

日志查看

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

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

🔄 更新部署

更新镜像版本

1. 使用脚本更新

   export NGINX_IMAGE_TAG=new-version
   ./deploy.sh
   

2. 手动更新

   kubectl set image deployment/nginx-deployment \
     nginx=harbor.example.com/test/nginx:new-version
   

3. 滚动更新策略

   # 查看滚动更新状态
   kubectl rollout status deployment/nginx-deployment
   
   # 回滚到上一个版本
   kubectl rollout undo deployment/nginx-deployment
   

🗑️ 清理资源

删除部署

kubectl delete -f nginx-deployment.yaml
kubectl delete secret harbor-registry-secret

删除命名空间（如果使用专用命名空间）

kubectl delete namespace <namespace-name>

🔐 安全注意事项

1. 敏感信息管理

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

2. 网络安全

   • 配置网络策略限制 Pod 间通信
   • 使用 HTTPS 和 TLS 证书
   • 配置防火墙规则

3. 镜像安全

   • 定期扫描镜像漏洞
   • 使用最小权限运行容器
   • 启用镜像签名验证

📚 参考资料

• Kubernetes 官方文档
• Harbor 官方文档
• NGINX 官方文档
• Docker 私有仓库配置

💡 提示

1. 性能优化

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

2. 监控配置

   • 集成 Prometheus 监控
   • 配置 Grafana 仪表板
   • 设置告警规则

3. 自动化

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

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

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

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

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