docker buildx bake Rehberi: Target, Group, Değişken ve Matrix

Bake ne çözer?

Belgeler Bake'i docker build komutu için bir soyutlama olarak tanımlar: CLI bayraklarını, ortam değişkenlerini ve diğer ayarları ekipteki herkes için tutarlı biçimde yönetmenin yolu. Basit bir derlemede fark küçüktür. Ancak derleme argümanları, platformlar, etiketler ve önbellek ayarları çoğaldıkça komut satırını hatırlamak ve paylaşmak zorlaşır. Bake dosyası versiyon kontrolüne girer; herkes aynı yapılandırmayla derler.

Belgelerdeki karşılaştırma bunu net gösterir. Şu komut:

docker build \
  -f Dockerfile \
  -t myapp:latest \
  --build-arg foo=bar \
  --no-cache \
  --platform linux/amd64,linux/arm64 \
  .

Bake dosyasında şu hedefe karşılık gelir:

target "myapp" {
  context = "."
  dockerfile = "Dockerfile"
  tags = ["myapp:latest"]
  args = {
    foo = "bar"
  }
  no-cache = true
  platforms = ["linux/amd64", "linux/arm64"]
}

docker buildx bake myapp

Hedef özellikleri docker build bayraklarına yakından benzer: -f yerine dockerfile, -t yerine tags, --build-arg yerine args, --platform yerine platforms. Tüm özelliklerin listesi Docker belgelerindeki Bake file reference sayfasındadır.

Hedefler ve gruplar

Bake dosyasındaki bir target bir derleme çağrısını temsil eder. Bir hedefi derlemek için adını bake komutuna verirsiniz; birden fazla hedef adı verirseniz hepsi derlenir. Hiç hedef belirtmezseniz Bake default adlı hedefi ya da grubu derler.

dockerfile özelliği Dockerfile'ın yolunu verir; ayrıca context belirtmişseniz yol o context'e göre çözülür. Örneğin context = "app" ve dockerfile = "src/www/Dockerfile" birlikte app/src/www/Dockerfile dosyasını gösterir.

group bloğu birlikte derlenecek hedefleri toplar. Belgelerin ilk örneği frontend ve backend hedeflerini default grubunda birleştirir; böylece argümansız docker buildx bake ikisini eşzamanlı derler:

group "default" {
  targets = ["frontend", "backend"]
}

target "frontend" {
  context = "./frontend"
  dockerfile = "frontend.Dockerfile"
  args = {
    NODE_VERSION = "22"
  }
  tags = ["myapp/frontend:latest"]
}

target "backend" {
  context = "./backend"
  dockerfile = "backend.Dockerfile"
  tags = ["myapp/backend:latest"]
}

Bir hedef başka bir hedefin sonucunu named context olarak da kullanabilir. Belgelerdeki tests hedefi contexts = { webapp = "target:webapp" } ile webapp hedefini kendi derlemesine bağlar. Named context kavramı build context yazısında anlatılıyor.

İmaj üretmeyen hedefler: test, lint, ikili dosya

Bake hedefleri imaj üretmeden kontrol çalıştırabilir. Belgelerdeki Go örneğinde Dockerfile'da test ve lint stage'leri tanımlanır, Bake tarafında her hedef ilgili stage'e eşlenir ve output olarak type=cacheonly verilir:

group "validate" {
  targets = ["test", "lint"]
}

target "test" {
  target = "test"
  output = ["type=cacheonly"]
}

target "lint" {
  target = "lint"
  output = ["type=cacheonly"]
}

docker buildx bake validate

İki kontrol eşzamanlı çalışır; biri başarısız olursa komut da başarısız olur. cacheonly çıktısı imaj dışa aktarmadan build önbelleğini korur. Aynı yaklaşımla bir hedef ikili dosyayı yerel klasöre de çıkarabilir: belgelerdeki bin hedefi output = ["type=local,dest=build/bin"] ve platforms = ["local"] ile istemcinin platformu için derler. Exporter türleri build output yazısında.

Joker karakterle hedef seçmek

Bake, hedef ve grup adlarında kabuk tarzı desenleri destekler: * her karakter dizisiyle, ? tek karakterle, [abc] köşeli parantezdeki karakterlerden biriyle eşleşir. Belgelerin uyarısı önemlidir: deseni her zaman tırnak içine alın; aksi hâlde kabuğunuz joker karakteri geçerli klasördeki dosyalarla genişletir ve hata alırsınız.

docker buildx bake "foo-*"
docker buildx bake "foo*" "tests"

Değişkenler

variable bloğu varsayılan değeri olan bir değişken tanımlar. Değişken doğrudan bir özelliğin değeri olarak ya da ${} ile bir metnin içine yerleştirilerek kullanılır:

variable "TAG" {
  default = "latest"
}

group "default" {
  targets = ["webapp"]
}

target "webapp" {
  context = "."
  dockerfile = "Dockerfile"
  tags = ["docker.io/username/webapp:${TAG}"]
}

Bu değişkene üç yoldan değer verilebilir. Belgelere göre öncelik sırası şöyledir: --var ile verilen açık değer, aynı adlı ortam değişkeninden ve dosyadaki varsayılandan önce gelir. Aynı adı birden fazla --var ile verirseniz sonuncusu geçerli olur; değerler değişkenin bildirilen türüne dönüştürülür.

docker buildx bake --var TAG=dev webapp
TAG=$(git rev-parse --short HEAD) docker buildx bake webapp
docker buildx bake --print webapp

Ortam değişkenleri yalnızca variable bloğu olarak tanımlanmış değerleri ezebilir. Bu aramayı tamamen kapatmak için BUILDX_BAKE_DISABLE_VARS_ENV_LOOKUP=1 ayarlanır; --var o durumda da çalışır. --print derleme yapmadan çözümlenmiş yapılandırmayı JSON olarak yazdırır; değişkenlerin gerçekte hangi değeri aldığını görmenin en kolay yoludur.

Doğrulama ve kaçış

Bir değişkene validation bloğu ekleyerek tür, aralık ya da başka bir koşulu zorunlu kılabilirsiniz. condition ifadesi false dönerse derleme başarısız olur ve error_message yazdırılır. Birden fazla validation bloğu tanımlanabilir; hepsinin true olması gerekir. Değerler doğrulamadan önce beklenen türe çevrildiği için ortam değişkeniyle verilen sayılar da doğru karşılaştırılır.

variable "PORT" {
  default = 3000
  validation {
    condition = PORT >= 1024
    error_message = "The variable 'PORT' must be 1024 or greater."
  }
}

Bake'in kendi interpolasyonunu atlamak, örneğin satır içi bir Dockerfile'da kabuk değişkeni kullanmak için çift dolar işareti ($${TARGETARCH}) yazılır. Birden fazla dosya yüklediğinizde bir dosya diğerinde tanımlanan değişkeni kullanabilir; belgelerdeki örnekte vars.hcl içindeki BASE_IMAGE değişkeni docker-bake.hcl içinde kullanılır.

Kalıtım: inherits

Hedefler inherits özelliğiyle başka hedeflerin özelliklerini devralır ve istediklerini ezer. Yaygın kalıp, ortak ayarları alt çizgiyle başlayan bir _common hedefinde toplayıp diğer hedeflerde miras almaktır:

target "_common" {
  args = {
    BUILDKIT_CONTEXT_KEEP_GIT_DIR = 1
  }
}

target "app-dev" {
  inherits = ["_common"]
  tags = ["docker.io/username/myapp:dev"]
}

target "app-release" {
  inherits = ["app-dev"]
  tags = ["docker.io/username/myapp:latest"]
  platforms = ["linux/amd64", "linux/arm64"]
}

inherits bir listedir, birden fazla hedeften miras alınabilir. Çakışma olduğunda belgelere göre listede en sonda yer alan hedef kazanır. Örneğin inherits = ["app-dev", "_common"] yazarsanız ikisinde de tanımlı bir argümanın değeri _common'dan gelir. Bütün hedef yerine tek bir özelliği almak için nokta gösterimi kullanılır: tags = target.foo.tags. Çok platformlu yayın ayarlarını app-release gibi bir hedefte toplamanın arka planı multi-platform build yazısında.

Matrix hedefleri

Matrix, tek bir hedefi verdiğiniz parametrelere göre birden fazla varyanta çatallar. matrix özelliği parametre adlarını değer listelerine eşler ve Bake her kombinasyonu ayrı bir hedef olarak derler. Üretilen her hedefin benzersiz bir adı olmalıdır; adın nasıl oluşacağını name özelliği belirler. Belgelerdeki sürüm ve hata ayıklama varyantı örneği:

target "app" {
  name = "app-${mode}"
  matrix = {
    mode = ["release", "debug"]
  }
  args = {
    BUILD_MODE = mode
  }
  tags = ["docker.io/username/app:${mode}"]
}

Bu tanım app-release ve app-debug hedeflerini üretir ve her birine kendi etiketini verir. Matrix'te birden fazla anahtar kullanırsanız Bake her olası kombinasyonu derler; iki hedef stage'i ve iki sürüm dört hedef demektir. Değerler tek tek değil de birlikte değişecekse matrix değeri olarak map listesi verilir ve iç değerlere nokta gösterimiyle erişilir. Belgelerin bir uyarısı da dosya çıktılarıyla ilgilidir: her varyanta ayrı bir çıktı klasörü verin, yoksa varyantlar birbirinin dosyalarının üzerine yazar.

Komut satırından ezme: --set

Bir hedef özelliğini dosyayı değiştirmeden tek bir çağrı için değiştirmek istediğinizde --set kullanılır. Belgelerdeki örnek bir build argümanını ve platformu ezer:

docker buildx bake --set app.arg.mybuildarg=bar \
    --set app.platform=linux/arm64 app --print

Ezme anahtarları arg, secret, tag gibi tekil adlar kullanır; dosyadaki özellikler ise args, tags gibi adlarını korur. --set tekrarlanabilir bir bayraktır. Dizi alanlarında += değiştirmeden ekleme yapar, --set app.tag= gibi boş atama diziyi temizler; [a,b] biçimindeki dizi söz dizimi desteklenmez. Desenle birden fazla hedefi aynı anda ezebilirsiniz; burada da tırnak kullanın:

docker buildx bake --set '*.platform=linux/arm64'
docker buildx bake --set app.secret.aws=env=AWS_CREDENTIALS app

İkinci komut, hedefte zaten tanımlı aws secret'ının yalnızca kaynağını değiştirir, diğer secret'lara dokunmaz. Belgelere göre hedef aws secret'ını bildirmiyorsa bu ezme başarısız olur. --var ile --set arasındaki fark da önemlidir: --var değişkeni tanımın kullanıldığı her yerde değiştirir, --set ise belirli bir hedef özelliğini hedefler. Build secret'larının kendisi build secrets yazısında.

Dosya arama sırası

-f ile dosya vermezseniz Bake şu sırayla dosya arar: compose.yaml, compose.yml, docker-compose.yml, docker-compose.yaml, docker-bake.json, docker-bake.hcl, docker-bake.override.json, docker-bake.override.hcl. Birden fazla dosya bulunursa hepsi bu sırayla yüklenip tek tanımda birleştirilir. Aynı özellik birden fazla dosyada tanımlıysa özelliğe göre birleştirilir ya da son yüklenenin değeri geçerli olur. Bu yüzden docker-bake.override.hcl dosyası, sunucuya özgü bir değişken değerini ana dosyaya dokunmadan ezmek için uygun bir yerdir.

Compose dosyasından Bake

Bake bir Compose dosyasını okuyup her servisi bir hedefe çevirir. Compose belirtiminde karşılığı olmayan alanlar için build altında x-bake uzantı alanı kullanılır. Belgelere göre x-bake içinde geçerli alanlar cache-from, cache-to, contexts, no-cache, no-cache-filter, output, platforms, pull, secret, ssh ve tags'tir. Aşağıdaki dosya Docker Compose v5.5.1 ile docker compose config doğrulamasından geçti; Compose x- ile başlayan alanı olduğu gibi korur:

services:
  app:
    image: registry.example.com/benim/app:latest
    build:
      context: ./app
      target: dev
      x-bake:
        platforms:
          - linux/amd64
          - linux/arm64
        cache-from:
          - type=registry,ref=registry.example.com/benim/app:buildcache
        cache-to:
          - type=registry,ref=registry.example.com/benim/app:buildcache,mode=max
  seed:
    build:
      context: ./seed

Belgeler Compose biçiminin HCL'e göre sınırlarını da sayar: değişken ve global kapsamlı özellik tanımlanamaz, inherits desteklenmez. Ortak ayarları paylaşmak için YAML anchor'ları kullanılabilir. Bake, komutun çalıştırıldığı klasördeki .env dosyasını da okuyup Compose tanımlarına uygular; sistem ortam değişkenleri .env dosyasındaki değerlerden önce gelir.

Compose ile geliştirme, HCL ile sürüm

Belgelerin önerdiği bir düzen, geliştirme ayarlarını Compose'da tutup sürüm derleme ayarlarını yanına koyduğunuz bir docker-bake.hcl dosyasında katmanlamaktır. Bake iki dosyayı otomatik yükleyip birleştirir:

group "default" {
  targets = ["app"]
}

target "_release" {
  platforms = ["linux/amd64", "linux/arm64"]
  attest = ["type=provenance,mode=max", "type=sbom"]
}

target "app" {
  inherits = ["_release"]
  target = "release"
}

Bu birleşimde app hedefi context'ini ve imaj etiketini Compose'dan alır, Dockerfile stage'ini dev yerine release yapar ve ortak platform ile attestation ayarlarını miras alır; Dockerfile'ın iki stage'i de tanımlaması gerekir. HCL dosyası default grubunun hedef listesini değiştirdiği için argümansız docker buildx bake yalnızca app'i derler; seed hedefi tanımda kalır ve docker buildx bake seed ile derlenebilir. Sonucu derlemeden görmek için docker buildx bake --print kullanın.

docker compose build ile Bake

Compose da derlemeleri Bake'e devredebilir. Belgelere göre COMPOSE_BAKE=true ortam değişkeniyle çalıştırıldığında Compose tüm servislerin derleme tanımını Bake'e verir ve yürütmeyi en verimli biçimde düzenlemesini sağlar. Bunu kalıcı yapmak için $HOME/.docker/config.json dosyasında plugins.compose.build değerini bake yapabilirsiniz. Compose'un genel kullanımı Docker Compose rehberinde.

COMPOSE_BAKE=true docker compose build

Bake ile build check

Dockerfile kontrollerini Bake üzerinden çalıştırmak için asıl hedefi miras alan ve call = "check" belirten ayrı bir hedef tanımlanır. Böylece kontroller gerçek derlemeyle aynı argümanlarla çalışır. Ayrıntılar build check yazısında.

Sık yapılan hatalar

• Joker karakterli hedefleri tırnaksız yazmak: kabuk deseni dosya adlarıyla genişletir.
• Ortam değişkeninin her özelliği ezeceğini sanmak: yalnızca variable bloklarına ortam değişkeniyle değer verilebilir; hedef özellikleri için --set gerekir.
• inherits sırasını ters düşünmek: çakışmada listenin sonundaki hedef kazanır.
• Matrix varyantlarına aynı çıktı klasörünü vermek: dosyalar birbirinin üzerine yazılır.
• Compose ve HCL dosyası birlikteyken default grubunu unutmak: HCL'deki default grubu Compose'dan gelen listeyi değiştirir; --print ile kontrol edin.

Sık Sorulan Sorular

Bake için ayrı bir araç kurmam gerekir mi?

Hayır. Belgelere göre Bake, Buildx CLI'ına yerleşik bir komuttur; Buildx kuruluysa docker buildx bake de kullanılabilir.

HCL mi, JSON mu, Compose mu?

Üçü de desteklenir. Belgeler HCL'i en ifade gücü yüksek ve esnek biçim olarak tanımlar ve örneklerin çoğunu HCL ile verir. Compose biçimi değişken ve inherits desteklemez; bu özelliklere ihtiyacınız varsa Compose'un yanına bir HCL dosyası ekleyebilirsiniz.

Derlemeden sonucu görebilir miyim?

docker buildx bake --print derleme yapmadan çözümlenmiş yapılandırmayı JSON olarak yazdırır. Değişkenlerin, kalıtımın ve dosya birleştirmenin sonucunu doğrulamak için bunu kullanın.

Bake hedefleri aynı anda mı çalışır?

Evet; bir gruptaki ya da komuta verilen hedefler eşzamanlı derlenir. Belgelerdeki validate grubunda test ve lint birlikte çalışır ve biri başarısız olursa komut da başarısız olur.

Marka adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen kuruluşlarla bayilik veya ortaklık ilişkisi bulunduğu anlamına gelmez.

İlgili içerikler: Docker öğrenme rehberi · BuildKit ve Buildx · Multi-platform build · Build output ve exporter · Docker build check · Docker Compose rehberi