Configuración de tu constructor de GitHub Actions

Tabla de contenidos

Esta página contiene instrucciones sobre cómo configurar tus instancias de BuildKit al utilizar nuestra Setup Buildx Action.

Fijación de versiones (version pinning)

De forma predeterminada, la acción intentará utilizar la última versión de Buildx disponible en el GitHub Runner (el cliente de compilación) y el último lanzamiento de BuildKit (el servidor de compilación).

Para fijar una versión específica de Buildx, utiliza la entrada version. Por ejemplo, para fijar Buildx en v0.10.0:

- name: Configurar Docker Buildx
  uses: docker/setup-buildx-action@v4
  with:
    version: v0.10.0

Para fijar una versión específica de BuildKit, utiliza la opción image en la entrada driver-opts. Por ejemplo, para fijar BuildKit en v0.11.0:

- name: Configurar Docker Buildx
  uses: docker/setup-buildx-action@v4
  with:
    driver-opts: image=moby/buildkit:v0.11.0

Logs del contenedor de BuildKit

Para mostrar los logs del contenedor de BuildKit cuando se utiliza el controlador docker-container, debes habilitar el registro de depuración del paso (step debug logging), o establecer la bandera --debug de buildkitd en la acción Docker Setup Buildx:

name: ci

on:
  push:

jobs:
  buildx:
    runs-on: ubuntu-latest
    steps:
      - name: Configurar Docker Buildx
        uses: docker/setup-buildx-action@v4
        with:
          buildkitd-flags: --debug

      - name: Build
        uses: docker/build-push-action@v7

Los logs estarán disponibles al final de un trabajo (job):

Configuración del demonio (Daemon) de BuildKit

Puedes proporcionar una configuración de BuildKit a tu constructor si estás utilizando el controlador docker-container (predeterminado) con las entradas config o buildkitd-config-inline:

Espejo de registro (registry mirror)

Puedes configurar un espejo de registro utilizando un bloque en línea directamente en tu flujo de trabajo con la entrada buildkitd-config-inline:

name: ci

on:
  push:

jobs:
  buildx:
    runs-on: ubuntu-latest
    steps:
      - name: Configurar Docker Buildx
        uses: docker/setup-buildx-action@v4
        with:
          buildkitd-config-inline: |
            [registry."docker.io"]
              mirrors = ["mirror.gcr.io"]

Para obtener más información sobre el uso de un espejo de registro, consulta Espejo de registro.

Paralelismo máximo (max parallelism)

Puedes limitar el paralelismo del solucionador (solver) de BuildKit, lo cual es especialmente útil para máquinas de baja potencia.

Puedes utilizar la entrada buildkitd-config-inline como en el ejemplo anterior, o puedes usar un archivo de configuración de BuildKit dedicado desde tu repositorio si lo deseas con la entrada config:

# .github/buildkitd.toml
[worker.oci]
  max-parallelism = 4

name: ci

on:
  push:

jobs:
  buildx:
    runs-on: ubuntu-latest
    steps:
      - name: Configurar Docker Buildx
        uses: docker/setup-buildx-action@v4
        with:
          config: .github/buildkitd.toml

Añadir nodos adicionales al constructor

Buildx permite ejecutar compilaciones en varias máquinas. Esto es útil para compilar imágenes multiplataforma en nodos nativos para casos más complejos que no pueden ser manejados por QEMU. Compilar en nodos nativos generalmente ofrece un mejor rendimiento y te permite distribuir la compilación en múltiples máquinas.

Puedes añadir nodos al constructor que estás creando utilizando la opción append. Toma la entrada en forma de un documento de cadena YAML para eliminar limitaciones intrínsecamente ligadas a GitHub Actions: solo puedes utilizar cadenas en los campos de entrada:

Nombre	Tipo	Descripción
`name`	String	Nombre del nodo. Si está vacío, es el nombre del constructor al que pertenece, con un sufijo de número de índice. Esto es útil para configurarlo si deseas modificar o eliminar un nodo en un paso posterior de tu flujo de trabajo.
`endpoint`	String	Contexto o endpoint de Docker del nodo a añadir al constructor.
`driver-opts`	Lista	Lista de opciones específicas del controlador adicionales.
`buildkitd-flags`	String	Banderas para el demonio buildkitd.
`platforms`	String	Plataformas fijas para el nodo. Si no está vacío, los valores tienen prioridad sobre los detectados.

Aquí tienes un ejemplo del uso de nodos remotos con el controlador remote y autenticación TLS:

name: ci

on:
  push:

jobs:
  buildx:
    runs-on: ubuntu-latest
    steps:
      - name: Configurar Docker Buildx
        uses: docker/setup-buildx-action@v4
        with:
          driver: remote
          endpoint: tcp://oneprovider:1234
          append: |
            - endpoint: tcp://graviton2:1234
              platforms: linux/arm64
            - endpoint: tcp://linuxone:1234
              platforms: linux/s390x
        env:
          BUILDER_NODE_0_AUTH_TLS_CACERT: ${{ secrets.ONEPROVIDER_CA }}
          BUILDER_NODE_0_AUTH_TLS_CERT: ${{ secrets.ONEPROVIDER_CERT }}
          BUILDER_NODE_0_AUTH_TLS_KEY: ${{ secrets.ONEPROVIDER_KEY }}
          BUILDER_NODE_1_AUTH_TLS_CACERT: ${{ secrets.GRAVITON2_CA }}
          BUILDER_NODE_1_AUTH_TLS_CERT: ${{ secrets.GRAVITON2_CERT }}
          BUILDER_NODE_1_AUTH_TLS_KEY: ${{ secrets.GRAVITON2_KEY }}
          BUILDER_NODE_2_AUTH_TLS_CACERT: ${{ secrets.LINUXONE_CA }}
          BUILDER_NODE_2_AUTH_TLS_CERT: ${{ secrets.LINUXONE_CERT }}
          BUILDER_NODE_2_AUTH_TLS_KEY: ${{ secrets.LINUXONE_KEY }}

Autenticación para constructores remotos

Los siguientes ejemplos muestran cómo manejar la autenticación para constructores remotos, utilizando SSH o TLS.

Autenticación SSH

Para poder conectarte a un endpoint SSH utilizando el controlador docker-container, debes configurar la clave privada SSH y su configuración en el GitHub Runner:

name: ci

on:
  push:

jobs:
  buildx:
    runs-on: ubuntu-latest
    steps:
      - name: Configurar SSH
        uses: MrSquaare/ssh-setup-action@2d028b70b5e397cf8314c6eaea229a6c3e34977a # v3.1.0
        with:
          host: graviton2
          private-key: ${{ secrets.SSH_PRIVATE_KEY }}
          private-key-name: aws_graviton2

      - name: Configurar Docker Buildx
        uses: docker/setup-buildx-action@v4
        with:
          endpoint: ssh://me@graviton2

Autenticación TLS

También puedes configurar una instancia remota de BuildKit utilizando el controlador remote. Para facilitar la integración en tu flujo de trabajo, puedes usar variables de entorno que configuran la autenticación mediante los certificados del cliente BuildKit para tcp://:

BUILDER_NODE_<idx>_AUTH_TLS_CACERT
BUILDER_NODE_<idx>_AUTH_TLS_CERT
BUILDER_NODE_<idx>_AUTH_TLS_KEY

El marcador de posición <idx> es la posición del nodo en la lista de nodos.

name: ci

on:
  push:

jobs:
  buildx:
    runs-on: ubuntu-latest
    steps:
      - name: Configurar Docker Buildx
        uses: docker/setup-buildx-action@v4
        with:
          driver: remote
          endpoint: tcp://graviton2:1234
        env:
          BUILDER_NODE_0_AUTH_TLS_CACERT: ${{ secrets.GRAVITON2_CA }}
          BUILDER_NODE_0_AUTH_TLS_CERT: ${{ secrets.GRAVITON2_CERT }}
          BUILDER_NODE_0_AUTH_TLS_KEY: ${{ secrets.GRAVITON2_KEY }}

Modo independiente (standalone)

Si no tienes instalada la CLI de Docker en el GitHub Runner, el binario de Buildx se invoca directamente en lugar de llamarlo como un plugin de la CLI de Docker. Esto puede ser útil si deseas utilizar el controlador kubernetes en tu runner autohospedado (self-hosted):

name: ci

on:
  push:

jobs:
  buildx:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Configurar Docker Buildx
        uses: docker/setup-buildx-action@v4
        with:
          driver: kubernetes

      - name: Compilar
        run: |
          buildx build .

Constructores aislados

El siguiente ejemplo muestra cómo puedes seleccionar diferentes constructores para diferentes trabajos (jobs).

Monorepo es un escenario de ejemplo donde esto podría ser útil: si deseas dirigir diferentes paquetes a constructores específicos. Por ejemplo, algunos paquetes pueden requerir muchos recursos para compilarse y necesitar más capacidad de cómputo. O requieren un constructor equipado con una capacidad o hardware específicos.

Para obtener más información sobre el constructor remoto, consulta el controlador remote y el ejemplo de anexar nodos de constructor.

name: ci

on:
  push:

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Configurar builder1
        uses: docker/setup-buildx-action@v4
        id: builder1

      - name: Configurar builder2
        uses: docker/setup-buildx-action@v4
        id: builder2

      - name: Compilar usando builder1
        uses: docker/build-push-action@v7
        with:
          builder: ${{ steps.builder1.outputs.name }}
          target: mytarget1

      - name: Compilar usando builder2
        uses: docker/build-push-action@v7
        with:
          builder: ${{ steps.builder2.outputs.name }}
          target: mytarget2

¿En qué te puedo ayudar?

Configuración de tu constructor de GitHub Actions