Runner'lar ve lokasyonlar

Yükü runner'lar üretir. Bu sayfa runner'ın ne olduğunu, kurulumla gelen yerel runner'ları, başka bir şehirden ya da bulut bölgesinden yük göndermek için uzak runner eklemeyi, lokasyonları, etiketleri, kapasiteyi, Kubernetes runner'larını, TLS pin'ini ve runner'ların neden çevrimdışı göründüğünü anlatır.

#Ne işe yarar

• Runner, test edilen sisteme istekleri gönderen ve her saniye metrikleri controller'a ileten süreçtir. Controller testi runner'lara böler; VU sayıları ve istek hızları toplamda tanımdakiyle birebir aynı kalır.
• Lokasyon (location), runner'ın yükü nereden gönderdiğidir (ör. istanbul, frankfurt). Bir koşuyu lokasyonlara yüzdeyle bölebilir, sonuçları lokasyon başına (istek, RPS, ort/p95/p99, hata, lokasyon başına p95 grafiği) görebilirsiniz.
• Runner'lar sayfası her runner'ın durumunu, CPU'sunu, aktif VU'sunu, saat farkını ve sürümünü canlı gösterir.

#Ne zaman kullanılır

• Kurulumdan sonra runner'ların bağlandığını doğrulamak için.
• Daha fazla yük üretmek için yeni runner eklerken.
• Kullanıcılarınızın bulunduğu başka bir şehirden ya da bulut bölgesinden yük göndermek istediğinizde.
• Dashboard'da "Bağlı runner yok; test başlatılamaz." gördüğünüzde.
• Bir runner Çevrimdışı, eski sürüm ya da CPU sınırında göründüğünde.

#Runner nedir

 tarayıcı ──► controller (web arayüzü + REST API) ──gRPC/TLS──► runner'lar (lokasyon A)
                  │                                └──────────► runner'lar (lokasyon B)
               Postgres                                              │
                                                       yük ──► test edilen sistem

• Runner controller'a dışarı doğru bağlanır (gRPC, tek kalıcı stream). Runner'ın sunucusunda gelen port açmak gerekmez; yalnızca controller'ın gRPC portuna (Docker kurulumunda 8471) giden TCP açık olmalıdır.
• Runner controller'a bir runner token'ıyla (sfrun_…) kendini tanıtır. Token Runner'lar sayfasında oluşturulur ve yalnızca bir kez gösterilir.
• Runner her 2 saniyede bir heartbeat gönderir. Üst üste 3 heartbeat (yaklaşık 6 sn) gelmezse controller bağlantıyı düşürür ve runner Çevrimdışı görünür. Bağlantı koparsa runner artan aralıklarla (en çok 15 sn) yeniden bağlanmayı dener.
• Test edilen sisteme giden trafik runner'dan çıkar; runner'ın o sisteme ağ erişimi olmalıdır. Connection secret'ları (veritabanı, Kafka… parolaları) koşu başında controller'dan runner'a bu şifreli hat üzerinden gider.

#Yerel runner ve uzak runner

Yerel runner sayısını değiştirmek için kurulumu yeni sayıyla yeniden çalıştırın: ~/spitfire/install.sh docker --runners 4.

#Runner'lar sayfası

Runner'lar sayfası: Runner, Lokasyon, Durum, Etiketler, CPU, Aktif VU, Saat farkı ve Son görülme sütunlarıyla runner tablosu, altında Runner token'ları kartı

Tablo sütunları:

• Runner — adı (varsayılan makine adı), sürümü ve çekirdek sayısı. Controller'dan farklı sürümdeki runner sarı eski sürüm etiketi taşır.
• Lokasyon — runner'ın lokasyonu; yoksa "tanımsız". Altında controller ile arasındaki gidiş-dönüş süresi.
• Durum — Boşta, Koşuda (yanında koşuya git bağlantısı ya da "sentetik izleme kontrolü"), Boşaltılıyor, Çevrimdışı.
• Etiketler, CPU (sınırdaysa kırmızı), Aktif VU, Saat farkı (50 ms'yi aşarsa sarı), Son görülme.
• Sağdaki düğmeler: Yeni koşu verme (boşalt) / Yeniden koşulara aç ve Kaldır.

Admin olmayanlar tabloyu görür ama runner ekleyemez.

#Runner ekleme

1. Altyapı → Runner'lar sayfasını açın (admin).
2. Sayfanın altındaki Runner token'ları kartında:
   • Ad (ör. eu-west runner'ları) alanına token'ı tanıyacağınız bir ad yazın (zorunlu).
   • Lokasyon (ör. frankfurt) alanına bu token'la gelen runner'ların yazılacağı lokasyonu girin (küçük harf, a-z, 0-9, -, _, .; en çok 40 karakter). Boş bırakırsanız runner lokasyonunu kendisi --location ile söyler.
3. Token oluştur'a tıklayın. Runner token'ı penceresi açılır.

Runner token'ı penceresi: bir kez gösterilen token, Docker, Docker'sız (systemd) ve Windows sekmeleri, hazır kurulum komutları ve controller key pin'i

4. "Bu token bir daha gösterilmeyecek. Şimdi kopyalayın." uyarısına uyun: token'ı Kopyala ile alın ya da doğrudan aşağıdaki hazır komutları kullanın; komutlarda controller adresi, token, pin ve lokasyon zaten yazılıdır.
5. Runner'ı kuracağınız sunucuya uygun sekmeyi seçin: Docker, Docker'sız (systemd) ya da Windows (aşağıdaki bölümler).
6. Komutu o sunucuda çalıştırın. Birkaç saniye içinde runner tabloda Boşta olarak görünür.
7. Pencereyi Kapat ile kapatın. Token listede geçerli olarak kalır; aynı token'la birden çok runner bağlanabilir.

#Docker ile uzak runner

Docker sekmesindeki kurulum betiği (Docker gerekir; bağlantıyı ve pin'i önceden doğrular):

curl -fsSL https://spitfire.tr/install.sh | SPITFIRE_VERSION=<controller sürümü> bash -s -- runner \
  --controller spitfire.ornek.com:8471 --token sfrun_... --ca-pin sha256:... --location frankfurt --runners 1

• --runners N bu sunucuda N runner başlatır.
• --tls pin yerine sistem CA'larıyla doğrular (controller'da şirket/genel CA sertifikası varsa).
• Betik runner'ı controller ile aynı sürüme sabitler; ayarları ~/spitfire/deploy/runner/.env'de tutar.
• Kaldırma: ~/spitfire/uninstall.sh runner (token'ı da silmek için --purge; arayüzden iptal etmeyi unutmayın).

Aynı sekmede tek bir docker run komutu da vardır:

docker run -d --name spitfire-runner --restart unless-stopped \
  -e SPITFIRE_RUNNER_CONTROLLER=spitfire.ornek.com:8471 \
  -e SPITFIRE_RUNNER_TOKEN=sfrun_... \
  -e SPITFIRE_RUNNER_CA_PIN=sha256:... \
  -e SPITFIRE_RUNNER_EPHEMERAL=true \
  algebransoft/spitfire:<sürüm> spitfire-runner

#Docker olmadan Linux sunucuda

Docker'sız (systemd) sekmesi, Linux (amd64/arm64, systemd) sunucuda runner'ı bir systemd servisi olarak kurar. Controller kendi sürümünün runner ikililerini ve install-runner.sh'ı /api/v1/runner-dist/ altında sunar:

curl -fsSLo install-runner.sh http://CONTROLLER:8470/api/v1/runner-dist/install-runner.sh
echo "<sayfadaki sha256>  install-runner.sh" | sha256sum -c -
sudo bash install-runner.sh --from http://CONTROLLER:8470 \
    --controller CONTROLLER:8471 --token sfrun_... --ca-pin sha256:...

• Betik ikiliyi indirir ve açmadan önce SHA-256'sını doğrular.
• spitfire sistem kullanıcısı, /etc/spitfire/runner.env (0600, token) ve sıkılaştırılmış spitfire-runner@.service kurar ve runner'ın bağlanmasını bekler.
• İnternetsiz sunucu: sayfadan .gz dosyasını indirip kopyalayın, --binary ./spitfire-runner-linux-amd64.gz ile kurun.
• Yeniden çalıştırmak günceller (ayarlar korunur); --instances N bir sunucuda N örnek; kaldırma --uninstall [--purge].
• Loglar: journalctl -u spitfire-runner@1.

Runner token'ı penceresinin Docker'sız (systemd) sekmesi: install-runner.sh indirme, sha256 kontrolü ve internetsiz kurulum için .gz dosyaları

#Docker olmadan Windows hizmeti

Windows sekmesinde iki komut vardır:

• Docker Desktop ile (PowerShell) — install.ps1 runner ile Docker'da runner.
• Docker'sız, Windows hizmeti olarak (Yönetici PowerShell) — controller'dan install-runner.ps1 indirilir, SHA-256'sı komutta doğrulanır, runner ikilisininki onun içinde doğrulanır.

Hizmetler spitfire-runner-1…N adıyla Windows ile başlar, çökerse yeniden başlatılır; ayarlar %ProgramData%\Spitfire altında yalnız SYSTEM ve Administrators'ın okuyabileceği dosyalardadır, loglar %ProgramData%\Spitfire\logs. Birden çok runner için -Count N; kaldırmak için -Uninstall.

Runner token'ı penceresinin Windows sekmesi: Docker Desktop komutu ve Windows hizmeti olarak kurulum komutu

#Lokasyonlar

Bir runner'ın lokasyonu iki yoldan belirlenir:

1. Token'a bağlı lokasyon (önerilen): token oluştururken Lokasyon alanını doldurduysanız o token'la gelen her runner bu lokasyona yazılır; runner başka bir lokasyon söylese de.
2. Runner'ın kendi söylediği: token lokasyona bağlı değilse runner --location AD (ya da SPITFIRE_RUNNER_LOCATION) ile söyler. Yerel runner'lar kurulumdaki --location değerini (varsayılan local) kullanır.

Koşuda kullanmak için: test sayfasında Çalıştır → Testi çalıştır penceresinde Lokasyonla'yı seçin, her lokasyonun payını (toplam %100) ve kullanılacak runner sayısını girin (Eşit dağıt yardımcı olur). Bir lokasyonun payı oradaki runner'lara eşit bölünür. Son dağılım testte hatırlanır.

Testi çalıştır penceresinin Lokasyonla sekmesi: her lokasyonun payı ve runner sayısı, Eşit dağıt ve Başlat

Threshold'lara lokasyon kapsamı verilebilir: {"metric":"req_duration","filter":{"location":"frankfurt"},"expr":"p(95)<800"}. Lokasyon filtresi senaryo/step filtresiyle birleştirilemez.

#Etiketler

Etiketler runner'ları gruplamak için serbest anahtar=değer çiftleridir: --labels region=eu,zone=a (ya da SPITFIRE_RUNNER_LABELS). Testi çalıştır penceresindeki Etiketle seçeneği koşuyu belirli etiketleri taşıyan runner'lara gönderir. Belirli runner'ları tek tek seçmek için Seçerek, yalnızca sayı vermek için Sayıyla.

#Kapasite: bir runner kaç VU taşır

Bir runner'ın taşıyabileceği VU sayısı sabit değildir; step'lerin ağırlığına, yanıt boyutuna, think time'a ve makinenin CPU'suna bağlıdır. Pratik yöntem:

1. Testi beklenen yükün küçük bir kısmıyla koşturun.
2. Runner'lar sayfasında CPU sütununu izleyin. CPU sınırına yaklaşan runner kırmızıya döner ve "Runner CPU sınırında: sonuçlar çarpık olabilir" uyarısı verir; bu durumda latency ölçümleri runner'ın kendisinden etkilenir.
3. CPU sınırdaysa runner sayısını artırın (aynı token'la yeni runner ekleyin ya da --runners N) ve yükü Sayıyla daha çok runner'a bölün.

--max-vus (ya da SPITFIRE_RUNNER_MAX_VUS) runner'ın ilan ettiği kapasitedir ve yalnızca bilgi amaçlıdır; yükü sınırlamaz. Kubernetes on-demand runner'larda öneri, pod başına SPITFIRE_ONDEMAND_VUS_PER_RUNNER (varsayılan 1000) VU'dur.

#Kubernetes üzerinde runner

Kubernetes kurulumu runner'ları spitfire-runner Deployment'ı olarak çalıştırır; sayıyı kurulumda --runners N ile ya da şöyle değiştirirsiniz:

kubectl -n spitfire scale deploy/spitfire-runner --replicas=N

On-demand runner'lar: install.sh kubernetes --runners 0 --on-demand-runners 20 sürekli açık yük üreteci bırakmaz. Bir koşu boştaki runner'lardan fazlasını isterse (Testi çalıştır → Sayıyla; pencere testin en yüksek VU'suna göre bir sayı önerir) controller eksikleri aynı imajdan pod olarak açar, koşu onlar bağlanana kadar kuyrukta bekler (genelde 20–60 sn), bitince pod'lar silinir; controller yeniden başlarsa kalanlar temizlenir. Aynı anda en çok N pod açılır. Controller'a yalnız kendi namespace'inde pod yetkisi (Role) verilir, o da yalnız seçenek açıkken (--on-demand-runners 0 kaldırır). Pod boyutu controller'da SPITFIRE_ONDEMAND_CPU, SPITFIRE_ONDEMAND_MEMORY, SPITFIRE_ONDEMAND_VUS_PER_RUNNER ile ayarlanır. Özellik açıkken Runner'lar sayfasının üstünde bilgi bandı görünür.

#Ephemeral runner

Container ya da pod olarak çalışan runner'lar yeniden oluşturulduklarında yeni bir kimlikle kaydolur. Bu yüzden Compose ve Kubernetes runner'ları ile docker run komutu SPITFIRE_RUNNER_EPHEMERAL=true (--ephemeral) ile çalışır: böyle bir runner çevrimdışı kalınca controller onu bir süre sonra listeden kaldırır (varsayılan 5 dakika; controller'da SPITFIRE_RUNNER_REAP_AFTER, 0 kapatır). Böylece eski kayıtlar birikmez.

systemd ve Windows hizmeti olarak kurulan runner'lar ephemeral değildir; kimliklerini bir dosyada (--id-file) tutar ve yeniden başladıklarında aynı satırda görünür.

#TLS pin ve sertifikalar

• Uzak runner'ların bağlandığı 8471 portu her zaman TLS'tir. Controller kendi kimliğini ilk açılışta üretir ve saklar.
• Runner controller'ı anahtarının pin'i ile doğrular: --ca-pin sha256:… (birden çok pin virgülle verilebilir). Pin, token penceresinin altında "Runner controller'ı bu key pin ile doğrular:" satırında yazar.
• Controller'a kendi sertifikanızı (SPITFIRE_GRPC_TLS_CERT, SPITFIRE_GRPC_TLS_KEY) verdiyseniz runner'da pin yerine --tls (sistem CA'ları) ya da --ca <PEM dosyası> kullanın.
• --tls-insecure sertifikayı doğrulamaz; yalnızca test içindir.
• Aynı makinedeki/cluster'daki runner'lar yayınlanmayan düz 8475'ten bağlanır (SPITFIRE_GRPC_INTERNAL_ADDR); bu portu asla dışarı açmayın.

#Runner güncelleme

Uzak runner'ları controller ile aynı sürümde tutun; Runner'lar sayfası farklı sürümü sarı eski sürüm etiketiyle işaretler.

• İkiliden kurulanlar (systemd, Windows hizmeti): eski runner'ın yanındaki Güncelle'ye tıklayın (ya da tablonun üstündeki N runner'ı X sürümüne güncelle). Runner yeni sürümü controller'dan indirir, Spitfire'ın imzasını kendisi doğrular (imzasız ya da daha eski bir sürümü kabul etmez) ve yeniden başlar; birkaç saniye bağlantısı kesilir. Koşudaki runner'lar güncellenmez.
• Runner'ları otomatik güncelle (varsayılan kapalı) açıkken controller bunu kendisi yapar: runner boşta kaldığı ilk anda, her lokasyonda aynı anda yalnız biri, koşudaki runner hiçbir zaman. Bir runner'da başarısız olan sürüm onda yeniden denenmez.
• Docker ve Kubernetes runner'ları imajlarıyla güncellenir: kurulum komutunu tekrar çalıştırın (uzak Docker runner'ı için token penceresindeki install.sh runner komutu; controller güncellemesi yerel runner'ları da günceller).

#Boşaltma, kaldırma ve token iptali

• Yeni koşu verme (boşalt): runner bağlı kalır ama yeni koşu almaz (durum Boşaltılıyor); bakım öncesi kullanın. Yeniden koşulara aç geri alır.
• Kaldır: runner listeden kaldırılır ve bağlantısı kesilir. Token'ı geçerliyse yeniden bağlanabilir. Koşudaki runner kaldırılamaz.
• İptal et (token listesinde): iptal edilen token'la bağlı runner'lar koşu dışındaysa hemen düşürülür ve bir daha bağlanamaz. systemd runner'ı bu durumda çıkış kodu 3 ile durur ve systemd onu yeniden başlatmaz.

#Runner ortam değişkenleri

Her --bayrak SPITFIRE_RUNNER_<BAYRAK> ortam değişkeniyle de verilebilir:

#Sık karşılaşılan sorunlar

Belirti: Dashboard "Bağlı runner yok; test başlatılamaz." diyor ya da koşu "Yeterli boşta runner yok" hatası veriyor. Neden: Hiç runner bağlı değil, hepsi başka bir koşuda ya da boşaltılıyor. Çözüm: Runner'lar sayfasında durumlara bakın. Yerel runner'lar duruyorsa cd ~/spitfire && docker compose -p spitfire -f deploy/docker/docker-compose.yml ps ile kontrol edip kurulumu yeniden çalıştırın. Süren koşunun bitmesini bekleyin ya da yeni runner ekleyin.

Belirti: Runner Çevrimdışı görünüyor; Son görülme ilerliyor. Neden: Runner süreci durdu ya da controller'a ağ erişimi kesildi (heartbeat 6 sn'den uzun gelmedi). Çözüm: Runner sunucusunda logu okuyun: Docker'da docker compose -p spitfire-runner -f deploy/runner/docker-compose.yml logs runner (~/spitfire'da) ya da docker logs spitfire-runner; systemd'de journalctl -u spitfire-runner@1; Windows'ta %ProgramData%\Spitfire\logs. Controller'ın gRPC portuna (8471) TCP erişimini nc -vz CONTROLLER 8471 ile test edin. Ephemeral bir runner'ın eski kaydıysa 5 dakika sonra kendiliğinden kalkar.

Belirti: Runner hiç görünmüyor; logda invalid enrollment token. Neden: Token yanlış kopyalandı ya da iptal edildi. Çözüm: Yeni bir token oluşturup komutu yeni token'la yeniden çalıştırın.

Belirti: Kurulum betiği pin doğrulamasında duruyor ya da runner TLS hatası veriyor. Neden: --ca-pin başka bir controller'ın pin'i, controller adresi yanlış ya da arada TLS'i kesen bir cihaz var. Çözüm: Pin'i token penceresinden yeniden kopyalayın; adresin bu controller'ın 8471 portu olduğundan emin olun. Kendi sertifikanızı kullanıyorsanız --tls ya da --ca kullanın.

Belirti: Testi çalıştır penceresinde "Boşta, lokasyonu tanımlı runner yok." Neden: Runner'lar lokasyonsuz bağlanmış. Çözüm: Lokasyonlu bir token oluşturup runner'ı onunla yeniden bağlayın ya da runner'ı --location ile başlatın.

Belirti: Runner'ın yanında sarı eski sürüm etiketi. Neden: Runner controller'dan farklı sürümde. Çözüm: Runner güncelleme.

Belirti: CPU sütunu kırmızı; "Runner CPU sınırında: sonuçlar çarpık olabilir". Neden: Runner'ın makinesi yükü üretmeye yetmiyor; ölçülen latency runner'ın kendi gecikmesini içerir. Çözüm: Daha çok runner ekleyip yükü bölün ya da daha güçlü bir makine kullanın.

Belirti: Saat farkı sarı. Neden: Runner'ın saati controller'dan 50 ms'den fazla farklı. Çözüm: Runner sunucusunda NTP'yi açın. Controller farkı düzeltir ama NTP önerilir.

Belirti: Koşu başlarken "Bu koşu 2 runner istiyor; ücretsiz sürüm bir koşuda en fazla 1 runner'a izin veriyor." Neden: Lisans limiti. Çözüm: Runner sayısını düşürün ya da lisansı yükseltin: Lisans.

Belirti: Kubernetes'te on-demand koşu kuyrukta uzun süre bekliyor. Neden: Pod'lar açılamıyor (kaynak yetersiz, imaj çekilemiyor). Çözüm: kubectl -n spitfire get pods ve kubectl -n spitfire describe pod <pod> ile nedenine bakın; Sistem olayları sayfasını kontrol edin.

#İlgili sayfalar

• Başlarken
• Kurulum
• Lisans
• Koşu ve sonuçlar
• Sorun giderme