如何架設 GitLab runner

GitLab Runner 是 GitLab CI/CD 系統的重要組件,用於執行 CI/CD pipeline 中定義的任務。 在持續整合和持續部署(CI/CD)流程中,GitLab Runner 扮演著執行自動化測試、構建和部署的關鍵角色。
通過在 Docker Compose 環境中設定 GitLab Runner,我們可以更靈活地管理和擴充我們的 CI/CD 基礎設施。

本文將詳細介紹如何在現有的 Docker Compose 環境中新增並設定 GitLab Runner。

前提條件

在開始之前,請確保您已具備以下條件:image 66

  • 已安裝 Docker 和 Docker Compose
  • 已設定 GitLab CI/CD pipeline
  • 已取得 GitLab Runner 註冊 Token(可在 GitLab 項目或組的 CI/CD 設定中找到)

修改 Docker Compose 檔案

首先,我們需要在 docker-compose.yml 檔案中加入 GitLab Runner 服務。

在 services 區塊中新增以下內容:

1
2
3
4
5
6
7
8
9
gitlab-runner:
image: gitlab/gitlab-runner
container_name: gitlab-runner
restart: unless-stopped
ports:
- "9252:9252"
volumes:
- ./gitlab_runner_config:/etc/gitlab-runner
- /var/run/docker.sock:/var/run/docker.sock

這個設定做了以下幾件事:

  • 使用官方的 gitlab/gitlab-runner image。
  • 設定容器名稱為 gitlab-runner。
  • 設定容器在停止後自動重新啟動。
  • 將容器的 9252 端點對應到主機的 9252 端點。
  • 掛載兩個磁碟區:
    • ./gitlab_runner_config:/etc/gitlab-runner
      • 用於儲存 GitLab Runner 的設定檔。
    • /var/run/docker.sock:/var/run/docker.sock
      • 允許 GitLab Runner 使用主機的 Docker 引擎。

建立設定目錄

在啟動服務之前,我們需要在主機上建立 GitLab Runner 的設定目錄:

1
mkdir gitlab_runner_config

啟動服務

現在,我們可以使用以下指令啟動 GitLab Runner 服務:

1
docker-compose up -d gitlab-runner

這將在背景啟動 GitLab Runner 容器。

註冊 GitLab Runner

啟動容器後,我們需要將 GitLab Runner 註冊到您的 GitLab Server。執行以下指令:

1
2
3
4
5
6
7
docker compose exec gitlab-runner gitlab-runner register \
--non-interactive \
--url "https://gitlab.xxxx/" \
--registration-token "your_gitlab_runner_token" \
--executor "docker" \
--docker-image alpine:latest \
--description "CodingMan Docker Runner"

這個指令如果沒有代入參數,則是會啟動一個互動式過程,讓您輸入以上資訊。這裡我們使用 --non-interactive 參數來避免互動式過程。

設定 GitLab Runner

註冊完成後,GitLab Runner 會自動產生一個 config.toml 檔案。讓我們來看看這個檔案的內容和意義:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
concurrent = 10
check_interval = 0
shutdown_timeout = 0
listen_address = ":9252"

[session_server]
session_timeout = 1800

[[runners]]
name = "CodingMan"
url = "https://gitlab.xxxx"
id = 147
token = "xxxxx"
token_obtained_at = 2024-05-27T04:47:34Z
token_expires_at = 0001-01-01T00:00:00Z
executor = "docker"
[runners.custom_build_dir]
[runners.cache]
MaxUploadedArchiveSize = 0
[runners.cache.s3]
[runners.cache.gcs]
[runners.cache.azure]
[runners.docker]
tls_verify = true
image = "docker:latest"
privileged = true
disable_entrypoint_overwrite = false
oom_kill_disable = false
disable_cache = false
volumes = ["/cache"]
shm_size = 0
network_mtu = 0

設定說明

全域設定:

  • concurrent = 10: 同時可以執行的工作數量上限為10個。
  • check_interval = 0: 檢查新工作的間隔時間,0表示使用預設值(3秒)。
  • shutdown_timeout = 0: Runner關閉時等待工作完成的逾時時間,0表示無限等待。
  • listen_address = “:9252”: Runner的監聽位址和端點,用於健康檢查和指標收集。

Session Server 設定:

  • session_timeout = 1800: 互動式 Web 終端機的逾時時間,單位為秒。

Runner 設定:

  • name = “CodingMan”: Runner 的名稱。
  • url = “https://gitlab.xxxx": GitLab server URL。
  • id = 147: Runner 的唯一識別碼。
  • token = “xxxxx”: Runner 的認證 Token (已隱藏)。
  • executor = “docker”: 使用 Docker 執行器來執行工作。

Docker 執行器設定:

  • tls_verify = true: 啟用 TLS 驗證。
  • image = “docker:latest”: 預設使用最新的 Docker image。
  • privileged = true: 允許容器以特權模式執行,這可能有安全風險。
  • volumes = [“/cache”]: 掛載 /cache 目錄用於快取。
  • tls_cert_path = “/etc/gitlab-runner/certs/“: TLS 憑證的路徑。

驗證 GitLab Runner 設定

要驗證 GitLab Runner 是否正確設定並能夠執行作業,您可以:

  1. 在 GitLab 的 CI/CD 設定頁面中檢查 Runner 是否出現並處於活動狀態。
  2. 在您的項目中創建一個簡單的 .gitlab-ci.yml 文件並提交,查看 CI/CD pipeline 是否成功觸發和執行。

例如,您可以使用以下簡單的 .gitlab-ci.yml

1
2
3
test_job:
script:
- echo "Hello, GitLab Runner!"

注意事項和最佳實踐

  • 安全性: privileged = true 設定允許容器以特權模式執行,這可能帶來安全風險。在正式環境中,請謹慎使用此設定。
  • 效能: concurrent = 10 設定允許同時執行 10 個工作,請根據您的系統資源和需求調整此值。
  • 網路: 確保 Runner 可以存取 GitLab 範例的 URL。
  • 憑證: 如果使用自簽憑證,您可能需要將憑證放在 tls_cert_path 指定的目錄中。
  • 快取: volumes = [“/cache”] 設定用於快取,可以提高建置速度,但也會佔用磁碟空間。定期清理快取是個好習慣。
  • 更新: 定期更新 GitLab Runner 以獲得最新的功能和安全修復。
  • 監視: 利用 listen_address 設定來監視 Runner 的健康狀況和效能。

結論

透過以上步驟,您已成功在 Docker Compose 環境中新增並設定了 GitLab Runner。這將使您能夠在此環境中執行 GitLab CI/CD
任務,實現自動化的軟體開發流程。
記住,GitLab Runner 的設定應該根據您的具體需求進行調整。定期檢視和更新設定,以確保它符合您的專案需求和安全標準。同時,密切關注
GitLab 官方文件,以獲取最新的最佳實踐和功能更新。

參考資料

也許你也會想看看