Docker Buildx ile Çoklu Mimarili İmaj Üretimi, İmzalama ve SBOM: Uçtan Uca Rehber

Giriş

Apple Silicon (arm64) ve x86_64 (amd64) dünyasının iç içe geçtiği günümüzde, tek bir Docker imajını birden fazla mimari için üretmek artık bir lüks değil, gereklilik. Üstelik iş yalnızca imajı derlemekle bitmiyor; tedarik zinciri güvenliği gereksinimleri sebebiyle imajları imzalamak ve yazılım malzeme listesi (SBOM) üretmek de kritik hale geldi. Bu rehberde, Docker Buildx ile çoklu mimari imaj üretmeyi, cosign ile imzalamayı ve syft ile SBOM oluşturup imaja iliştirmeyi adım adım anlatıyorum.

Önkoşullar

Makinenizde güncel Docker (mümkünse 24+), Buildx eklentisi (Docker Desktop veya docker-buildx plugin), ve emülasyon için QEMU kurulu olmalı. Çapraz derleme için binfmt yardımıyla arm64/amd64 emülasyonu etkinleştirilebilir. Ayrıca imzalama için cosign, SBOM için syft ve opsiyonel zafiyet taraması için grype kurmanız faydalı olacaktır.

Kontrol komutları: docker buildx version, mevcut builder'ları görmek için docker buildx ls. Gerekirse yeni bir builder oluşturun: docker buildx create --name multiarch --driver docker-container --use. Emülasyon için: docker run --privileged --rm tonistiigi/binfmt --install arm64,amd64.

Çoklu Mimarili İmaj Derleme ve Push

Çoklu mimari imaj üretmenin en pratik yolu Buildx ile manifest list oluşturmaktır. Örnek komut: docker buildx build --platform linux/amd64,linux/arm64 -t ghcr.io/kullanici/uygulama:1.0 --push . Bu komut, her mimari için ayrı imaj derleyip registry'e yükler ve üzerinde mimari bilgisi bulunan tek bir etiket altında (manifest list) birleştirir.

İşin sorunsuz ilerlemesi için taban imajınızın da çoklu mimari desteklemesi gerekir. Örneğin alpine, debian ya da popüler dil imajlarının çoğu arm64/amd64 sürümleri sağlar. Derleme aşamasında Go/Node/Rust gibi dillerde hedef mimariyi belirtmek için ilgili araçların bayraklarından yararlanın; örneğin Go için --build-arg ile GOOS=linux, GOARCH=arm64 gibi değişkenler verilebilir.

Derleme süresini kısaltmak ve tekrarlayan işlerden kaçınmak için BuildKit cache’i kullanın: --cache-to type=registry,ref=ghcr.io/kullanici/uygulama:buildcache,mode=max --cache-from type=registry,ref=ghcr.io/kullanici/uygulama:buildcache. Bu, özellikle CI/CD boru hatlarında çok fark yaratır.

Manifest List Doğrulama

Push tamamlandığında manifest içeriğini şöyle inceleyebilirsiniz: docker buildx imagetools inspect ghcr.io/kullanici/uygulama:1.0. Çıktıda linux/amd64 ve linux/arm64 varyantlarını görmelisiniz. Her cihaz, kendi mimarisine uygun katmanı otomatik olarak çekecektir.

Cosign ile İmaj İmzalama ve Doğrulama

Tedarik zinciri güvenliğinde ilk adım imajları imzalamaktır. Cosign iki biçimde çalışabilir: anahtarlı (key-pair) ve keyless (OIDC). Hızlı başlangıç için keyless önerilir. GitHub veya Google hesabınızla kimlik doğrulama yaparak: COSIGN_EXPERIMENTAL=1 cosign sign ghcr.io/kullanici/uygulama:1.0. Bu komut, imza verisini registry üzerinde imaj referansına bağlı şekilde saklar.

Doğrulama için: cosign verify ghcr.io/kullanici/uygulama:1.0. Çıktıda sertifika zinciri ve imzanın geçerliliği görünmelidir. İmzalama politikanızı CI’da zorunlu kılmak, üretim öncesi kabul kriterlerinin önemli bir parçasıdır.

Syft ile SBOM Üretimi ve İliştirme

SBOM (Software Bill of Materials), imajın içindeki bağımlılıkların envanteridir. Syft ile tek satırda oluşturabilirsiniz: syft ghcr.io/kullanici/uygulama:1.0 -o spdx-json > sbom.spdx.json. Bu dosyayı imaja iliştirmek için cosign attest kullanın: cosign attest --predicate sbom.spdx.json --type spdx ghcr.io/kullanici/uygulama:1.0.

SBOM’u doğrulamak veya çekmek için: cosign verify-attestation ghcr.io/kullanici/uygulama:1.0 ve cosign download attestation ghcr.io/kullanici/uygulama:1.0. SBOM, güvenlik taraması (grype, trivy) ve uyumluluk kontrolleri için referans noktasıdır.

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

GitHub Actions’da setup-buildx ve login adımlarını ekleyip ardından çoklu mimari derlemeyi tetikleyebilirsiniz. Tipik adımlar: registry’e giriş (docker/login-action), Buildx kurulum (docker/setup-buildx-action), cache ayarları, ardından docker/build-push-action ile platform: linux/amd64,linux/arm64 şeklinde build ve push. Sonraki adımlarda sigstore/cosign-installer ile cosign kurulumu, COSIGN_EXPERIMENTAL=1 cosign sign ve syft ile SBOM üretimi yer alabilir. Workflow gizli değişkenleriyle registry token’larını ve imza politikalarını yönetmeyi unutmayın.

İpuçları ve Yaygın Hatalar

- Taban imajı multi-arch değilse derleme bir mimaride başarılı olurken diğerinde başarısız olabilir. Alternatif taban imajları deneyin veya kendi tabanınızı üretin.

- QEMU emülasyonu derlemeyi yavaşlatabilir. Yerel arm64 runner veya native builder node’ları ile süreyi ciddi şekilde düşürebilirsiniz.

- Reproducible build için sabit sürümler ve kilit dosyaları (go.sum, package-lock.json, Cargo.lock) kullanın. Değişken sürümler, SBOM ve zafiyet taraması sonuçlarını dalgalandırır.

- Cache’i registry üzerinde tutmak, farklı runner’lar arasında tekrar derlemeyi azaltır. mode=max ile en agresif önbelleği etkinleştirebilirsiniz.

- İmza ve attestation objeleri için üretim ve test kayıtlarını ayırın. Etiketleme stratejinizde :dev, :staging, :prod gibi net kanallar oluşturun.

Sonuç

Docker Buildx ile çoklu mimari imaj üretmek, hem geliştirici deneyimini iyileştirir hem de farklı donanım platformlarında tek bir etiket üzerinden dağıtım yapmanızı sağlar. Cosign ile imzalama ve Syft ile SBOM üretimi ise tedarik zinciri güvenliğinizin bel kemiğidir. Bu üç adımı CI/CD boru hattınıza entegre ettiğinizde, yalnızca hızlı değil, aynı zamanda doğrulanabilir ve denetlenebilir bir yayın sürecine sahip olursunuz. Bugünden başlayın; manifest list, imza ve SBOM’u varsayılanınız haline getirin.

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.