Docker Buildx ile Çok Mimarili (Multi-Arch) Konteyner İmajı Oluşturma Rehberi (2025)

Giriş

Farklı mimarilerde (ARM64, AMD64 gibi) çalışan sunucuların ve geliştirici makinelerinin arttığı bir dönemde, tek bir Docker imajını her yerde sorunsuz çalıştırmak kritik hale geldi. Apple Silicon (M1/M2/M3) kullanan geliştiriciler, AMD64 tabanlı üretim sunucularına dağıtım yaparken uyumluluk sorunları yaşayabiliyor. Bu rehberde, Docker Buildx ve BuildKit kullanarak çok mimarili (multi-arch) Docker imajı oluşturmayı, imajı bir container kayıt deposuna itip SBOM/provenance gibi modern güvenlik özelliklerini eklemeyi adım adım anlatıyorum.

Neden Çok Mimarili İmaj?

Çok mimarili imajlar, tek bir etiket altında birden fazla işlemci mimarisini içeren bir manifest listesi barındırır. Böylece docker pull çalıştığında istemcinin mimarisine uygun katmanlar otomatik olarak indirilir. Sonuç: tek etiket, tek dağıtım akışı ve daha az sürpriz. Ayrıca CI/CD hatlarınız basitleşir ve hem ARM64 hem de AMD64 için ayrı imaj yönetme yükünüz azalır.

Gereksinimler ve Kurulum

- Docker 24+ ve Buildx etkin olmalı (Docker Desktop ile varsayılan gelir). Linux sunucularda buildx plugin’inin kurulu olduğundan emin olun.

- Farklı mimariler için yerel derleme yapmıyorsanız, emülasyon için QEMU/binfmt gerekir. Docker Desktop bunu sağlar; çıplak Linux’ta bir defaya mahsus şu komutla etkinleştirebilirsiniz: docker run --privileged --rm tonistiigi/binfmt --install all

- Kayıt deposu erişimi (Docker Hub, GHCR, GitLab Registry vb.) ve push yetkisi.

Adım 1: Buildx Builder Oluşturma

Yeni bir builder örneği, BuildKit özelliklerini (cache, çoklu platform, SBOM) etkin kullanmanızı sağlar. Aşağıdaki komut genel bir başlangıçtır: docker buildx create --name multi --use --bootstrap. Bu, “multi” adında bir builder oluşturur ve aktif hale getirir.

Adım 2: Dockerfile’ı Multi-Arch Uyumlu Yazma

Temel imaj olarak multi-arch sağlayan resmi imajları seçin (örneğin node:20-alpine, python:3.12-slim, golang:1.22-alpine). Derleme sırasında mimari fark yaratabilecek bağımlılıklar (ör. native modüller, OS paketleri) için hedef platforma duyarlı bayrakları düşünün. Multi-stage derleme (builder + runtime) hem boyutu küçültür hem de taşınabilirliği artırır.

Adım 3: Çok Mimarili İmajı İnşa Etme ve Gönderme

Örnek bir komut: docker buildx build --platform linux/amd64,linux/arm64 -t ghcr.io/kullanici/uygulama:1.0 --push . Bu komut iki mimari için derler ve manifest listesi ile birlikte etikete gönderir. Yerelde test etmek isterseniz --load kullanabilirsiniz; ancak --load tek mimari için çalışır. Multi-arch için en iyi pratik --push kullanmaktır.

Adım 4: SBOM ve Provenance Eklemek

SBOM (Software Bill of Materials) ve provenance, tedarik zinciri güvenliği için giderek zorunlu hale geliyor. BuildKit ile şu bayrakları ekleyebilirsiniz: --sbom=true --provenance=true. Tam örnek: docker buildx build --platform linux/amd64,linux/arm64 -t ghcr.io/kullanici/uygulama:1.0 --sbom=true --provenance=true --push . Çoğu kayıt deposu bu metadataları saklayıp sonradan denetlenmesine izin verir.

Adım 5: Cache Yapılandırması ile Hız Kazanın

Buildx, uzak kayıt deposu tabanlı cache’i destekler. İlk derlemede --cache-to type=registry,ref=ghcr.io/kullanici/uygulama:buildcache,mode=max; sonraki derlemelerde --cache-from type=registry,ref=ghcr.io/kullanici/uygulama:buildcache kullanın. Bu sayede farklı CI runner’ları arasında katmanlar paylaşılarak derleme süresi ciddi şekilde kısalır.

Gizli Anahtarlar ve Çok Aşamalı Derlemeler

Derleme esnasında gizli anahtar (örneğin NPM_TOKEN) kullanacaksanız, komutta --secret id=NPM_TOKEN,env=NPM_TOKEN bayrağını, Dockerfile içinde de RUN --mount=type=secret,id=NPM_TOKEN kullanın. Bu yaklaşım sırları imaj katmanlarına sızdırmadan bağımlılık yüklemeyi mümkün kılar.

Doğrulama ve Hata Ayıklama

İmajınızın gerçekten çok mimarili olup olmadığını kontrol etmek için docker buildx imagetools inspect ghcr.io/kullanici/uygulama:1.0 çalıştırın. Manifest listesinde linux/amd64 ve linux/arm64 girdiğini görmelisiniz. Yerel test için Apple Silicon’da docker run --platform linux/amd64 ile x86_64 çalıştırıp davranışı karşılaştırabilirsiniz.

CI/CD Entegrasyonu (GitHub Actions Örneği)

GitHub Actions’ta tipik adımlar: QEMU kurulumu, Buildx kurulumu, kayıt deposuna login, cache ayarları, ardından çok mimarili build ve push. Resmi docker/setup-qemu-action ve docker/setup-buildx-action aksiyonlarını kullanın. Workflow’da gizli anahtarları secrets ile yönetin, etiketleri semantik sürümleme veya git SHA ile otomatik üretin.

Performans ve Maliyet İpuçları

- Mümkünse her mimari için yerel runner kullanın; emülasyon (QEMU) doğru ama yavaştır. Büyük derlemelerde süreyi belirgin etkiler.

- Minimal taban imajları (alpine, distroless) boyutu küçültür ve indirme süresini hızlandırır. Ağ maliyeti ve soğuk başlangıç süreleri düşer.

- Çok aşamalı derlemeyle derleme araçlarını final imajdan uzak tutun; güvenlik taramalarında daha az yüzey alanı elde edersiniz.

Sonuç

Docker Buildx ile çok mimarili imaj üretmek, bugün heterojen altyapılarda sürdürülebilir bir dağıtım stratejisinin bel kemiği. Doğru taban imajları, cache ve güvenlik metadatalarıyla desteklendiğinde, tek etiketle tüm platformlara güvenle dağıtım yapabilirsiniz. Üstelik CI/CD hatlarınıza entegre edilmesi kolay ve uzun vadede bakım yükünü ciddi biçimde azaltıyor. Bir kez kurduktan sonra, “nerede çalışacak?” sorusu gündemden düşüyor; geriye sadece uygulamanızın değer üretmesi kalıyor.

Docker Buildx ile Çok Mimarili (AMD64 + ARM64) Container İmajı Yayınlama: Adım Adım Rehber

Giriş

Apple Silicon (ARM64) makinelerin ve bulut ortamlarında ARM sunucuların yaygınlaşmasıyla, tek mimariye (örneğin yalnızca AMD64) derlenen imajlar kullanıcı deneyimini ve dağıtımı zorlaştırıyor. Docker Buildx, tek komutla birden fazla mimari için (AMD64, ARM64, ARMv7 vb.) imaj üretmeyi ve tek bir manifest altında yayımlamayı kolaylaştırıyor. Bu yazıda, yerelde ve GitHub Actions ile CI/CD hattında çok mimarili imaj oluşturmayı, cache kullanmayı, SBOM/provenance üretmeyi ve sık karşılaşılan sorunları çözmeyi adım adım ele alacağım.

Neden Çok Mimarili İmaj?

- Kullanıcı kapsama alanı: Hem x86_64 (AMD/Intel) hem ARM64 (Apple M-serisi, Graviton) sistemlerde sorunsuz çalışır.

- Performans ve maliyet: ARM altyapılarında daha düşük maliyet ve daha iyi watt başına performans elde edilebilir.

- Tek etiket, çok platform: Manifest listesi sayesinde docker pull myorg/app:latest komutu, çalıştığınız platforma uygun imajı otomatik çeker.

Ön Koşullar

- Docker 24+ ve Buildx etkin (Docker Desktop kullanıyorsanız Buildx varsayılan gelir).

- Registry erişimi: Docker Hub, GitHub Container Registry (GHCR) veya özel bir OCI uyumlu kayıt defteri.

- Yerel testlerde emülasyon gerekebilir; QEMU binfmt kurulu olmalı. Docker Desktop bunu genellikle otomatik sağlar.

Yerelde Buildx ile Çok Mimarili Build

1) Bir Buildx builder oluşturun ve kullanın: docker buildx create --name multiarch --use ve ardından docker buildx inspect --bootstrap. Bu adım BuildKit’i ve platform desteğini başlatır.

2) Emülasyon (gerekiyorsa): Linux makinelerde yoksa docker run --privileged --rm tonistiigi/binfmt --install all komutuyla QEMU kurabilirsiniz. Docker Desktop kullananlar çoğu zaman bu adımı atlayabilir.

3) Çoklu platform build ve push: Örneğin docker login ile kayıt defterine giriş yaptıktan sonra docker buildx build --platform linux/amd64,linux/arm64 -t ghcr.io/kullanici/uygulama:1.0 -t ghcr.io/kullanici/uygulama:latest --push . komutunu çalıştırın. Bu komut, her iki mimari için imaj üretir, registry’ye yükler ve tek bir manifest altında birleştirir.

4) Doğrulama: docker buildx imagetools inspect ghcr.io/kullanici/uygulama:latest çıktısında manifest içinde AMD64 ve ARM64 platformlarını görmelisiniz.

Dockerfile İpuçları (TARGETPLATFORM ve BUILDPLATFORM)

- Çok mimaride tutarlı build’ler için Dockerfile’ın başına ARG TARGETPLATFORM ve ARG BUILDPLATFORM ekleyin. Bazı taban imajlarını seçerken bu argümanlar kritik olabilir.

- Derleme araçları içeren çok aşamalı bir yaklaşım kullanın: “builder” aşamasında derleyin, “runtime” aşamasında minimal taban imajına kopyalayın.

- Go/Node/Python gibi ekosistemlerde platforma duyarlı bağımlılıklar için koşullu adımlar planlayın. Örneğin Go’da CGO kullanıyorsanız uygun CC ve GOARCH ayarlarını set edin.

GitHub Actions ile Otomasyon

CI/CD sürecinde multi-arch build için tipik adımlar: QEMU kurulum, Buildx hazırlığı, registry’ye giriş, build-push ve cache. Örnek akış şu şekildedir:

- QEMU: docker/setup-qemu-action@v3 ile arm64 ve amd64 emülasyonunu etkinleştirin.

- Buildx: docker/setup-buildx-action@v3 ile bir builder oluşturun.

- Registry Login: docker/login-action@v3 ile Docker Hub veya GHCR’a giriş yapın.

- Build & Push: docker/build-push-action@v5 ile platforms=linux/amd64,linux/arm64, push=true, tags alanlarını doldurun. Ön bellek için cache-from=type=gha ve cache-to=type=gha,mode=max kullanın. Yazılım tedarik zinciri metadatası için provenance=mode=max ve sbom=true parametrelerini etkinleştirin.

- Semantik etiket: 1.2.3, 1.2 ve latest gibi çoklu etiket yayınlayarak tüketimi kolaylaştırın.

Cache ve Performans

- Build sürelerini kısaltmak için katmanları sabitleyin ve gereksiz dosyaları kopyalamayın (örn. .dockerignore kullanın).

- Registry tabanlı cache ile farklı runner’larda bile hız kazanın. BuildKit GHA cache, büyük monorepo’larda ciddi fayda sağlar.

- Dil/araç cache’leri (Go mod, npm ci, pip cache) için katman sırasını optimize edin; bağımlılıkların daha az değiştiği katmanları üstte tutun.

Güvenlik: SBOM ve Provenance

- SBOM (Software Bill of Materials) ve provenance, tedarik zinciri görünürlüğü sağlar. Buildx ile oluşturulan attestation’lar, imaj içeriğini ve nasıl üretildiğini kanıtlar.

- Gerektiğinde imza eklemek için Cosign gibi araçları entegre edin. İmajlarınızı politikalarla (örn. Kyverno, Tekton Chains) doğrulayabilirsiniz.

Yaygın Hatalar ve Çözümleri

- Exec format error: Genellikle QEMU/binfmt kurulmadığında veya emülasyon devre dışı olduğunda görülür. QEMU’yu yeniden yükleyin ve Buildx builder’ı --bootstrap ile yenileyin.

- Yerel bağımlılıklar: Node-gyp, Python C uzantıları gibi bileşenler mimariye duyarlıdır. Derleme aşamasında uygun derleyicilerin ve kütüphanelerin kurulduğundan emin olun.

- Taban imaj uyumsuzluğu: Bazı hafif taban imajlar (distroless, alpine) belirli mimarilerde ek paket gerektirebilir. İmaj seçiminde --platform ile test edin, mümkünse resmi çok mimarili taban imajları tercih edin.

- Performans: Emülasyon ile derleme yavaştır. Mümkünse native ARM64 ve AMD64 runner’lar kullanın (örn. karma self-hosted runner filosu).

Sonuç

Docker Buildx, modern dağıtım ihtiyaçları için kritik olan çok mimarili imajları üretmenin en pratik yolu. Yerelde basit bir builder ve gerektiğinde QEMU ile başlayabilir, üretim ortamında GitHub Actions gibi bir CI/CD hattı üzerinden cache, SBOM ve provenance özellikleriyle güvenli ve hızlı yayın yapabilirsiniz. Sonuçta tek bir etiketle her platformda çalışan imajlar sunar, kullanıcı deneyimini iyileştirir ve operasyonel karmaşıklığı azaltırsınız.

Docker Buildx ile Çok Mimarili (amd64/arm64) Container İmajı Oluşturma Rehberi

Giriş

Apple Silicon (ARM64), Raspberry Pi ve buluttaki x86 sunucular gibi farklı mimarileri hedeflemek artık modern uygulamalar için kaçınılmaz. Tek bir imajın hem amd64 hem de arm64 için çalışması, dağıtım ve bakım yükünü azaltır. Bu rehberde, Docker Buildx kullanarak çok mimarili (multi-arch) container imajı oluşturmayı, kayıt depolarına (registry) göndermeyi ve doğrulamayı adım adım anlatıyorum. Ayrıca pratik ipuçları ve sık karşılaşılan sorunlara da değineceğim.

Önkoşullar

- Docker Desktop 4.x (macOS/Windows) veya Docker Engine 24+ (Linux). Çoğu sistemde Buildx ve QEMU desteği dahili gelir.
- Registry hesabı (Docker Hub veya GitHub Container Registry: ghcr.io).
- Terminal erişimi ve temel Docker komutlarına aşinalık.

Adım 1: Buildx builder oluşturun

Linux sunucularda QEMU emülasyonu gerekebilir. Gerekirse şu komutla kurun:
docker run --privileged --rm tonistiigi/binfmt --install all

Buildx builder oluşturun ve varsayılan olarak atayın:
docker buildx create --name multi --driver docker-container --use
Kurulumun aktif olduğunu doğrulayın:
docker buildx ls

Adım 2: Örnek Dockerfile (Node.js)

Aşağıdaki Dockerfile, hem amd64 hem de arm64 için derlenebilen basit bir Node.js uygulamasını paketler. Dikkat edilmesi gereken nokta, derleme aşamasında --platform=$BUILDPLATFORM kullanımıdır; bu, builder konteynerinin mimarisine uygun taban imajı çekerek tutarlı derleme sağlar.

# syntax=docker/dockerfile:1.6
ARG NODE_VERSION=20-alpine
FROM --platform=$BUILDPLATFORM node:${NODE_VERSION} AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .
RUN npm run build || echo "derlenecek bir şey yok"

FROM node:${NODE_VERSION}
WORKDIR /app
COPY --from=builder /app ./
EXPOSE 3000
CMD ["node", "server.js"]

Not: Base imaj olarak node:20-alpine çok mimarili manifest içerir. Uygulamanız Go, Rust veya Python ise benzer yaklaşımla çok mimari derleme yapabilirsiniz. Go için CGO_ENABLED=0 gibi bayraklarla statik build tercih edilebilir.

Adım 3: Çok mimarili build ve push

Önce kayıt deposuna giriş yapın:
docker login ghcr.io

Tek komutla her iki mimari için imaj üretip manifest list olarak push edin:
docker buildx build \
--platform linux/amd64,linux/arm64 \
-t ghcr.io/kullanici/uygulama:1.0 \
-t ghcr.io/kullanici/uygulama:latest \
--push .

Build süresini kısaltmak için --provenance=false veya uzak cache kullanabilirsiniz:
--cache-to type=registry,ref=ghcr.io/kullanici/uygulama:cache,mode=max
--cache-from type=registry,ref=ghcr.io/kullanici/uygulama:cache

Doğrulama

Manifest’ı inceleyin ve mimarileri kontrol edin:
docker buildx imagetools inspect ghcr.io/kullanici/uygulama:latest

Çıktıda Platforms: linux/amd64, linux/arm64 görmelisiniz. Farklı cihazlarda docker run çalıştırdığınızda, Docker otomatik olarak uygun mimariye karşılık gelen imajı çekecektir.

Çalıştırma

Yerelde test etmek için:
docker run -p 3000:3000 ghcr.io/kullanici/uygulama:latest
Sunucu başlatıldıktan sonra http://localhost:3000 üzerinden uygulamayı doğrulayın.

Sık karşılaşılan sorunlar ve ipuçları

Manifest bulunamadı: “no matching manifest” hatası alıyorsanız, seçtiğiniz base imajın çok mimarili desteği olmayabilir. Debian/Alpine gibi resmi imajların çoğu multi-arch’tır; özel imajlar için alternatife geçin.

Illegal instruction: Özellikle kriptografik kütüphaneler kullanan Node/Go projelerinde CPU özelliği uyumsuzluğu görülebilir. Derleme sırasında hedef mimarinin özellikleriyle uyumlu bayraklar kullanın veya musl/glibc farklarını göz önünde bulundurun.

Performans yavaşlığı: QEMU emülasyonu altında yerel olmayan mimariyi derlemek yavaş olabilir. Mümkünse arm64 runner (ör. Graviton) veya amd64 runner kullanarak native build tercih edin.

Deterministik build: npm ci, package-lock.json ve versiyon sabitleme kullanın. Go için mod dosyalarını kilitleyin, Python için requirements.txt sabitleyin.

--platform ve --build-arg: Dockerfile içinde FROM --platform=$BUILDPLATFORM kullanın, ancak çalışma katmanını mimari bağımsız tutmaya özen gösterin. Yer yer TARGETPLATFORM ile koşullu bağımlılık kurabilirsiniz.

GitHub Actions ile otomasyon (kısa örnek)

name: Build and Push Multi-Arch
on: [push]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: docker/setup-qemu-action@v3
- uses: docker/setup-buildx-action@v3
- uses: docker/login-action@v3
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
- uses: docker/build-push-action@v6
with:
context: .
push: true
platforms: linux/amd64,linux/arm64
tags: ghcr.io/kullanici/uygulama:latest

Sonuç

Docker Buildx ile çok mimarili imaj üretmek, farklı cihaz ve bulut altyapılarında aynı etiketle sorunsuz dağıtım yapmanızı sağlar. Doğru base imaj seçimi, QEMU/runner stratejisi ve cache kullanımıyla süreç hem hızlı hem de tekrarlanabilir hale gelir. Bu rehberdeki adımları CI/CD hattınıza taşıyarak, amd64 ve arm64 dünyalarını tek bir manifest altında birleştirebilirsiniz.