Phần 5 — GitLab Runner self-hosted: cài đặt và executors (Shell/Docker)

Series GitLab CI/CD Toàn Tập — 9 phần:

1. Phần 1 — Tổng quan: GitLab CI/CD, kiến trúc và các khái niệm

2. Phần 2 — .gitlab-ci.yml đầu tiên và Variables (predefined, UI, masked)

3. Phần 3 — Cache vs Artifacts: chiến lược và Reports

4. Phần 4 — Rules và Merge Request Pipelines

5. Phần 5 — GitLab Runner self-hosted: cài đặt và executors (Shell/Docker) ← bạn đang đọc

6. Phần 6 — Kubernetes executor: scale runner trên K8s

7. Phần 7 — include, extends, anchors — pipeline modular

8. Phần 8 — Environments, Deployments và Review Apps

9. Phần 9 — Pipeline thực tế Next.js → Docker → K8s + best practices + debug

Mở đầu

Đây là phần thực hành quan trọng nhất. Self-hosted runner cho phép pipeline chạy trên hạ tầng của bạn — vào được mạng nội bộ, tận dụng GPU/RAM lớn, tiết kiệm chi phí và không phụ thuộc quota của shared runner. Phần này hướng dẫn cài binary trên Ubuntu, đăng ký với GitLab, cấu hình Docker executor (phổ biến nhất) và config.toml nâng cao với S3 cache shared giữa các runner.

1. Cài GitLab Runner trên server riêng

Đây là phần thực hành quan trọng nhất. Mình hướng dẫn cài runner trên Ubuntu 22.04+ với 2 executor phổ biến: Docker và Shell.

1.1. Yêu cầu phần cứng

• Ubuntu 22.04+ / Debian 11+ / RHEL 8+.

• 2 CPU + 4GB RAM (đủ cho 2-3 job song song).

• 20GB+ disk trống.

• Kết nối outbound đến GitLab instance trên port 443.

• Docker (nếu dùng docker executor).

1.2. Cài binary

# Tải gói cài chính thức
curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | sudo bash

# Cài
sudo apt install gitlab-runner

# Kiểm tra
sudo gitlab-runner --version

1.3. Đăng ký runner

Vào repo/group GitLab → Settings → CI/CD → Runners → New project runner. Đặt tag (vd self-hosted,docker,prod), chọn untagged jobs hay không. GitLab trả về registration token (cũ) hoặc authentication token (mới — GitLab 16+):

sudo gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com" \
  --token "glrt-xxxxxxxxxxxxx" \
  --executor "docker" \
  --docker-image "alpine:3.20" \
  --description "vps-prod-01" \
  --docker-privileged=false \
  --docker-volumes "/var/run/docker.sock:/var/run/docker.sock"

Lệnh trên đăng ký runner với:

• Docker executor — mỗi job chạy trong container.

• Image mặc định alpine:3.20 — dùng nếu job không khai báo image:.

• Mount Docker socket — cho phép job bên trong container chạy được docker build trên host (kỹ thuật Docker-in-Docker).

1.4. Khởi chạy như service

sudo systemctl enable --now gitlab-runner
sudo systemctl status gitlab-runner

Vào lại trang Runners trong GitLab, runner hiện Online với chấm xanh.

1.5. Cấu hình nâng cao — /etc/gitlab-runner/config.toml

concurrent = 4              # Số job song song toàn runner
check_interval = 3          # Poll GitLab mỗi 3s
log_level = "info"

[[runners]]
  name = "vps-prod-01"
  url = "https://gitlab.com"
  token = "glrt-xxx"
  executor = "docker"
  limit = 2                 # Số job song song của runner này
  environment = [
    "DOCKER_AUTH_CONFIG={\"auths\":...}",
  ]
  [runners.docker]
    image = "alpine:3.20"
    privileged = false
    pull_policy = ["always", "if-not-present"]
    cache_dir = "/cache"
    volumes = [
      "/var/run/docker.sock:/var/run/docker.sock",
      "/cache",
    ]
  [runners.cache]
    Type = "s3"
    Shared = true
    [runners.cache.s3]
      ServerAddress = "s3.amazonaws.com"
      AccessKey = "xxx"
      SecretKey = "xxx"
      BucketName = "my-runner-cache"
      BucketLocation = "ap-southeast-1"

Hai điểm cần chú ý:

• S3 cache — bắt buộc khi có nhiều runner. Local cache chỉ khả dụng trên 1 máy, scale ra là mất cache.

• pull_policy — always rồi if-not-present giúp tận dụng image local nếu pull fail (vd registry offline).

Tóm tắt

Trong phần này bạn đã nắm:

• Yêu cầu: Ubuntu 22.04+, 2 CPU + 4GB RAM, 20GB disk, outbound 443 đến GitLab instance, Docker.

• Cài 4 bước: package script → apt install gitlab-runner → gitlab-runner register với --token glrt-... → systemd service.

• Docker executor: mỗi job chạy trong container; mount /var/run/docker.sock để build Docker-in-Docker; --docker-privileged=false trừ khi thật cần.

• config.toml production: concurrent = 4, pull_policy = ["always", "if-not-present"], và S3 cache shared — bắt buộc khi có nhiều runner.

Trong Phần 6, ta scale runner bằng Kubernetes executor: mỗi job là một pod ephemeral — kiến trúc hiệu quả nhất cho workload bursty.

Phần 6: Kubernetes executor: scale runner trên K8s →