Vérification de votre configuration de compilation

Les vérifications de compilation (build checks) sont une fonctionnalité introduite dans Dockerfile 1.8. Elles vous permettent de valider votre configuration de compilation et d'effectuer une série de vérifications avant d'exécuter votre compilation. Considérez-les comme une forme avancée de linting pour votre Dockerfile et vos options de compilation, ou un mode de simulation pour les compilations.

Vous pouvez trouver la liste des vérifications disponibles, ainsi qu'une description de chacune, dans la référence des vérifications de compilation.

Comment fonctionnent les vérifications de compilation

Typiquement, lorsque vous exécutez une compilation, Docker exécute les étapes de compilation de votre Dockerfile et les options de compilation comme spécifié. Avec les vérifications de compilation, plutôt que d'exécuter les étapes de compilation, Docker vérifie le Dockerfile et les options que vous fournissez et signale les problèmes qu'il détecte.

Les vérifications de compilation sont utiles pour :

• Valider votre Dockerfile et vos options de compilation avant d'exécuter une compilation.
• S'assurer que votre Dockerfile et vos options de compilation sont à jour avec les dernières meilleures pratiques.
• Identifier les problèmes potentiels ou les anti-modèles dans votre Dockerfile et vos options de compilation.

Tip

Vous voulez une meilleure expérience d'édition pour les Dockerfiles dans VS Code ? Découvrez l'extension Docker pour VS Code (Bêta) pour le linting, la navigation dans le code et l'analyse des vulnérabilités.

Compiler avec des vérifications

Les vérifications de compilation sont prises en charge dans :

• Buildx version 0.15.0 et ultérieures
• docker/build-push-action version 6.6.0 et ultérieures
• docker/bake-action version 5.6.0 et ultérieures

L'invocation d'une compilation exécute les vérifications par défaut et affiche les violations dans la sortie de la compilation. Par exemple, la commande suivante compile l'image et exécute les vérifications :

$ 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)

Dans cet exemple, la compilation s'est déroulée avec succès, mais un avertissement JSONArgsRecommended a été signalé, car les instructions CMD doivent utiliser la syntaxe de tableau JSON.

Avec les actions GitHub, les vérifications s'affichent dans la vue des différences des pull requests.

name: Build and push Docker images
on:
  push:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Build and push
        uses: docker/[email protected]

Sortie plus verbeuse

Les avertissements de vérification pour une compilation docker build régulière affichent un message concis contenant le nom de la règle, le message et le numéro de ligne où le problème est apparu dans le Dockerfile. Si vous souhaitez voir des informations plus détaillées sur les vérifications, vous pouvez utiliser l'indicateur --debug. Par exemple :

$ 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.com/go/dockerfile/rule/json-args-recommended/
Dockerfile:4
--------------------
   2 |
   3 |     FROM alpine
   4 | >>> CMD echo "Hello, world!"
   5 |
--------------------

Avec l'indicateur --debug, la sortie inclut un lien vers la documentation de la vérification et un extrait du Dockerfile où le problème a été trouvé.

Vérifier une compilation sans construire

Pour exécuter les vérifications de compilation sans construire réellement, vous pouvez utiliser la commande docker build comme vous le feriez normalement, mais avec l'ajout de l'indicateur --check. Voici un exemple :

$ docker build --check .

Au lieu d'exécuter les étapes de compilation, cette commande exécute uniquement les vérifications et signale les problèmes qu'elle trouve. S'il y a des problèmes, ils seront signalés dans la sortie. Par exemple :

[+] 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.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 |
--------------------

Cette sortie avec --check montre le message verbeux pour la vérification.

Contrairement à une compilation normale, si des violations sont signalées lors de l'utilisation de l'indicateur --check, la commande se termine avec un code de sortie non nul.

Faire échouer la compilation en cas de violations de vérification

Les violations de vérification pour les compilations sont signalées comme des avertissements, avec un code de sortie 0, par défaut. Vous pouvez configurer Docker pour faire échouer la compilation lorsque des violations sont signalées, en utilisant une directive check=error=true dans votre Dockerfile. Cela provoquera une erreur de compilation après l'exécution des vérifications de compilation, avant que la compilation réelle ne soit exécutée.

1
2
3
4
5

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

FROM alpine
CMD echo "Hello, world!"

Sans la directive # check=error=true, cette compilation se terminerait avec un code de sortie de 0. Cependant, avec la directive, la violation de la vérification de compilation entraîne un code de sortie non nul :

$ 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

Vous pouvez également définir la directive d'erreur sur la CLI en passant l'argument de compilation BUILDKIT_DOCKERFILE_CHECK :

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

Ignorer les vérifications

Par défaut, toutes les vérifications sont exécutées lorsque vous compilez une image. Si vous souhaitez ignorer des vérifications spécifiques, vous pouvez utiliser la directive check=skip dans votre Dockerfile. Le paramètre skip prend une chaîne CSV des ID de vérification que vous souhaitez ignorer. Par exemple :

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

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

La compilation de ce Dockerfile n'entraîne aucune violation de vérification.

Vous pouvez également ignorer les vérifications en passant l'argument de compilation BUILDKIT_DOCKERFILE_CHECK avec une chaîne CSV des ID de vérification que vous souhaitez ignorer. Par exemple :

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

Pour ignorer toutes les vérifications, utilisez le paramètre skip=all :

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

Combiner les paramètres error et skip pour les directives de vérification

Pour ignorer des vérifications spécifiques et provoquer une erreur en cas de violations de vérification, passez à la fois les paramètres skip et error séparés par un point-virgule (;) à la directive check dans votre Dockerfile ou dans un argument de compilation. Par exemple :

# syntax=docker/dockerfile:1
# check=skip=JSONArgsRecommended,StageNameCasing;error=true

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

Vérifications expérimentales

Avant que les vérifications ne soient promues stables, elles peuvent être disponibles en tant que vérifications expérimentales. Les vérifications expérimentales sont désactivées par défaut. Pour voir la liste des vérifications expérimentales disponibles, reportez-vous à la référence des vérifications de compilation.

Pour activer toutes les vérifications expérimentales, définissez l'argument de compilation BUILDKIT_DOCKERFILE_CHECK sur experimental=all :

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

Vous pouvez également activer les vérifications expérimentales dans votre Dockerfile en utilisant la directive check :

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

Pour activer sélectivement les vérifications expérimentales, vous pouvez passer une chaîne CSV des ID de vérification que vous souhaitez activer, soit à la directive check dans votre Dockerfile, soit en tant qu'argument de compilation. Par exemple :

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

Notez que la directive experimental a priorité sur la directive skip, ce qui signifie que les vérifications expérimentales s'exécuteront quel que soit le paramètre skip que vous avez défini. Par exemple, if vous définissez skip=all et activez les vérifications expérimentales, les vérifications expérimentales s'exécuteront quand même :

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

Lectures complémentaires

Pour plus d'informations sur l'utilisation des vérifications de compilation, consultez :

• Référence des vérifications de compilation
• Validation de la configuration de compilation avec GitHub Actions