Variables de build

Dans Docker Build, les arguments de build (ARG) et les variables d'environnement (ENV) servent tous deux de moyen pour passer des informations dans le processus de build. Vous pouvez les utiliser pour paramétrer le build, ce qui permet des builds plus flexibles et configurables.

Warning

Les arguments de build et les variables d'environnement ne sont pas appropriés pour passer des secrets à votre build, car ils sont exposés dans l'image finale. Utilisez plutôt des montages de secrets ou des montages SSH, qui exposent les secrets à vos builds en toute sécurité.

Voir Secrets de build pour plus d'informations.

Similitudes et différences

Les arguments de build et les variables d'environnement sont similaires. Ils sont tous deux déclarés dans le Dockerfile et peuvent être définis à l'aide d'indicateurs pour la commande docker build. Les deux peuvent être utilisés pour paramétrer le build. Mais ils ont chacun un but distinct.

Arguments de build

Les arguments de build sont des variables pour le Dockerfile lui-même. Utilisez-les pour paramétrer les valeurs des instructions du Dockerfile. Par exemple, vous pouvez utiliser un argument de build pour spécifier la version d'une dépendance à installer.

Les arguments de build n'ont aucun effet sur le build à moins qu'ils ne soient utilisés dans une instruction. Ils ne sont pas accessibles ou présents dans les conteneurs instanciés à partir de l'image à moins d'être explicitement passés du Dockerfile au système de fichiers ou à la configuration de l'image. Ils peuvent persister dans les métadonnées de l'image, en tant qu'attestations de provenance et dans l'historique de l'image, c'est pourquoi ils ne conviennent pas pour contenir des secrets.

Ils rendent les Dockerfiles plus flexibles et plus faciles à maintenir.

Pour un exemple sur la façon dont vous pouvez utiliser les arguments de build, voir Exemple d'utilisation de ARG.

Variables d'environnement

Les variables d'environnement sont transmises à l'environnement d'exécution du build, et persistent dans les conteneurs instanciés à partir de l'image.

Les variables d'environnement sont principalement utilisées pour :

• Configurer l'environnement d'exécution pour les builds
• Définir les variables d'environnement par défaut pour les conteneurs

Les variables d'environnement, si elles sont définies, peuvent directement influencer l'exécution de votre build, et le comportement ou la configuration de l'application.

Vous ne pouvez pas remplacer ou définir une variable d'environnement au moment du build. Les valeurs des variables d'environnement doivent être déclarées dans le Dockerfile. Vous pouvez combiner des variables d'environnement et des arguments de build pour permettre aux variables d'environnement d'être configurées au moment du build.

Pour un exemple sur la façon d'utiliser les variables d'environnement pour configurer les builds, voir Exemple d'utilisation de ENV.

Exemple d'utilisation de ARG

Les arguments de build sont couramment utilisés pour spécifier les versions des composants, tels que les variantes d'images ou les versions de packages, utilisés dans un build.

Spécifier les versions en tant qu'arguments de build vous permet de construire avec différentes versions sans avoir à mettre à jour manuellement le Dockerfile. Cela facilite également la maintenance du Dockerfile, car cela vous permet de déclarer les versions en haut du fichier.

Les arguments de build peuvent également être un moyen de réutiliser une valeur à plusieurs endroits. Par exemple, si vous utilisez plusieurs saveurs d'alpine dans votre build, vous pouvez vous assurer que vous utilisez la même version d'alpine partout :

• golang:1.22-alpine${ALPINE_VERSION}
• python:3.12-alpine${ALPINE_VERSION}
• nginx:1-alpine${ALPINE_VERSION}

L'exemple suivant définit la version de node et alpine à l'aide d'arguments de build.

# syntax=docker/dockerfile:1

ARG NODE_VERSION="20"
ARG ALPINE_VERSION="3.21"

FROM node:${NODE_VERSION}-alpine${ALPINE_VERSION} AS base
WORKDIR /src

FROM base AS build
COPY package*.json ./
RUN npm ci
RUN npm run build

FROM base AS production
COPY package*.json ./
RUN npm ci --omit=dev && npm cache clean --force
COPY --from=build /src/dist/ .
CMD ["node", "app.js"]

Dans ce cas, les arguments de build ont des valeurs par défaut. Spécifier leurs valeurs lorsque vous invoquez un build est facultatif. Pour remplacer les valeurs par défaut, vous utiliseriez l'indicateur CLI --build-arg :

$ docker build --build-arg NODE_VERSION=current .

Pour plus d'informations sur la façon d'utiliser les arguments de build, reportez-vous à :

• Référence Dockerfile ARG
• Référence docker build --build-arg

Exemple d'utilisation de ENV

La déclaration d'une variable d'environnement avec ENV rend la variable disponible pour toutes les instructions suivantes dans l'étape de build. L'exemple suivant montre un exemple de définition de NODE_ENV sur production avant d'installer les dépendances JavaScript avec npm. La définition de la variable fait que npm omet les packages nécessaires uniquement pour le développement local.

# syntax=docker/dockerfile:1

FROM node:20
WORKDIR /app
COPY package*.json ./
ENV NODE_ENV=production
RUN npm ci && npm cache clean --force
COPY . .
CMD ["node", "app.js"]

Les variables d'environnement не sont pas configurables au moment du build par défaut. Si vous souhaitez modifier la valeur d'un ENV au moment du build, vous pouvez combiner des variables d'environnement et des arguments de build :

# syntax=docker/dockerfile:1

FROM node:20
ARG NODE_ENV=production
ENV NODE_ENV=$NODE_ENV
WORKDIR /app
COPY package*.json ./
RUN npm ci && npm cache clean --force
COPY . .
CMD ["node", "app.js"]

Avec ce Dockerfile, vous pouvez utiliser --build-arg pour remplacer la valeur par défaut de NODE_ENV :

$ docker build --build-arg NODE_ENV=development .

Notez que, comme les variables d'environnement que vous définissez persistent dans les conteneurs, leur utilisation peut entraîner des effets secondaires involontaires pour l'exécution de l'application.

Pour plus d'informations sur la façon d'utiliser les variables d'environnement dans les builds, reportez-vous à :

• Référence Dockerfile ENV

Portée

Les arguments de build déclarés dans la portée globale d'un Dockerfile ne sont pas automatiquement hérités dans les étapes de build. Ils ne sont accessibles que dans la portée globale.

# syntax=docker/dockerfile:1

# L'argument de build suivant est déclaré dans la portée globale :
ARG NAME="joe"

FROM alpine
# L'instruction suivante n'a pas accès à l'argument de build $NAME
# car l'argument a été défini dans la portée globale, pas pour cette étape.
RUN echo "hello ${NAME}!"

La commande echo dans cet exemple s'évalue à hello ! car la valeur de l'argument de build NAME est hors de portée. Pour hériter des arguments de build globaux dans une étape, vous devez les consommer :

# syntax=docker/dockerfile:1

# Déclarer l'argument de build dans la portée globale
ARG NAME="joe"

FROM alpine
# Consommer l'argument de build dans l'étape de build
ARG NAME
RUN echo $NAME

Une fois qu'un argument de build est déclaré ou consommé dans une étape, il est automatiquement hérité par les étapes enfants.

# syntax=docker/dockerfile:1
FROM alpine AS base
# Déclarer l'argument de build dans l'étape de build
ARG NAME="joe"

# Créer une nouvelle étape basée sur "base"
FROM base AS build
# L'argument de build NAME est disponible ici
# car il est déclaré dans une étape parente
RUN echo "hello $NAME!"

Le diagramme suivant illustre encore davantage comment l'héritage des arguments de build et des variables d'environnement fonctionne pour les builds multi-étapes.

Arguments de build prédéfinis

Cette section décrit les arguments de build prédéfinis disponibles pour tous les builds par défaut.

Arguments de build multi-plateforme

Les arguments de build multi-plateforme décrivent la plateforme de build et la plateforme cible pour le build.

La plateforme de build est le système d'exploitation, l'architecture et la variante de plateforme du système hôte où le constructeur (le démon BuildKit) est en cours d'exécution.

• BUILDPLATFORM
• BUILDOS
• BUILDARCH
• BUILDVARIANT

Les arguments de plateforme cible contiennent les mêmes valeurs pour les plateformes cibles du build, spécifiées à l'aide du drapeau --platform pour la commande docker build.

• TARGETPLATFORM
• TARGETOS
• TARGETARCH
• TARGETVARIANT

Ces arguments sont utiles pour la cross-compilation dans les builds multi-plateforme. Ils sont disponibles dans la portée globale du Dockerfile, mais ils ne sont pas automatiquement hérités par les étapes de build. Pour les utiliser à l'intérieur d'une étape, vous devez les déclarer :

# syntax=docker/dockerfile:1

# Les arguments de build prédéfinis sont disponibles dans la portée globale
FROM --platform=$BUILDPLATFORM golang
# Pour les hériter dans une étape, déclarez-les avec ARG
ARG TARGETOS
RUN GOOS=$TARGETOS go build -o ./exe .

Pour plus d'informations sur les arguments de build multi-plateforme, reportez-vous à Arguments multi-plateforme

Arguments de proxy

Les arguments de proxy permettent de spécifier des proxies à utiliser pour votre build. Vous n'avez pas besoin de les déclarer ou de les référencer dans le Dockerfile. La spécification d'un proxy avec --build-arg est suffisante pour faire fonctionner votre build avec le proxy.

Les arguments de proxy sont automatiquement exclus du cache de build et de la sortie de docker history par défaut. Si vous faites référence aux arguments dans votre Dockerfile, la configuration du proxy se retrouve dans le cache de build.

Le constructeur respecte les arguments de proxy suivants. Les variables sont insensibles à la casse.

• HTTP_PROXY
• HTTPS_PROXY
• FTP_PROXY
• NO_PROXY
• ALL_PROXY

Pour configurer un proxy pour votre build :

$ docker build --build-arg HTTP_PROXY=https://my-proxy.example.com .

Pour plus d'informations sur les arguments de proxy de build, reportez-vous à Arguments de proxy.

Variables de configuration de l'outil de build

Les variables d'environnement suivantes permettent d'activer, de désactiver ou de modifier le comportement de Buildx et BuildKit. Notez que ces variables ne sont pas utilisées pour configurer le conteneur de build ; elles ne sont pas disponibles à l'intérieur du build et elles n'ont aucun lien avec l'instruction ENV. Elles sont utilisées pour configurer le client Buildx ou le démon BuildKit.

BuildKit prend également en charge quelques paramètres de configuration supplémentaires. Reportez-vous à Arguments de build intégrés à BuildKit.

Vous pouvez exprimer des valeurs booléennes pour les variables d'environnement de différentes manières. Par exemple, true, 1 et T évaluent tous à true. L'évaluation est effectuée à l'aide de la fonction strconv.ParseBool de la bibliothèque standard Go. Voir la documentation de référence pour plus de détails.

BUILDKIT_COLORS

Changes the colors of the terminal output. Set BUILDKIT_COLORS to a CSV string in the following format:

$ export BUILDKIT_COLORS="run=123,20,245:error=yellow:cancel=blue:warning=white"

Color values can be any valid RGB hex code, or one of the BuildKit predefined colors.

Setting NO_COLOR to anything turns off colorized output, as recommended by no-color.org.

BUILDKIT_HOST

You use the BUILDKIT_HOST to specify the address of a BuildKit daemon to use as a remote builder. This is the same as specifying the address as a positional argument to docker buildx create.

Usage:

$ export BUILDKIT_HOST=tcp://localhost:1234
$ docker buildx create --name=remote --driver=remote

If you specify both the BUILDKIT_HOST environment variable and a positional argument, the argument takes priority.

BUILDKIT_PROGRESS

Sets the type of the BuildKit progress output. Valid values are:

• auto (default)
• plain
• tty
• quiet
• rawjson

Usage:

$ export BUILDKIT_PROGRESS=plain

BUILDKIT_TTY_LOG_LINES

You can change how many log lines are visible for active steps in TTY mode by setting BUILDKIT_TTY_LOG_LINES to a number (default to 6).

$ export BUILDKIT_TTY_LOG_LINES=8

EXPERIMENTAL_BUILDKIT_SOURCE_POLICY

Lets you specify a BuildKit source policy file for creating reproducible builds with pinned dependencies.

$ export EXPERIMENTAL_BUILDKIT_SOURCE_POLICY=./policy.json

Example:

{
  "rules": [
    {
      "action": "CONVERT",
      "selector": {
        "identifier": "docker-image://docker.io/library/alpine:latest"
      },
      "updates": {
        "identifier": "docker-image://docker.io/library/alpine:latest@sha256:4edbd2beb5f78b1014028f4fbb99f3237d9561100b6881aabbf5acce2c4f9454"
      }
    },
    {
      "action": "CONVERT",
      "selector": {
        "identifier": "https://raw.githubusercontent.com/moby/buildkit/v0.10.1/README.md"
      },
      "updates": {
        "attrs": {"http.checksum": "sha256:6e4b94fc270e708e1068be28bd3551dc6917a4fc5a61293d51bb36e6b75c4b53"}
      }
    },
    {
      "action": "DENY",
      "selector": {
        "identifier": "docker-image://docker.io/library/golang*"
      }
    }
  ]
}

BUILDX_BAKE_GIT_AUTH_HEADER

Sets the HTTP authentication scheme when using a remote Bake definition in a private Git repository. This is equivalent to the GIT_AUTH_HEADER secret, but facilitates the pre-flight authentication in Bake when loading the remote Bake file. Supported values are bearer (default) and basic.

Usage:

$ export BUILDX_BAKE_GIT_AUTH_HEADER=basic

BUILDX_BAKE_GIT_AUTH_TOKEN

Sets the HTTP authentication token when using a remote Bake definition in a private Git repository. This is equivalent to the GIT_AUTH_TOKEN secret, but facilitates the pre-flight authentication in Bake when loading the remote Bake file.

Usage:

$ export BUILDX_BAKE_GIT_AUTH_TOKEN=$(cat git-token.txt)

BUILDX_BAKE_GIT_SSH

Lets you specify a list of SSH agent socket filepaths to forward to Bake for authenticating to a Git server when using a remote Bake definition in a private repository. This is similar to SSH mounts for builds, but facilitates the pre-flight authentication in Bake when resolving the build definition.

Setting this environment is typically not necessary, because Bake will use the SSH_AUTH_SOCK agent socket by default. You only need to specify this variable if you want to use a socket with a different filepath. This variable can take multiple paths using a comma-separated string.

Usage:

$ export BUILDX_BAKE_GIT_SSH=/run/foo/listener.sock,~/.creds/ssh.sock

BUILDX_BUILDER

Overrides the configured builder instance. Same as the docker buildx --builder CLI flag.

Usage:

$ export BUILDX_BUILDER=my-builder

BUILDX_CONFIG

You can use BUILDX_CONFIG to specify the directory to use for build configuration, state, and logs. The lookup order for this directory is as follows:

• $BUILDX_CONFIG
• $DOCKER_CONFIG/buildx
• ~/.docker/buildx (default)

Usage:

$ export BUILDX_CONFIG=/usr/local/etc

BUILDX_CPU_PROFILE

If specified, Buildx generates a pprof CPU profile at the specified location.

Note

This property is only useful for when developing Buildx. The profiling data is not relevant for analyzing a build's performance.

Usage:

$ export BUILDX_CPU_PROFILE=buildx_cpu.prof

BUILDX_EXPERIMENTAL

Enables experimental build features.

Usage:

$ export BUILDX_EXPERIMENTAL=1

BUILDX_GIT_CHECK_DIRTY

When set to true, checks for dirty state in source control information for provenance attestations.

Usage:

$ export BUILDX_GIT_CHECK_DIRTY=1

BUILDX_GIT_INFO

When set to false, removes source control information from provenance attestations.

Usage:

$ export BUILDX_GIT_INFO=0

BUILDX_GIT_LABELS

Adds provenance labels, based on Git information, to images that you build. The labels are:

• com.docker.image.source.entrypoint: Location of the Dockerfile relative to the project root
• org.opencontainers.image.revision: Git commit revision
• org.opencontainers.image.source: SSH or HTTPS address of the repository

Example:

  "Labels": {
    "com.docker.image.source.entrypoint": "Dockerfile",
    "org.opencontainers.image.revision": "5734329c6af43c2ae295010778cd308866b95d9b",
    "org.opencontainers.image.source": "[email protected]:foo/bar.git"
  }

Usage:

• Set BUILDX_GIT_LABELS=1 to include the entrypoint and revision labels.
• Set BUILDX_GIT_LABELS=full to include all labels.

If the repository is in a dirty state, the revision gets a -dirty suffix.

BUILDX_MEM_PROFILE

If specified, Buildx generates a pprof memory profile at the specified location.

Note

This property is only useful for when developing Buildx. The profiling data is not relevant for analyzing a build's performance.

Usage:

$ export BUILDX_MEM_PROFILE=buildx_mem.prof

BUILDX_METADATA_PROVENANCE

By default, Buildx includes minimal provenance information in the metadata file through --metadata-file flag. This environment variable allows you to customize the provenance information included in the metadata file:

• min sets minimal provenance (default).
• max sets full provenance.
• disabled, false or 0 does not set any provenance.

BUILDX_METADATA_WARNINGS

By default, Buildx does not include build warnings in the metadata file through --metadata-file flag. You can set this environment variable to 1 or true to include them.

BUILDX_NO_DEFAULT_ATTESTATIONS

By default, BuildKit v0.11 and later adds provenance attestations to images you build. Set BUILDX_NO_DEFAULT_ATTESTATIONS=1 to disable the default provenance attestations.

Usage:

$ export BUILDX_NO_DEFAULT_ATTESTATIONS=1

BUILDX_NO_DEFAULT_LOAD

When you build an image using the docker driver, the image is automatically loaded to the image store when the build finishes. Set BUILDX_NO_DEFAULT_LOAD to disable automatic loading of images to the local container store.

Usage:

$ export BUILDX_NO_DEFAULT_LOAD=1