docs: align Build Cloud with standard Buildx

content/manuals/build-cloud/builder-settings.md

@@ -56,6 +56,14 @@ To get more Build cache space, [upgrade your subscription](/manuals/subscription
 
 ## Private resource access
 
+> [!IMPORTANT]
+>
+> Private resource access requires the private Buildx client. The `cloud`
+> driver in standard Buildx doesn't support this feature. If your cloud builder
+> uses private resource access, continue using the
+> [latest private Buildx release](https://github.com/docker/buildx-desktop/releases/latest)
+> until the feature is supported in standard Buildx.
+
 Private resource access lets cloud builders pull images and packages from private resources. This feature is useful when builds rely on self-hosted artifact repositories or private OCI registries.
 
 For example, if your organization hosts a private [PyPI](https://pypi.org/) repository on a private network, Docker Build Cloud would not be able to access it by default, since the cloud builder is not connected to your private network.

content/manuals/build-cloud/ci.md

@@ -23,9 +23,10 @@ registry directly, rather than loading the image and then pushing it. Pushing
 directly speeds up your builds and avoids unnecessary file transfers.
 
 If you just want to build and discard the output, export the results to the
-build cache or build without tagging the image. When you use Docker Build Cloud,
-Buildx automatically loads the build result if you build a tagged image.
-See [Loading build results](./usage/#loading-build-results) for details.
+build cache or build without tagging the image. With no explicit output, Buildx
+leaves an untagged result in the cloud build cache and automatically loads
+eligible tagged images. See
+[Loading build results](./usage/#loading-build-results) for details.
 
 > [!NOTE]
 >
@@ -67,6 +68,21 @@ If you are not an organization administrator:
 
 ## CI platform examples
 
+> [!IMPORTANT]
+>
+> These examples require Buildx version 0.37.0 or later, which includes the
+> `cloud` driver. The Docker CLI version doesn't determine the installed Buildx
+> plugin version, and CI runner images may include an earlier Buildx release.
+>
+> Check the installed version:
+>
+> ```console
+> $ docker buildx version
+> ```
+>
+> If the version is earlier than 0.37.0, install Buildx as a
+> [Docker CLI plugin](https://github.com/docker/buildx#manual-download).
+
 > [!NOTE]
 >
 > In your CI/CD configuration, set the following variables/secrets:
@@ -78,6 +94,8 @@ If you are not an organization administrator:
 
 ### GitHub Actions
 
+<!-- TODO: Confirm whether standard Buildx requires a minimum setup-buildx-action version. -->
+
 ```yaml
 name: ci
 
@@ -140,19 +158,12 @@ For more information about the `BUILDX_BUILDER` environment variable, see
 
 ```yaml
 default:
-  image: docker:24-dind
+  image: docker:cli
   services:
-    - docker:24-dind
+    - docker:dind
   before_script:
     - docker info
     - echo "$DOCKER_ACCESS_TOKEN" | docker login --username "$DOCKER_ACCOUNT" --password-stdin
-    - |
-      apk add curl jq
-      ARCH=${CI_RUNNER_EXECUTABLE_ARCH#*/}
-      BUILDX_URL=$(curl -s https://raw.githubusercontent.com/docker/actions-toolkit/main/.github/buildx-lab-releases.json | jq -r ".latest.assets[] | select(endswith(\"linux-$ARCH\"))")
-      mkdir -vp ~/.docker/cli-plugins/
-      curl --silent -L --output ~/.docker/cli-plugins/docker-buildx $BUILDX_URL
-      chmod a+x ~/.docker/cli-plugins/docker-buildx
     - docker buildx create --use --driver cloud ${DOCKER_ACCOUNT}/${CLOUD_BUILDER_NAME}
 
 variables:
@@ -195,13 +206,6 @@ jobs:
     steps:
       - checkout
 
-      - run: |
-          mkdir -vp ~/.docker/cli-plugins/
-          ARCH=amd64
-          BUILDX_URL=$(curl -s https://raw.githubusercontent.com/docker/actions-toolkit/main/.github/buildx-lab-releases.json | jq -r ".latest.assets[] | select(endswith(\"linux-$ARCH\"))")
-          curl --silent -L --output ~/.docker/cli-plugins/docker-buildx $BUILDX_URL
-          chmod a+x ~/.docker/cli-plugins/docker-buildx
-
       - run: echo "$DOCKER_ACCESS_TOKEN" | docker login --username $DOCKER_ACCOUNT --password-stdin
       - run: docker buildx create --use --driver cloud "${DOCKER_ACCOUNT}/${CLOUD_BUILDER_NAME}"
 
@@ -218,13 +222,6 @@ jobs:
     steps:
       - checkout
 
-      - run: |
-          mkdir -vp ~/.docker/cli-plugins/
-          ARCH=amd64
-          BUILDX_URL=$(curl -s https://raw.githubusercontent.com/docker/actions-toolkit/main/.github/buildx-lab-releases.json | jq -r ".latest.assets[] | select(endswith(\"linux-$ARCH\"))")
-          curl --silent -L --output ~/.docker/cli-plugins/docker-buildx $BUILDX_URL
-          chmod a+x ~/.docker/cli-plugins/docker-buildx
-
       - run: echo "$DOCKER_ACCESS_TOKEN" | docker login --username $DOCKER_ACCOUNT --password-stdin
       - run: docker buildx create --use --driver cloud "${DOCKER_ACCOUNT}/${CLOUD_BUILDER_NAME}"
 
@@ -281,28 +278,6 @@ steps:
 Create the `build.sh` script:
 
 ```bash
-DOCKER_DIR=/usr/libexec/docker
-
-# Get download link for latest buildx binary.
-# Set $ARCH to the CPU architecture (e.g. amd64, arm64)
-UNAME_ARCH=`uname -m`
-case $UNAME_ARCH in
-  aarch64)
-    ARCH="arm64";
-    ;;
-  amd64)
-    ARCH="amd64";
-    ;;
-  *)
-    ARCH="amd64";
-    ;;
-esac
-BUILDX_URL=$(curl -s https://raw.githubusercontent.com/docker/actions-toolkit/main/.github/buildx-lab-releases.json | jq -r ".latest.assets[] | select(endswith(\"linux-$ARCH\"))")
-
-# Download docker buildx with Build Cloud support
-curl --silent -L --output $DOCKER_DIR/cli-plugins/docker-buildx $BUILDX_URL
-chmod a+x ~/.docker/cli-plugins/docker-buildx
-
 # Connect to your builder and set it as the default builder
 docker buildx create --use --driver cloud "${DOCKER_ACCOUNT}/${CLOUD_BUILDER_NAME}"
 
@@ -328,7 +303,6 @@ pipeline {
   agent any
 
   environment {
-    ARCH = 'amd64'
     DOCKER_ACCESS_TOKEN = credentials('docker-access-token')
     DOCKER_ACCOUNT = credentials('docker-account')
     CLOUD_BUILDER_NAME = '<CLOUD_BUILDER_NAME>'
@@ -337,13 +311,7 @@ pipeline {
 
   stages {
     stage('Build') {
-      environment {
-        BUILDX_URL = sh (returnStdout: true, script: 'curl -s https://raw.githubusercontent.com/docker/actions-toolkit/main/.github/buildx-lab-releases.json | jq -r ".latest.assets[] | select(endswith(\\"linux-$ARCH\\"))"').trim()
-      }
       steps {
-        sh 'mkdir -vp ~/.docker/cli-plugins/'
-        sh 'curl --silent -L --output ~/.docker/cli-plugins/docker-buildx $BUILDX_URL'
-        sh 'chmod a+x ~/.docker/cli-plugins/docker-buildx'
         sh 'echo "$DOCKER_ACCESS_TOKEN" | docker login --username $DOCKER_ACCOUNT --password-stdin'
         sh 'docker buildx create --use --driver cloud "${DOCKER_ACCOUNT}/${CLOUD_BUILDER_NAME}"'
         // Cache-only build
@@ -372,12 +340,7 @@ env:
 before_install: |
   echo "$DOCKER_ACCESS_TOKEN" | docker login --username "$DOCKER_ACCOUNT" --password-stdin
 
-install: |
-  set -e 
-  BUILDX_URL=$(curl -s https://raw.githubusercontent.com/docker/actions-toolkit/main/.github/buildx-lab-releases.json | jq -r ".latest.assets[] | select(endswith(\"linux-$TRAVIS_CPU_ARCH\"))")
-  mkdir -vp ~/.docker/cli-plugins/
-  curl --silent -L --output ~/.docker/cli-plugins/docker-buildx $BUILDX_URL
-  chmod a+x ~/.docker/cli-plugins/docker-buildx
+before_script: |
   docker buildx create --use --driver cloud "${DOCKER_ACCOUNT}/${CLOUD_BUILDER_NAME}"
 
 script: |
@@ -393,18 +356,13 @@ script: |
 # Prerequisites: $DOCKER_ACCOUNT, $CLOUD_BUILDER_NAME, $DOCKER_ACCESS_TOKEN setup as deployment variables
 # This pipeline assumes $BITBUCKET_REPO_SLUG as the image name
 
-image: atlassian/default-image:3
+image: docker:cli
 
 pipelines:
   default:
     - step:
         name: Build multi-platform image
         script:
-          - mkdir -vp ~/.docker/cli-plugins/
-          - ARCH=amd64
-          - BUILDX_URL=$(curl -s https://raw.githubusercontent.com/docker/actions-toolkit/main/.github/buildx-lab-releases.json | jq -r ".latest.assets[] | select(endswith(\"linux-$ARCH\"))")
-          - curl --silent -L --output ~/.docker/cli-plugins/docker-buildx $BUILDX_URL
-          - chmod a+x ~/.docker/cli-plugins/docker-buildx
           - echo "$DOCKER_ACCESS_TOKEN" | docker login --username $DOCKER_ACCOUNT --password-stdin
           - docker buildx create --use --driver cloud "${DOCKER_ACCOUNT}/${CLOUD_BUILDER_NAME}"
           - IMAGE_NAME=$BITBUCKET_REPO_SLUG
@@ -421,15 +379,6 @@ pipelines:
 ```bash
 #!/bin/bash
 
-# Get download link for latest buildx binary. Set $ARCH to the CPU architecture (e.g. amd64, arm64)
-ARCH=amd64
-BUILDX_URL=$(curl -s https://raw.githubusercontent.com/docker/actions-toolkit/main/.github/buildx-lab-releases.json | jq -r ".latest.assets[] | select(endswith(\"linux-$ARCH\"))")
-
-# Download docker buildx with Build Cloud support
-mkdir -vp ~/.docker/cli-plugins/
-curl --silent -L --output ~/.docker/cli-plugins/docker-buildx $BUILDX_URL
-chmod a+x ~/.docker/cli-plugins/docker-buildx
-
 # Login to Docker Hub with an access token. See https://docs.docker.com/build-cloud/ci/#creating-access-tokens
 echo "$DOCKER_ACCESS_TOKEN" | docker login --username $DOCKER_ACCOUNT --password-stdin
 
@@ -452,35 +401,18 @@ docker buildx build \
 
 ### Docker Compose
 
-Use this implementation if you want to use `docker compose build` with
-Docker Build Cloud in CI.
+This example requires Buildx version 0.37.0 or later. Set the cloud builder as
+the default builder before running `docker compose build` in CI:
 
 ```bash
 #!/bin/bash
 
-# Get download link for latest buildx binary. Set $ARCH to the CPU architecture (e.g. amd64, arm64)
-ARCH=amd64
-BUILDX_URL=$(curl -s https://raw.githubusercontent.com/docker/actions-toolkit/main/.github/buildx-lab-releases.json | jq -r ".latest.assets[] | select(endswith(\"linux-$ARCH\"))")
-COMPOSE_URL=$(curl -sL \
-  -H "Accept: application/vnd.github+json" \
-  -H "Authorization: Bearer <GITHUB_TOKEN>" \
-  -H "X-GitHub-Api-Version: 2022-11-28" \
-  https://api.github.com/repos/docker/compose-desktop/releases \
-  | jq "[ .[] | select(.prerelease==false and .draft==false) ] | .[0].assets.[] | select(.name | endswith(\"linux-${ARCH}\")) | .browser_download_url")
-
-# Download docker buildx with Build Cloud support
-mkdir -vp ~/.docker/cli-plugins/
-curl --silent -L --output ~/.docker/cli-plugins/docker-buildx $BUILDX_URL
-curl --silent -L --output ~/.docker/cli-plugins/docker-compose $COMPOSE_URL
-chmod a+x ~/.docker/cli-plugins/docker-buildx
-chmod a+x ~/.docker/cli-plugins/docker-compose
-
 # Login to Docker Hub with an access token. See https://docs.docker.com/build-cloud/ci/#creating-access-tokens
 echo "$DOCKER_ACCESS_TOKEN" | docker login --username $DOCKER_ACCOUNT --password-stdin
 
 # Connect to your builder and set it as the default builder
 docker buildx create --use --driver cloud "${DOCKER_ACCOUNT}/${CLOUD_BUILDER_NAME}"
 
-# Build the image build
+# Build the images
 docker compose build
 ```

content/manuals/build-cloud/setup.md

@@ -15,21 +15,24 @@ environment.
 
 To get started with Docker Build Cloud, you need to:
 
-- Download and install Docker Desktop version 4.26.0 or later.
+- Install Docker Desktop version 4.26.0 or later, or Buildx version 0.37.0 or
+  later.
 - Create a cloud builder on the [Docker Build Cloud Dashboard](https://app.docker.com/build/).
   - When you create the builder, choose a name for it (for example, `default`). You will use this name as `BUILDER_NAME` in the CLI steps below.
 
 ### Use Docker Build Cloud without Docker Desktop
 
-To use Docker Build Cloud without Docker Desktop, you must download and install
-a version of Buildx with support for Docker Build Cloud (the `cloud` driver).
-You can find compatible Buildx binaries on the releases page of
-[this repository](https://github.com/docker/buildx-desktop).
+Buildx version 0.37.0 or later includes the
+[`cloud` driver](/manuals/build/builders/drivers/cloud.md). To use Docker Build
+Cloud without Docker Desktop, check your installed version:
 
-If you plan on building with Docker Build Cloud using the `docker compose
-build` command, you also need a version of Docker Compose that supports Docker
-Build Cloud. You can find compatible Docker Compose binaries on the releases
-page of [this repository](https://github.com/docker/compose-desktop).
+```console
+$ docker buildx version
+```
+
+If your Docker CLI installation doesn't include a compatible Buildx version,
+[install Buildx](https://github.com/docker/buildx#manual-download) as a Docker
+CLI plugin.
 
 ## Steps
 

content/manuals/build-cloud/usage.md

@@ -46,8 +46,8 @@ builder for the `docker buildx build` command. The `docker build` command still
 uses the `default` builder, unless you specify the `--builder` flag explicitly.
 
 If you use build scripts, such as `make`, that use the `docker build` command,
-we recommend updating your build commands to `docker buildx build`. Alternatively,
-you can set the [`BUILDX_BUILDER` environment
+update your build commands to `docker buildx build`. Alternatively, you can set
+the [`BUILDX_BUILDER` environment
 variable](/manuals/build/building/variables.md#buildx_builder) to specify which
 builder `docker build` should use.
 
@@ -58,7 +58,7 @@ cloud builder as your selected builder, then run your build.
 
 > [!NOTE]
 >
-> Make sure you're using a supported version of Docker Compose, see
+> Make sure Buildx version 0.37.0 or later is installed. See
 > [Prerequisites](setup.md#prerequisites).
 
 ```console
@@ -72,13 +72,16 @@ variable](/manuals/build/building/variables.md#buildx_builder) to select the clo
 
 ## Loading build results
 
-Building with `--tag` loads the build result to the local image store
-automatically when the build finishes. To build without a tag and load the
-result, you must pass the `--load` flag.
+When you don't specify an output, Buildx leaves an untagged build result in the
+cloud build cache and doesn't load it into Docker Engine. If you use `--tag`,
+Buildx automatically loads the image when the build targets a single platform
+and runs on one cloud node. Use `--load` to request loading explicitly.
 
-Loading the build result for multi-platform images is not supported. Use the
-`docker buildx build --push` flag when building multi-platform images to push
-the output to a registry.
+The target Docker context determines which Docker Engine image store receives
+the result. For details about loading behavior and other output configurations,
+see [Load results from Docker Build Cloud](/manuals/build/exporters/_index.md#load-results-from-docker-build-cloud).
+
+To push a multi-platform image to a registry instead of loading it:
 
 ```console
 $ docker buildx build --builder cloud-<ORG>-<BUILDER_NAME> \
@@ -87,8 +90,8 @@ $ docker buildx build --builder cloud-<ORG>-<BUILDER_NAME> \
   --push .
 ```
 
-If you want to build with a tag, but you don't want to load the results to your
-local image store, you can export the build results to the build cache only:
+To keep a tagged result in the build cache instead of loading it into Docker
+Engine, use the `cacheonly` exporter:
 
 ```console
 $ docker buildx build --builder cloud-<ORG>-<BUILDER_NAME> \

content/manuals/build/_index.md

@@ -29,6 +29,10 @@ grid:
   description: Configure where and how you run your builds.
   icon: wrench-screwdriver
   link: /build/builders/drivers/
+- title: Docker Build Cloud
+  description: Run builds on managed cloud builders with a shared cache.
+  icon: /icons/logo-build-cloud.svg
+  link: /build-cloud/
 - title: Exporters
   description: Export any artifact you like, not just Docker images.
   icon: arrow-up-on-square