Kubernetes Admission Webhook Timeout ile Deploy Kilitlenmesi Runbook’u

Kubernetes admission webhook’ları (Validating/Mutating) güvenlik ve yönetişim için çok değerli; ama üretimde en sık gördüğüm failure mode şu: tek bir webhook yavaşlar ve cluster “deploy edilemez” hâle gelir. Çünkü API Server, CREATE/UPDATE akışında webhook yanıtını bekler.

Bu runbook’un hedefi basit: “deploy neden asılı kaldı?” sorusunu dakikalara indirip, risk kontrollü bir mitigasyon uygulamak.

Belirtiler (incident sırasında hızlı tanı)

• kubectl apply / helm upgrade çok uzun sürer veya timeout olur
• Error from server (InternalError): ... calling webhook ... context deadline exceeded
• API Server latency artar, 5xx dalgası görülür
• Bazı namespace’lerde deploy olurken bazılarında olmaz (match/selectors)

0) Güvenlik notu: “Mitigasyon” = risk kabulü

Webhook’ları bypass etmek (örn. failurePolicy: Ignore) çoğu zaman “servisi kurtarır” ama security/regulatory etkisi vardır.

1) Hızlı triage: hangi webhook kilitliyor?

A) Hata mesajından webhook adını yakala

Timeout hatalarında genelde ... calling webhook "<name>" ... çıkar. Bu isim ValidatingWebhookConfiguration veya MutatingWebhookConfiguration içindeki webhook ismidir.

kubectl get validatingwebhookconfigurations
kubectl get mutatingwebhookconfigurations

B) Hangi servis endpoint’i? (DNS/TLS/Network şüphesi)

Webhook konfigini açıp clientConfig.service değerini kontrol edin:

kubectl get validatingwebhookconfiguration <cfg> -o yaml | rg -n "clientConfig|service|url|caBundle|timeoutSeconds|failurePolicy"

Kontrol listesi:

• Service adı doğru mu?
• Namespace doğru mu?
• caBundle güncel mi? (sertifika rotasyonu sonrası sık kırılır)
• timeoutSeconds çok mu düşük? (aşırı düşükse false positive, çok yüksekse kontrol düzlemini kilitler)

2) “Kilitlenme” nedenleri: en sık 5 kök neden

1. Webhook pod’ları down/evicted (PDB yok, node ölümü, OOM)
2. DNS sorunları (kube-dns/CoreDNS latency, upstream timeouts)
3. TLS/CA bundle bozulması (sertifika yenilendi, webhook config güncellenmedi)
4. NetworkPolicy/egress ile webhook’a erişim kesildi
5. Webhook uygulaması yavaş (CPU satürasyonu, cold start, downstream bağımlılık)

3) Mitigasyon seçenekleri (en düşük riskten yükseğe)

Seçenek 1 — timeout’ı düşür, “fail fast” yap (en güvenlisi değil, en deterministiği)

Amaç: API Server’ın dakikalarca beklemesini engellemek.

• timeoutSeconds: makul bir değer (örn. 2–5s)
• Webhook yavaşsa “hızlı fail” ile deploy’ları çabuk geri çevirirsiniz; kontrol düzlemi nefes alır.

Bu yöntem hizmeti düzeltmez, ama incident davranışını öngörülebilir yapar.

Seçenek 2 — sadece belirli namespace/objeleri dışarıda bırak (hassas ama ideal)

Webhook kurallarında selector/match koşulları varsa:

• Yalnızca problemli kontrolü devre dışı bırak
• Örn. kube-system veya belirli team=platform namespace’lerini hariç tut

Bu model, “her şeyi bypass” yerine blast radius’i daraltır.

Seçenek 3 — geçici failurePolicy: Ignore (en yüksek operasyonel hız, en yüksek risk)

Bu seçenek deploy’u açar ama guardrail’i kaldırır. Uygulamadan önce:

• Ne kadar süre? (örn. 30–60 dk)
• Kim onayladı? (IC + security owner)
• Ne izlenecek? (audit/alert)

4) Onarım: webhook’u üretime dayanıklı yap (kalıcı çözüm)

A) Availability

• En az 2 replika, PDB, HPA
• Node affinity/anti-affinity (tek node’a yığılmasın)
• Liveness/readiness doğru (API Server “ready olmayan” endpoint’e gitmesin)

B) Performans

• Webhook’un downstream bağımlılıklarını azalt (DB/remote call varsa caching/timeout)
• Cold start’ı ölç (özellikle Java/Go büyük image)

C) TLS/CA yönetimi

• Sertifika rotasyonunu otomasyona bağla
• caBundle güncellemelerini drift’e bırakma

D) Gözlemlenebilirlik

• Webhook latency histogram
• Error rate + timeout count
• API Server tarafında admission latency (mümkünse trace)

5) “Deploy kilidi” runbook akışı (özet)

1. Hata mesajından webhook adını yakala
2. clientConfig ile endpoint/DNS/TLS doğrula
3. En düşük riskli mitigasyonu seç (timeout/selector → ignore en son)
4. Webhook availability/perf/tls kök nedenini düzelt
5. Mitigasyonu geri al ve bir daha yaşanmaması için guardrail kur (PDB/HPA/alarmlar)

Sonuç

Admission webhook’lar güvenlik kapısıdır; ama aynı zamanda delivery’nin parçasıdır. Bu yüzden onları “kurduk oldu” değil, SLO’su olan bir servis gibi işletmek gerekir. Doğru runbook; kimin hangi kararı vereceğini, hangi mitigasyonun hangi riski taşıdığını ve geri dönüş adımlarını incident anında tartışmaya yer bırakmayacak şekilde netleştirir.