Helm ile Kubernetes Uygulama Kurulumu

Kubernetes'te tek bir uygulamayı çalıştırmak için genelde beş altı ayrı nesne yazarsın: Deployment, Service, Ingress, ConfigMap, Secret, belki bir PVC ve bir HPA. Test ve canlı ortam için bu dosyaları kopyalayıp birkaç değeri değiştirdiğinde iki ayrı gerçek kaynağın olur ve aralarındaki fark zamanla sessizce büyür. Helm ile Kubernetes uygulama kurulumu bu dağınıklığı çözer: nesneleri şablona dönüştürür, ortama göre değişen değerleri tek bir values.yaml dosyasında toplar ve tüm kümeyi tek komutla kurulabilir, yükseltilebilir, geri alınabilir bir pakete indirger.

Bu rehberde Helm'in ne yaptığını ve ne yapmadığını, hazır chart kurmayı, values katmanlarının öncelik sırasını, kendi chart'ını yazmayı, yükseltme ve geri alma mekaniğini, üretimde güvenli dağıtım için kullanman gereken bayrakları ve en sık düşülen tuzakları anlatacağım. Kubernetes'in temel nesnelerine henüz hâkim değilsen Kubernetes Pod, Deployment ve Service yazısı bu rehberin doğal ön adımı.

Helm Ne Yapar, Ne Yapmaz#

Helm'i Kubernetes'in paket yöneticisi olarak tanıtmak yaygın ama biraz eksik bir tarif. Yaptığı iş üç adımdan ibarettir: şablonları verdiğin değerlerle işler, ortaya çıkan düz YAML'ı Kubernetes API'sine gönderir ve bu işlemin kaydını sürüm (release) olarak saklar.

Üç kavramı ayırmak önemli:

Helm 3 ile birlikte kümede çalışan bir sunucu bileşeni yoktur; sürüm bilgisi doğrudan ad alanındaki Secret nesnelerinde saklanır. Yani Helm yalnızca senin makinendeki ya da CI koşucundaki bir komut satırı aracıdır ve kümeye kubectl ile aynı yetkiyle bağlanır.

Ne yapmadığını da bilmek gerek: Helm bir yapılandırma yönetim sistemi değildir, uygulamanın çalışıp çalışmadığını sürekli izlemez ve kümedeki bir nesneyi biri elle değiştirdiğinde bunu kendiliğinden düzeltmez. Sürekli uzlaştırma istiyorsan Helm'in üstüne bir GitOps aracı koyman gerekir.

Kurulum ve Depo Yönetimi#

Helm tek bir ikili dosyadır; paket yöneticisiyle ya da resmî kurulum betiğiyle kurulur.

# Kurulumu doğrula
helm version

# Bir chart deposu ekle ve dizini güncelle
helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update

# Depoda arama yap
helm search repo redis
helm search repo redis --versions | head -n 5

Bir chart'ı kurmadan önce hangi değerleri kabul ettiğine bakmak en değerli alışkanlıktır:

# Varsayılan değerleri gör (çıktı uzun olur, dosyaya yaz)
helm show values bitnami/redis > redis-varsayilan.yaml

# Chart hakkında özet bilgi
helm show chart bitnami/redis

Bu dosyayı okumadan --set ile deneme yanılma yapmak, sonradan neyi neden değiştirdiğini hatırlamadığın bir kuruluma yol açar.

İlk Kurulum ve values Katmanları#

Kurulum komutunun anatomisi şöyle:

helm install cache bitnami/redis \
  --namespace uretim --create-namespace \
  -f values-uretim.yaml \
  --set auth.password=ornek-guclu-parola \
  --wait --timeout 5m

Burada cache sürüm adıdır ve aynı ad alanında benzersiz olmalıdır; oluşan nesnelerin adları da bu önekten türetilir. Üretimde helm install yerine neredeyse her zaman helm upgrade --install kullanılır, çünkü bu biçim hem ilk kurulumda hem sonraki güncellemelerde aynı komutla çalışır ve CI hattında koşul yazmanı gerektirmez.

Değerlerin öncelik sırası, karıştırılması en kolay konulardan biri:

Yani şu komutta values-uretim.yaml dosyasındaki değerler values-ortak.yaml dosyasını ezer:

helm upgrade --install api ./chart \
  -f values-ortak.yaml \
  -f values-uretim.yaml \
  -n uretim

Gerçekte hangi değerlerin uygulandığını görmek istersen tahmin etme, sor:

# Kullanıcının verdiği değerler
helm get values api -n uretim

# Varsayılanlar dahil tüm birleşik değerler
helm get values api -n uretim --all

# Kümeye gönderilen son YAML
helm get manifest api -n uretim | head -n 40

Parolaları --set ile geçirmek pratiktir ama kabuk geçmişine ve CI loglarına düşer. Üretimde sırları ayrı bir Secret olarak yönetip chart'a yalnızca Secret adını vermek daha sağlıklıdır; yaklaşımın ayrıntısı ConfigMap ve Secret kullanımı yazısında.

Kendi Chart'ını Yazmak#

Kendi uygulaman için chart oluşturmak tek komutluk iştir:

helm create firmaniz-api

Oluşan yapı şöyledir:

firmaniz-api/
├── Chart.yaml          # ad, sürüm, appVersion, bağımlılıklar
├── values.yaml         # varsayılan değerler
├── .helmignore         # pakete girmeyecek dosyalar
├── charts/             # alt chart bağımlılıkları
└── templates/
    ├── deployment.yaml
    ├── service.yaml
    ├── ingress.yaml
    ├── _helpers.tpl    # tekrar eden isim/etiket üretimi
    └── NOTES.txt       # kurulum sonrası ekrana basılan metin

Bir şablonun içi düz YAML'a benzer, farkı değerlerin dışarıdan gelmesidir:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "firmaniz-api.fullname" . }}
spec:
  replicas: {{ .Values.replicaCount }}
  template:
    metadata:
      annotations:
        # ConfigMap değiştiğinde Pod'ların otomatik yenilenmesini sağlar
        checksum/config: {{ include (print $.Template.BasePath "/configmap.yaml") . | sha256sum }}
    spec:
      containers:
        - name: api
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
          resources:
            {{- toYaml .Values.resources | nindent 12 }}

Buradaki checksum/config açıklaması küçük ama çok değerli bir desendir: ConfigMap içeriği değiştiğinde özet değişir, Pod şablonu değişmiş sayılır ve Deployment kendiliğinden kademeli yeniden başlatma yapar. Bu satır olmadan yapılandırma güncellemesi çalışan Pod'lara hiç yansımaz.

Şablonu kümeye göndermeden önce mutlaka yerelde işle ve gözünle kontrol et:

helm lint ./firmaniz-api
helm template test ./firmaniz-api -f values-uretim.yaml | less
helm upgrade --install api ./firmaniz-api -n uretim --dry-run --debug

helm template kümeyle hiç konuşmaz, tamamen yereldir; --dry-run ise API sunucusuna doğrulama için gönderir ve şema hatalarını da yakalar. Üretim öncesi ikisini de çalıştırmak iyi bir alışkanlıktır. Uzun YAML çıktılarını okurken biçim kontrolü için JSON formatlayıcı aracımız da işine yarayabilir.

Yükseltme, Geri Alma ve Sürüm Geçmişi#

Helm'in en çok değer kattığı yer burasıdır: her upgrade yeni bir revizyon üretir ve eskisine dönmek tek komuttur.

# Yeni imaj sürümüne geç
helm upgrade --install api ./firmaniz-api -n uretim \
  --set image.tag=1.5.0 --atomic --timeout 5m

# Geçmişi gör
helm history api -n uretim
# REVISION  UPDATED       STATUS      CHART            APP VERSION  DESCRIPTION
# 1         2026-08-20    superseded  firmaniz-api-0.3  1.4.0        Install complete
# 2         2026-08-25    deployed    firmaniz-api-0.4  1.5.0        Upgrade complete

# Bir önceki revizyona dön
helm rollback api 1 -n uretim

Üretimde her zaman kullanman gereken iki bayrak var. --atomic, yükseltme başarısız olursa değişiklikleri otomatik geri alır — yani yarım kalmış, bir kısmı yeni bir kısmı eski bir kurulumla baş başa kalmazsın. --timeout ise bu beklemenin ne kadar süreceğini belirler; varsayılan beş dakika, yavaş açılan uygulamalar için yetersiz kalabilir. --atomic bayrağı --wait davranışını da içerir, yani Pod'lar hazır olana kadar bekler.

Sürüm kaldırma sırasında bir noktaya dikkat: helm uninstall chart'ın oluşturduğu nesneleri siler ama StatefulSet'in volumeClaimTemplates ile ürettiği PVC'leri silmez. Bu kasıtlı bir koruma önlemidir; kümeyi gerçekten temizliyorsan bu diskleri elle kaldırman gerekir. Ayrıntısı Kubernetes Persistent Volume yönetimi yazısında.

helm uninstall cache -n uretim
kubectl get pvc -n uretim          # arta kalan diskler burada görünür

Üretimde Güvenli Dağıtım Alışkanlıkları#

Helm'i CI hattına bağlarken işe yarayan birkaç kural:

1. Her zaman upgrade --install kullan. Koşulsuz, idempotent ve ilk kurulumla güncellemeyi ayırmanı gerektirmez.
2. Chart sürümü ile uygulama sürümünü ayır. Chart.yaml içindeki version chart'ın kendi sürümüdür, appVersion ise paketlediğin uygulamanın sürümü. İkisini karıştırmak, geçmişte hangi kodun çalıştığını bulmayı imkânsız hâle getirir.
3. Değişikliği önce gör. helm diff upgrade eklentisi, uygulanacak farkı satır satır gösterir; üretimde kör dağıtım yapmamanın en ucuz yolu budur.
4. Değer dosyalarını sürüm kontrolünde tut, sırları tutma. values-uretim.yaml depoda dursun, parolalar ayrı bir sır yönetim katmanından gelsin.
5. CRD'lerin yükseltilmediğini bil. Helm, crds/ dizinindeki özel kaynak tanımlarını yalnızca ilk kurulumda uygular; sonraki yükseltmelerde dokunmaz. CRD güncellemesi gerektiren chart'larda bunu elle yapman gerekir ve bu, atlanınca çok kafa karıştırıcı hatalar üretir.
6. --dry-run çıktısını sürüm notu gibi sakla. Bir sorun çıktığında "ne değişti" sorusuna en hızlı cevap orada olur.

Ingress controller, cert-manager gibi altyapı bileşenlerini de Helm ile kurmak yaygın ve doğru bir yaklaşımdır; Kubernetes Ingress Controller kurulumu yazısındaki komutların tamamı Helm üzerinden ilerler.

Sık Yapılan Hatalar ve Tuzaklar#

1. helm install ile ilerleyip her seferinde farklı sürüm adı vermek. Aynı uygulamanın üç kopyası ayrı adlarla kümede birikir ve hangisinin canlı olduğu belirsizleşir. upgrade --install ile tek sürüm adına bağlı kal.
2. values dosyasının sırasını yanlış kurmak. -f ile verilen son dosya öncekileri ezer. Ortak değerleri önce, ortama özel değerleri sonra yaz.
3. --set ile karmaşık yapı geçirmeye çalışmak. Nokta ve köşeli parantez söz dizimi (ingress.hosts[0].host=...) hızla okunmaz hâle gelir ve hata yapmak kolaydır. İki seviyeden derin her şeyi değer dosyasına taşı.
4. Sayısal görünen dizeleri --set ile geçirmek. --set image.tag=1.20 değeri sayı olarak yorumlanır ve 1.2 hâline gelebilir; bu durumda --set-string kullanmalısın.
5. Chart sürümünü hiç artırmamak. Chart.yaml içindeki sürüm sabit kalırsa geçmiş anlamsızlaşır ve hangi revizyonun hangi şablonla oluştuğu bilinemez.
6. --atomic kullanmamak. Yarım kalan bir yükseltme, bir kısmı yeni bir kısmı eski Pod'larla çalışan bir sistem bırakır; teşhisi en zor durumlardan biridir.
7. Şablonu doğrudan üretime uygulamak. helm template ve --dry-run adımları on saniye sürer ve girinti hatasından yanlış ad alanına kadar pek çok sorunu kümeye ulaşmadan yakalar.

Sıkça Sorulan Sorular#

Helm 3 için kümeye bir şey kurmam gerekiyor mu#

Hayır. Helm 3 ile birlikte eski sürümlerdeki sunucu bileşeni kaldırıldı; Helm artık tamamen istemci tarafında çalışır ve kümeye kubectl ile aynı kimlik bilgisiyle bağlanır. Sürüm bilgisi, kurulumun yapıldığı ad alanındaki Secret nesnelerinde saklanır. Yani Helm'i kurmak için kümeye ek yetki ya da ek bileşen gerekmez.

Helm chart'ı ile kubectl apply arasındaki fark nedir#

kubectl apply düz YAML dosyalarını olduğu gibi uygular; ortamlar arası farkı sen kopyalayarak yönetirsin. Helm ise şablon ve değer ayrımı sunar, böylece tek bir chart farklı değer dosyalarıyla test ve canlı ortamda kullanılabilir. Ayrıca kurulum geçmişi tutar; tek komutla önceki sürüme dönebilirsin ki kubectl apply bunu sağlamaz.

helm upgrade sonrası uygulamam bozuldu, nasıl geri dönerim#

helm history <sürüm-adı> -n <ad-alanı> komutuyla revizyon listesini gör, ardından helm rollback <sürüm-adı> <revizyon> -n <ad-alanı> ile istediğin noktaya dön. Bu tür durumları baştan önlemek için yükseltmeleri --atomic bayrağıyla yapman en iyisidir; başarısız bir yükseltme kendiliğinden geri alınır ve elle müdahaleye gerek kalmaz.

Bir chart'ın hangi ayarları kabul ettiğini nasıl öğrenirim#

helm show values <chart> komutu chart'ın varsayılan values.yaml dosyasını olduğu gibi gösterir; çıktıyı bir dosyaya yazıp okumak en verimli yöntemdir. Ayrıca helm show readme <chart> çoğu popüler chart'ta ayrıntılı bir parametre tablosu içerir. Kurulumdan sonra gerçekte hangi değerlerin uygulandığını helm get values <sürüm> --all ile doğrulayabilirsin.

helm uninstall verilerimi siler mi#

Chart'ın oluşturduğu Deployment, Service ve ConfigMap gibi nesneler silinir. Ancak StatefulSet'in volumeClaimTemplates ile ürettiği PersistentVolumeClaim nesneleri kasıtlı olarak korunur, çünkü Kubernetes veriyi kazara kaybetmeni engellemeye çalışır. Diskleri de kaldırmak istiyorsan kubectl get pvc ile listeleyip elle silmen gerekir; aksi hâlde kullanılmayan diskler ve maliyetleri devam eder.

Kendi chart'ımı yazmak zorunda mıyım#

Çok yaygın uygulamalar (veritabanları, önbellekler, izleme yığınları) için olgun ve bakımlı chart'lar zaten mevcut; onları kullanmak kendi şablonunu yazmaktan hem hızlı hem güvenlidir. Kendi yazdığın uygulamalar içinse helm create ile üretilen iskelet çoğu zaman yeterlidir; birkaç değeri değiştirip kullanmaya başlayabilirsin. Ekipte birden fazla benzer servis varsa tek bir ortak chart yazıp değer dosyalarıyla farklılaştırmak en verimli yöntemdir.

Kapanış#

Helm, Kubernetes'te dağıtımı "onlarca YAML dosyasını doğru sırayla uygulamak" olmaktan çıkarıp tek bir sürümlenmiş işleme dönüştürür. Aklında kalması gereken dört alışkanlık şunlar: her zaman upgrade --install kullan, üretim yükseltmelerini --atomic ile yap, değer dosyalarını sürüm kontrolünde tut ama sırları dışarıda bırak ve kümeye göndermeden önce mutlaka helm template ya da --dry-run ile çıktıyı gözünle gör. Bir şeyler ters gittiğinde ilk komutun helm history, ikincisi helm rollback olsun.

Kubernetes ve Helm tabanlı bir altyapıyı kurarken ya da işletirken destek istersen Clou.TR tarafında birkaç seçenek var. Küme düğümleri için bulut sunucu ve VDS paketlerimizi inceleyebilir, kurulum ve bakım yükünü devretmek istersen sunucu yönetimi hizmetimize göz atabilir, kümedeki kalıcı verilerin düzenli kopyaları için yedekleme çözümümüzü değerlendirebilirsin.