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 İmaj Oluşturma ve Cosign ile İmzalama (Güncel Rehber)

Giriş

Apple Silicon (ARM64) cihazların yaygınlaşması ve edge sunucuların çoğalmasıyla, tek bir mimariye derlenmiş konteyner imajları hızla demode oldu. Üretim ortamında aynı uygulamayı hem linux/amd64 hem de linux/arm64 üzerinde sorunsuz çalıştırmak için Docker Buildx ile çok mimarili (multi-arch) imaj üretmek artık bir zorunluluk. Bu yazıda, Buildx’i etkinleştirme, çok mimarili push, önbellek optimizasyonu ve imaj imzalama (Sigstore Cosign) adımlarını pratik ve güncel bir yaklaşımla anlatıyorum.

Neden Çok Mimarili İmaj?

M1/M2/M3 Mac’lerde lokal geliştirme yapıp, üretimde x86_64 (amd64) sunuculara deploy etmek en yaygın senaryo. Multi-arch sayesinde tek bir etiket ile iki mimariyi de içeren bir manifest yayınlarsınız; docker pull işlemi çalıştığı platforma uygun katmanı otomatik indirir. Böylece ayrı Dockerfile’lar, ayrı registry etiketleri ve karmaşık akışlar ortadan kalkar.

Önkoşullar

- Docker 20.10+ ve BuildKit etkin (varsayılan).
- QEMU emülasyonu için binfmt kurulumu (host’ta veya builder içinde).
- Bir container registry (Docker Hub, GHCR, ECR vb.).
- Opsiyonel: İmaj imzalama için Cosign ve SBOM üretimi.

Buildx’i Etkinleştirme ve Binfmt Kurulumu

Önce Buildx sürümünüzü kontrol edin: docker buildx version. Yeni bir builder oluşturup varsayılan yapın: docker buildx create --name multi --use. Gerekirse platform emülasyonu için docker run --privileged --rm tonistiigi/binfmt --install all komutunu çalıştırın. Bu adım, ARM64 makinede amd64 image derlemek gibi çapraz mimari senaryoları mümkün kılar.

Tek Komutta Çok Mimarili İmaj Üretme

Proje dizininizde basit bir Dockerfile olduğunu varsayalım. Multi-arch build ve push için şu kalıbı kullanabilirsiniz: docker buildx build --platform linux/amd64,linux/arm64 -t kullanici/uygulama:1.0 --push . Bu komut, her iki mimari için ayrı katmanlar üretir ve registry’e tek bir manifest altında yükler. Test etmek için docker buildx imagetools inspect kullanici/uygulama:1.0 çıktısında iki platformu görmelisiniz.

Performans ve Önbellek İpuçları

Yapı sürelerini kısaltmak için BuildKit cache kullanın. Registry tabanlı önbellek için: --cache-to type=registry,ref=kullanici/uygulama:cache,mode=max ve --cache-from type=registry,ref=kullanici/uygulama:cache seçeneklerini ekleyin. Ayrıca, Dockerfile’ı katman dostu yazmak (bağımlılıkları erken kopyalamak, --mount=type=cache kullanımı, çok aşamalı derleme) build sürelerini dramatik şekilde azaltır.

CI/CD’de Otomasyon (GitHub Actions Örneği)

CI’da tipik akış: checkout → docker/setup-qemu-action ile QEMU → docker/setup-buildx-action ile Buildx → registry’ye login → docker buildx build --platform linux/amd64,linux/arm64 --push. Sürüm etiketlerini v1.2.3, latest ve commit SHA gibi çoklu tag’lerle birlikte yayınlamak, tüketicilerin sağlam bir sürüm stratejisi izlemesine yardımcı olur.

Güvenlik: Cosign ile İmaj İmzalama ve SBOM

Supply chain güvenliği artık lüks değil. Cosign ile imajlarınızı imzalayarak, imajın sizden çıktığını kanıtlayabilirsiniz. Adımlar basit: cosign generate-key-pair ile bir anahtar çifti üretin; cosign sign --key cosign.key kullanici/uygulama:1.0 ile imzalayın; doğrulama için cosign verify --key cosign.pub kullanici/uygulama:1.0 çalıştırın. Build aşamasında SBOM eklemek için Buildx’in --sbom=true ve --provenance=mode=max seçeneklerini kullanabilir, yazılım bileşen envanterini otomatik üretip imajla ilişkilendirebilirsiniz.

Yaygın Hatalar ve Çözüm Yolları

- “no match for platform in manifest”: Multi-arch manifest push edilmemiş olabilir; --push bayrağını ve --platform listesini kontrol edin.
- Temel imaj arm64 yok: Kullandığınız base image’in her iki mimari için resmi desteği olduğundan emin olun. Örneğin alpine, debian ve ubuntu çoğunlukla multi-arch sunar.
- Yavaş build: QEMU emülasyonu doğal olarak yavaştır; mümkünse native runner kullanın (amd64 için amd64 runner). Cache’i registry’ye yazmayı ve tekrar kullanmayı unutmayın.
- İmza doğrulanmıyor: Doğru public key kullandığınızdan ve imzanın ilgili etikete uygulandığından emin olun. CI ortamında key yönetimi için OIDC ile keyless imzalama da değerlendirilmelidir.

En İyi Uygulamalar

- Tag stratejisi: semver (+ latest), commit SHA ve platform bağımsız tek etiket kullanın.
- Reproducible build: Sabit bağımlılık versiyonları ve belirli builder sürümleri seçin.
- Güvenlik: İmza ve SBOM’u pipeline’ın ayrılmaz parçası haline getirin, hatalı doğrulamada deploy’u durdurun.
- Gözlemlenebilirlik: Build süreleri, cache isabet oranı ve başarısızlık nedenlerini CI’da raporlayın.

Sonuç

Docker Buildx, çok mimarili konteyner üretimini günlük pratiğin doğal bir parçası haline getiriyor. Doğru yapılandırmayla tek komutta amd64 ve arm64 için imaj üretip push edebilir, CI/CD’de otomatikleştirip, Cosign ile imzalayarak supply chain güvenliğini güçlendirebilirsiniz. Bu yaklaşım, hem geliştirici deneyimini iyileştirir hem de üretim ortamlarında taşınabilirlik ve güvenilirliği artırır.

GitHub Actions ile Docker Buildx Kullanarak Çok Mimarili İmaj (amd64 + arm64) Yayınlama Rehberi

Kapsayıcı tabanlı dağıtımların hızla arttığı günümüzde, tek bir mimariye bağlı kalmak ciddi bir kısıt olabilir. Özellikle bulut sağlayıcılar ve edge cihazları (Raspberry Pi gibi ARM tabanlı sistemler) söz konusu olduğunda, amd64 ve arm64 için tek bir sürüm hattından imaj üretebilmek büyük avantaj sağlar. Bu yazıda, GitHub Actions ve Docker Buildx kullanarak çok mimarili (multi-arch) imajı nasıl inşa edip hem Docker Hub hem de GHCR’ye nasıl yayınlayacağınızı adım adım anlatıyorum.

Neden Buildx? Buildx, BuildKit’i temel alır ve çoklu platform inşa, gelişmiş önbellekleme, yerleşik SBOM/provenance gibi özellikleri etkinleştirir. Bunun anlamı: Tek bir pipeline ile linux/amd64 ve linux/arm64 hedeflerini derleyebilir, tek bir manifest altında birleştirip push edebilirsiniz.

Önkoşullar ve depo ayarları

- GitHub repository’nizde Actions etkin olmalı.
- Docker Hub’a push edecekseniz bir erişim token’ı oluşturun ve GitHub’da Settings > Secrets and variables > Actions altında DOCKERHUB_USERNAME ve DOCKERHUB_TOKEN olarak ekleyin.
- GHCR (GitHub Container Registry) kullanacaksanız, secrets.GITHUB_TOKEN çoğu durumda yeterlidir. Özel bir PAT kullanıyorsanız gerekli scope’lar: write:packages ve read:packages.

Workflow mantığı

Pipeline’da sırasıyla QEMU etkinleştirmesi (arm64 emülasyonu için), Buildx builder kurulumu, metadata/etiket üretimi, cache ayarı, çok mimarili build ve push adımları yer alacak. Ek olarak SBOM ve provenance (inşa kanıtı) bilgilerini de ekleyebiliriz.

Örnek workflow (/.github/workflows/release.yml)

name: release-multi-arch
on:
push:
tags:
- 'v*.*.*'
jobs:
build-and-push:
runs-on: ubuntu-latest
permissions:
contents: read
packages: write
id-token: write
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Set up QEMU
uses: docker/setup-qemu-action@v3
with:
platforms: arm64
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
- name: Docker metadata
id: meta
uses: docker/metadata-action@v5
with:
images: |
ghcr.io/<kullanici>/<imaj-adi>
<kullanici>/<imaj-adi>
tags: |
type=semver,pattern={{version}}
type=semver,pattern={{major}}.{{minor}}
type=raw,value=latest
- name: Login to Docker Hub
uses: docker/login-action@v3
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
- name: Login to GHCR
uses: docker/login-action@v3
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
- name: Build and push multi-arch
uses: docker/build-push-action@v6
with:
context: .
file: ./Dockerfile
platforms: linux/amd64,linux/arm64
push: true
tags: ${{ steps.meta.outputs.tags }}
labels: ${{ steps.meta.outputs.labels }}
cache-from: type=gha
cache-to: type=gha,mode=max
provenance: true
sbom: true

Önemli noktalar ve iyi uygulamalar

• QEMU: Yerel runner’ınız x86 ise, arm64 imajı için QEMU emülasyonu gerekir. docker/setup-qemu-action bunu sizin yerinize yapar. Performans, yerel ARM runner’a göre daha düşük olabilir; kritik projelerde self-hosted ARM runner düşünebilirsiniz.

• Metadata ve etiketleme: docker/metadata-action; semver uyumlu etiketleri (v1.2.3, 1.2, latest) otomatik üretir. Böylece kullanıcılarınız ister sürüm sabitlemesi, ister “latest” ile hızlı çekim yapabilir.

• Cache: GHA (GitHub Actions) cache’i ile katmanlar arası hız kazanırsınız. Dockerfile’ınızı cache verimini maksimize edecek şekilde düzenleyin: bağımlılık kurulumunu, sık değişen dosyalardan önce konumlandırmayın. Örneğin, package.json kopyası ve “npm ci” adımları, uygulama kodlarından önce gelmeli.

• Güvenlik: provenance: true ve sbom: true ile tedarik zinciri bilgilerini imaja iliştirebilirsiniz. Cosign ile imzalama eklemek isterseniz OIDC tabanlı keyless imzayı tercih edin; sigstore/cosign-installer ve “cosign sign” adımıyla workflow’u genişletebilirsiniz.

• Çok kayıtlı push: Yukarıdaki örnek aynı anda hem GHCR hem Docker Hub’a push eder. Kimlik bilgileri doğru ise manifest listesi, her iki registry’de de aynı etiketlerle yer alır.

Sorun giderme

• “no match for platform in manifest” hatası: Çekmeye çalıştığınız hedef platform için imaj manifest’i yoktur. buildx ile push sonrası, “docker buildx imagetools inspect <image:tag>” çıktısında amd64 ve arm64 görünmelidir.

• QEMU ile yavaş derleme: Bazı bağımlılıklar (ör. kriptografik kütüphaneler) arm64 derlemede ciddi süre alabilir. Mümkünse çok aşamalı (multi-stage) Dockerfile kullanın ve ağır kısımları önbelleğe alın. Alternatif olarak self-hosted arm64 runner veya BuildKit’in uzak builder modlarını düşünebilirsiniz.

• Önbellek isabeti düşükse: “cache-from: type=gha” etkin olmasına rağmen isabet zayıfsa, Dockerfile adımlarının sıralamasını gözden geçirin. “COPY . .” gibi geniş kapsamlı kopyalar, küçük değişikliklerde bile önbelleği bozabilir. Yalnızca gerekli dosyaları kopyalayın.

• Docker Hub hız limitleri: Anonim veya düşük planlı hesaplarda rate limit’e takılabilirsiniz. Login adımı şarttır. Gerekiyorsa workflow’u yeniden deneme stratejisiyle (retry) sarmalayın.

Performans ve maliyet ipuçları

• Katman sayısını azaltın, gereksiz paketleri temizleyin (apk/apt ile “--no-cache” ve “rm -rf /var/lib/apt/lists/*”).
• Dil ekosistemlerinde üretim odaklı taban imajları (distroless, alpine, slim) tercih edin.
• Çok aşamalı derlemede builder imajını üretim katmanından ayırın; sadece çalışma zamanı için gereken dosyaları kopyalayın.

Sonuç

GitHub Actions ve Docker Buildx ikilisi, tek bir pipeline üzerinden hem amd64 hem de arm64 imajlarını üreterek modern dağıtım ihtiyaçlarınıza güçlü bir yanıt sunar. Doğru önbellekleme, tutarlı etiketleme ve güvenlik metadatalarıyla (SBOM, provenance) birlikte kullanıldığında, CI/CD hattınız hızlı, izlenebilir ve güvenli çalışır. Bu rehberi temel alarak projenizi kolayca ölçeklendirebilir, bulut ve edge senaryolarında tek bir imaj adını kullanarak tüm platformlara rahatlıkla dağıtım yapabilirsiniz.

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.