Comment utiliser Docker Build Args pour configurer les builds d’image

Le mécanisme « build args » de Docker vous permet de définir des variables d’environnement qui peuvent être référencées dans votre Dockerfile lors de la création d’images. Contrairement à la normale ENV instructions, les arguments de construction ne sont pas présents dans l’image de sortie finale. Ils sont destinés aux cas où vous souhaitez configurer le processus de génération au lieu des conteneurs créés.

Définition des arguments de construction

Vous définissez les arguments de construction dans votre Dockerfile utilisant ARG des instructions:

ARG EXAMPLE_VAR
ARG DEMO_VAR

RUN echo $EXAMPLE_VAR

Deux arguments, EXAMPLE_VAR et DEMO_VARsont ajoutés à la construction par le Dockerfile ci-dessus.

Vous définissez les valeurs des arguments disponibles via le --build-arg drapeau pour docker build. Répétez l’indicateur plusieurs fois pour couvrir tous les arguments définis dans votre Dockerfile:

docker build -t example-image:latest 
    --build-arg EXAMPLE_VAR=value1 
    --build-arg DEMO_VAR=value2 
    .

Construire l’échantillon Dockerfile l’utilisation de cette commande émettra value1 à votre terminal pendant la construction. La EXAMPLE_VAR la variable est rendue disponible dans l’environnement de construction avec la valeur value1. La composante valeur du --build-arg le drapeau est facultatif ; l’omettre sélectionnera automatiquement la valeur de la variable dans votre environnement shell local.

Comme les arguments de construction ne sont pas conservés dans l’image construite, vous verrez une chaîne vide lors de l’exécution echo $EXAMPLE_VAR à l’intérieur de conteneurs créés à partir de example-image:latest. Les variables auxquelles les conteneurs en cours d’exécution doivent faire référence doivent être ajoutées à l’aide de ENV consignes et --env ou -e construire des drapeaux.

Bien qu’ils ne soient pas dans l’image finale, les arguments de construction ont toujours un impact sur le cache de construction de Docker. La modification de la valeur d’un argument entre les versions peut entraîner des échecs de cache pour les instructions qui suivent la première référence à la variable. La définition ARG n’est pas responsable de l’invalidation du cache.

FROM alpine:latest
ARG EXAMPLE_VAR

# Cache is not invalidated - arg hasn't been used
RUN example-command

# Build cache can't be used from this point onwards
RUN echo $EXAMPLE_VAR

Valeurs d’argument de construction par défaut

La ARG l’instruction peut recevoir une valeur par défaut à utiliser en l’absence de correspondance --build-arg drapeau est fourni :

ARG EXAMPLE_VAR=demo

Docker préférera toujours la valeur donnée par le --build-arg signaler lorsqu’il y en a un de disponible. S’il manque, EXAMPLE_VAR sera fixé à demo dans l’environnement de construction. Cela réduit le nombre d’indicateurs que vous devez fournir lors de la construction d’une image avec des arguments rarement remplacés.

Où Build Args peut-il être utilisé ?

Les arguments de construction peuvent être référencés dans les instructions Dockerfile qui les suivent. Ils travaillent avec la plupart des types d’instructions, y compris RUN commandes exécutées dans les conteneurs de construction intermédiaires. Les arguments sont référencés de la même manière que les variables d’environnement, en utilisant le $EXAMPLE_VAR syntaxe.

ARG les instructions sont uniques car elles affectent matériellement la construction mais peuvent être utilisées avant FROM déclarations. Il est permis de référencer des arguments de construction à l’intérieur d’un FROM instruction, permettant de sélectionner une image de base différente selon la configuration de l’utilisateur :

ARG BASE_IMAGE_VERSION=alpine
FROM my-app-base:2-${BASE_IMAGE_VERSION}

docker build -t my-app:latest --build-arg BASE_IMAGE_VERSION=debian .

Les arguments de construction sont disponibles à partir de la ligne sur laquelle ils sont définis. Toute instruction suivante peut référencer la valeur des arguments de construction créés au-dessus dans le Dockerfile. Tu devoir ajouter ARG instructions pour tous les arguments de construction que vous utiliserez. Faire référence à un argument avant qu’il ne soit défini – ou utiliser un --build-arg sans correspondant ARG – se traduira par une chaîne vide.

Les arguments de construction ne fonctionnent pas à travers les étapes de construction. Chaque étape agit comme une nouvelle génération avec son propre ensemble d’arguments de génération. ARG les instructions incluses dans les étapes précédentes n’ont aucun effet sur les suivantes à moins qu’elles ne soient répétées à chaque étape :

FROM php:latest
ARG BUILD_VERSION

FROM composer:latest
ARG BUILD_VERSION

Les deux étapes définissent explicitement la BUILD_VERSION arg donc la valeur définie avec --build-arg seront fournis à chacun.

Les considérations relatives à l’étape de génération s’appliquent également lorsque vous utilisez ARG avant un FROM instruction. Ces arguments existent en dehors de toute étape de génération ; ils sont partagés par tous FROM mais ne peut pas être référencé en suivant les instructions. Si vous souhaitez réutiliser un FROM-level build arg à l’intérieur d’une étape, répétez la ARG instruction de tirer sa valeur:

# Only applies to FROM instructions
ARG BASE_IMAGE_VERSION=alpine
FROM my-app-base:2-${BASE_IMAGE_VERSION}

# Reference the outer build argument
ARG BASE_IMAGE_VERSION

# Works as expected
RUN echo $BASE_IMAGE_VERSION

Mis à part ces préoccupations particulières, les arguments se comportent de la même manière que les variables d’environnement à tous autres égards. Vous pouvez remplacer leurs valeurs en utilisant ARG et ENV instructions, interpolez-les dans des chaînes et utilisez-les dans des expressions d’expansion de la forme ${EXAMPLE_VAR:-demo}. Cela sélectionne demo comme valeur lorsque le EXAMPLE_VAR la variable n’est pas définie.

Args de construction prédéfinis

Docker prend en charge certains arguments de construction par défaut, même si vous n’incluez pas leur ARG instructions dans votre Dockerfile. Ils se rapportent aux paramètres de proxy et fonctionnent chaque fois que leurs correspondants --build-arg drapeau est utilisé. Les variables sont également exclues de docker history output pour éviter de divulguer les détails potentiellement sensibles auxquels ils sont destinés – plus d’informations sur cette commande et ses implications ci-dessous.

Les builds gérés par le backend BuildKit peuvent également accéder à plusieurs autres arguments de build prédéfinis. Ceux-ci sont fournis avec des valeurs injectées automatiquement. La liste comprend TARGETOS, TARGETARCH, TARGETPLATFORMet BUILDOS, BUILDARCHet BUILDPLATFORM, parmi plusieurs autres. Les variables décrivent les caractéristiques de l’environnement de construction et de la plate-forme ciblée par la nouvelle image.

Quand utiliser Build Args ?

Les arguments de build peuvent être utilisés pour injecter la configuration dans les builds d’image Docker. C’est un moyen de modifier dynamiquement l’image finale sans écrire plusieurs Dockerfiles.

Vous pouvez utiliser ce mécanisme pour modifier l’image de base d’un build, changer les commandes exécutées par RUN instructions et fournir des paramètres modifiables par l’utilisateur qui exposent les options de personnalisation d’image. Les arguments de construction ont un sens pour la plupart des valeurs qui ne sont utilisées que pendant le processus de construction et que vous ne voulez pas coder en dur dans votre Dockerfile.

Il existe certaines situations où des approches alternatives doivent être utilisées. Bien que pratiques, les arguments de construction ne sont pas idéaux pour les données secrètes telles que les jetons et les clés d’authentification. Car ARG est une instruction Dockerfile, les variables et leurs valeurs sont visibles lors de l’inspection d’une image avec le docker history commande. Toute personne ayant accès à votre image peut donc visualiser les clés utilisées lors de la construction.

Les informations d’identification utilisées pour authentifier votre processus de génération auprès des registres de packages et des référentiels de contrôle de source sont mieux fournies en tant que secrets de génération BuildKit. Ceux-ci sont conçus pour gérer des informations sensibles et sont montés en tant que fichiers dans l’environnement de construction, au lieu de devenir des instructions d’image.

Sommaire

Les arguments de génération vous permettent de configurer les générations d’images Docker à l’aide d’une combinaison d’instructions Dockerfile et d’arguments de ligne de commande au moment de la génération. Contrairement aux variables d’environnement, les arguments de construction ne sont pas accessibles aux conteneurs en cours d’exécution, bien qu’ils soient toujours visibles dans l’historique des couches de l’image.

Un argument de construction est le bon choix pour les paramètres personnalisables par l’utilisateur non sensibles qui affectent votre processus de construction. Utilisez plutôt une variable d’environnement lorsque vous souhaitez exposer la valeur dans l’image finale. Les secrets BuildKit sont une meilleure troisième option pour toutes les données précieuses auxquelles votre build doit accéder.