SIG Architecture API Governance: Kubernetes’in Sessiz Kahramanı
Kubernetes dışarıdan bakınca düzenli bir makine gibi görünüyor, değil mi? Ben de uzun süre öyle sandım. Ta ki 2021’de bir telekom müşterisinde özel bir CRD tasarlarken, “ee bu alanı camelCase mi yapalım, snake_case mi?” diye masaya oturana kadar. O gün anladım ki perde arkasında API Governance diye ayrı bir dünya varmış, üstelik kuralları da baya yazılı.
Bugün bu konuyu biraz açmak istiyorum. Çünkü Kubernetes ile ciddi iş yapan herkesin — özellikle operatör ya da custom controller geliştirenlerin — bu sub-projenin ne yaptığını bilmesi lazım. Hani “bilmesem de olur” gibi geliyor ama açık konuşayım, bir gün API tasarlarken aklınıza direkt bu yazı gelecek.
API Governance Tam Olarak Nedir?
Doğrusu, SIĞ Architecture’ın altında çalışan bir alt proje bu. Jordan Liggitt liderliğinde yürüyor; kendisi 2014’ten beri Kubernetes tarafında epey iş yapmış, auth tarafına da dokunmuş bir mühendis ve Google’da çalışıyor. 2019’dan beri de işin başında.
İşin can alıcı tarafı şu: Çoğumuz “Kubernetes API’si” deyince sadece REST API’yi düşünüyoruz. Yanı kubectl get pods çalıştırınca arka planda konuştuğumuz şey. Ama aslında Kubernetes’in çok daha geniş bir “API yüzeyi” var. Tahmin eder mısınız? Ve bunların hepsi governance kapsamında değerlendiriliyor.
Ne demek istediğimi şöyle toparlayayım:
- kubelet’in komut satırı flag’leri — bir API (bu kritik)
- kubeconfig dosyasının formatı — bir API
- CRI (container runtime ile konuşma protokolü) — bir API
- etcd’ye yazılan veri formatı — bir API — bunu es geçmeyin
- Konfigürasyon dosyalarının yapısı — yine API (bence en önemlisi)
Yanı sadece kullanıcının doğrudan gördüğü REST endpoint’leri değil, sistem bileşenlerinin birbirleriyle ve dış dünyayla konuştuğu her arayüz bu kapsamda. Geçen yıl bir bankacılık projesinde kubelet konfigürasyonunu otomatikleştirirken bunu çok net hissettim; bir flag’in “deprecated” olması bizim ansible playbook’larımızı doğrudan etkiliyordu. Küçük detay gibi dürüyor, ama değil.
Stabil Kalmak ve Değişmek Aynı Anda
Size bir şey söyleyeyim, Bence API Governance’ın en zor kısmı burası. Hiçbir şeyi ellemezseniz sistem stabil kalıyor, evet. Ama Kubernetes gibi hızlı evrilen bir platformda bunu sonsuza kadar sürdüremezsiniz. O yüzden temel denge şu: stabilite ile evrim arasında ip üstünde yürümek.
Jordan’ın röportajda söylediği şu cümle hoşuma gitmişti: “Audience ne kadar geniş işe esneklik o kadar az.” Yanı milyonlarca kullanıcının doğrudan gördüğü REST API’sinde değişiklik yapmak zor, çünkü kıracağınız iş yükü çok fazla olur. Ama mesela CRI gibi daha dar bir kitleye hitap eden, sadece runtime entegrasyonu yazanların kullandığı bir API’de hareket alanınız biraz daha geniş oluyor.
API Reviewer ve Approver: O Sıkı Süzgeç
Peki pratikte ne oluyor? Bir KEP (Kubernetes Enhancement Proposal) açtığınızda ya da core’a yeni bir API eklemek istediğinizde süreç nasıl işliyor? Çoğu kişi bunu bilmiyor.
Süreç iki seviyeli incelemeye giriyor: Bu konuyla ilgili Microsoft Sovereign Private Cloud: Azure Local ile Ölçek Büyürken Kontrolü Kaybetmemek yazımıza da göz atmanızı tavsiye ederim.
- API Reviewer: Tasarımın temelden düzgün olup olmadığına bakar. İsimlendirme, alan tipleri, defaulting mantığı, validation kuralları…
- API Approver: Daha kıdemlidir. Stratejik kararlar, geriye dönük uyumluluk, uzun vadeli etkiler burada devreye girer.
Şunu söyleyeyim, Jordan 2016’da reviewer olmuş, 2017’de approver’a geçmiş (evet, doğru duydunuz). Bu pozisyonlar öyle “ben de isterim” deyince gelen işler değil; yıllarca tutarlı ve kaliteli katkı yapmanız gerekiyor (şaşırtıcı ama gerçek). Şu anda Kubernetes’te az sayıda approver var ve hepsi de baya meşgul insanlar.
İlginç olan şu ki, Laf aramızda, Logosoft’taki bir AKS müşterimizde geçen sene CRD tasarlarken ekipçe Kubernetes API Conventions dokümanını sıfırdan okuduk. İnanın bana, neredeyse 200 sayfalık döküman içinde “Optional vs Required nasıl işaretlenir”, “boolean alan nasıl isimlendirilir”, “list semantics neye göre seçilir” gibi soruların cevabı var. İlk başta “abi bu kadar detay olur mu?” dedik. Sonra fark ettik ki o detaylar olmasa ekosistem çoktan yamulurmuş (eh, fena değil) Daha fazla bilgi için kubernetes konusundaki yazımız yazımıza bakabilirsiniz.
Quality Gates Tam Olarak Nerede Devreye Giriyor?
Tuhaf ama, Bunu düz tabloyla anlatmak kolay oluyor — feature’ın yolculuğu kabaca böyle ilerliyor:
| Aşama | API Governance Müdahalesi |
|---|---|
| KEP draft | Genelde yok, topluluk geri bildirimi |
| KEP review | API reviewer/approver atanır |
| Alpha implementation | Conventions kontrolü, naming review |
| Beta’ya geçiş | Sıkı kontrol — çünkü beta = default açık |
| GA | Dönüşü zor kararlar; en sıkı süzgeç burada çalışır |
Beni en çok şaşırtan şey Beta aşamasının ne kadar kritik olduğuydu. Çünkü beta artık varsayılan olarak açık oluyor ve insanlar production’da kullanmaya başlıyor. Dolayısıyla Beta’ya geçen bir API’yi sonra geri almak baya zahmetli; kullanıcılar zaten bağlanmış oluyor.
Türkiye’deki Şirketler İçin Bu Ne Anlama Geliyor?
Bunu yaşayan biri olarak söyleyeyim, Kendi gördüğüm kadarıyla Türkiye’de bu konuya dair farkındalık düşük kalıyor. Şirketler genelde “biz Kubernetes kullanıyoruz” deyip geçiyor ama kendi geliştirdikleri operatör’lar ya da CRD’ler için aynı disiplini uygulamıyorlar. Sonuç mu? İki yıl sonra herkes birbirine bakıp “şu alan adını niye böyle koymuşuz?” diye kafa kaşıyor. Bu konuyla ilgili GPT-5.2 ve GPT-5.2-Codex Emekli Oluyor: Şimdi Ne Olacak? yazımıza da göz atmanızı tavsiye ederim.
Neyse uzatmayayım, geçen yıl İstanbul’da bir sigorta şirketinde buna benzer bir şey gördüm: İç platform ekipleri tam 14 farklı CRD yazmıştı ve hiçbir tutarlılık yoktu. Bir CRD’de true/false, diğerinde false/true?, pardon yanlış söyledim; biri düzgün gidiyordu. Diğeri büyük ölçüde başka tarzdaydı diyeyim… Mesela biri alertEnabled: true, diğeri daha eski kafalı şekilde başka isimlendirme kullanıyordu, üçüncüsü işe bambaşka pattern’e kaymıştı (buna dikkat edin). Geliştirici ekipleri çıldırıyordu resmen.
Hmm, bunu nasıl anlatsamdı… Bu konuyla ilgili Visual Studio’da Bulut Ajanları: Kod Akışını Değiştiren Güncelleme yazımıza da göz atmanızı tavsiye ederim.
İnanın, Açık önerim şu: Eğer ekibinizde CRD yazan biri varsa ona “Kubernetes v1.36 Memory QoS: Katmanlı Bellek Koruması Geldi” gibi yeni gelen API örneklerini inceletin. Çünkü Kubernetes core ekibi nasıl tasarlıyorsa sizin de aynı mantıkla tasarlamanız uzun vadede sizi rahatlatır. MCP Tool Çağrılarını .NET’te Yönetmek: AGT ile Pratik Yol yazımızda bu konuya da değinmiştik.
Küçük Ekip mi Büyük Kurumsal Yapı mı?
Burada önemli bir ayrımı netleştireyim:
- Küçük startup veya 5-10 kişilik ekip: Çok detaya boğulmayın derim. API Conventions’ın özellikle naming ve versioning tarafına odaklanın. CRD’lerinizi
v1alpha1‘den başlatın ki production’a gerçekten girmeden önce değiştirme özgürlüğünüz olsun. - Banka, telko ya da kamu gibi enterprise yapı: İlk günden disiplin kurun demek daha doğru olur sanırım. Internal API review board oluşturun. Her CRD mutlaka review alsın.
b1beta1...buna benzer geçişlerde...b1beta1...
Sıkça Sorulan Sorular
API Governance sadece core Kubernetes API’lerini mi kapsıyor?
Hayır, aslında çok daha geniş bir kapsam bu. Komut satırı flag’leri, konfig dosyaları, CRI gibi protokoller, etcd’deki veri formatı — hepsi dahil yanı. Ama en sıkı kontrol REST API’lerinde oluyor, çünkü orada kullanıcı kitlesi en geniş.
Kendi CRD’lerimi tasarlarken bu kuralları uygulamak zorunda mıyım?
Zorunlu değil açıkçası, ama şiddetle tavsiye ederim. Kubernetes API Conventions dokümanını takip edersen kullanıcıların — ki zaten kubectl’e alışkın oluyorlar — seninle çalışmayı çok daha kolay buluyor. Üstelik server-side apply gibi gelişmiş özellikler de düzgün çalışıyor, mesela bu bile başlı başına yeterli bir sebep bence.
Bakın, burayı atlarsanız yazının kalanı anlamsız kalır.
API Approver nasıl olunur?
Doğrudan başvuru diye bir şey yok. Yıllarca tutarlı, kaliteli API katkıları yapman ve mevcut approver’ların gözüne girmen lazım. Önce reviewer, sonra approver — tipik yol hani bu (ciddiyim). Kısa yolu yok.
Alpha, Beta ve GA arasındaki fark nedir kullanıcı açısından?
Garip gelecek ama, Alpha varsayılan olarak kapalı geliyor ve breaking change yapılabiliyor. Beta varsayılan açık, breaking change kural olarak yapılmıyor ama edge case’lerde olabiliyor. GA işe tam anlamıyla stabilite garantisi — geriye dönük uyumluluk kırılmıyor. Açıkçası production’da Alpha kullanmamanızı tavsiye ederim, tecrübeme göre birkaç kez güzel yandım oradan.
API Conventions dokümanı nereden okunur?
Kubernetes community repo’sunda contributors/devel/sig-architecture/api-conventions.md dosyasında bulabilirsin. Bir kahve alıp en azından bir kez baştan sona okuman lazım bence, yanı gerçekten baya öğretici bir şey.
Kaynaklar ve İleri Okuma
Spotlight on SIĞ Architecture: API Governance — Kubernetes Blog
Kubernetes API Conventions — Resmî Doküman
SIĞ Architecture GitHub Reposu
İşin garibi, Kubernetes Enhancement Proposals (KEPs) Reposu
20+ yıl deneyimli Azure Solutions Architect. Microsoft sertifikalı bulut mimari ve DevOps danışmanı. Azure, yapay zekâ ve bulut teknolojileri üzerine Türkçe teknik içerikler üretiyor.
İlgili Yazılar
Bu içerik işinize yaradı mı?
Benzer içerikleri kaçırmamak için beni sosyal medyada takip edin.
4 comments