Comment utiliser les arguments de construction Docker pour personnaliser une construction d’image

Le mécanisme « build arguments » de Docker vous permet de définir des variables d’environnement qui peuvent être référencées Dockerfilependant le processus de construction de l’image. Contrairement aux ENVinstructions normales, les arguments d’assemblage ne sont pas présents dans l’image de sortie finale. Ils sont utiles lorsque vous souhaitez personnaliser le processus de génération au lieu des conteneurs générés.

Définition des arguments de construction

Vous définissez les arguments de construction dans vos instructions d’utilisationDockerfile :ARG

ARG EXAMPLE_VAR

ARG DEMO_VAR

RUN echo $EXAMPLE_VAR

Les deux arguments EXAMPLE_VARet DEMO_VARsont ajoutés à la construction Dockerfile ci-dessus.

Vous définissez les arguments disponibles avec un --build-argindicateur pour docker build. Répétez le drapeau plusieurs fois pour couvrir tous les arguments définis dans votreDockerfile :

docker build -t example-image:latest

–build-arg EXAMPLE_VAR=value1

–build-arg DEMO_VAR=valeur2

.

La création d’un exemple Dockerfileavec cette commande sera transmise value1à votre terminal au moment de la construction. La variable EXAMPLE_VARdevient disponible dans l’environnement de génération avec la valeur value1. Le composant de valeur d’indicateur --build-argest facultatif ; l’omettre sélectionnera automatiquement la valeur de la variable dans votre environnement shell local.

Étant donné que les arguments de construction ne sont pas stockés dans l’image construite, vous verrez une chaîne vide lors de l’exécution echo $EXAMPLE_VARdans des conteneurs construits à partir de example-image:latest. Les variables qui doivent être référencées par les conteneurs en cours d’exécution doivent être ajoutées à l’aide d’ ENVinstructions de construction --envou d’ -eindicateurs.

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

FROM alpine:latest

ARG EXAMPLE_VAR

# Le cache n’est pas invalidé – arg n’a pas été utilisé

Exemple de commande RUN

# Le cache de construction ne peut plus être utilisé à partir de ce moment

RUN echo $EXAMPLE_VAR

Construire les valeurs par défaut des arguments

L’instruction ARGpeut recevoir une valeur par défaut à utiliser lorsque l’ --build-argindicateur correspondant n’est pas spécifié :

ARG EXAMPLE_VAR=demo

Docker préférera toujours la valeur donnée par --build-argle drapeau lorsqu’il est disponible. S’il est manquant, EXAMPLE_VARil sera installé demodans l’environnement de construction. Cela réduit le nombre d’indicateurs qui doivent être spécifiés lors de la création d’une image avec des arguments rarement remplacés.

Où les arguments de construction peuvent-ils être utilisés ?

Les arguments de construction peuvent être référencés dans les instructions Dockerfile qui les suivent. Ils fonctionnent avec la plupart des types d’instructions, y compris RUNles commandes exécutées dans des 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 la $EXAMPLE_VARsyntaxe.

ARGLes instructions sont uniques en ce sens qu’elles affectent de manière significative l’assemblage, mais peuvent être utilisées avant les FROMinstructions. Il est permis de faire référence à des arguments d’assemblage dans FROMune instruction, ce qui permet de sélectionner une image de base différente en fonction de 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 accessibles à partir de la chaîne dans laquelle ils sont définis. Toute instruction suivante peut faire référence à la valeur des arguments de construction créés au-dessus dans le Dockerfile. Vous devez ajouter ARGdes instructions pour tous les arguments de construction que vous utiliserez. Faire référence à un argument avant qu’il n’ait été défini, ou l’utiliser --build-argsans argument correspondant, ARGse traduira par une chaîne vide.

Les arguments de construction ne fonctionnent pas à différentes étapes de construction. Chaque étape agit comme une nouvelle construction avec son propre ensemble d’arguments de construction. ARGles instructions incluses dans les étapes précédentes n’affectent pas les suivantes à moins qu’elles ne soient répétées à chaque étape :

FROM php:latest

ARG BUILD_VERSION

DE compositeur : le plus récent

ARG BUILD_VERSION

Les deux étapes définissent explicitement BUILD_VERSIONun argument, de sorte que la valeur définie avec --build-argsera donnée à chacune d’elles.

Les considérations relatives à l’étape d’assemblage s’appliquent également lorsque vous utilisez une ARGpré – FROMinstruction. Ces arguments existent en dehors de toute étape de génération ; elles sont communes à toutes les FROMinstructions, mais elles ne peuvent pas être référencées en suivant les instructions. Si vous souhaitez réutiliser FROMl’argument de construction -level dans une étape, itérez l’ ARGinstruction pour obtenir sa valeur :

# Only applies to FROM instructions

ARG BASE_IMAGE_VERSION=alpin

À PARTIR de ma-base-d’application :2-${BASE_IMAGE_VERSION}

# Référencez l’argument de construction externe

ARG BASE_IMAGE_VERSION

# Fonctionne comme prévu

RUN echo $BASE_IMAGE_VERSION

En dehors de ces problèmes particuliers, les arguments se comportent de la même manière que les variables d’environnement à tous autres égards. Vous pouvez redéfinir leurs valeurs avec les instructions ARGet ENV, les interpoler en chaînes et les utiliser dans des expressions d’expansion de la forme ${EXAMPLE_VAR:-demo}. Ceci est choisi democomme valeur lorsque EXAMPLE_VARla variable n’est pas définie.

Arguments de construction prédéfinis

Docker prend en charge certains arguments de construction par défaut, même si vous n’incluez pas leurs ARGinstructions dans votre Dockerfile. Ils sont liés aux paramètres de proxy et fonctionnent chaque fois que le --build-argdrapeau correspondant est utilisé. Les variables sont également exclues de la docker historysortie pour éviter de révéler les informations potentiellement sensibles auxquelles elles sont destinées – plus d’informations sur cette commande et ses implications ci-dessous.

Les assemblages traités par le backend BuildKit peuvent également accéder à plusieurs autres arguments de construction prédéfinis. Ils viennent avec des valeurs saisies automatiquement. La liste comprend TARGETOS, TARGETARCH, TARGETPLATFORM, et BUILDOS, BUILDARCH, et BUILDPLATFORM, ainsi que quelques autres. Les variables décrivent les caractéristiques de l’environnement de génération et de la plateforme ciblés par la nouvelle image.

Quand utiliser les arguments de build ?

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

Ce mécanisme peut être utilisé pour modifier l’image de base d’un assemblage, modifier les commandes exécutées par les RUNinstructions et fournir des options modifiables par l’utilisateur qui fournissent des 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 souhaitez pas coder en dur dans votre Dockerfile.

Dans certaines situations, des approches alternatives doivent être utilisées. Bien que pratiques, les arguments d’assemblage ne sont pas idéaux pour les données sensibles telles que les jetons et les clés d’authentification. Comme ARGil s’agit d’une instruction Dockerfile, les variables et leurs valeurs sont visibles lorsque vous vérifiez l’image avec la docker historycommande. De cette façon, toute personne ayant accès à votre image peut voir les clés utilisées lors de la construction.

Les informations d’identification utilisées pour authentifier le processus de génération par rapport aux registres de packages et aux référentiels de contrôle de source sont mieux fournies sous la forme de secrets de génération BuildKit. Ils sont conçus pour gérer des informations sensibles et sont montés sous forme de fichiers dans l’environnement de construction plutôt que de devenir des instructions d’image.

Sommaire

Les arguments de génération vous permettent de personnaliser 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 disponibles pour les conteneurs en cours d’exécution, bien qu’ils soient toujours visibles dans l’historique des couches de l’image.

L’argument de construction est le bon choix pour les options configurables par l’utilisateur non sensibles qui affectent le processus de construction. Utilisez plutôt une variable d’environnement si vous souhaitez afficher la valeur dans l’image finale. BuildKit Secrets est la meilleure troisième option pour toutes les données précieuses auxquelles votre build doit accéder.