234 lines
6.5 KiB
Markdown
234 lines
6.5 KiB
Markdown
# GitHub Actions CI/CD 配置说明
|
||
|
||
本文档详细说明如何配置 GitHub Actions 的 Secrets，以实现自动构建、推送镜像到 Harbor 仓库，并部署到 Kubernetes 集群。
|
||
|
||
## 📋 必需的 GitHub Secrets
|
||
|
||
在 GitHub 仓库设置中添加以下 Secrets（Settings → Secrets and variables → Actions）：
|
||
|
||
### Harbor 仓库配置
|
||
|
||
| Secret 名称 | 描述 | 示例值 |
|
||
|------------|------|--------|
|
||
| `HARBOR_REGISTRY` | Harbor 仓库地址 | `harbor.example.com` |
|
||
| `HARBOR_USERNAME` | Harbor 用户名 | `admin` |
|
||
| `HARBOR_PASSWORD` | Harbor 密码 | `your-password` |
|
||
|
||
### Kubernetes 配置（可选）
|
||
|
||
| Secret 名称 | 描述 | 是否必需 |
|
||
|------------|------|----------|
|
||
| `KUBE_CONFIG` | base64 编码的 kubeconfig 文件 | 仅部署到 K8s 时需要 |
|
||
| `K8S_NAMESPACE` | Kubernetes 命名空间 | 可选，默认为 `default` |
|
||
|
||
## 🔧 配置步骤
|
||
|
||
### 1. 配置 Harbor 仓库访问
|
||
|
||
1. **获取 Harbor 仓库信息**
|
||
```bash
|
||
# Harbor 仓库地址格式
|
||
https://harbor.example.com
|
||
# 或
|
||
harbor.example.com
|
||
```
|
||
|
||
2. **在 GitHub 中添加 Secrets**
|
||
- 进入仓库 Settings → Secrets and variables → Actions
|
||
- 点击 "New repository secret"
|
||
- 添加以下三个 secrets：
|
||
- `HARBOR_REGISTRY`: Harbor 仓库地址
|
||
- `HARBOR_USERNAME`: Harbor 用户名
|
||
- `HARBOR_PASSWORD`: Harbor 密码
|
||
|
||
### 2. 配置 Kubernetes 部署（可选）
|
||
|
||
如果需要自动部署到 Kubernetes 集群，需要配置以下 secrets：
|
||
|
||
#### 生成 KUBE_CONFIG
|
||
|
||
**方法一：从现有 kubeconfig 文件**
|
||
```bash
|
||
# 1. 找到您的 kubeconfig 文件
|
||
ls ~/.kube/config
|
||
|
||
# 2. 对内容进行 base64 编码
|
||
cat ~/.kube/config | base64 -w 0
|
||
|
||
# 3. 将输出的 base64 字符串作为 KUBE_CONFIG secret 的值
|
||
```
|
||
|
||
**方法二：从 Kubernetes 集群生成**
|
||
```bash
|
||
# 1. 创建服务账户
|
||
kubectl create serviceaccount github-actions -n default
|
||
|
||
# 2. 创建 ClusterRoleBinding（根据需要调整权限）
|
||
kubectl create clusterrolebinding github-actions \
|
||
--clusterrole=cluster-admin \
|
||
--serviceaccount=default:github-actions
|
||
|
||
# 3. 获取服务账户的 token（Kubernetes 1.24+）
|
||
kubectl create token github-actions --duration=8760h > token.txt
|
||
|
||
# 4. 生成 kubeconfig 文件
|
||
CLUSTER_NAME=$(kubectl config current-context)
|
||
SERVER=$(kubectl config view --minify -o jsonpath='{.clusters[0].cluster.server}')
|
||
CA_DATA=$(kubectl config view --raw --minify --flatten -o jsonpath='{.clusters[0].cluster.certificate-authority-data}')
|
||
TOKEN=$(cat token.txt)
|
||
|
||
cat > kubeconfig-github-actions.yaml << EOF
|
||
apiVersion: v1
|
||
kind: Config
|
||
clusters:
|
||
- cluster:
|
||
certificate-authority-data: $CA_DATA
|
||
server: $SERVER
|
||
name: $CLUSTER_NAME
|
||
contexts:
|
||
- context:
|
||
cluster: $CLUSTER_NAME
|
||
user: github-actions
|
||
name: github-actions
|
||
current-context: github-actions
|
||
users:
|
||
- name: github-actions
|
||
user:
|
||
token: $TOKEN
|
||
EOF
|
||
|
||
# 5. 编码为 base64
|
||
cat kubeconfig-github-actions.yaml | base64 -w 0
|
||
|
||
# 6. 清理临时文件
|
||
rm token.txt kubeconfig-github-actions.yaml
|
||
```
|
||
|
||
#### 添加到 GitHub Secrets
|
||
|
||
1. **KUBE_CONFIG**
|
||
- 将上述生成的 base64 编码字符串添加为 secret
|
||
- 注意：这应该是一个很长的字符串，没有换行符
|
||
|
||
2. **K8S_NAMESPACE**（可选）
|
||
- 指定部署的命名空间，如 `production`、`staging`
|
||
- 如果不设置，默认使用 `default` 命名空间
|
||
|
||
## 🚀 CI/CD 流程说明
|
||
|
||
### 触发条件
|
||
|
||
CI/CD 管道在以下情况下触发：
|
||
- 推送代码到任何分支
|
||
- 创建 Pull Request 到 main 分支
|
||
|
||
### 自动部署条件
|
||
|
||
Kubernetes 自动部署仅在以下情况下执行：
|
||
- 推送到 `main` 分支
|
||
- 且配置了 `KUBE_CONFIG` secret
|
||
|
||
### 流程步骤
|
||
|
||
1. **代码检出和环境准备**
|
||
2. **编译 NGINX**
|
||
3. **构建 Docker 镜像**
|
||
4. **推送镜像到 Harbor**
|
||
- 标签：`${{ github.sha }}` 和 `latest`
|
||
5. **部署到 Kubernetes**（条件触发）
|
||
- 检查 kubectl 是否已安装
|
||
- 配置 kubectl 连接
|
||
- 运行部署脚本
|
||
|
||
## 🔍 故障排除
|
||
|
||
### 常见问题
|
||
|
||
1. **Harbor 登录失败**
|
||
```
|
||
Error: unauthorized: unauthorized to access repository
|
||
```
|
||
- 检查 `HARBOR_USERNAME` 和 `HARBOR_PASSWORD` 是否正确
|
||
- 确认用户有推送权限到 `test/nginx` 项目
|
||
|
||
2. **Kubernetes 连接失败**
|
||
```
|
||
ERROR: 无法连接到 Kubernetes 集群
|
||
```
|
||
- 检查 `KUBE_CONFIG` 是否正确 base64 编码
|
||
- 验证集群是否可从 GitHub Actions runner 访问
|
||
- 检查证书是否已过期
|
||
|
||
3. **kubectl 安装失败**
|
||
```
|
||
kubectl 下载失败
|
||
```
|
||
- 网络问题，会自动尝试使用 apt 安装
|
||
- 检查 GitHub Actions runner 的网络连接
|
||
|
||
### 调试技巧
|
||
|
||
1. **查看详细日志**
|
||
- GitHub Actions 提供详细的执行日志
|
||
- 每个步骤都有展开的日志输出
|
||
|
||
2. **测试 kubeconfig**
|
||
```bash
|
||
# 在本地测试 kubeconfig 是否正确
|
||
export KUBECONFIG=./kubeconfig-github-actions.yaml
|
||
kubectl cluster-info
|
||
kubectl get nodes
|
||
```
|
||
|
||
3. **验证 base64 编码**
|
||
```bash
|
||
# 验证编码是否正确
|
||
echo "YOUR_BASE64_STRING" | base64 -d > test-config.yaml
|
||
kubectl --kubeconfig=test-config.yaml cluster-info
|
||
```
|
||
|
||
## 🔐 安全注意事项
|
||
|
||
1. **最小权限原则**
|
||
- 为 GitHub Actions 创建专用的服务账户
|
||
- 只授予必要的权限
|
||
- 定期轮换访问凭据
|
||
|
||
2. **Secret 管理**
|
||
- 不要在代码中硬编码敏感信息
|
||
- 定期检查和更新 secrets
|
||
- 使用组织级 secrets 共享通用配置
|
||
|
||
3. **网络安全**
|
||
- 确保 Harbor 仓库启用 HTTPS
|
||
- 使用防火墙限制访问
|
||
- 启用 Harbor 的镜像安全扫描
|
||
|
||
## 📚 相关文档
|
||
|
||
- [GitHub Actions Secrets 文档](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions)
|
||
- [kubectl 安装指南](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/)
|
||
- [Harbor 用户指南](https://goharbor.io/docs/2.0.0/working-with-projects/working-with-images/)
|
||
- [Kubernetes 服务账户](https://kubernetes.io/docs/concepts/security/service-accounts/)
|
||
|
||
## 💡 最佳实践
|
||
|
||
1. **环境分离**
|
||
- 为不同环境（dev、staging、prod）使用不同的 Harbor 项目
|
||
- 使用不同的 Kubernetes 命名空间
|
||
|
||
2. **版本管理**
|
||
- 使用 `${{ github.sha }}` 作为主要标签
|
||
- 保留 `latest` 标签用于快速部署
|
||
- 考虑使用语义化版本标签
|
||
|
||
3. **监控和告警**
|
||
- 配置 GitHub Actions 失败通知
|
||
- 监控 Harbor 仓库存储使用情况
|
||
- 设置 Kubernetes 集群监控
|
||
|
||
4. **备份和恢复**
|
||
- 定期备份 kubeconfig 文件
|
||
- 保存 Harbor 仓库配置
|
||
- 制定灾难恢复计划
|