Compartir comentarios
Las respuestas se generan en base a la documentación.

Verificación de la configuración de compilación

Tabla de contenidos
Disponibilidad: Beta
Requiere: Docker Buildx 0.15.0 y posterior

Las verificaciones de compilación (build checks) son una característica introducida en Dockerfile 1.8. Te permiten validar tu configuración de compilación y realizar una serie de verificaciones antes de ejecutar tu compilación. Piensa en ello como una forma avanzada de análisis estático (linting) para tu Dockerfile y opciones de compilación, o un modo de prueba (dry-run) para las compilaciones.

Puedes encontrar la lista de verificaciones disponibles y una descripción de cada una en la referencia de verificaciones de compilación.

Cómo funcionan las verificaciones de compilación

Normalmente, cuando ejecutas una compilación, Docker ejecuta los pasos de compilación en tu Dockerfile y las opciones de compilación tal como se especifican. Con las verificaciones de compilación, en lugar de ejecutar los pasos de compilación, Docker verifica el Dockerfile y las opciones que proporcionas e informa sobre cualquier problema que detecte.

Las verificaciones de compilación son útiles para:

  • Validar tu Dockerfile y las opciones de compilación antes de ejecutar una compilación.
  • Asegurar que tu Dockerfile y las opciones de compilación estén actualizados con las últimas buenas prácticas.
  • Identificar posibles problemas o antipatrones en tu Dockerfile y opciones de compilación.
Tip

Para mejorar el análisis estático, la navegación de código y el escaneo de vulnerabilidades de tus Dockerfiles en Visual Studio Code, consulta la extensión Docker DX.

Compilar con verificaciones

Las verificaciones de compilación son compatibles con:

Invocar una compilación ejecuta las verificaciones por defecto y muestra cualquier violación en la salida de compilación. Por ejemplo, el siguiente comando compila la imagen y ejecuta las verificaciones:

$ docker build .
[+] Building 3.5s (11/11) FINISHED
...

1 warning found (use --debug to expand):
  - Lint Rule 'JSONArgsRecommended': JSON arguments recommended for CMD to prevent unintended behavior related to OS signals (line 7)

En este ejemplo, la compilación se ejecutó con éxito, pero se informó una advertencia JSONArgsRecommended, ya que las instrucciones CMD deben usar la sintaxis de array JSON.

Con GitHub Actions, las verificaciones se muestran en la vista de diferencias (diff) de las pull requests.

name: Build and push Docker images
on:
  push:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Build and push
        uses: docker/build-push-action@v7
GitHub Actions build check annotations

Salida más detallada

Las advertencias de verificación para un docker build normal muestran un mensaje conciso que contiene el nombre de la regla, el mensaje y el número de línea en el Dockerfile de donde se originó el problema. Si deseas ver información más detallada sobre las verificaciones, puedes usar la bandera (flag) --debug. Por ejemplo:

$ docker --debug build .
[+] Building 3.5s (11/11) FINISHED
...

 1 warning found:
 - JSONArgsRecommended: JSON arguments recommended for CMD to prevent unintended behavior related to OS signals (line 4)
JSON arguments recommended for ENTRYPOINT/CMD to prevent unintended behavior related to OS signals
More info: https://docs-docker.esdocu.com/go/dockerfile/rule/json-args-recommended/
Dockerfile:4
--------------------
   2 |
   3 |     FROM alpine
   4 | >>> CMD echo "Hello, world!"
   5 |
--------------------

Con la bandera --debug, la salida incluye un enlace a la documentación para la verificación y un fragmento del Dockerfile donde se encontró el problema.

Verificar una compilación sin compilar

Para ejecutar verificaciones de compilación sin realizar la compilación real, puedes usar el comando docker build como lo harías normalmente, pero añadiendo la bandera --check. Aquí tienes un ejemplo:

$ docker build --check .

En lugar de ejecutar los pasos de compilación, este comando solo ejecuta las verificaciones e informa sobre cualquier problema que encuentre. Si hay algún problema, se informará en la salida. Por ejemplo:

Output with --check
[+] Building 1.5s (5/5) FINISHED
=> [internal] connecting to local controller
=> [internal] load build definition from Dockerfile
=> => transferring dockerfile: 253B
=> [internal] load metadata for docker.io/library/node:22
=> [auth] library/node:pull token for registry-1.docker.io
=> [internal] load .dockerignore
=> => transferring context: 50B
JSONArgsRecommended - https://docs-docker.esdocu.com/go/dockerfile/rule/json-args-recommended/
JSON arguments recommended for ENTRYPOINT/CMD to prevent unintended behavior related to OS signals
Dockerfile:7
--------------------
5 |
6 |     COPY index.js .
7 | >>> CMD node index.js
8 |
--------------------

Esta salida con --check muestra el mensaje detallado de la verificación.

A diferencia de una compilación normal, si se informa alguna violación al usar la bandera --check, el comando finaliza con un código de estado distinto de cero.

Fallar la compilación por violaciones de verificación

Las violaciones de verificación para las compilaciones se informan como advertencias, con código de salida 0, por defecto. Puedes configurar Docker para que falle la compilación cuando se informen violaciones, utilizando una directiva check=error=true en tu Dockerfile. Esto hará que la compilación falle con un error después de que se ejecuten las verificaciones de compilación, antes de que se ejecute la compilación real.

Dockerfile
1
2
3
4
5

# syntax=docker/dockerfile:1
# check=error=true

FROM alpine
CMD echo "Hello, world!"

Sin la directiva # check=error=true, esta compilación se completaría con un código de salida 0. Sin embargo, con la directiva, la violación de la verificación de compilación da como resultado un código de salida distinto de cero:

$ docker build .
[+] Building 1.5s (5/5) FINISHED
...

 1 warning found (use --debug to expand):
 - JSONArgsRecommended: JSON arguments recommended for CMD to prevent unintended behavior related to OS signals (line 5)
Dockerfile:1
--------------------
   1 | >>> # syntax=docker/dockerfile:1
   2 |     # check=error=true
   3 |
--------------------
ERROR: lint violation found for rules: JSONArgsRecommended
$ echo $?
1

También puedes establecer la directiva de error en la CLI pasando el argumento de compilación BUILDKIT_DOCKERFILE_CHECK:

$ docker build --check --build-arg "BUILDKIT_DOCKERFILE_CHECK=error=true" .

Omitir verificaciones

Por defecto, todas las verificaciones se ejecutan cuando compilas una imagen. Si deseas omitir verificaciones específicas, puedes usar la directiva check=skip en tu Dockerfile. El parámetro skip acepta una lista de IDs de verificación separados por comas que deseas omitir. Por ejemplo:

Dockerfile
# syntax=docker/dockerfile:1
# check=skip=JSONArgsRecommended,StageNameCasing

FROM alpine AS BASE_STAGE
CMD echo "Hello, world!"

Compilar este Dockerfile no genera violaciones de verificación.

También puedes omitir verificaciones pasando el argumento de compilación BUILDKIT_DOCKERFILE_CHECK con una lista de IDs de verificación separados por comas. Por ejemplo:

$ docker build --check --build-arg "BUILDKIT_DOCKERFILE_CHECK=skip=JSONArgsRecommended,StageNameCasing" .

Para omitir todas las verificaciones, utiliza el parámetro skip=all:

Dockerfile
# syntax=docker/dockerfile:1
# check=skip=all

Combinar parámetros de error y omisión para directivas de verificación

Para omitir verificaciones específicas y al mismo tiempo fallar en caso de violaciones, pasa los parámetros skip y error separados por un punto y coma (;) a la directiva check en tu Dockerfile o en un argumento de compilación. Por ejemplo:

Dockerfile
# syntax=docker/dockerfile:1
# check=skip=JSONArgsRecommended,StageNameCasing;error=true
Build argument
$ docker build --check --build-arg "BUILDKIT_DOCKERFILE_CHECK=skip=JSONArgsRecommended,StageNameCasing;error=true" .

Verificaciones experimentales

Antes de que las verificaciones pasen a ser estables, pueden estar disponibles como verificaciones experimentales. Las verificaciones experimentales están deshabilitadas por defecto. Para ver la lista de verificaciones experimentales disponibles, consulta la referencia de verificaciones de compilación.

Para habilitar todas las verificaciones experimentales, establece el argumento de compilación BUILDKIT_DOCKERFILE_CHECK en experimental=all:

$ docker build --check --build-arg "BUILDKIT_DOCKERFILE_CHECK=experimental=all" .

También puedes habilitar verificaciones experimentales en tu Dockerfile usando la directiva check:

Dockerfile
# syntax=docker/dockerfile:1
# check=experimental=all

Para habilitar selectivamente las verificaciones experimentales, puedes pasar una lista de los IDs de verificación que deseas habilitar, ya sea en la directiva check de tu Dockerfile o como un argumento de compilación. Por ejemplo:

Dockerfile
# syntax=docker/dockerfile:1
# check=experimental=JSONArgsRecommended,StageNameCasing

Ten en cuenta que la directiva experimental tiene prioridad sobre la directiva skip, lo que significa que las verificaciones experimentales se ejecutarán independientemente de la directiva skip que hayas establecido. Por ejemplo, si estableces skip=all y habilitas las verificaciones experimentales, las verificaciones experimentales se seguirán ejecutando:

Dockerfile
# syntax=docker/dockerfile:1
# check=skip=all;experimental=all

Lectura adicional

Para obtener más información sobre el uso de verificaciones de compilación, consulta: