Docker Bake and Buildx: Declarative Multi-Platform Builds Without the Pain

Every team that manages more than a handful of Docker images confronts the same wall: a sprawling Makefile that tries to coordinate building, tagging, and pushing multiple images across multiple platforms. The script grows from 50 lines to 500. Cache configuration is copy-pasted across CI pipelines. At this point, the build script has become the bottleneck — not the build itself.

Docker Bake solves this by moving build configuration from imperative scripts into a declarative file. Instead of nested for-loops over platforms and images, you define targets with their context, Dockerfile, platforms, and cache settings. Bake handles the DAG of dependencies — building base images before services that depend on them — and parallelizes independent targets automatically.

Bake is one part of the docker buildx ecosystem. Buildx itself brings multi-platform builds, managed cloud builders (Docker Build Cloud for native ARM and AMD runners), remote builds (SSH to a more powerful machine), and advanced cache configuration.

Writing Your First docker-bake.hcl File

Docker Bake supports three file formats: HCL (HashiCorp Configuration Language, recommended for complex configs), JSON (for programmatic generation), and docker-compose YAML (for simple setups). The HCL format is the most powerful — it supports variables, functions, inheritance, and dynamic target generation.

A bake file defines one or more 'target' blocks. Each target specifies: a name, context, dockerfile, platforms, tags, cache-from/cache-to, and args.

Variables and functions in HCL make bake files DRY. Define common values (like image_registry, platforms, cache_ref) at the top and reference them across targets.

# docker-bake.hcl — Declarative build configuration
variable "IMAGE_REGISTRY" {
  default = "registry.example.com"
}
variable "SHA" {
  default = "latest"
}
variable "PLATFORMS" {
  default = ["linux/amd64", "linux/arm64"]
}

function "cache_config" {
  params = ["ref"]
  result = {
    cache-from = ["type=registry,ref=${ref}:cache"]
    cache-to   = ["type=registry,ref=${ref}:cache,mode=max"]
  }
}

target "api" {
  context    = "./services/api"
  dockerfile = "Dockerfile"
  tags = [
    "${var.IMAGE_REGISTRY}/api:${var.SHA}",
    "${var.IMAGE_REGISTRY}/api:latest"
  ]
  platforms = var.PLATFORMS
  cache-from = cache_config("${var.IMAGE_REGISTRY}/api").cache-from
  cache-to   = cache_config("${var.IMAGE_REGISTRY}/api").cache-to
}

target "worker" {
  context    = "./services/worker"
  dockerfile = "Dockerfile"
  tags = [
    "${var.IMAGE_REGISTRY}/worker:${var.SHA}",
    "${var.IMAGE_REGISTRY}/worker:latest"
  ]
  platforms    = var.PLATFORMS
  cache-from   = cache_config("${var.IMAGE_REGISTRY}/worker").cache-from
  cache-to     = cache_config("${var.IMAGE_REGISTRY}/worker").cache-to
}

group "default" {
  targets = ["api", "worker"]
}

Multi-Platform Builds with BUILDPLATFORM and TARGETPLATFORM

Building Docker images for multiple CPU architectures (amd64, arm64, arm/v7) is required for mixed-architecture Kubernetes clusters. Buildx supports two approaches: emulation (QEMU) and cross-compilation. QEMU emulates the target architecture — it works for any Dockerfile but is slow for compiled languages. Cross-compilation runs the build natively and produces a binary for the target architecture — it's fast but requires platform-aware Dockerfiles.

The key is BUILDPLATFORM and TARGETPLATFORM ARGs, automatically provided by BuildKit when using docker buildx build --platform. These ARGs are only available with Buildx, not legacy docker build.

In the Dockerfile, use ARG TARGETPLATFORM and ARG BUILDPLATFORM to set platform-specific build variables.

# syntax=docker/dockerfile:1
FROM golang:1.22-alpine AS builder

ARG TARGETPLATFORM
ARG BUILDPLATFORM

RUN echo "Building for $TARGETPLATFORM on $BUILDPLATFORM"

WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .

RUN GOOS=$(echo ${TARGETPLATFORM} | cut -d/ -f1) && \
    GOARCH=$(echo ${TARGETPLATFORM} | cut -d/ -f2) && \
    CGO_ENABLED=0 go build -ldflags="-s -w" -o /app/server ./cmd/server

FROM alpine:3.19
RUN apk add --no-cache ca-certificates
COPY --from=builder /app/server /server
ENTRYPOINT ["/server"]

Cache Configuration: Registry, GHA, and Inline Cache

Cache configuration is the single biggest lever for CI build speed. Buildx supports four cache backends: registry (store cache alongside the image in the registry), gha (GitHub Actions cache), inline (embed cache into the image), and local (local filesystem cache).

type=registry,mode=max is the recommended default for production CI. It pushes build cache layers to the registry as a separate cache image. The mode=max option caches all layers, not just those exported to the final image.

type=gha uses the built-in GHA cache service — faster than registry cache but limited to 10 GB per repository. Ideal for open-source projects.

type=inline embeds cache into the image manifest. Only caches final image layers — use only when registry or GHA cache is unavailable.

# Registry cache (recommended for production)
docker buildx build \
  --cache-from type=registry,ref=myapp:cache \
  --cache-to type=registry,ref=myapp:cache,mode=max \
  -t myapp:latest --push .

# GitHub Actions cache (for GHA runners)
docker buildx build \
  --cache-from type=gha \
  --cache-to type=gha,mode=max \
  -t myapp:latest --push .

# Inline cache (fallback, no separate storage)
docker buildx build \
  --cache-from type=registry,ref=myapp:latest \
  --cache-to type=inline \
  -t myapp:latest --push .

# In bake.hcl
target "myapp" {
  cache-from = ["type=registry,ref=myapp:cache"]
  cache-to   = ["type=registry,ref=myapp:cache,mode=max"]
}

Matrix Builds: Building Multiple Targets Across Multiple Platforms

Docker Bake supports dynamic target generation using for_each (HCL). This is useful when you have multiple services that follow the same build pattern — define the pattern once, and Bake generates a target for each service × platform combination.

In HCL, use a locals block to define the services, then a target block with for_each to generate targets dynamically. Each target gets its context, tags, and platforms from the local variables.

This pattern eliminates duplication entirely: adding a new service is a one-line addition to the services list.

# docker-bake-matrix.hcl
# Matrix build: generate targets for multiple services

variable "IMAGE_REGISTRY" {
  default = "registry.example.com"
}
variable "SHA" {
  default = "latest"
}

locals {
  services = {
    api   = { path = "./services/api",   port = 8080 }
    web   = { path = "./services/web",   port = 3000 }
    queue = { path = "./services/queue", port = 5000 }
  }
  platforms = ["linux/amd64", "linux/arm64"]
}

target "default" {
  for_each = local.services
  name     = each.key
  context  = each.value.path
  tags = [
    "${var.IMAGE_REGISTRY}/${each.key}:${var.SHA}",
    "${var.IMAGE_REGISTRY}/${each.key}:latest"
  ]
  platforms   = local.platforms
  cache-from  = ["type=registry,ref=${var.IMAGE_REGISTRY}/${each.key}:cache"]
  cache-to    = ["type=registry,ref=${var.IMAGE_REGISTRY}/${each.key}:cache,mode=max"]
}

Docker Build Cloud and Remote Builders

Docker Build Cloud is Docker's managed build service that provides native AMD64 and ARM64 build infrastructure. It solves two problems: (1) local machines that can't build for all target platforms, and (2) CI runners with limited resources.

Build Cloud provides cloud-hosted builders with native architecture support. When you run docker buildx build --platform linux/amd64,linux/arm64 --builder cloud-<name>, Build Cloud splits the build across native AMD64 and ARM64 machines. No emulation needed.

Beyond Build Cloud, Buildx supports connecting to any Docker host as a remote builder via SSH: docker buildx create --name remote --driver docker-container ssh://user@host.

# Set up Docker Build Cloud
docker buildx create --driver cloud myorg/mybuilder

# Use the cloud builder for multi-platform build
docker buildx build \
  --builder cloud-myorg-mybuilder \
  --platform linux/amd64,linux/arm64 \
  -t myapp:latest --push .

# Set cloud builder as default
export BUILDX_BUILDER=cloud-myorg-mybuilder

# Or use in bake (add builder field)
target "myapp" {
  builder = "cloud-myorg-mybuilder"
}

# Remote builder via SSH
docker buildx create \
  --name remote-builder \
  --driver docker-container \
  ssh://user@build-server.example.com

# Use remote builder
docker buildx build --builder remote-builder -t myapp:latest --push .