Docker Compose’tan Kubernetes’e Geçiş: Helm Chart ile Adım Adım Dağıtım Rehberi

Giriş

Docker Compose, tek makinede çok konteynerli uygulamaları hızla ayağa kaldırmak için harika. Ancak ölçek, güvenlik ve gözlemlenebilirlik ihtiyaçları arttığında, Kubernetes’e geçiş kaçınılmaz oluyor. Bu yazıda, mevcut Compose tanımınızı Helm Chart’a dönüştürerek Kubernetes üzerinde modern, sürdürülebilir ve otomasyona uygun bir dağıtım yapmayı adım adım ele alacağız. Rehber, pratik örnekler, en iyi uygulamalar ve sık yapılan hatalara karşı öneriler içerir.

Neden Helm?

Helm, Kubernetes manifestlerini paketleyip versiyonlayarak tekrar kullanılabilir hale getirir. values.yaml ile çevreye göre yapılandırma yönetimi kolaylaşır, helm upgrade --install ile idempotent dağıtımlar yapılır, rollback ile hızlı geri dönüş sağlanır. Çeviklik, izlenebilirlik ve CI/CD uyumluluğu açısından Compose’a kıyasla çok daha güçlü bir yönetim modeli sunar.

Ön Koşullar

- Kubernetes kümesi (minikube, kind, AKS, EKS veya GKE)
- kubectl ve helm kurulu (Helm v3 önerilir)
- Mevcut Docker Compose dosyası (docker-compose.yml)
- Bir container registry erişimi (Docker Hub, GHCR, ECR vs.)

Compose’tan Helm’e Modelleme

Compose servislerini tek tek Deployment ve Service kaynaklarına bölün. Her servis için bir Deployment (replica sayısı, image, env, volume mount) ve bir Service (ClusterIP veya LoadBalancer) oluşturun. Ağ politikaları, health check, kaynak limitleri gibi Kubernetes yerleşik yeteneklerle güvenilirlik ve ölçeklenebilirlik kazanın.

Helm Chart İskeleti Oluşturma

Proje dizininde helm create uyg-app komutunu çalıştırın. Oluşan yapı:
charts/
templates/
values.yaml
Chart.yaml
Yararlı şablonlar gelse de, gereksiz varsayılanları sadeleştirmek iyi bir başlangıçtır.

values.yaml Tasarımı

Uygulamanın farklı ortamları için değişecek alanları values.yaml içine alın. Örnek bir iskelet:
image.repository: ghcr.io/org/uyg-app
image.tag: 1.2.3
replicaCount: 3
resources.limits.cpu: "500m"
resources.limits.memory: "512Mi"
env: { APP_ENV: "prod", LOG_LEVEL: "info" }
service.type: ClusterIP
service.port: 8080
ingress.enabled: true
ingress.hosts: ["api.ornek.com"]

Deployment ve Service Şablonları

Deployment için şunları ihmal etmeyin:
- resources: request ve limit belirleyin (örn. cpu: 200m, memory: 256Mi).
- livenessProbe ve readinessProbe: HTTP endpoint veya TCP check ile hızlı hata tespiti.
- securityContext: root dışı kullanıcı, readOnlyRootFilesystem, capabilities kısıtlaması.
- envFrom: ConfigMap ve Secret’lardan çevresel değişken yönetimi.
Service için uygun type (ClusterIP, NodePort, LoadBalancer) ve port seçin. Dış dünyaya açılacaksanız Ingress tanımı ve TLS sertifikası (ör. cert-manager) planlayın.

İnşa, Push ve İlk Dağıtım

- Container imajınızı CI üzerinden versiyonlayın ve registry’ye push edin (örn. 1.2.3 tag’i).
- values.yaml içindeki image.tag değerini güncelleyin.
- İlk kurulum: helm upgrade --install uyg-app ./uyg-app -n prod
- Dağıtımı doğrulayın: kubectl get pods -n prod ve kubectl describe ile olayları inceleyin.

Yükseltme ve Geri Alma

- Versiyon güncellemesi: helm upgrade uyg-app ./uyg-app -n prod
- Farkları görmek için: helm diff upgrade (helm-diff eklentisi).
- Sorun varsa: helm rollback uyg-app <REVISION> -n prod. Helm, geçmiş sürümleri sakladığından geri dönüşler saniyeler içinde tamamlanır.

Gizli Bilgiler ve Config Yönetimi

Şifreler, token’lar ve API anahtarlarını Secret içinde tutun. Git’te açık tutmamak için Sealed Secrets veya External Secrets Operator kullanın. Konfigürasyonlarınızı ConfigMap olarak versiyonlayın; uygulama yeniden başlatması gerektiren değişikliklerde checksum/config anotasyonuyla otomatik rollout sağlayın.

Otomatik Ölçeklendirme ve Sağlık

HPA (Horizontal Pod Autoscaler) ile CPU/Memory metriklerine göre pod sayısını otomatik artırıp azaltın. readinessProbe doğru ayarlı değilse HPA ölçeklense bile trafiğin başarısız olacağını unutmayın. Ayrıca PodDisruptionBudget ile planlı bakım sırasında minimum sağlıklı pod sayısını garanti altına alın.

Güvenlik ve RBAC

Uygulamaya özel bir ServiceAccount tanımlayın, yalnızca gerekli izinleri veren bir Role/RoleBinding ekleyin. PodSecurityContext ile kullanıcı/GRUP ID belirleyin, root olarak çalışmayın. Ağ tarafında NetworkPolicy ile trafik kısıtlaması yaparak saldırı yüzeyini daraltın.

CI/CD ve GitOps

- CI adımları: test → build → scan → push → helm lint → helm template/diff → deploy.
- GitOps için Argo CD veya Flux kullanın. Helm chart’ınızı bir Git deposuna koyun, values dosyalarını ortam bazlı dallarda yönetin. Her commit, küme durumunu deklaratif olarak günceller; manuel hataları azaltır.

Gözlemlenebilirlik: Log, Metrik ve İz

Log’lar için stdout/stderr yazın; kümede Loki/ELK ile toplayın. Metrikler için Prometheus, dashboard için Grafana kurun. Uygulama düzeyinde OpenTelemetry ile dağıtık izlemeyi etkinleştirerek istek gecikmelerini uçtan uca görünür kılın.

Yaygın Hatalar ve İpuçları

- imagePullPolicy yanlış: Geliştirme dışında IfNotPresent genelde yeterlidir; prod’da immutable tag kullanın (örn. SHA digest).
- resource tanımsız: Limit/Request yoksa scheduler tutarsız davranır; önceliklendirme zorlaşır.
- probe endpoint’leri: Uygulama hazır olmadan trafiğe açmayın; readiness’i gerçek bağımlılıklar sağlandığında başarılı olacak şekilde ayarlayın.
- config değişikliği rollout: ConfigMap değişikliğini pod’lara yansıtmak için anotasyon checksum tekniğini kullanın.

Sonuç

Helm ile Kubernetes’e geçiş, yalnızca bir orkestrasyon değişimi değil; aynı zamanda daha iyi sürümleme, güvenlik, otomasyon ve gözlemlenebilirlik kültürüne geçiştir. Compose dünyasındaki sadeliği, şablonlanabilir manifestler, values tabanlı yapılandırma ve GitOps süreçleriyle kaybetmeden; aksine kurumsal ölçekte yönetilebilirlik kazanırsınız. Küçük başlayın, her sürümde bir iyileştirme ekleyin ve dağıtımlarınızı otomatikleştirerek güvenle ölçekleyin.

Docker Buildx ile Çok Mimarili İmaj Oluşturma ve GitHub Actions ile Otomatik Yayınlama (2025 Rehberi)

Giriş

Apple Silicon (arm64) makineler, Raspberry Pi gibi ARM tabanlı cihazlar ve geleneksel x86_64 sunucuların aynı anda hedeflenmesi artık modern projeler için kaçınılmaz. Çok mimarili (multi-arch) Docker imajları, tek bir etiket altında hem amd64 hem de arm64 varyantlarını barındırarak bu ihtiyacı şık biçimde çözer. Bu rehberde, Docker Buildx ile yerelde çok mimarili imaj üretmeyi ve GitHub Actions üzerinden Docker Hub’a otomatik yayınlamayı adım adım anlatıyorum. Hedefimiz: sürtünmesiz bir CI/CD hattı, hızlı önbellekleme ve güvenilir üretim dağıtımları.

Ön Gereksinimler

Yerel ortamda Docker Engine veya Docker Desktop’ın güncel bir sürümünü (tercihen 24+) kullanın. BuildKit artık varsayılan, ancak gerekirse DOCKER_BUILDKIT=1 ile etkinleştirildiğinden emin olun. Bir Docker Hub hesabı ve GitHub deposu hazırlayın. Reponuzda hassas bilgileri GitHub Secrets ile saklayacağız (DOCKERHUB_USERNAME, DOCKERHUB_TOKEN vb.).

Yerelde Buildx ile Çok Mimarili İmaj Oluşturma

Önce Buildx sürümünü kontrol edin: docker buildx version. Özel bir builder oluşturup devreye alın: docker buildx create --name multi --use. Ardından QEMU emülasyonunu etkinleştirin ki yerel mimariniz dışında da derleme yapabilesiniz: docker run --privileged --rm tonistiigi/binfmt --install all. Builder’ı hazırlayın: docker buildx inspect --bootstrap. Artık çok mimarili derleme komutu hazır: docker buildx build --platform linux/amd64,linux/arm64 -t KULLANICI/IMAJ:1.0 --push . Bu komut Docker Hub’a doğrudan push yapacağından, önce docker login ile oturum açmayı unutmayın.

Dockerfile İpuçları (Mimariden Bağımsız ve Hızlı)

Temel imaj seçimi kritik: Hem amd64 hem arm64 desteği olan resmi imajları tercih edin (ör. node:20-alpine, python:3.12-slim, golang:1.22-alpine). Çok aşamalı (multi-stage) Dockerfile kullanarak build bağımlılıklarını runtime’dan ayırın; bu boyutu küçültür ve güvenliği artırır. Mimariye özel binary indiriyorsanız TARGETARCH veya TARGETOS argümanlarını kullanın. Örnek: ARG TARGETARCH satırından sonra, curl -L https://example.com/bin-$TARGETARCH -o /usr/local/bin/app gibi bir strateji uygulayabilirsiniz. Node.js projelerinde native modüller (ör. Sharp) için build araçlarını sadece builder aşamasında yükleyip, final aşamada minimal tabana geçmek iyi bir pratik.

Örnek Build Komutu ve Hızlı Doğrulama

Yerel denemede aşağıdaki tek satır oldukça pratik çalışır: docker buildx build --platform linux/amd64,linux/arm64 -t KULLANICI/IMAJ:latest --push -f Dockerfile . Yayın sonrası manifesti doğrulamak için: docker buildx imagetools inspect KULLANICI/IMAJ:latest. Çıktıda iki platformu birden görmelisiniz. Ayrıca farklı makinelerde docker pull yaparak gerçek koşullarda test edin (ör. bir M2 Mac ve bir x86_64 bulut sunucusu).

GitHub Actions ile Otomatik Yayınlama (CI/CD)

Depo köküne .github/workflows/docker.yml oluşturun ve şu adımları içeren bir iş akışı kurgulayın: kaynak kodu checkout, QEMU kurulumu, Buildx kurulumu, Docker Hub’a giriş, imaj etiketlerini otomatik üreten metadata, çok mimarili build ve push. Özet akış şöyle olmalı: checkout → setup-qemu → setup-buildx → login → metadata → build-push.

Önerilen ana adımlar: actions/checkout@v4 ile kodu çekin. docker/setup-qemu-action@v3 QEMU’yu kurar. docker/setup-buildx-action@v3 Buildx’i etkinleştirir. docker/login-action@v3 ile Docker Hub’a giriş yapın (secrets kullanın). docker/metadata-action@v5 commit SHA, branch, semver tag’lerden akıllı etiketler üretir. docker/build-push-action@v6 ile platforms: linux/amd64,linux/arm64, push: true parametreleriyle build ve yayın yapın.

Önbellek (cache) çok önemlidir. docker/build-push-action içinde cache-from: type=gha ve cache-to: type=gha,mode=max kullanarak GitHub’ın yerleşik önbelleğini devreye alın. Bu, aynı bağımlılıkları tekrar tekrar derlemeyi önleyerek build süresini ciddi ölçüde azaltır.

Sık Karşılaşılan Sorunlar ve Çözümleri

1) QEMU kaynaklı derleme hataları: setup-qemu-action adımının çalıştığını ve en güncel binfmt’nin kurulduğunu doğrulayın. Gerekirse yerelde tonistiigi/binfmt konteyneriyle tazeleyin.

2) Temel imajda arm64 desteği yok: Kullanılan base image’ın manifestini kontrol edin veya alternatif bir resmi imaja geçin (-alpine sürümleri genellikle çok mimarili gelir).

3) Native modül derleme sorunları: Build aşamasında gerekli paketleri (ör. build-base, python3, libvips-dev) kurup final aşamada temizleyin. Node projelerinde npm ci --omit=dev ve npm rebuild --arch=$TARGETARCH gibi çözümler işe yarar.

4) Büyük imaj boyutu: Multi-stage yapı, --chown ile katman optimizasyonu, gereksiz dosyaları .dockerignore ile hariç tutma ve distroless/slim tabanlar boyutu ciddi şekilde düşürür.

Performans ve Güvenlik İpuçları

- CI’da cache’i etkin kullanın; bağımlılıkların hash’lenmesi ve doğru katmanlama build’i hızlandırır. - Tek bir manifest altında birden çok mimari barındırmak, çekme (pull) sırasında istemcinin doğru varyantı otomatik seçmesini sağlar; bu da kullanıcı deneyimini iyileştirir. - Minimum yetkili kullanıcı oluşturun (USER node gibi) ve kök kullanıcıyla çalışmaktan kaçının. - Sürüm etiketlerine özen gösterin: latest yanında 1.2.3, 1.2 gibi semantik etiketler yayınlamak geriye dönük uyumluluk ve geri dönüş kolaylığı sağlar.

Sonuç

Docker Buildx ve GitHub Actions kombinasyonu, çok mimarili imajları üretme ve dağıtma işini otomatikleştirerek geliştirme ekiplerine önemli hız kazandırır. Bu rehberdeki adımları izleyerek hem yerelde hem de CI ortamında linux/amd64 ve linux/arm64 için tek komutta güvenilir, hızlı ve ölçeklenebilir bir yayın akışı kurabilirsiniz. Doğru taban imajı, akıllı önbellek, temiz Dockerfile ve iyi etiket yönetimiyle, 2025’te çok mimarili dağıtım stratejinizi gönül rahatlığıyla standart hale getirebilirsiniz.