207 lines
7.9 KiB
Markdown
207 lines
7.9 KiB
Markdown
# 05-03-k3s 安装 GitLab（含 Runner）
|
||
|
||
> 通过 Helm 在 K3s 部署 GitLab，并接入 Runner 执行 CI 任务。
|
||
|
||
|
||
## TL;DR
|
||
|
||
- **自动化验收**：`./ansible/bin/verify.sh run 05-03`
|
||
- **关键前置**：按本文「前置条件」准备环境变量/Secret/入口 IP
|
||
- **成功判据**：达到本文「预期」且 playbook 断言通过
|
||
- **排障**：见本文「排障」
|
||
|
||
---
|
||
|
||
## 前置条件
|
||
|
||
### 基座（必须）
|
||
|
||
- **01 系列已就绪**：K3s 集群与节点初始化等实验室基座完成（见 `01-00` / `01-05` 等），本机可 `kubectl` 管理集群。
|
||
- **不**将 `02`（nginx 验证矩阵）、`04-01`（Node.js 高级部署）等列为本文硬性前置；仅当你要沿用同环境的入口/域名习惯时，再自行参考。
|
||
|
||
### 资源（强烈建议）
|
||
|
||
- GitLab 组件多、默认资源占用高，请为集群预留足够 CPU/内存/存储（具体以官方 Chart 与 `values` 为准）。
|
||
|
||
### 域名与入口（按场景选用）
|
||
|
||
| 场景 | 建议先完成的文档 | 说明 |
|
||
|------|------------------|------|
|
||
| **无公网域名**：仅用集群内访问（如 NodePort、`*.svc`、内网 Ingress IP） | 无额外 03-xx | `values` 与 Runner 的 `--url` 使用你可访问的地址即可（常为内网或 IP）。 |
|
||
| **公网域名 + HTTPS（Traefik + ACME）** | **`03-02`** 或 **`03-03`** | 需要合法 DNS 与证书自动化时二选一：仅证书/入口见 **`03-02`**；若你已在 **`03-03`** 路径上统一 Dashboard+ACME，可沿用同一套 Traefik/证书策略。 |
|
||
| **经 Cloudflare Tunnel 暴露 GitLab** | **`03-04`** | 走 Tunnel 时，入口与证书策略以 Tunnel 与 Cloudflare 侧为准；集群内需已按 `03-04` 完成接入。 |
|
||
|
||
本文示例中的 `git.example.com` 仅作占位；请替换为你的真实域名或内网访问地址。
|
||
|
||
---
|
||
|
||
## 为什么这里用 Helm 而不是纯 YAML？
|
||
|
||
- GitLab 属于重量级应用：组件多（Web/Sidekiq/Registry/DB/Redis 等），关联的 YAML 数量非常大。
|
||
- 官方维护的 Helm Chart 已经帮你整理好了依赖关系、默认参数和升级路径，本质上还是“渲染出一堆 YAML 再 `kubectl apply`”。
|
||
- 在本仓库里：简单/教学型服务（nginx、Node.js demo、Homer、OneNav 等）我们通过示例 YAML 手写；而像 GitLab 这种复杂应用，则更推荐直接沿用官方 Chart，在本地以 **`values-gitlab.yaml`** 覆盖参数；仓库内提供起点示例 **`ansible/files/05-03/values-gitlab.example.yaml`**（复制后修改）。
|
||
|
||
---
|
||
|
||
## 存储与节点（实验室：固定 ylc63、本地落盘）
|
||
|
||
本仓库 **`inventory.ini`** 中 **`ylc63`（192.168.2.63）** 作为 GitLab **数据落盘节点**：示例 `values-gitlab.example.yaml` 已配置：
|
||
|
||
- **`global.nodeSelector.kubernetes.io/hostname: ylc63`**：GitLab 自带组件（如 Webservice、Gitaly 等）调度到该节点。
|
||
- **PostgreSQL / Redis / MinIO** 等依赖子 chart **不一定会继承** `global.nodeSelector`，示例中为 **`postgresql.primary` / `redis.master` / `minio`** 补了同样的 **`nodeSelector`**，避免数据卷漂到其他节点。
|
||
- **持久卷**：各组件 **`persistence.storageClass: local-path`**，与 K3s 默认 **local-path-provisioner** 一致，卷与 Pod 同节点，即 **落在 ylc63 本地磁盘**（逻辑与 **`03-05-k3s-local-path-pvc.md`** 一致；若需改基路径见该文 **`local-path-config`**）。
|
||
|
||
部署前请确认 **`ylc63` 磁盘容量** 覆盖 Gitaly / PG / Redis / MinIO 等 `size` 之和；节点名若与 inventory 不一致，请 `kubectl get nodes` 后全局替换 `ylc63`。
|
||
|
||
---
|
||
|
||
## 安装 Helm
|
||
|
||
```bash
|
||
curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
|
||
```
|
||
|
||
---
|
||
|
||
## 安装 GitLab
|
||
|
||
```bash
|
||
helm repo add gitlab https://charts.gitlab.io/
|
||
helm repo update
|
||
kubectl create namespace gitlab
|
||
```
|
||
|
||
本仓库提供示例 values（占位域名 `example.com`、实验室缩小副本；**请复制后按需改域名与资源**）：
|
||
|
||
- 示例文件：[`ansible/files/05-03/values-gitlab.example.yaml`](../ansible/files/05-03/values-gitlab.example.yaml)
|
||
|
||
```bash
|
||
cp ansible/files/05-03/values-gitlab.example.yaml values-gitlab.yaml
|
||
# 编辑 values-gitlab.yaml：域名、Ingress/TLS、资源等；完整键名以当前 Chart 为准：
|
||
# helm show values gitlab/gitlab
|
||
```
|
||
|
||
然后安装：
|
||
|
||
```bash
|
||
helm upgrade --install gitlab gitlab/gitlab \
|
||
-n gitlab \
|
||
-f values-gitlab.yaml
|
||
```
|
||
|
||
---
|
||
|
||
## 安装/绑定 Runner
|
||
|
||
1. 在 GitLab 管理后台获取 Runner 注册信息
|
||
2. 按节点类型（x86 / arm64 / armv7）分别部署 Runner，并为每类 Runner 设置不同的 tag
|
||
3. 确认 Job 能被对应架构的 Runner 拉起执行
|
||
|
||
### 安装 gitlab-runner 二进制（各架构通用）
|
||
|
||
GitLab 官方提供多架构的 Runner 二进制，常见 Linux 节点可以用如下方式安装（以 root 或具备 sudo 权限的用户为例）：
|
||
|
||
```bash
|
||
# x86_64
|
||
sudo curl -L https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-amd64 -o /usr/local/bin/gitlab-runner
|
||
sudo chmod +x /usr/local/bin/gitlab-runner
|
||
|
||
# arm64
|
||
sudo curl -L https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-arm64 -o /usr/local/bin/gitlab-runner
|
||
sudo chmod +x /usr/local/bin/gitlab-runner
|
||
|
||
# armv7 (arm32)
|
||
sudo curl -L https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-arm -o /usr/local/bin/gitlab-runner
|
||
sudo chmod +x /usr/local/bin/gitlab-runner
|
||
```
|
||
|
||
安装完成后，可按官方文档将 Runner 注册为 systemd 服务；下面的注册命令默认 `gitlab-runner` 已在对应架构节点上就绪。
|
||
|
||
### x86 Runner（两种典型方式）
|
||
|
||
#### 方案一：在 K3s 集群内，使用 Helm 部署 Kubernetes executor
|
||
|
||
适合大部分“直接对接 K3s”的 CI 场景，Runner 以 Pod 形式运行在集群中：
|
||
|
||
```bash
|
||
helm repo add gitlab https://charts.gitlab.io/
|
||
helm repo update
|
||
|
||
kubectl create namespace gitlab-runner
|
||
|
||
helm upgrade --install gitlab-runner-x86 gitlab/gitlab-runner \
|
||
-n gitlab-runner \
|
||
--set gitlabUrl=https://git.example.com/ \
|
||
--set runnerRegistrationToken=<YOUR_RUNNER_TOKEN> \
|
||
--set runners.tags=x86
|
||
```
|
||
|
||
后续在 `.gitlab-ci.yml` 中通过 `tags: [x86]` 指定由该 Runner 执行。
|
||
|
||
#### 方案二：在独立 x86 节点上，使用 shell/docker executor
|
||
|
||
如果你有独立的 x86 机器（不在 K3s 集群中），也可以在该节点上直接安装 Runner，并打上 `x86` tag：
|
||
|
||
```bash
|
||
sudo gitlab-runner register \
|
||
--url https://git.example.com/ \
|
||
--registration-token <YOUR_RUNNER_TOKEN> \
|
||
--executor shell \
|
||
--description "x86-standalone-runner" \
|
||
--tag-list "x86" \
|
||
--non-interactive
|
||
```
|
||
|
||
### arm64 / armv7 Runner（物理机上，shell/docker executor）
|
||
|
||
对于 arm64 与 armv7 这类非 x86 节点，更常见的做法是在对应物理机上直接安装 GitLab Runner，并打上架构标签。例如：
|
||
|
||
```bash
|
||
# 在 arm64 主机上
|
||
sudo gitlab-runner register \
|
||
--url https://git.example.com/ \
|
||
--registration-token <YOUR_RUNNER_TOKEN> \
|
||
--executor shell \
|
||
--description "arm64-runner" \
|
||
--tag-list "arm64" \
|
||
--non-interactive
|
||
|
||
# 在 armv7 主机上
|
||
sudo gitlab-runner register \
|
||
--url https://git.example.com/ \
|
||
--registration-token <YOUR_RUNNER_TOKEN> \
|
||
--executor shell \
|
||
--description "armv7-runner" \
|
||
--tag-list "armv7" \
|
||
--non-interactive
|
||
```
|
||
|
||
在 `.gitlab-ci.yml` 中即可按需指定不同架构运行 Job，示例见 [`ansible/files/05-03/gitlab-ci-runner-tags.example.yml`](../ansible/files/05-03/gitlab-ci-runner-tags.example.yml)。
|
||
|
||
---
|
||
|
||
## 验证
|
||
|
||
```bash
|
||
kubectl -n gitlab get pods
|
||
kubectl -n gitlab get svc
|
||
```
|
||
|
||
在 GitLab 页面检查：
|
||
|
||
- 项目能正常访问
|
||
- Pipeline 可成功执行
|
||
|
||
---
|
||
|
||
## 下一步
|
||
|
||
- `05-04-k3s-配置gitlab-cicd.md`
|
||
- `03-04-k3s-cloudflare-tunnel-配置接入.md`
|
||
|
||
## 排障
|
||
|
||
- **先看 playbook 输出**：失败时先定位是 deploy/wait/http_check 哪一步。
|
||
- **集群侧总览**：`kubectl get nodes -o wide`、`kubectl -n kube-system get pods -o wide`。
|
||
- **事件与日志**：`kubectl -n <ns> describe ...`、`kubectl -n <ns> logs ... --tail=200`。
|