All Articles
การติดตั้ง GitLab Runner บน Kubernetes Cluster 🎉🚀

2024-06-27

การติดตั้ง GitLab Runner บน Kubernetes Cluster 🎉🚀

Read on Medium

แชร์บทความนี้

การติดตั้ง GitLab Runner บน Kubernetes Cluster 🎉🚀

GitLab Runner คือคนงานที่หยิบ Job จาก Pipeline มาทำ ส่วน Kubernetes executor ทำให้ Job แต่ละตัวได้ Pod ใหม่ของตัวเอง ทำเสร็จแล้วก็เก็บ Pod กลับ ไม่ต้องมีเครื่อง Build หนึ่งตัวที่สะสมไฟล์ Cache และเศษโปรเจกต์จนกลายเป็นห้องเก็บของใต้บันไดครับ

ปี 2026 Helm chart ยังเป็นวิธีทางการสำหรับติดตั้ง GitLab Runner บน Kubernetes แต่ขั้นตอน Registration เปลี่ยนจากบทความยุคก่อนพอสมควร ปัจจุบันควรสร้าง Runner ใน GitLab UI ก่อน แล้วใช้ Runner authentication token ซึ่งมักขึ้นต้นด้วย glrt- แทน Workflow เก่าที่ใช้ Registration token

อีกจุดที่ต้องแก้คือไม่ควรเริ่มจาก privileged: true และ Mount /var/run/docker.sock โดยอัตโนมัติ เพราะเท่ากับยื่นกุญแจ Host ให้ Build job ทุกตัวครับ

ภาพการทำงาน

GitLab Pipeline
      ↓ รับ Job
Runner manager Pod
      ↓ สร้าง Pod ชั่วคราว
Build Pod → ทำงาน → ส่งผลลัพธ์ → ถูกลบ

Runner manager ไม่ได้ Compile งานทั้งหมดใน Pod ตัวเอง มันคุยกับ Kubernetes API เพื่อสร้าง Pod ต่อ Job ตาม Config ที่กำหนด

สิ่งที่ต้องมี

  • Kubernetes cluster และ kubectl
  • Helm CLI
  • GitLab project หรือ group ที่มีสิทธิ์สร้าง Runner
  • Namespace สำหรับ Runner
  • Network จาก Cluster ไป GitLab และ Container registry
  • Storage/Cache backend ถ้าต้องการ Cache ข้าม Job

ตรวจ Context ก่อน:

kubectl config current-context
kubectl auth can-i create pods --namespace gitlab-runner

สร้าง Runner ใน GitLab

ไปที่ Project หรือ Group:

Settings → CI/CD → Runners → New project/group runner

กำหนด Description, Tag, การรับ Untagged job และ Protection ตามที่ต้องการ แล้วเก็บ Runner authentication token ไว้ใน Secret manager Token นี้เป็น Credential ไม่ควร Commit ใน values.yaml

ถ้าระบบของทีมยังแสดงคำว่า Registration token ให้ตรวจ GitLab version และ Migration guide เพราะ Workflow เก่าถูกทยอยยกเลิกไปแล้วครับ

เพิ่ม Helm repository

helm repo add gitlab https://charts.gitlab.io
helm repo update
helm search repo -l gitlab/gitlab-runner

เลือก Chart version และ Pin ไว้ใน Pipeline แทนติดตั้งล่าสุดแบบลอย ๆ เพื่อให้ Upgrade มีจังหวะ Review

สร้าง Namespace และ Secret

kubectl create namespace gitlab-runner

สร้าง Secret โดยไม่เขียน Token ลงไฟล์:

kubectl create secret generic gitlab-runner-token \
  --namespace gitlab-runner \
  --from-literal=runner-token='glrt-REPLACE_ME' \
  --from-literal=runner-registration-token=''

ชื่อ Key อาจขึ้นกับ Chart version ที่ใช้งาน ตรวจ values.yaml ทางการของ Version นั้นเสมอ ถ้าองค์กรมี External Secrets ให้ดึง Token จาก Secret manager แทนการสร้างมือครับ

เขียน values.yaml แบบสิทธิ์พอดีตัว

gitlabUrl: https://gitlab.com/

rbac:
  create: true

serviceAccount:
  create: true

concurrent: 5
checkInterval: 10

runners:
  secret: gitlab-runner-token
  tags: "kubernetes"
  runUntagged: false
  protected: true
  config: |
    [[runners]]
      [runners.kubernetes]
        namespace = "gitlab-runner"
        image = "alpine:3.20"
        privileged = false
        poll_timeout = 600

        cpu_request = "250m"
        memory_request = "256Mi"
        cpu_limit = "1"
        memory_limit = "1Gi"

      [runners.kubernetes.pod_security_context]
        run_as_non_root = true
        run_as_user = 1000

ตัวอย่าง Resource เป็นจุดเริ่มต้น ต้องวัดจาก Job จริง ถ้าต่ำเกิน Job ถูก OOMKilled ถ้าสูงเกิน Scheduler วาง Pod ได้น้อยเหมือนจองโต๊ะสิบที่ให้คนนั่งคนเดียวครับ

Field ใน Helm chart เปลี่ยนได้ตาม Version ให้เทียบกับ Default values.yaml และเอกสารก่อน Apply โดยเฉพาะชื่อ Secret และ Runner token

ติดตั้ง Runner

helm upgrade --install gitlab-runner gitlab/gitlab-runner \
  --namespace gitlab-runner \
  --version <PINNED_CHART_VERSION> \
  --values values.yaml \
  --wait \
  --timeout 5m

ตรวจ Resource:

kubectl get pods -n gitlab-runner
kubectl logs deployment/gitlab-runner -n gitlab-runner
helm status gitlab-runner -n gitlab-runner

กลับไปหน้า Runners ใน GitLab สถานะควร Online

ทดสอบด้วย Pipeline เล็ก ๆ

ไฟล์ .gitlab-ci.yml:

stages:
  - test

hello-runner:
  stage: test
  tags:
    - kubernetes
  image: alpine:3.20
  script:
    - echo "Hello from Kubernetes executor"
    - cat /etc/os-release

เมื่อ Pipeline เริ่ม Runner manager จะสร้าง Build Pod ใหม่ ดูได้ด้วย:

kubectl get pods -n gitlab-runner --watch

ถ้า Job ค้างที่ Pending ให้ดู Event:

kubectl describe pod <job-pod> -n gitlab-runner

สาเหตุมักเป็น Image pull, Resource ไม่พอ, Admission policy, ServiceAccount หรือ Node selector ไม่ตรงครับ

ทำไมไม่ควร Mount Docker socket

Config แบบเก่ามักมี:

/var/run/docker.sock:/var/run/docker.sock
privileged = true

เมื่อ Container ควบคุม Docker socket ของ Node ได้ มันอาจสร้าง Container ใหม่ Mount filesystem ของ Host หรือขยายสิทธิ์ออกนอก Job Pod ได้ Isolation ที่ Kubernetes เตรียมไว้จึงแทบหายไป

ถ้าต้อง Build image พิจารณาทางเลือกที่ไม่ยื่น Socket ของ Host ให้ Job เช่น:

  • BuildKit แบบ Rootless
  • Buildah ตาม Environment ที่รองรับ
  • Cloud-native image builder ของ Platform
  • แยก Runner สำหรับงานที่ต้องสิทธิ์สูงออกจาก Runner ทั่วไป

ถ้าจำเป็นต้อง Privileged จริง ให้ใช้ Dedicated node, Taint/Toleration, Network policy และไม่รับ Job จาก Repository ที่ไม่ไว้ใจ อย่าให้ Pull request จากคนแปลกหน้ารันบน Runner ที่ถือกุญแจ Cluster ครับ

จำกัด Blast radius

Runner เป็นระบบประมวลผลโค้ดจาก Repository จึงควรมองเหมือนห้องทดลองที่อาจมีสารเคมี ไม่ใช่ Pod ธรรมดา

แนวปฏิบัติที่ควรมี:

  • Namespace แยก
  • ServiceAccount และ RBAC ขั้นต่ำ
  • NetworkPolicy จำกัดปลายทาง
  • Pod Security Admission ระดับที่เหมาะสม
  • Resource requests/limits และ Namespace quota
  • Runner แยกตาม Trust boundary
  • Protected runner สำหรับ Branch/Tag สำคัญ
  • ไม่ส่ง Secret ให้ Job ที่ไม่ต้องใช้
  • Rotate Runner token เมื่อสงสัยว่ารั่ว

Cache และ Artifact คนละอย่าง

  • Cache ช่วยให้ Job รอบต่อไปเร็วขึ้น เช่น Dependency cache ลบได้และ Pipeline ควรสร้างใหม่ได้
  • Artifact คือผลลัพธ์ของ Job เช่น Binary, Test report หรือ Coverage ที่ต้องส่งต่อหรือตรวจย้อนหลัง

สำหรับ Runner ที่ Pod หายหลังจบ Job Local cache ไม่ได้อยู่ถาวร ถ้าต้องแชร์ข้าม Pod ให้ตั้ง Object storage เช่น S3-compatible backend และกำหนด Lifecycle ไม่ให้ Cache เก่าสะสมจนค่าใช้จ่ายโตเงียบ ๆ

Upgrade อย่างไม่สะดุด

ก่อน Upgrade:

  1. Pause Runner ใน GitLab ถ้าต้องการหยุดรับงานใหม่
  2. รอ Job ปัจจุบันจบ
  3. อ่าน Release note ของ Chart และ Runner
  4. helm diff หรือดูค่าที่เปลี่ยน
  5. Upgrade ด้วย Version ที่ Pin
  6. รัน Pipeline ทดสอบ
helm upgrade gitlab-runner gitlab/gitlab-runner \
  --namespace gitlab-runner \
  --version <NEW_CHART_VERSION> \
  --values values.yaml \
  --wait

สรุป

Helm chart ทำให้ติดตั้ง GitLab Runner บน Kubernetes ได้ไม่ยาก ส่วน Kubernetes executor ช่วยสร้าง Pod ใหม่ต่อ Job และเก็บกวาดหลังทำงานเสร็จ

สิ่งสำคัญในปี 2026 คือใช้ Runner authentication token รุ่นใหม่ เก็บ Token ใน Secret, Pin Chart version และเริ่มจาก Runner ที่ไม่ Privileged อย่า Mount Docker socket เป็นค่าเริ่มต้น ความเร็วของ CI สำคัญครับ แต่ถ้า Pipeline หนึ่งตัวสามารถเปิดประตูทั้ง Node ได้ เรากำลังประหยัดเวลาสร้าง Imageแลกกับการยกกุญแจ Data center ให้ Job ไปถือเล่น

อ่านต่อจากเอกสารทางการ:

© 2026 Nanpipat Klinpratoom. All Rights Reserved.