Agent kurulumu

Agent nedir, neden dışarı bağlanır?#

Agent, pipeline step'lerini sizin altyapınızda çalıştıran süreçtir. Master'a kendisi bağlanır: düzenli aralıklarla HTTPS üzerinden heartbeat gönderir, bekleyen işleri bu heartbeat'lerde üstlenir, logları ve sonuçları geri yollar.

Bu yüzden:

• Agent'ın çalıştığı makineye ya da cluster'a dışarıdan bağlantı açmanız gerekmez. NAT ve firewall arkasında çalışır.
• Agent'ın yalnızca EJO adresinize (https://acme.ejocloud.com) HTTPS ile çıkabilmesi gerekir. Bir proxy kullanıyorsanız bu adrese çıkışa izin verin.
• Master hiçbir zaman sizin cluster'ınıza bağlanmaz ve kubeconfig istemez.

Ön koşullar#

• Agent'ın kaydolacağı bir environment. Yoksa Altyapı > Environment'lar > Yeni environment ile oluşturun. Bkz. Environment'lar.
• Agent kurulumunda token ve manifest yalnızca admin kullanıcılara gösterilir.
• Kubernetes için cluster'a kubectl apply yapabileceğiniz yetki; Docker için Docker kurulu bir Linux sunucu.

Kurulum yöntemini seçin#

Environment sayfasında Agent kur'a basın. Üç sekme vardır:

Kubernetes'e kurulum#

1. Kubernetes (otomatik kurulum) sekmesini açın.

2. Alanları doldurun:

   • Agent name: Agent'ın konsolda görünecek adı.
   • Namespace (opsiyonel): Agent'ın çalışacağı namespace. Boş bırakırsanız ejo-agent kullanılır; yoksa oluşturulur.
   • Master URL (opsiyonel override): Agent'ın master'a ulaşacağı adres. EJO Cloud'da varsayılan, EJO adresinizdir; genellikle değiştirmeniz gerekmez.
   • Registry pull credential: EJO Cloud'da agent image'ını çekmek için gereken bilgi hazır gelir; bu alanları boş bırakabilirsiniz.
   • Preview namespace'leri (Review App'ler): Bu agent PR başına preview namespace'leri oluşturacaksa işaretleyin. Production agent'larında işaretlemeyin. Bkz. Preview'lar.

3. Manifest üret'e basın.

4. Sayfada çıkan komutu kendi kubectl erişiminizle çalıştırın:

   kubectl apply -f "https://acme.ejocloud.com/api/v1/agent-installations/<id>/manifest?key=<gizli-anahtar>"
   

5. Agent ilk heartbeat'ini gönderdiğinde sayfa kendiliğinden güncellenir. Kurulum tamamlanınca Agent'ı gör ile agent sayfasına geçebilirsiniz.

Uyarı: Komuttaki URL bir gizli anahtar içerir ve manifest agent'ın token'ını taşır. Bu URL'i paylaşmayın. Manifest kullanıldıktan sonra tekrar indirilemez.

Manifest; namespace'i, agent'ın ServiceAccount'unu, agent namespace'iyle sınırlı bir Role'ü, gerekli Secret'ları ve agent Deployment'ını oluşturur. Uygulamadan önce içeriğini Manifest'i göster ile inceleyebilirsiniz.

İpucu: Agent, kendi namespace'indeki Secret'ları okuyabilir. Uygulamanızın secret'larını agent'ın namespace'inde tutmayın.

Preview namespace'leri ve admission policy#

Preview namespace'leri (Review App'ler) işaretliyse manifest, agent'ın yalnızca ejo.dev/preview=true label'lı namespace'leri oluşturup silebilmesi için ek ClusterRole'ler ve bir ValidatingAdmissionPolicy ekler. Admission policy Kubernetes 1.30 veya üstünü gerektirir; daha eski bir cluster'da Admission policy for preview namespaces kutusunun işaretini kaldırın.

Docker'a kurulum#

1. Docker / Manuel sekmesini açın.

2. Agent name ve Master URL (agent'ın göreceği adres) alanlarını kontrol edin. Master URL, agent'ın çalışacağı makineden EJO'ya ulaşılan adres olmalıdır: https://acme.ejocloud.com.

3. Registration token oluştur'a basın. Token komutlara eklenir; tek kullanımlıktır, varsayılan olarak 1 saat geçerlidir ve sayfadan ayrılınca tekrar gösterilmez.

4. Docker container seçeneğindeki komutu kopyalayıp Docker host'unuzda çalıştırın. Komut şu biçimdedir:

   docker run -d --name ejo-agent \
     -e EJO_AGENT_MASTER_URL=https://acme.ejocloud.com \
     -e EJO_AGENT_NAME=production-agent \
     -e EJO_AGENT_ENVIRONMENT_ID=<environment-id> \
     -e EJO_AGENT_REGISTRATION_TOKEN=<registration-token> \
     -v ./ejo-agent-data:/etc/ejo-agent \
     -v ejo-agent-cache:/var/cache/ejo \
     -e EJO_AGENT_CACHE_DIR=/var/cache/ejo \
     -v /var/run/docker.sock:/var/run/docker.sock \
     <agent-image>
   

   Image adı olarak konsolun gösterdiğini kullanın.

• -v /var/run/docker.sock:/var/run/docker.sock agent'ın host'un Docker daemon'ıyla build alıp container başlatmasını sağlar.

• -v ./ejo-agent-data:/etc/ejo-agent zorunludur: registration token tek kullanımlık olduğu için agent aldığı kimliği buraya yazar ve container yeniden başladığında tekrar kaydolmaya çalışmaz.

• -v ejo-agent-cache:/var/cache/ejo ve EJO_AGENT_CACHE_DIR=/var/cache/ejo agent'ın lokal step cache'ini bir volume'de tutar; container yeniden başlayınca ya da image yükseltilince cache kaybolmaz. Bunlar olmadan cache container'ın içinde durur ve her seferinde boş başlar. EJO her cache'in bir kopyasını master'da da tutar (remote cache), yeni bir agent oradan ısınır; limitler için Organization settings altındaki cache ayarlarına bakın.

Binary kurulumu#

Config dosyası (manuel / systemd) seçeneği, /etc/ejo-agent/config.json içeriğini ve agent'ı başlatacak komutu verir:

{
  "master_url": "https://acme.ejocloud.com",
  "name": "production-agent",
  "environment_id": "<environment-id>",
  "heartbeat_interval": "10s"
}

sudo EJO_AGENT_REGISTRATION_TOKEN=<registration-token> ./ejo-agent --config /etc/ejo-agent/config.json

Agent ilk açılışta kaydolur ve aldığı token'ı aynı dosyaya geri yazar.

Agent ayarları#

Docker ve binary kurulumlarında şu environment variable'ları da kullanılabilir:

Agent durumunu izleme#

Altyapı > Agent'lar sayfası tüm agent'ları, sürümlerini ve son heartbeat zamanlarını listeler.

• Yeni kurulan agent ilk heartbeat'ine kadar PENDING görünür.
• Heartbeat süresini kaçıran agent OFFLINE olur. Yeniden bağlandığında kendiliğinden ONLINE'a döner.
• Bekleyen bir deployment, environment'taki online bir agent'ın bir sonraki heartbeat'inde üstlenilir.

Agent'ı silerseniz kaydı kaldırılır; agent çalışıyorsa bir sonraki heartbeat'inde çalışan işini iptal eder ve kapanır.

Agent'ı güncelleme#

Kubernetes agent'ları#

1. Altyapı > Agent'lar sayfasında agent'ı açın.
2. Image'ı yükselt bölümünde yeni image'ı girin. Boş bırakırsanız EJO'nun varsayılan agent image'ı kullanılır.
3. Onaylayın. Görev önce "rolling out" görünür; yeni agent süreci master'a bağlanınca "done" olur.

Notlar:

• Agent bir iş çalıştırırken upgrade başlatılamaz; iş bitince tekrar deneyin.
• Yeni süreç 5 dakika içinde bağlanmazsa "stalled" uyarısı çıkar: yeni pod ayağa kalkmamış, eski pod çalışmaya devam ediyordur.
• Agent sayfasındaki Build ve Image digest değerleri yükseltmeden sonra değişmelidir. Aynı kalırsa konsol uyarır; kullandığınız tag büyük ihtimalle hâlâ eski image'ı gösteriyordur.

Kubernetes agent'larda cache#

Deployment, lokal step cache için /var/cache/ejo altına bir emptyDir mount eder; boyutu environment'ın Cache maks. (GB) değerinden türetilir. Bilerek kalıcı volume değildir: kalıcı kopya master'daki remote cache'tir ve yeniden başlayan pod oradan restore eder. Container step'ler kendi Job pod'unda çalışır; cache ve needs_artifacts o pod'a restore edilir ve oradan save edilir, böylece davranış Docker agent'ıyla aynıdır. Bunun için agent'ın remote_cache capability'sini bildiren bir sürüme yükseltilmiş olması gerekir.

Step log'ları#

log_append capability'sini bildiren bir agent, step log'unu her saniye komple göndermek yerine büyüdükçe yalnızca yeni byte'ları gönderir. Her step'in log'u Organization settings altındaki Step log maks. (MB) ile sınırlanır (default 10). Daha fazla log yazan step'te console'da ilk yarı ve son yarı kalır, ortası kesilen yerde tek bir marker satırı görünür; tam log blob store'a yüklenir ve step'te Ham logu indir ile alınır. Ham log'lar, log metniyle birlikte Log retention tarafından silinir. Eski agent'lar tam snapshot göndermeye devam eder; master bunları da aynı limite keser.

Docker ve binary agent'lar#

Konsoldan image yükseltme yalnızca Kubernetes agent'ları için vardır. Docker agent'ını güncellemek için container'ı yeni image ile yeniden oluşturun; ./ejo-agent-data volume'ünü aynı bıraktığınız sürece agent kimliğini korur ve yeniden kaydolmaz. Binary kurulumda binary'yi değiştirip servisi yeniden başlatın.

Not: Bazı özellikler (harici secret manager'lar, otomatik SBOM taraması, debug oturumları) agent'ın yeni bir sürümde olmasını gerektirir. Agent eskiyse deployment "upgrade the agent" mesajıyla durur ya da ilgili özellik atlanır.

Sonraki adımlar#

• Environment'lar
• Bir repo bağlayın
• Sorun giderme: agent offline