Docker Buildx Bake: Build Image Multi-Platform Deklaratif

Cukup lama build container saya hidup di dalam skrip shell: tumpukan perintah docker buildx build, masing-masing dengan flag --platform, --tag, --cache-from, dan --build-arg sendiri yang disalin-tempel dengan perbedaan kecil. Setiap image baru berarti satu blok yang hampir identik lagi, dan YAML CI perlahan menyimpang dari yang saya jalankan di laptop. docker buildx bake memperbaiki ini dengan memindahkan seluruh matriks build ke file HCL deklaratif yang dibaca dengan cara sama oleh mesin saya maupun GitHub Actions.

Bake bukan tool terpisah yang perlu diinstal; ia ikut di dalam Buildx sebagai subperintah bake. Anda mengarahkannya ke sebuah file definisi, menyebut target yang diinginkan, dan BuildKit membangunnya secara bersamaan, berbagi cache dan layer sebisa mungkin. Saya menjalankan file yang sama di VPS ber-Docker dan di CI, dan satu-satunya perbedaan adalah beberapa override yang dilewatkan lewat command line.

Anatomi sebuah file HCL bake

File bake punya tiga blok penyusun: variabel yang memparameterisasi konfigurasi, target yang mendeskripsikan satu build masing-masing, dan grup yang membundel target agar satu perintah membangun beberapa sekaligus. Nama file default-nya adalah docker-bake.hcl, dan bake mengambilnya otomatis. Fitur paling berguna adalah inherits: definisikan setelan bersama sekali di target dasar, lalu perluas, sehingga image baru cukup beberapa baris alih-alih salinan penuh.

# docker-bake.hcl
variable "REGISTRY" {
  default = "ghcr.io/matthewswongofficial"
}

variable "TAG" {
  default = "latest"
}

# Shared base — every real target inherits from this.
target "_common" {
  context    = "."
  dockerfile = "Dockerfile"
  platforms  = ["linux/amd64", "linux/arm64"]
  labels = {
    "org.opencontainers.image.source" = "https://github.com/MatthewsWongOfficial/app"
  }
}

target "api" {
  inherits = ["_common"]
  target   = "api"
  tags     = ["${REGISTRY}/api:${TAG}"]
}

target "worker" {
  inherits = ["_common"]
  target   = "worker"
  tags     = ["${REGISTRY}/worker:${TAG}"]
}

# A group ties targets together so one command builds both.
group "default" {
  targets = ["api", "worker"]
}

Dengan file itu di tempatnya, docker buildx bake tanpa argumen membangun grup default, yang membangun api dan worker sekaligus untuk amd64 dan arm64 secara paralel. Menyebut satu target hanya membangun target itu. Karena REGISTRY dan TAG adalah variabel, saya tidak pernah mengedit file untuk merilis; saya menimpanya saat pemanggilan.

# Build everything in the default group
docker buildx bake

# Build just one target
docker buildx bake api

# Print the fully-resolved config as JSON without building
docker buildx bake --print

# Override a variable and push instead of loading locally
TAG=v1.4.0 docker buildx bake --set "*.output=type=registry"

Matrix target: satu definisi, banyak varian

Matrix target adalah tempat bake membuktikan nilainya. Atribut matrix adalah map dari nama parameter ke daftar nilai, dan bake membangun setiap kombinasi sebagai target terpisah. Field name yang wajib mengatur bagaimana tiap target hasil dinamai lewat interpolasi variabel. Beginilah saya membangun service yang sama terhadap tiga versi Node, atau memecah satu stage Dockerfile menjadi varian debug dan produksi, tanpa mengulang satu blok pun.

target "test" {
  name = "test-node${nodeversion}"
  matrix = {
    nodeversion = ["18", "20", "22"]
  }
  args = {
    NODE_VERSION = nodeversion
  }
  target = "test"
}

# Multi-axis: 2 x 2 = 4 targets
target "image" {
  name = "${svc}-${flavor}"
  matrix = {
    svc    = ["api", "worker"]
    flavor = ["debug", "release"]
  }
  target = flavor
  tags   = ["ghcr.io/matthewswongofficial/${svc}:${flavor}"]
}

Blok pertama mengembang menjadi test-node18, test-node20, dan test-node22. Blok kedua adalah matriks dua sumbu yang menghasilkan empat target mencakup setiap kombinasi service dan flavour. Satu kali jalan docker buildx bake membangun semuanya secara paralel, dan BuildKit menghapus duplikasi layer bersama di antaranya secara otomatis.

Caching yang benar-benar dipakai ulang

Cache diatur per target dengan cache-from dan cache-to, dan backend yang Anda pilih sangat menentukan di CI. Di VPS saya backend registry lokal sudah memadai, tetapi runner GitHub bersifat sementara, jadi saya memakai backend cache GitHub Actions (type=gha). Satu aturan yang paling menyelamatkan: beri setiap varian matrix scope cache sendiri. Jika dua varian berbagi scope, keduanya saling menimpa dan setiap build tampak seperti cache dingin.

# In the bake file — reference-type gha cache, scoped per target name.
target "_common" {
  # ...
  cache-from = ["type=gha,scope=build-${target}"]
  cache-to   = ["type=gha,scope=build-${target},mode=max"]
}

# Or override entirely from the CLI / CI:
docker buildx bake \
  --set "*.cache-from=type=gha,scope=api" \
  --set "*.cache-to=type=gha,scope=api,mode=max"

Menyambungkan bake ke GitHub Actions

Action resmi docker/bake-action membungkus perintah bake untuk CI. Per pertengahan 2026 ia berada di v7, dan sejak v6 ia membangun dari konteks Git secara default, artinya BuildKit meng-checkout repo sendiri dan Anda bisa melewati actions/checkout untuk build murni. Input push: true adalah singkatan untuk mengatur output setiap target ke registry. Berikut workflow minimal yang saya pakai untuk membangun dan mendorong image multi-platform pada setiap push.

# .github/workflows/build.yml
name: build
on:
  push:
    branches: [main]

jobs:
  bake:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4
      - uses: docker/setup-qemu-action@v3   # arm64 emulation
      - uses: docker/setup-buildx-action@v4
      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - uses: docker/bake-action@v7
        with:
          files: docker-bake.hcl
          targets: default
          push: true
        env:
          TAG: ${{ github.sha }}

Untuk matriks besar ada pola yang lebih tajam: pakai docker buildx bake --print yang disalurkan lewat jq di satu job untuk memancarkan daftar nama target, umpankan itu ke strategi matrix GitHub Actions, dan jalankan tiap target di job paralelnya sendiri. Itu memberi tiap target runner terisolasi dan, yang penting, scope cache sendiri, sehingga build arm64 yang lambat tak pernah menghambat yang amd64. Saya tetap memakai setup-qemu-action di workflow karena layer arm64 di-cross-compile lewat emulasi pada runner amd64 kecuali Anda memasang builder arm64 native.

Kapan bake sepadan, dan kapan tidak

Patokan saya: begitu saya menyadari sedang menyalin-tempel perintah docker build dengan sedikit ubahan, saya memindahkannya ke sebuah target bake. File deklaratif menjadi satu sumber kebenaran, keluaran --print mendokumentasikan dirinya sendiri, dan CI berhenti menjadi tempat logika build diam-diam melenceng dari yang saya jalankan manual. Itu saja sudah menangkap lebih banyak rilis rusak ketimbang tes apa pun yang bisa saya tulis di sekitar skrip shell yang digantikannya.