← blog · 12 Kasım 2026

Kubernetes'te StatefulSet ve Kalıcı Disk: Bölgeye Bağlı Hacimler, Düğüm Çöküşü, Disk Büyütme ve Unutulan PVC'ler

StatefulSet sorunlarının çoğu depolama katmanından çıkar: Pending'de takılan pod, düğüm çöktüğünde açılmayan replika, şablondan büyütülemeyen disk ve ölçek küçültünce kalan PVC'ler. WaitForFirstConsumer, out-of-service kirlenmesi, PVC saklama politikası ve partition ile doğru kurulum.

Durumsuz bir Deployment'ta pod'lar birbirinin yerine geçebilir: biri ölür, başka bir düğümde yenisi açılır, kimse fark etmez. Veritabanı, mesaj aracısı ya da arama motoru gibi durum taşıyan bir iş yükünde ise her pod'un kendi diski vardır ve o disk fiziksel olarak bir yere bağlıdır. StatefulSet bu bağı yönetmek için var, ama sorunların çoğu StatefulSet'in kendisinden değil, altındaki depolama katmanının davranışından çıkar. Pod'un "Pending" durumunda takılması, düğüm çöktüğünde yerine yenisinin hiç açılmaması, disk büyütmenin neden şablondan yapılamadığı bu yazının konusu.

Disk bir bölgeye bağlıdır, pod değil

Bulut sağlayıcılarının blok diskleri genellikle tek bir erişilebilirlik bölgesinde yaşar. Dinamik olarak oluşturulan PersistentVolume, bu yüzden topology.kubernetes.io/zone üzerinden bir düğüm yakınlığı (node affinity) taşır. Pod o diske bağlandığı sürece yalnızca o bölgedeki bir düğümde çalışabilir.

Tuzak, diskin ne zaman oluşturulduğundadır. StorageClass'ta volumeBindingMode: Immediate ise PVC oluşturulduğu anda disk de oluşturulur ve sağlayıcı bölgeyi kendisi seçer. Ardından zamanlayıcı pod'u yerleştirmeye çalışır; pod'un başka kısıtları (düğüm seçici, kaynak isteği, pod karşıtlık kuralı) o bölgede karşılanamıyorsa pod "node(s) had volume node affinity conflict" olayıyla sonsuza kadar bekler.

Doğrusu, diski pod'un yeri belli olduktan sonra oluşturmaktır:

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: ssd-bolgeli
provisioner: ebs.csi.aws.com
volumeBindingMode: WaitForFirstConsumer
allowVolumeExpansion: true
reclaimPolicy: Retain
parameters:
  type: gp3

provisioner ve parameters sağlayıcıya göre değişir, buradaki AWS örneğidir. Önemli olan üç alan: WaitForFirstConsumer zamanlayıcının pod için düğüm seçmesini bekler ve diski o bölgede açar. allowVolumeExpansion sonradan büyütmeye izin verir. reclaimPolicy: Retain ise PVC silindiğinde diskin de silinmesini engeller; dinamik oluşturmada varsayılan Delete'tir ve durum taşıyan veride bu varsayılan tehlikelidir.

WaitForFirstConsumer ilk yerleşimi çözer, sonrasını çözmez. Disk bir kez bir bölgede doğduysa pod artık hep oraya bağlıdır. O bölgedeki düğümler dolarsa ya da bölge kesintiye girerse pod başka bölgeye kaçamaz. Bu yüzden durum taşıyan iş yükünde yüksek erişilebilirlik diskten değil uygulamadan gelmelidir: üç replikalı bir veritabanı kümesinin her üyesi ayrı bölgede olmalı, veriyi uygulama kendi replikasyonuyla çoğaltmalıdır. Bunu sağlamak için pod'ları bölgelere yaymak gerekir:

topologySpreadConstraints:
  - maxSkew: 1
    topologyKey: topology.kubernetes.io/zone
    whenUnsatisfiable: DoNotSchedule
    labelSelector:
      matchLabels:
        app: veritabani

Otomatik ölçekleyici kullanıyorsanız her bölgede ayrı bir düğüm grubu tanımlayın. Tek bir düğüm grubu birden fazla bölgeye yayılıyorsa ölçekleyici, bekleyen pod'un diskinin bulunduğu bölgede düğüm açacağının garantisini veremez.

Düğüm çöktüğünde pod neden yeniden açılmaz

Deployment'ta bir düğüm erişilemez olduğunda kontrolcü bir süre sonra başka yerde yeni pod açar. StatefulSet bunu bilerek yapmaz. Her pod'un sabit bir kimliği vardır (veritabani-0, veritabani-1) ve StatefulSet aynı kimlikle iki pod'un aynı anda var olmamasını garanti eder. Düğüm erişilemez olduğunda API sunucusu oradaki pod'un gerçekten ölüp ölmediğini bilemez; belki yalnızca ağ koptu ve pod hâlâ diske yazıyor. Bu yüzden pod "Terminating" durumunda kalır ve yerine yenisi açılmaz.

Burada ilk akla gelen kubectl delete pod --force --grace-period=0 olur. Bu komut yalnızca API'deki kaydı siler, düğümdeki süreci öldürmez. Düğüm aslında yaşıyorsa iki pod aynı veriye yazmaya başlar ve veri bozulur. Zorla silmeyi yalnızca düğümün gerçekten kapalı olduğundan emin olduğunuzda yapın.

Daha doğru yol, düğümün kapalı olduğunu Kubernetes'e açıkça söylemektir. Düğümü kapattığınızı (ya da sağlayıcı konsolundan durdurduğunuzu) doğruladıktan sonra şu kirlenme (taint) eklenir:

kubectl taint nodes <dugum-adi> node.kubernetes.io/out-of-service=nodeshutdown:NoExecute

Bu kirlenme pod'ların zorla silinmesini ve disklerin o düğümden ayrılmasını başlatır; StatefulSet de yeni pod'u başka bir düğümde açar. Düğüm geri geldiğinde kirlenmeyi kaldırmayı unutmayın. Bu adım otomatikleştirilebilir ama otomasyonun "düğüm kapalı" kararını güvenilir bir kaynaktan (sağlayıcı API'si, uzaktan güç yönetimi) alması şarttır; yalnızca "ağdan cevap vermiyor" bilgisine dayanırsanız zorla silmenin riskini otomatikleştirmiş olursunuz.

Bir de erişim kipine dikkat edin. ReadWriteOnce sanıldığı gibi "tek pod" değil "tek düğüm" demektir; aynı düğümdeki iki pod aynı diski yazılabilir olarak bağlayabilir. Gerçekten tek yazar istiyorsanız CSI sürücünüzün desteklediği ReadWriteOncePod kipini kullanın.

Disk büyütmek şablondan yapılmaz

Disk dolmaya başladığında ilk refleks StatefulSet'in volumeClaimTemplates alanındaki boyutu artırmaktır. Bu alan değiştirilemez (immutable) olduğu için API isteği reddeder. Şablon yalnızca yeni PVC oluşturulurken kullanılır, var olan PVC'lere geriye dönük uygulanmaz.

İşleyen yol şudur:

kubectl patch pvc veri-veritabani-0 -p '{"spec":{"resources":{"requests":{"storage":"200Gi"}}}}'
kubectl patch pvc veri-veritabani-1 -p '{"spec":{"resources":{"requests":{"storage":"200Gi"}}}}'
kubectl patch pvc veri-veritabani-2 -p '{"spec":{"resources":{"requests":{"storage":"200Gi"}}}}'

kubectl delete statefulset veritabani --cascade=orphan
kubectl apply -f veritabani-statefulset.yaml

Önce her PVC tek tek büyütülür. Ardından StatefulSet, pod'ları silinmeden (--cascade=orphan) kaldırılır ve yeni boyutu içeren şablonla yeniden oluşturulur; yeni nesne var olan pod'ları ve PVC'leri etiketlerinden tanıyıp sahiplenir. Böylece ileride eklenecek replika da doğru boyutla doğar. Büyütme sonrası PVC'de FileSystemResizePending koşulu görürseniz sürücü dosya sistemini çevrim içi büyütemiyor demektir ve pod'un yeniden başlatılması gerekir.

Disk küçültmek ise desteklenmez. Küçültmeniz gerekiyorsa yeni bir PVC açıp veriyi uygulama düzeyinde taşımaktan başka yol yoktur. Bu yüzden ilk boyutu cimri seçip sonra büyütmek, cömert seçip küçültmeye çalışmaktan her zaman daha ucuzdur.

Ölçek küçültünce diskler kalır

StatefulSet'i üç replikadan ikiye indirdiğinizde veritabani-2 silinir ama PVC'si kalır. Varsayılan davranış budur ve bilinçlidir: yeniden üçe çıktığınızda aynı pod aynı veriyle döner. Fark edilmeyen sonucu ise faturadır; denemeler sırasında açılıp kapanan replikaların diskleri aylarca ödenmeye devam eder.

Bu davranış persistentVolumeClaimRetentionPolicy ile ayarlanabilir:

spec:
  persistentVolumeClaimRetentionPolicy:
    whenDeleted: Retain
    whenScaled: Delete

whenScaled: Delete ölçek küçültüldüğünde artan PVC'leri siler, whenDeleted ise StatefulSet tamamen silindiğinde ne olacağını belirler. Üretim veritabanında whenDeleted için Retain dışında bir değer seçmeyin; yanlış ad alanında yapılmış tek bir silme komutu bütün veriyi götürür. whenScaled: Delete ise ancak replikalar veriyi birbirinden yeniden kurabiliyorsa mantıklıdır. StorageClass'taki reclaimPolicy: Retain burada ikinci bir emniyet katmanıdır: PVC silinse bile disk sağlayıcıda kalır.

Güncelleme takıldığında

StatefulSet varsayılan olarak pod'ları sırayla (podManagementPolicy: OrderedReady) açar ve güncellemeyi en yüksek sıradan başlayıp birer birer yapar. Yeni şablondaki bir hata pod'u hazır hâle gelmekten alıkoyarsa güncelleme orada durur. Şablonu düzeltseniz bile kontrolcü bozuk pod'un hazır olmasını beklemeye devam edebilir; bu durumda düzeltmeyi uyguladıktan sonra takılı pod'u elle silmeniz gerekir. Belgelerde de bu bilinen bir davranış olarak geçer.

Riskli bir güncellemeyi önce tek replikada denemek için partition kullanılır:

updateStrategy:
  type: RollingUpdate
  rollingUpdate:
    partition: 2

Bu ayarla yalnızca sırası 2 ve üzeri olan pod'lar güncellenir. Sonuçtan memnunsanız değeri adım adım sıfıra indirirsiniz.

Büyük disklerde gözden kaçan bir yavaşlık kaynağı da fsGroup'tur. Pod güvenlik bağlamında fsGroup tanımlıysa kubelet her bağlamada diskteki bütün dosyaların sahipliğini özyinelemeli olarak değiştirebilir; milyonlarca dosyalı bir diskte bu, pod'un dakikalarca açılmaması demektir. fsGroupChangePolicy: OnRootMismatch yalnızca kök dizinin izinleri uyuşmadığında bu işlemi yapar ve sorunu çoğunlukla ortadan kaldırır.

Ne zaman StatefulSet seçmemeli

Durum taşıyan her şeyi kümeye koymak zorunda değilsiniz. Yönetilen bir veritabanı hizmeti kullanabiliyorsanız yedekleme, sürüm yükseltme ve yük devretme işini sağlayıcıya bırakmak çoğu ekip için daha ucuzdur. Kümede çalıştırmaya karar verdiyseniz StatefulSet'i elle yönetmek yerine ilgili veritabanının olgun bir operatörünü tercih edin; operatörler yukarıdaki adımların çoğunu (sıralı güncelleme, replika yeniden kurma, yedekten dönme) zaten bilir.

StatefulSet'i doğrudan kullanmanın mantıklı olduğu yer, uygulamanın kendi replikasyonunu yaptığı ve sizin depolama katmanının davranışını bilerek tasarladığınız durumlardır. Tek replikalı ve yüksek erişilebilirlik beklenmeyen bir iş yükünde ise StatefulSet'in sıralama garantileri size bir şey kazandırmaz; tek replikalı bir Deployment ve Recreate güncelleme stratejisi de aynı işi görür, yalnızca aynı diski aynı anda iki pod'un bağlamaya çalışmayacağından emin olun.