Uso de Docker Build Cloud en CI

Tabla de contenidos

El uso de Docker Build Cloud en CI puede acelerar tus pipelines de compilación, lo que se traduce en menos tiempo de espera y menos cambios de contexto. Controlas tus flujos de trabajo de CI de la forma habitual y delegas la ejecución de la compilación en Docker Build Cloud.

La compilación con Docker Build Cloud en CI implica los siguientes pasos:

Iniciar sesión en una cuenta de Docker.
Configurar Buildx y conectarse al builder.
Ejecutar la compilación.

Al utilizar Docker Build Cloud en CI, se recomienda subir el resultado directamente a un registro, en lugar de cargar la imagen de manera local y luego subirla. Subir la imagen directamente acelera las compilaciones y evita transferencias de archivos innecesarias.

Si solo deseas compilar y descartar el resultado, exporta los resultados a la caché de compilación o realiza la compilación sin etiquetar la imagen. Al utilizar Docker Build Cloud, Buildx carga automáticamente el resultado de la compilación si compilas una imagen etiquetada. Consulta Cargar resultados de compilación para obtener más detalles.

Note
Las compilaciones en Docker Build Cloud tienen un límite de tiempo de espera (timeout) de 90 minutos. Las compilaciones que se ejecuten durante más de 90 minutos se cancelarán automáticamente.

Configurar credenciales para CI/CD

Para permitir que tu sistema de CI/CD compile y suba imágenes utilizando Docker Build Cloud, proporciona tanto un token de acceso como un nombre de usuario. El tipo de token y el nombre de usuario utilizados dependen del tipo de cuenta y de los permisos.

Si eres administrador de la organización o tienes permiso para crear tokens de acceso de la organización (OAT), utiliza un OAT y establece DOCKER_ACCOUNT con el nombre de tu organización de Docker Hub.
Si no tienes permiso para crear OATs o utilizas una cuenta personal, utiliza un token de acceso personal (PAT) y establece DOCKER_ACCOUNT con tu nombre de usuario de Docker Hub.

Crear tokens de acceso

Para cuentas de organización

Si eres administrador de la organización:

Crea un token de acceso de la organización (OAT). El token debe tener estos permisos:
1. Alcance (scope) cloud-connect
2. Permiso Leer repositorios públicos (Read public repositories)
3. Acceso al repositorio (Repository access) con permiso Subir imagen (Image push) para el repositorio de destino:
  - Despliega el menú Repositorio (Repository).
  - Selecciona Añadir repositorio (Add repository) y elige el repositorio de destino.
  - Establece el permiso Subir imagen (Image push) para el repositorio.

Si no eres administrador de la organización:

Solicita al administrador de tu organización un token de acceso con los permisos enumerados anteriormente, o utiliza un token de acceso personal.

Para cuentas personales

Crea un token de acceso personal (PAT) con los siguientes permisos:
1. Acceso de Lectura y escritura (Read & write).
  - Nota: Compilar con Docker Build Cloud solo requiere acceso de lectura, pero necesitas acceso de escritura para subir imágenes a un repositorio de Docker Hub.

Ejemplos de plataformas de CI

Note
En la configuración de tu CI/CD, establece las siguientes variables/secretos:
DOCKER_ACCESS_TOKEN — tu token de acceso (PAT u OAT). Utiliza un secreto para almacenar el token.
DOCKER_ACCOUNT — el nombre de tu organización de Docker Hub (para OAT) o nombre de usuario (para PAT)
CLOUD_BUILDER_NAME — el nombre del builder en la nube que creaste en el Panel de control de Docker Build Cloud
Esto garantiza que las compilaciones se autentiquen correctamente con Docker Build Cloud.

GitHub Actions

name: ci

on:
  push:
    branches:
      - "main"

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Login to Docker Hub
        uses: docker/login-action@v4
        with:
          username: ${{ vars.DOCKER_ACCOUNT }}
          password: ${{ secrets.DOCKER_ACCESS_TOKEN }}

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4
        with:
          driver: cloud
          endpoint: "${{ vars.DOCKER_ACCOUNT }}/${{ vars.CLOUD_BUILDER_NAME }}" # por ejemplo, "acme/default"

      - name: Build and push
        uses: docker/build-push-action@v7
        with:
          tags: "<IMAGE>" # por ejemplo, "acme/my-image:latest"
          # Para pull requests, exportar los resultados a la caché de compilación.
          # De lo contrario, subir a un registro.
          outputs: ${{ github.event_name == 'pull_request' && 'type=cacheonly' || 'type=registry' }}

El ejemplo anterior utiliza docker/build-push-action, que utiliza automáticamente el builder configurado por setup-buildx-action. Si en su lugar necesitas utilizar el comando docker build de forma directa, tienes dos opciones:

Utilizar docker buildx build en lugar de docker build

Establecer la variable de entorno BUILDX_BUILDER para utilizar el builder en la nube:

- name: Set up Docker Buildx
  id: builder
  uses: docker/setup-buildx-action@v4
  with:
    driver: cloud
    endpoint: "${{ vars.DOCKER_ACCOUNT }}/${{ vars.CLOUD_BUILDER_NAME }}"

- name: Build
  run: |
    docker build .
  env:
    BUILDX_BUILDER: ${{ steps.builder.outputs.name }}

Para obtener más información sobre la variable de entorno BUILDX_BUILDER, consulta Variables de compilación.

GitLab

default:
  image: docker:24-dind
  services:
    - docker:24-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:
  IMAGE_NAME: <IMAGE>
  DOCKER_ACCOUNT: <DOCKER_ACCOUNT> # el nombre de tu organización de Docker Hub (o usuario al usar cuenta personal)
  CLOUD_BUILDER_NAME: <CLOUD_BUILDER_NAME> # el nombre del builder en la nube que creaste en el [Panel de control de Docker Build Cloud](https://app.docker.com/build/)

# Compilar una imagen multiplataforma y subirla a un registro
build_push:
  stage: build
  script:
    - |
      docker buildx build \
        --platform linux/amd64,linux/arm64 \
        --tag "${IMAGE_NAME}:${CI_COMMIT_SHORT_SHA}" \
        --push .

# Compilar una imagen y descartar el resultado
build_cache:
  stage: build
  script:
    - |
      docker buildx build \
        --platform linux/amd64,linux/arm64 \
        --tag "${IMAGE_NAME}:${CI_COMMIT_SHORT_SHA}" \
        --output type=cacheonly \
        .

Circle CI

version: 2.1

jobs:
  # Compilar una imagen multiplataforma y subirla a un registro
  build_push:
    machine:
      image: ubuntu-2204:current
    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_ --password-stdin
      - run: docker buildx create --use --driver cloud "${DOCKER_ACCOUNT}/${CLOUD_BUILDER_NAME}"

      - run: |
          docker buildx build \
          --platform linux/amd64,linux/arm64 \
          --push \
          --tag "<IMAGE>" .

  # Compilar una imagen y descartar el resultado
  build_cache:
    machine:
      image: ubuntu-2204:current
    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_ --password-stdin
      - run: docker buildx create --use --driver cloud "${DOCKER_ACCOUNT}/${CLOUD_BUILDER_NAME}"

      - run: |
          docker buildx build \
          --tag temp \
          --output type=cacheonly \
          .

workflows:
  pull_request:
    jobs:
      - build_cache
  release:
    jobs:
      - build_push

Buildkite

El siguiente ejemplo configura una pipeline de Buildkite utilizando Docker Build Cloud. El ejemplo asume que el nombre de la pipeline es build-push-docker y que gestionas el token de acceso de Docker utilizando hooks de entorno, pero siéntete libre de adaptarlo a tus necesidades.

Añade el siguiente hook environment al directorio de hooks de tu agente:

#!/bin/bash
set -euo pipefail

if [[ "$BUILDKITE_PIPELINE_NAME" == "build-push-docker" ]]; then
 export DOCKER_ACCESS_TOKEN="<DOCKER_ACCESS_TOKEN>"
fi

Crea un archivo pipeline.yml que utilice el plugin docker-login:

env:
  DOCKER_ACCOUNT: <DOCKER_ACCOUNT> # el nombre de tu organización de Docker Hub (o usuario al usar cuenta personal)
  CLOUD_BUILDER_NAME: <CLOUD_BUILDER_NAME> # el nombre del builder en la nube que creaste en el [Panel de control de Docker Build Cloud](https://app.docker.com/build/)
  IMAGE_NAME: <IMAGE>

steps:
  - command: ./build.sh
    key: build-push
    plugins:
      - docker-login#v2.1.0:
          username: DOCKER_ACCOUNT
          password-env: DOCKER_ACCESS_TOKEN # el nombre de la variable en el hook de entorno

Crea el script build.sh:

DOCKER_DIR=/usr/libexec/docker

# Obtener el enlace de descarga del binario de buildx más reciente.
# Establece $ARCH a la arquitectura de CPU (ej. 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\"))")

# Descargar docker buildx con soporte para Build Cloud
curl --silent -L --output $DOCKER_DIR/cli-plugins/docker-buildx $BUILDX_URL
chmod a+x ~/.docker/cli-plugins/docker-buildx

# Conectarte a tu builder y establecerlo como builder predeterminado
docker buildx create --use --driver cloud "${DOCKER_ACCOUNT}/${CLOUD_BUILDER_NAME}"

# Compilación de imagen solo en caché
docker buildx build \
    --platform linux/amd64,linux/arm64 \
    --tag "$IMAGE_NAME:$BUILDKITE_COMMIT" \
    --output type=cacheonly \
    .

# Compilar, etiquetar y subir una imagen docker multiarquitectura
docker buildx build \
    --platform linux/amd64,linux/arm64 \
    --push \
    --tag "$IMAGE_NAME:$BUILDKITE_COMMIT" \
    .

Jenkins

pipeline {
  agent any

  environment {
    ARCH = 'amd64'
    DOCKER_ACCESS_TOKEN = credentials('docker-access-token')
    DOCKER_ACCOUNT = credentials('docker-account')
    CLOUD_BUILDER_NAME = '<CLOUD_BUILDER_NAME>'
    IMAGE_NAME = '<IMAGE>'
  }

  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}"'
        // Compilación solo en caché
        sh 'docker buildx build --platform linux/amd64,linux/arm64 --tag "$IMAGE_NAME" --output type=cacheonly .'
        // Compilar y subir una imagen multiplataforma
        sh 'docker buildx build --platform linux/amd64,linux/arm64 --push --tag "$IMAGE_NAME" .'
      }
    }
  }
}

Travis CI

language: minimal
dist: jammy

services:
  - docker

env:
  global:
    - IMAGE_NAME=<IMAGE> # por ejemplo, "acme/my-image:latest"

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
  docker buildx create --use --driver cloud "${DOCKER_ACCOUNT}/${CLOUD_BUILDER_NAME}"

script: |
  docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --push \
  --tag "$IMAGE_NAME" .

BitBucket Pipelines

# Requisitos previos: configurar $DOCKER_ACCOUNT, $CLOUD_BUILDER_NAME, $DOCKER_ACCESS_TOKEN como variables de despliegue
# Esta pipeline asume $BITBUCKET_REPO_SLUG como nombre de la imagen

image: atlassian/default-image:3

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
          - docker buildx build
            --platform linux/amd64,linux/arm64
            --push
            --tag "$IMAGE_NAME" .
        services:
          - docker

Script de shell

#!/bin/bash

# Obtener enlace de descarga de la versión de buildx más reciente. Establece $ARCH a la arquitectura de CPU (ej. 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\"))")

# Descargar docker buildx con soporte para Build Cloud
mkdir -vp ~/.docker/cli-plugins/
curl --silent -L --output ~/.docker/cli-plugins/docker-buildx $BUILDX_URL
chmod a+x ~/.docker/cli-plugins/docker-buildx

# Iniciar sesión en Docker Hub con un token de acceso. Consulta https://docs-docker.esdocu.com/build-cloud/ci/#crear-tokens-de-acceso
echo "$DOCKER_ACCESS_TOKEN" | docker login --username $DOCKER_ACCOUNT --password-stdin

# Conectarte a tu builder y establecerlo como builder predeterminado
docker buildx create --use --driver cloud "${DOCKER_ACCOUNT}/${CLOUD_BUILDER_NAME}"

# Compilación de imagen solo en caché
docker buildx build \
    --tag temp \
    --output type=cacheonly \
    .

# Compilar, etiquetar y subir una imagen docker multiarquitectura
docker buildx build \
    --platform linux/amd64,linux/arm64 \
    --push \
    --tag "<IMAGE>" \
    .

Docker Compose

Utiliza esta implementación si deseas utilizar docker compose build con Docker Build Cloud en CI.

#!/bin/bash

# Obtener enlace de descarga de la versión de buildx más reciente. Establece $ARCH a la arquitectura de CPU (ej. 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")

# Descargar docker buildx con soporte para Build Cloud
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

# Iniciar sesión en Docker Hub con un token de acceso. Consulta https://docs-docker.esdocu.com/build-cloud/ci/#crear-tokens-de-acceso
echo "$DOCKER_ACCESS_TOKEN" | docker login --username $DOCKER_ACCOUNT --password-stdin

# Conectarte a tu builder y establecerlo como builder predeterminado
docker buildx create --use --driver cloud "${DOCKER_ACCOUNT}/${CLOUD_BUILDER_NAME}"

# Ejecutar la compilación de la imagen
docker compose build

¿En qué te puedo ayudar?

Uso de Docker Build Cloud en CI