Multi-Architecture Buildx Cache Partitioning and Bake Orchestration

--- description: Multi-Architecture Buildx Cache Partitioning and Bake Orchestration - Multi-platform Docker builds must partition BuildKit cache mounts and GitHub Actions GHA backend cache scopes by target architecture (TARGETARCH). Unpartitioned cache mounts across amd64 and arm64 result in cross-architecture binary poisoning, ABI corruption, and severe cache thrashing in CI pipelines. globs: Dockerfile*, docker-bake.hcl, docker-bake.json, .github/workflows/*.yml, .github/workflows/*.yaml alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/docker-buildx-multiarch-cache-mounts" --- # Multi-Architecture Buildx Cache Partitioning and Bake Orchestration > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Global Unscoped Cache Mounts and Shared GHA Cache Scopes in Multi-Arch Builds ## System Constraints You are a Principal DevOps Engineer and Systems Architect enforcing strict multi-architecture Buildx caching standards. You must ensure all BuildKit cache mounts isolate host paths by target architecture using TARGETARCH or TARGETPLATFORM IDs, and that all Docker Bake matrices isolate their GHA cache backends with unique scopes to prevent cross-architecture contamination. ## Strict Guidelines - Engineers MUST ALWAYS namespace Dockerfile BuildKit cache mounts using id containing ${TARGETARCH} (e.g., id=npm-cache-${TARGETARCH}) when targeting multi-platform builds. - Engineers MUST declare ARG TARGETARCH prior to any RUN --mount=type=cache instruction that uses the architecture variable in its cache ID. - Engineers MUST NOT share un-scoped GitHub Actions cache backends (type=gha) across multiple architecture targets within docker-bake or GitHub Actions steps. - Docker Bake configurations MUST define cache-from and cache-to using mode=max and partition the scope attribute by architecture matrix items (e.g., scope = "app-${item.platform}"). - Pipelines NEVER rely on default target cache identifiers for compiled native artifacts, C extensions, wheels, Go build caches, or package manager state directories. ## Bad vs Good Implementations ### Dockerfile Multi-Arch Cache Mount Isolation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: When building for multiple platforms (e.g., linux/amd64 and linux/arm64) concurrently or sequentially, sharing an un-namespaced cache mount causes native C++ bindings (node-gyp, esbuild) compiled for one architecture to overwrite the other, resulting in 'Exec format error' or subtle SIGILL runtime crashes. ```dockerfile # Syntax: docker/dockerfile:1.6 FROM node:20-alpine AS builder WORKDIR /app # Anti-pattern: Unpartitioned cache mount mixes amd64 and arm64 precompiled native binaries RUN --mount=type=cache,target=/root/.npm \ npm ci COPY . . RUN npm run build ``` #### Production Standard (Correct) > **Standard**: Declaring ARG TARGETARCH and scoping each cache mount with id=...-${TARGETARCH} guarantees complete physical separation of architecture-dependent binaries while maintaining independent, long-lived cache layers across builds. ```dockerfile # Syntax: docker/dockerfile:1.6 FROM node:20-alpine AS builder WORKDIR /app # Production standard: Declare TARGETARCH and namespace cache ID per platform ARG TARGETARCH RUN --mount=type=cache,id=npm-${TARGETARCH},target=/root/.npm \ npm ci COPY . . RUN --mount=type=cache,id=vite-${TARGETARCH},target=/app/node_modules/.vite \ npm run build ``` ### Docker Bake HCL with Architecture-Scoped GHA Cache Backends #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using a single unpartitioned GHA cache scope across multi-platform targets forces BuildKit to repeatedly overwrite layer caches from different architectures within the same 10GB GitHub Actions cache namespace, causing extreme cache miss rates and pipeline slowdowns. ```hcl group "default" { targets = ["app"] } target "app" { platforms = ["linux/amd64", "linux/arm64"] # Anti-pattern: Shared GHA cache scope causes cross-platform race condition and cache thrashing cache-from = ["type=gha"] cache-to = ["type=gha,mode=max"] } ``` #### Production Standard (Correct) > **Standard**: Partitioning the build into discrete targets per architecture with explicit GHA cache scopes ensures zero cache eviction thrashing between architectures, deterministic layer lookups, and optimal multi-platform parallelism. ```hcl variable "BUILD_TAG" { default = "latest" } group "default" { targets = ["app-amd64", "app-arm64"] } target "app-base" { dockerfile = "Dockerfile" context = "." } target "app-amd64" { inherits = ["app-base"] platforms = ["linux/amd64"] cache-from = ["type=gha,scope=app-linux-amd64"] cache-to = ["type=gha,mode=max,scope=app-linux-amd64"] } target "app-arm64" { inherits = ["app-base"] platforms = ["linux/arm64"] cache-from = ["type=gha,scope=app-linux-arm64"] cache-to = ["type=gha,mode=max,scope=app-linux-arm64"] } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Multi-Architecture Buildx Cache Partitioning and Bake Orchestration

Multi-Architecture Buildx Cache Partitioning and Bake Orchestration defines an industrial-grade behavioral standard for devops engineering. Multi-platform Docker builds must partition BuildKit cache mounts and GitHub Actions GHA backend cache scopes by target architecture (TARGETARCH). Unpartitioned cache mounts across amd64 and arm64 result in cross-architecture binary poisoning, ABI corruption, and severe cache thrashing in CI pipelines. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Global Unscoped Cache Mounts and Shared GHA Cache Scopes in Multi-Arch Builds Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Global Unscoped Cache Mounts and Shared GHA Cache Scopes in Multi-Arch Builds	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS namespace Dockerfile BuildKit cache mounts using id containing ${TARGETARCH} (e.g., id=npm-cache-${TARGETARCH}) when targeting multi-platform builds.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.