如何架設 GitLab runner

Posted on 2024-07-11

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

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

前提條件

在開始之前，請確保您已具備以下條件：

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

修改 Docker Compose 檔案

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

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

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。執行以下指令:

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 檔案。讓我們來看看這個檔案的內容和意義:

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 是否正確設定並能夠執行作業，您可以：

在 GitLab 的 CI/CD 設定頁面中檢查 Runner 是否出現並處於活動狀態。
在您的項目中創建一個簡單的 .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 官方文件，以獲取最新的最佳實踐和功能更新。