Troubleshooting Fleet Deployments in Rancher

Dağıtım Yaşam Döngüsünü İzleme: "Happy Path"

Bir sorunu çözmeden önce, her şeyin yolunda gittiği bir senaryonun nasıl göründüğünü anlamamız gerekir. Fleet, bir değişikliği Git deposundan alıp kümenize dağıttığında, bu süreç birkaç aşamadan geçer.

1. Rancher Arayüzü (UI) ile İzleme

Rancher UI, dağıtımlarınızın durumu hakkında hızlı bir görsel geri bildirim sağlar.

• Git Repoları: Rancher'da Sürekli Teslimat (Continuous Delivery) bölümüne gittiğinizde, GitRepo kaynaklarınızı ve durumlarını görürsünüz. Active durumu, Fleet'in depoyu başarıyla klonladığı ve izlediği anlamına gelir.
• Bundle'lar (Demetler): Bir GitRepo'ya tıkladığınızda, içindeki Bundle'ları görürsünüz. Her bir Bundle, fleet.yaml dosyanızdaki bir hedef (target) için oluşturulan kaynak koleksiyonunu temsil eder. Bundle'ın durumu da dağıtımın genel sağlığı hakkında bilgi verir.

Aşağıdaki kısa video kesiti, bir değişiklik push edildikten sonra Fleet'in dağıtım durumunu in progress (devam ediyor) olarak nasıl güncellediğini ve ardından kısa sürede completed (tamamlandı) durumuna geçtiğini göstermektedir. Bu, başarılı bir dağıtım döngüsüdür.

2. kubectl ile İzleme

Arayüzün yanı sıra, kubectl komut satırı aracı da size daha detaylı ve script'lenebilir bir izleme imkanı sunar. Fleet'in temel nesneleri Kubernetes CRD'leridir (Custom Resource Definitions).

• GitRepo: Dağıtımın başlangıç noktası.

  
  
  
  # fleet-default ad alanındaki (veya sizinkinin) GitRepo'ları listeleyin
  kubectl get gitrepos -n fleet-default
  

  Çıktıda RESOURCES ve READY sütunlarını kontrol edin. Örneğin 1/1 değeri, hedeflenen 1 bundle'ın da hazır olduğu anlamına gelir. 0/1 ise bir sorun olduğunu gösterir.

• Bundle: GitRepo tarafından oluşturulan ve belirli bir hedef kümeye yönelik kaynakları içeren paket.

  
  
  
  # Tüm Bundle'ları listeleyin
  kubectl get bundles -A
  

• BundleDeployment: Bir Bundle'ın hedef kümedeki gerçek dağıtımını temsil eden nesne. Her hedef küme için bir tane oluşturulur.

  
  
  
  # Tüm BundleDeployment'ları listeleyin
  kubectl get bundledeployments -A
  

Bu üç kaynak arasında hiyerarşik bir ilişki vardır:
GitRepo -> Bundle -> BundleDeployment

Bir sorunu teşhis ederken genellikle bu zinciri yukarıdan aşağıya doğru takip edersiniz.

Sorun Giderme: "Unhappy Path"

Dağıtımınız takıldığında veya başarısız olduğunda, sistematik bir yaklaşımla sorunu bulabilirsiniz. İşte temel sorun giderme adımları ve kontrol edilecek yerler.

Bu süreçte ana kaynağımız Fleet'in resmi sorun giderme rehberi olacak.

Yukarıdaki dokümanı temel alarak sorun giderme adımlarımızı sıralayalım.

Adım 1: Durumu Kontrol Et (kubectl get/describe)

İlk olarak, GitRepo kaynağının durumuna bakın.

# GitRepo'nun detaylı durumunu görmek için 'describe' kullanın
kubectl describe gitrepo <repo-adi> -n fleet-default

Çıktının en altındaki Status ve Events bölümlerini inceleyin. Status.Conditions alanı genellikle hatanın ne olduğuna dair ipuçları içerir. Örneğin, "Repo not found" (Depo bulunamadı) veya "Authentication failed" (Kimlik doğrulama başarısız) gibi mesajlar görebilirsiniz.

Adım 2: İlgili Pod'ların Günlüklerini (Log) İnceleme

Hata mesajı net değilse, bir sonraki adım Fleet'in operasyonel bileşenlerinin günlüklerini kontrol etmektir.

1. Git Klonlama veya İşleme Hataları (gitjob pod'u): Fleet, Git deposunu klonlamak için geçici gitjob pod'ları oluşturur. Eğer sorun depo erişimiyle ilgiliyse (yanlış URL, yetki sorunu vb.), bu pod'un loglarında hatayı bulursunuz.

   • Dokümanın "Check errors about watching or checking out the GitRepo..." bölümündeki talimatları izleyerek ilgili gitjob pod'unu bulun ve loglarını kontrol edin.

2. Bundle Oluşturma Hataları (fleet-controller pod'u): Fleet'in ana beyni fleet-controller'dır. GitRepo'yu işlemekten ve Bundle'ları oluşturmaktan sorumludur. Manifest dosyalarınızda bir YAML veya Kustomize/Helm hatası varsa, hata büyük ihtimalle bu pod'un loglarında olacaktır.

   • Dokümanın "Fetch the log from fleet-controller?" bölümündeki kubectl logs komutunu kullanarak bu pod'un loglarını alın.

3. Hedef Kümeye Dağıtım Hataları (fleet-agent pod'u): Her bir hedef kümede çalışan fleet-agent, Bundle'ı alıp küme üzerine uygulamaktan sorumludur. Eğer manifestler geçerli ama kümede bir sorun varsa (örn. yetersiz RBAC izinleri, bulunamayan bir StorageClass vb.), hata fleet-agent loglarında olacaktır.

   • Dokümanın "Fetch the log from the fleet-agent?" bölümündeki komutu kullanarak hedef kümedeki agent loglarını kontrol edin.

Adım 3: Gelişmiş Teşhis Aracı: fleet CLI

Fleet, fleet adında bir komut satırı aracı sunar. Bu aracın monitor komutu, tüm Fleet kaynaklarının anlık bir görüntüsünü alarak otomatik teşhisler çalıştırır ve sorunları bulmayı inanılmaz derecede kolaylaştırır.

fleet monitor nasıl kullanılır?

Komutu çalıştırmak için fleet CLI'nin kurulu olması gerekir. Çıktısı JSON formatındadır, bu nedenle genellikle jq ile birlikte kullanılır.

# Tüm Fleet kaynaklarının anlık durumunu al ve jq ile formatla
fleet monitor | jq

Örnek Senaryo: Bir Bundle'ın neden dağıtılmadığını teşhis etmek.

fleet monitor çıktısında şu bölümleri kontrol edebilirsiniz:

• diagnostics.bundlesWithNoDeployments: Bundle'ınızın herhangi bir hedef kümeyle eşleşip eşleşmediğini gösterir. Eğer burada listeleniyorsa, fleet.yaml dosyanızdaki clusterSelector veya clusterGroup tanımınızda bir hata var demektir.
• diagnostics.gitRepoBundleInconsistencies: GitRepo ve Bundle arasındaki commit karması gibi tutarsızlıkları bulur.
• diagnostics.clustersWithAgentIssues: Hedef kümedeki fleet-agent'ın sağlıklı olup olmadığını kontrol eder.

Bu araç, özellikle karmaşık ve çok kümeli ortamlarda sorunları hızlıca izole etmenizi sağlar.

Özel Bir Durum: "Modified" Statüsü

Bazen bir Bundle'ın durumu Active yerine Modified (Değiştirilmiş) olarak görünür ve orada takılı kalır. Bu, Fleet'in en kafa karıştırıcı yönlerinden biridir.

Modified ne anlama gelir? Git'teki istenen durum ile kümedeki gerçek durum arasında bir fark olduğu anlamına gelir.

Bunun birkaç nedeni olabilir:

1. Beklenen Bir Davranış: Örneğin, bir HorizontalPodAutoscaler (HPA) kullanıyorsanız, HPA'nın replicas sayısını dinamik olarak değiştirmesi beklenir. Bu, Git'teki orijinal manifestten bir sapmadır ve Fleet bunu "Modified" olarak işaretler. Bu durum zararsızdır.
2. Manuel Değişiklik: Birisi kubectl edit ile kümedeki bir kaynağı manuel olarak değiştirdi.
3. Bir Controller Tarafından Yapılan Değişiklik: Kubernetes'teki başka bir controller (örneğin bir admission webhook), Fleet'in oluşturduğu bir kaynağa ek etiketler veya alanlar ekliyor olabilir.

Fleet'in bu tür sapmaları (drift) sürekli olarak geri almadığını hatırlamak önemlidir. Bu, aracın temel bir tasarım özelliğidir.

Modified durumu nasıl ele alınır?
LINK dokümanının "Fleet deployment stuck in modified state" bölümü çözümü açıklar.

• Sorunu Teşhis Et: fleet-agent loglarında hangi alanın fark yarattığını gösteren bir hata mesajı arayın.
• Farkı Yoksay: fleet.yaml dosyanıza bir diff.comparePatches bölümü ekleyerek Fleet'e belirli alanlardaki değişiklikleri yoksaymasını söyleyebilirsiniz. Bu, beklenen değişikliklerin (HPA gibi) Modified durumuna neden olmasını engeller.
• Zorla Güncelleme: Rancher UI'da GitRepo'yu seçip Force Update (Zorla Güncelle) düğmesine tıklayarak Fleet'i durumu yeniden senkronize etmeye zorlayabilirsiniz.

Özet ve Sonuç

Bu derste, otomatikleştirilmiş bir sistemin kaçınılmaz bir parçası olan sorun giderme sürecini ele aldık. Artık bir Fleet dağıtımı başarısız olduğunda veya beklendiği gibi davranmadığında nereye bakacağınızı biliyorsunuz.

Temel Çıkarımlar:

• Başarılı bir dağıtım, Rancher UI'da ve kubectl get komutlarında Active durumuyla kendini gösterir.
• Sorun giderme, GitRepo -> Bundle -> BundleDeployment hiyerarşisini takip ederek başlar.
• Temel teşhis araçları, kubectl describe ile durum ve olayları incelemek ve fleet-controller, gitjob, fleet-agent pod'larının loglarını kontrol etmektir.
• fleet monitor CLI aracı, yaygın sorunları otomatik olarak tespit eden güçlü bir gelişmiş teşhis aracıdır.
• Modified durumu, istenen ve gerçek durum arasındaki bir farkı (drift) gösterir ve logları inceleyerek veya fleet.yaml içinde yapılandırılarak yönetilebilir.

Gelecek Dersin Önizlemesi:
Artık bir dağıtımı nasıl tetikleyeceğimizi ve sorun çıkarsa nasıl çözeceğimizi biliyoruz. Kursumuzun son modülüne geçmeye hazırız! Bir sonraki dersimizde, tüm öğrendiklerimizi bir araya getireceğiz. CI sürecimizin (GitHub Actions) testleri geçtikten sonra, GitOps depomuzdaki imaj etiketini otomatik olarak güncelleyip değişikliği commit eden bir iş akışı yapılandıracağız. Bu, baştan sona tam otomatik CI/CD boru hattımızı tamamlayan son adım olacak.