GitHub Actions Runner Controller (ARC) Kubernetes Kurulum Rehberi

GitHub Actions, modern yazılım geliştirme süreçlerinin vazgeçilmez bir parçası haline geldi. Ancak bulut tabanlı runner'lar bazen yetersiz kalabiliyor - özellikle özel ağ kaynaklarına erişim gerektiren, büyük build'ler çalıştıran veya maliyet optimizasyonu isteyen ekipler için. İşte tam bu noktada GitHub Actions Runner Controller (ARC) devreye giriyor. ARC, Kubernetes cluster'ınız üzerinde self-hosted runner'lar çalıştırmanıza olanak tanıyan güçlü bir çözüm. Bu makalede, ARC'nin ne olduğunu, neden kullanmanız gerektiğini ve Kubernetes üzerinde nasıl kuracağınızı detaylı olarak ele alacağız.

GitHub Actions Runner Controller Nedir?

Actions Runner Controller, Kubernetes üzerinde GitHub Actions self-hosted runner'larınızı çalıştırmanızı sağlayan bir Kubernetes controller'ıdır. GitHub'ın sunduğu hazır runner'ların aksine, kendi altyapınızda runner'ları barındırarak tam kontrol sahibi olursunuz. ARC, runner'ların otomatik olarak ölçeklenmesini, yeniden başlatılmasını ve yönetilmesini sağlar, böylece CI/CD pipeline'larınız kesintisiz çalışır.

ARC'nin sunduğu temel özellikler arasında otomatik yatay ölçeklendirme, yüksek kullanılabilirlik, özelleştirilebilir runner ortamları ve maliyet optimizasyonu bulunur. Özellikle büyük ekipler ve kurumsal projeler için bu özellikler kritik öneme sahiptir. Runner'lar yalnızca ihtiyaç duyulduğunda oluşturulur ve iş tamamlandığında otomatik olarak temizlenir, bu da kaynak kullanımını optimize eder.

ARC ve Actions Runner Controller Arasındaki Fark

GitHub, eski "actions-runner-controller" (ARC) projesini kullanımdan kaldırarak yerine "Actions Runner Scale Set" adlı yeni bir mimari getirdi. Yeni mimari, runner'ların GitHub API ile doğrudan iletişim kurmasını sağlar ve daha iyi ölçeklenebilirlik sunar. Bu makalede güncel olan Scale Set yaklaşımını ele alacağız. Eski PAT (Personal Access Token) tabanlı kimlik doğrulama yerine artık GitHub App kimlik doğrulaması tercih ediliyor.

Neden Kubernetes Üzerinde Runner Kullanmalısınız?

Kubernetes üzerinde self-hosted runner'lar çalıştırmanın birçok avantajı vardır. İlk olarak, ölçeklenebilirlik açısından büyük esneklik elde edersiniz. Yoğun CI/CD dönemlerinde runner sayısı otomatik olarak artar, düşük trafikli dönemlerde ise sıfıra iner. Bu, bulut maliyetlerinizi önemli ölçüde düşürür. İkinci olarak, güvenlik açısından runner'lar izole edilmiş pod'larda çalışır ve özel ağ kaynaklarına erişim sağlayabilir. Üçüncü olarak, özelleştirme açısından kendi Docker image'larınızı kullanarak spesifik yazılım araçları ve bağımlılıkları yükleyebilirsiniz.

Geleneksel VM Tabanlı Runner'lara Göre Avantajları

Geleneksel VM tabanlı runner'larla karşılaştırıldığında, Kubernetes tabanlı yaklaşım birçok avantaj sunar. VM'lerde her runner için ayrı bir makine tutmanız gerekirken, Kubernetes'te aynı node üzerinde birden fazla runner pod'u çalışabilir. Bu, kaynak kullanımını %80'e varan oranlarda artırır. Ayrıca, Kubernetes'in sağladığı otomatik yeniden başlatma özelliği sayesinde arızalı runner'lar hızla yerine yenileri gelir. Bildirimler ve log yönetimi de Kubernetes'in doğal integrasyonlarıyla çok daha kolay hale gelir.

Ön Gereksinimler

ARC kurulumuna başlamadan önce bazı ön gereksinimleri karşılamanız gerekir. İlk olarak, çalışan bir Kubernetes cluster'ınız olmalıdır. Bu bir minikube, kind, k3s veya bulut tabanlı bir Kubernetes servisi olabilir. İkinci olarak, kubectl komut satırı aracınızın yapılandırılmış olması ve cluster'a erişim yetkisine sahip olmanız gerekir. Üçüncü olarak, Helm 3 veya daha yüksek bir sürümünün yüklü olması gerekir. Son olarak, GitHub hesabınızda bir organizasyon veya repository sahibi olmanız ve bir GitHub App oluşturma yetkinizin bulunması gerekir.

Kubernetes Cluster Hazırlığı

Kubernetes cluster'ınızda birkaç namespace oluşturmanız gerekecek. İlk olarak, controller'ın çalışacağı sistem namespace'ini oluşturun:

kubectl create namespace arc-systems

Ardından, runner'ların çalışacağı namespace'i oluşturun:

kubectl create namespace arc-runners

Bu namespace'ler, controller ve runner pod'larının izole edilmiş ortamlarda çalışmasını sağlar. Production ortamlar için bu ayrımı korumanızı öneririz.

GitHub App Oluşturma ve Yapılandırma

ARC, GitHub API ile iletişim kurmak için bir GitHub App kullanır. Bu, PAT'ye göre daha güvenli ve ölçeklenebilir bir kimlik doğrulama yöntemidir. GitHub App oluşturmak için organizasyon ayarlarına gidin ve "Developer settings" bölümünden "GitHub Apps" seçeneğine tıklayın. Yeni bir GitHub App oluşturun ve gerekli izinleri yapılandırın.

GitHub App İzinleri

GitHub App'in doğru çalışması için belirli izinleri vermeniz gerekir. Repository izinleri bölümünde "Administration" (okuma-yazma), "Contents" (okuma-yazma), "Metadata" (salt okunur) ve "Workflows" (okuma-yazma) izinlerini etkinleştirin. Ayrıca, "Self-hosted runners" bölümünde "Read and write" iznini vermeniz gerekir. Bu izinler, runner'ların kayıt edilmesi, workflow'ların izlenmesi ve sonuçların raporlanması için gereklidir.

Webhook URL'si olarak, GitHub App'inize erişilebilir bir URL vermeniz gerekir. Geliştirme ortamında bu sorun yaratabilir, bu nedenle webhook olmadan da kurulum yapabilirsiniz - runner'lar çalışır ancak GitHub tarafından bazı event'ler kaçırılabilir. Alternatif olarak, ngrok gibi bir tunnel servisi kullanarak webhook'ları yerel ortamınıza yönlendirebilirsiniz.

GitHub App Kimlik Bilgilerini İndirme

GitHub App'i oluşturduktan sonra, App ID'sini ve private key'i indirmeniz gerekir. App ayarlarında "General" bölümünde App ID'yi bulabilirsiniz. Private key'i oluşturmak için "Private keys" bölümüne gidin ve "Generate a new private key" butonuna tıklayın. Bu key'i güvenli bir yerde saklayın - bir daha indiremeyeceksiniz.

cert-manager Kurulumu

ARC, Kubernetes üzerinde çalışırken TLS sertifikaları için cert-manager'ı kullanır. Öncelikle cert-manager'ı yükleyin:

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.14.0/cert-manager.yaml

Bu komut, cert-manager'ı default namespace'e kurar. Kurulumun tamamlandığını doğrulamak için pod'ların çalışıp çalışmadığını kontrol edin:

kubectl get pods -n cert-manager

Tüm pod'lar "Running" durumuna geçtikten sonra bir sonraki adıma geçebilirsiniz. Bu genellikle birkaç dakika sürer.

Helm Repository Ekleme

ARC'yi Helm ile kurmak için GitHub'ın resmi Helm repository'sini ekleyin:

helm repo add actions-runner-controller https://actions-runner-controller.github.io/actions-runner-controller
helm repo update

Repository güncellemesi tamamlandıktan sonra, mevcut chart'ları listeleyebilirsiniz:

helm search repo actions-runner-controller

Bu komut, mevcut ARC chart'larını ve versiyonlarını gösterecektir. En güncel versiyonu kullanmanızı öneririz.

Runner Controller Kurulumu

Şimdi runner controller'ı kurma zamanı geldi. Öncelikle, GitHub App kimlik bilgilerini içeren bir Kubernetes secret oluşturun. App ID ve private key'inizi kullanarak secret'ı oluşturun:

kubectl create secret generic arc-github-app-secret \
  -n arc-systems \
  --from-literal=github_app_id=YOUR_APP_ID \
  --from-file=github_app_private_key=./your-private-key.pem

Secret oluşturulduktan sonra, Helm ile controller'ı kurun:

helm upgrade --install --namespace arc-systems --create-namespace \
  --set=githubConfigSecret=arc-github-app-secret \
  --set=githubConfigUrl=https://github.com/YOUR_ORGANIZATION \
  actions-runner-controller actions-runner-controller/actions-runner-controller

Bu komut, controller'ı arc-systems namespace'ine kurar ve GitHub organizasyonunuzla bağlantılandırır. Kurulum tamamlandıktan sonra, controller pod'unun çalışıp çalışmadığını kontrol edin:

kubectl get pods -n arc-systems

Controller pod'u "Running" durumunda olmalıdır. Eğer bir hata görürseniz, log'ları inceleyin:

kubectl logs -n arc-systems -l app.kubernetes.io/name=gha-runner-scale-set-controller

Runner Scale Set Oluşturma

Controller kurulduktan sonra, bir Runner Scale Set oluşturmanız gerekir. Bu scale set, ihtiyaca göre runner pod'larını otomatik olarak ölçeklendirecektir. Öncelikle, aşağıdaki içerikle bir YAML dosyası oluşturun (örneğin runner-scale-set.yaml):

apiVersion: actions.github.com/v1alpha1
kind: RunnerScaleSet
metadata:
  name: my-runner-scale-set
  namespace: arc-runners
spec:
  githubConfigUrl: https://github.com/YOUR_ORGANIZATION
  githubConfigSecret: arc-github-app-secret
  minRunners: 0
  maxRunners: 5
  runnerGroupName: "Default"
  template:
    spec:
      containers:
      - name: runner
        image: ghcr.io/actions/actions-runner:latest
        command: ["./runner.sh"]

Bu yapılandırma, 0 ile 5 arasında runner oluşturulmasına izin verir. Workflow talebi geldiğinde runner'lar otomatik olarak oluşturulur ve iş tamamlandıktan sonra temizlenir. Organizasyon adınızı ve gerekli diğer değerleri değiştirmeyi unutmayın.

Scale Set'i Uygulama

YAML dosyasını oluşturduktan sonra, Kubernetes'e uygulayın:

kubectl apply -f runner-scale-set.yaml

Scale set'in oluşturulduğunu doğrulamak için:

kubectl get runnerscaleset -n arc-runners

Birkaç dakika içinde, GitHub organizasyonunuzun "Actions" ayarlarında yeni runner'ların göründüğünü görmeniz gerekir. İlk runner pod'u oluşturulana kadar biraz zaman alabilir - bu, GitHub App kimlik doğrulaması ve ilk Runner kaydının gerçekleşmesi için gereklidir.

Workflow Dosyası ile Test

Kurulumun çalışıp çalışmadığını test etmek için basit bir workflow oluşturun. Repository'nizde .github/workflows/ dizininde test.yaml adlı bir dosya oluşturun:

name: Test Self-Hosted Runner
on:
  workflow_dispatch:

jobs:
  test-runner:
    runs-on: self-hosted
    steps:
      - name: Check runner info
        run: |
          echo "Runner: $(hostname)"
          echo "Kubernetes: $(kubectl version --client)"
      - name: List files
        run: ls -la

Bu workflow, "workflow_dispatch" tetikleyicisiyle manuel olarak çalıştırılabilir. runs-on: self-hosted ifadesi, GitHub'a bu işin organizasyonunuzdaki herhangi bir self-hosted runner'da çalışabileceğini bildirir.

Workflow'u Tetikleme

Workflow'u tetiklemek için GitHub repository'nize gidin, "Actions" sekmesine tıklayın ve "Test Self-Hosted Runner" workflow'unu seçin. Sağ üstteki "Run workflow" butonuna tıklayarak workflow'u başlatın. Bir runner pod'unun oluşturulduğunu Kubernetes'te gözlemleyebilirsiniz:

kubectl get pods -n arc-runners -w

Workflow başarıyla tamamlandığında, runner pod'unun otomatik olarak silindiğini görmeniz gerekir - bu, maxRunners parametresine ve idle timeout'a bağlıdır.

Ölçeklendirme Stratejileri

ARC'nin sunduğu ölçeklendirme seçeneklerini anlamak, altyapınızı optimize etmek için kritik öneme sahiptir. MinRunners parametresi, her zaman çalışır durumda tutulacak minimum runner sayısını belirler. Sürekli CI/CD aktivitesi olan ekipler için bu değer sıfır olmamalıdır - böylece ilk workflow başlatma süresi azalır. MaxRunners parametresi ise aynı anda çalışabilecek maksimum runner sayısını belirler.

Otomatik Ölçeklendirme Davranışı

Runner Scale Set, GitHub'dan gelen workflow talep sayısına göre otomatik olarak ölçeklenir. Bir workflow tetiklendiğinde ve mevcut runner yoksa veya mevcut runner'lar meşgulse, yeni bir runner pod'u oluşturulur. Runner pod'u GitHub'a kaydolur ve workflow'u çalıştırmaya hazır hale gelir. Workflow tamamlandıktan sonra, runner belirli bir süre (varsayılan olarak 1 saat) boşta kalırsa otomatik olarak temizlenir.

Ölçeklendirme davranışını daha iyi kontrol etmek için, maxRunners değerini iş yükünüze göre ayarlayın. Büyük ekipler veya yoğun CI/CD süreçleri için bu değeri artırabilirsiniz. Ayrıca, runner pod'larının kaynak limitlerini de yapılandırabilirsiniz - bu, tek bir runner'ın cluster kaynaklarını aşırı tüketmesini önler.

Güvenlik En İyi Uygulamaları

ARC kurulumunuzun güvenliğini sağlamak için birkaç en iyi uygulamayı takip etmenizi öneririz. İlk olarak, GitHub App'in izinlerini yalnızca gerekli olanlarla sınırlayın. İkinci olarak, runner pod'ları için RBAC politikaları oluşturun - yalnızca gerekli Kubernetes kaynaklarına erişim izni verin. Üçüncü olarak, runner'ların çalıştığı namespace'ler için network politikaları uygulayın.

Runner İzolasyonu

Her runner pod'unun izole bir ortamda çalışmasını sağlamak için, pod güvenlik politikaları veya security context'ler kullanın. Runner'ların root yetkisiyle çalışmasını engelleyin ve yalnızca gerekli yeteneklere (capabilities) izin verin. Ayrıca, sensitive verileri runner'lara environment variable olarak değil, Kubernetes secret'ları aracılığıyla aktarın.

Özellikle public repository'lerde çalışan workflow'lar için, runner'ların dışarıdan gelen kötü amaçlı kodlara karşı korunması önemlidir. Runner'ları ayrı bir Kubernetes node pool'unda çalıştırmayı düşünün - bu, potansiyel saldırıların ana cluster'ı etkilemesini önler.

Monitoring ve Troubleshooting

ARC kurulumunuzu izlemek ve sorunları gidermek için Kubernetes'in native monitoring araçlarını kullanabilirsiniz. İlk olarak, controller ve runner log'larını düzenli olarak kontrol edin:

kubectl logs -n arc-systems -l app.kubernetes.io/name=gha-runner-scale-set-controller
kubectl logs -n arc-runners -l app.kubernetes.io/name=actions-runner

İkinci olarak, Prometheus ve Grafana kullanarak metrikleri toplayabilirsiniz. ARC, controller ve runner metriklerini Prometheus formatında sunar. Bu metrikler arasında toplam runner sayısı, active runner sayısı, queued jobs sayısı ve ölçeklendirme olayları bulunur.

Sık Karşılaşılan Sorunlar

Kurulum sırasında en sık karşılaşılan sorunlar arasında GitHub App kimlik doğrulama hataları, network bağlantı sorunları ve kaynak yetersizlikleri yer alır. Kimlik doğrulama hataları genellikle yanlış App ID veya private key'den kaynaklanır - secret'ları doğrulayın. Network sorunları için GitHub API endpoint'lerine erişimi kontrol edin. Kaynak yetersizlikleri için Kubernetes node'larının yeterli CPU ve memory'ye sahip olduğundan emin olun.

Sonuç

GitHub Actions Runner Controller, Kubernetes üzerinde self-hosted runner'lar çalıştırmak isteyen ekipler için güçlü ve esnek bir çözüm sunar. Otomatik ölçeklendirme, maliyet optimizasyonu ve tam kontrol avantajlarıyla CI/CD pipeline'larınızı bir üst seviyeye taşıyabilirsiniz. Bu makalede ele aldığımız kurulum adımlarını takip ederek, kendi Kubernetes cluster'ınızda self-hosted runner'ları dakikalar içinde çalıştırabilirsiniz.

ARC'nin sunduğu esneklik sayesinde, özel build ortamları oluşturabilir, özel ağ kaynaklarına erişim sağlayabilir ve CI/CD maliyetlerinizi önemli ölçüde düşürebilirsiniz. Özellikle büyük ekipler ve kurumsal projeler için bu yaklaşım, GitHub'ın sunduğu hazır runner'lara göre çok daha avantajlıdır. Kurulum sürecinde herhangi bir sorunla karşılaşırsanız, GitHub'ın resmi dokümantasyonunu ve topluluk kaynaklarını incelemenizi öneririz.