Variables de compilación

En Docker Build, tanto los argumentos de compilación (ARG) como las variables de entorno (ENV) sirven como un medio para pasar información al proceso de compilación. Puedes utilizarlos para parametrizar la compilación, lo que permite obtener compilaciones más flexibles y configurables.

Warning

Los argumentos de compilación y las variables de entorno no son adecuados para pasar secretos a tu compilación porque quedan expuestos en la imagen final. En su lugar, utiliza montajes de secretos o montajes SSH, que exponen los secretos a tus compilaciones de forma segura.

Consulta la documentación de Secretos de compilación para obtener más información.

Similitudes y diferencias

Los argumentos de compilación y las variables de entorno son similares. Ambos se declaran en el Dockerfile y se pueden configurar mediante opciones para el comando docker build. Ambos se pueden utilizar para parametrizar la compilación. Sin embargo, cada uno sirve para un propósito distinto.

Argumentos de compilación

Los argumentos de compilación son variables para el propio Dockerfile. Úsalos para parametrizar los valores de las instrucciones del Dockerfile. Por ejemplo, podrías usar un argumento de compilación para especificar la versión de una dependencia que deseas instalar.

Los argumentos de compilación no tienen ningún efecto en la compilación a menos que se utilicen en una instrucción. No son accesibles ni están presentes en los contenedores instanciados a partir de la imagen a menos que se pasen explícitamente desde el Dockerfile al sistema de archivos o a la configuración de la imagen. Pueden persistir en los metadatos de la imagen, como atestaciones de procedencia (provenance) y en el historial de la imagen, por lo que no son adecuados para contener secretos.

Hacen que los Dockerfiles sean más flexibles y fáciles de mantener.

Para ver un ejemplo de cómo puedes utilizar los argumentos de compilación, consulta la sección Ejemplo de uso de ARG.

Variables de entorno

Las variables de entorno se transmiten al entorno de ejecución de la compilación y persisten en los contenedores instanciados a partir de la imagen.

Las variables de entorno se utilizan principalmente para:

• Configurar el entorno de ejecución para las compilaciones
• Establecer variables de entorno predeterminadas para los contenedores

Las variables de entorno, si se configuran, pueden influir directamente en la ejecución de la compilación y en el comportamiento o la configuración de la aplicación.

No puedes sobrescribir o establecer una variable de entorno en tiempo de compilación. Los valores de las variables de entorno deben declararse en el Dockerfile. Puedes combinar variables de entorno y argumentos de compilación para permitir que las variables de entorno se configuren en tiempo de compilación.

Para ver un ejemplo de cómo utilizar las variables de entorno para configurar las compilaciones, consulta la sección Ejemplo de uso de ENV.

Ejemplo de uso de ARG

Los argumentos de compilación se utilizan comúnmente para especificar versiones de componentes, como variantes de imagen o versiones de paquetes, utilizados en una compilación.

Especificar versiones como argumentos de compilación te permite compilar con diferentes versiones sin tener que actualizar manualmente el Dockerfile. También facilita el mantenimiento del Dockerfile, ya que te permite declarar las versiones en la parte superior del archivo.

Los argumentos de compilación también pueden ser una forma de reutilizar un valor en varios lugares. Por ejemplo, si utilizas varias variantes de alpine en tu compilación, puedes asegurarte de estar utilizando la misma versión de alpine en todas partes:

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

El siguiente ejemplo define la versión de node y alpine utilizando argumentos de compilación.

# syntax=docker/dockerfile:1

ARG NODE_VERSION="24"
ARG ALPINE_VERSION="3.23"

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"]

En este caso, los argumentos de compilación tienen valores predeterminados. Especificar sus valores al invocar una compilación es opcional. Para sobrescribir los valores predeterminados, utilizarías la opción --build-arg de la CLI:

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

Para obtener más información sobre cómo utilizar los argumentos de compilación, consulta:

• Referencia de ARG en Dockerfile
• Referencia de docker build --build-arg

Ejemplo de uso de ENV

Declarar una variable de entorno con ENV hace que la variable esté disponible para todas las instrucciones posteriores en la etapa de compilación. El siguiente ejemplo muestra un caso en el que se establece NODE_ENV como production antes de instalar las dependencias de JavaScript con npm. Establecer esta variable hace que npm omita los paquetes necesarios únicamente para el desarrollo 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"]

Las variables de entorno no son configurables en tiempo de compilación por defecto. Si deseas cambiar el valor de un ENV en tiempo de compilación, puedes combinar variables de entorno y argumentos de compilación:

# 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"]

Con este Dockerfile, puedes usar --build-arg para sobrescribir el valor predeterminado de NODE_ENV:

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

Ten en cuenta que, debido a que las variables de entorno que configuras persisten en los contenedores, su uso puede provocar efectos secundarios no deseados en el tiempo de ejecución de la aplicación.

Para obtener más información sobre cómo utilizar variables de entorno en las compilaciones, consulta:

• Referencia de ENV en Dockerfile

Alcance (Scoping)

Los argumentos de compilación declarados en el alcance global de un Dockerfile no se heredan automáticamente en las etapas de compilación. Solo son accesibles en el alcance global.

# syntax=docker/dockerfile:1

# El siguiente argumento de compilación se declara en el alcance global:
ARG NAME="joe"

FROM alpine
# La siguiente instrucción no tiene acceso al argumento de compilación $NAME
# porque el argumento se definió en el alcance global, no para esta etapa.
RUN echo "hello ${NAME}!"

El comando echo en este ejemplo se evalúa como hello ! porque el valor del argumento de compilación NAME está fuera de alcance. Para heredar argumentos de compilación globales en una etapa, debes consumirlos:

# syntax=docker/dockerfile:1

# Declarar el argumento de compilación en el alcance global
ARG NAME="joe"

FROM alpine
# Consumir el argumento de compilación en la etapa de compilación
ARG NAME
RUN echo $NAME

Una vez que un argumento de compilación se declara o consume en una etapa, es heredado automáticamente por las etapas secundarias.

# syntax=docker/dockerfile:1
FROM alpine AS base
# Declarar el argumento de compilación en la etapa de compilación
ARG NAME="joe"

# Crear una nueva etapa basada en "base"
FROM base AS build
# El argumento de compilación NAME está disponible aquí
# ya que está declarado en una etapa padre
RUN echo "hello $NAME!"

El siguiente diagrama ejemplifica aún más cómo funciona la herencia de argumentos de compilación y variables de entorno para compilaciones multi-etapa.

Argumentos de compilación predefinidos

Esta sección describe los argumentos de compilación predefinidos disponibles para todas las compilaciones por defecto.

Argumentos de compilación multiplataforma

Los argumentos de compilación multiplataforma describen las plataformas de compilación y de destino para la compilación.

La plataforma de compilación es el sistema operativo, la arquitectura y la variante de plataforma del sistema host donde se ejecuta el builder (el demonio BuildKit).

• BUILDPLATFORM
• BUILDOS
• BUILDARCH
• BUILDVARIANT

Los argumentos de plataforma de destino contienen los mismos valores para las plataformas de destino de la compilación, especificadas mediante la opción --platform para el comando docker build.

• TARGETPLATFORM
• TARGETOS
• TARGETARCH
• TARGETVARIANT

Estos argumentos son útiles para realizar la compilación cruzada en compilaciones multiplataforma. Están disponibles en el alcance global del Dockerfile, pero no son heredados automáticamente por las etapas de compilación. Para utilizarlos dentro de una etapa, debes declararlos:

# syntax=docker/dockerfile:1

# Los argumentos de compilación predefinidos están disponibles en el alcance global
FROM --platform=$BUILDPLATFORM golang
# Para heredarlos a una etapa, decláralos con ARG
ARG TARGETOS
RUN GOOS=$TARGETOS go build -o ./exe .

Para obtener más información sobre los argumentos de compilación multiplataforma, consulta la sección Argumentos automáticos de plataforma en el alcance global

Argumentos de proxy

Los argumentos de compilación de proxy te permiten especificar los proxies a utilizar para tu compilación. No necesitas declarar ni hacer referencia a estos argumentos en el Dockerfile. Especificar un proxy con --build-arg es suficiente para que tu compilación utilice el proxy.

Los argumentos de proxy se excluyen automáticamente del caché de compilación y de la salida de docker history por defecto. Si haces referencia a los argumentos en tu Dockerfile, la configuración del proxy terminará en el caché de compilación.

El builder respeta los siguientes argumentos de compilación de proxy. Las variables no distinguen entre mayúsculas y minúsculas.

• HTTP_PROXY
• HTTPS_PROXY
• FTP_PROXY
• NO_PROXY
• ALL_PROXY

Para configurar un proxy para tu compilación:

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

Para obtener más información sobre los argumentos de compilación de proxy, consulta la sección Argumentos de proxy.

Variables de configuración de la herramienta de compilación

Las siguientes variables de entorno habilitan, deshabilitan o cambian el comportamiento de Buildx y BuildKit. Ten en cuenta que estas variables no se utilizan para configurar el contenedor de compilación; no están disponibles dentro de la compilación y no tienen relación con la instrucción ENV. Se utilizan para configurar el cliente Buildx o el demonio BuildKit.

BuildKit también admite algunos parámetros de configuración adicionales. Consulta la sección Argumentos de compilación integrados de BuildKit.

Puedes expresar valores booleanos para las variables de entorno de diferentes maneras. Por ejemplo, true, 1 y T se evalúan como verdadero. La evaluación se realiza utilizando la función strconv.ParseBool de la biblioteca estándar de Go. Consulta la documentación de referencia para obtener más detalles.

BUILDKIT_COLORS

Cambia los colores de la salida de la terminal. Establece BUILDKIT_COLORS en una cadena CSV con el siguiente formato:

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

Los valores de color pueden ser cualquier código hexadecimal RGB válido, o uno de los colores predefinidos de BuildKit.

Establecer NO_COLOR en cualquier valor desactiva la salida coloreada, tal como lo recomienda no-color.org.

BUILDKIT_HOST

Utilizas BUILDKIT_HOST para especificar la dirección de un demonio BuildKit para usarlo como un builder remoto. Esto es lo mismo que especificar la dirección como un argumento posicional para docker buildx create.

Uso:

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

Si especificas tanto la variable de entorno BUILDKIT_HOST como un argumento posicional, el argumento tiene prioridad.

BUILDKIT_PROGRESS

Establece el tipo de salida de progreso de BuildKit. Los valores válidos son:

• auto (predeterminado): utiliza automáticamente tty en terminales interactivas, y plain en caso contrario
• plain: muestra los pasos de compilación secuencialmente en formato de texto simple
• tty: salida interactiva con barras de progreso formateadas y pasos de compilación
• quiet: suprime la salida de progreso, solo muestra errores y el ID de la imagen final
• none: sin salida de progreso, solo muestra errores
• rawjson: muestra el progreso de la compilación como JSON sin procesar (útil para ser analizado por otras herramientas)

Uso:

$ export BUILDKIT_PROGRESS=plain

BUILDKIT_TTY_LOG_LINES

Puedes cambiar cuántas líneas de registro son visibles para los pasos activos en modo TTY estableciendo BUILDKIT_TTY_LOG_LINES en un número (por defecto es 6).

$ export BUILDKIT_TTY_LOG_LINES=8

EXPERIMENTAL_BUILDKIT_SOURCE_POLICY

Te permite especificar un archivo de política de origen de BuildKit para crear compilaciones reproducibles con dependencias fijadas.

$ export EXPERIMENTAL_BUILDKIT_SOURCE_POLICY=./policy.json

Ejemplo:

{
  "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_FILE

Especifica uno o más archivos de definición de compilación para docker buildx bake.

Esta variable de entorno proporciona una alternativa a la opción de línea de comandos -f / --file.

Se pueden especificar múltiples archivos separándolos con el separador de rutas del sistema (":" en Linux/macOS, ";" en Windows):

export BUILDX_BAKE_FILE=file1.hcl:file2.hcl

O con un separador personalizado definido por la variable BUILDX_BAKE_FILE_SEPARATOR:

export BUILDX_BAKE_FILE_SEPARATOR=@
export [email protected]

Si se establecen tanto BUILDX_BAKE_FILE como la opción -f, solo se utilizarán los archivos proporcionados a través de -f.

Si un archivo de la lista no existe o no es válido, bake devuelve un error.

BUILDX_BAKE_FILE_SEPARATOR

Controla el separador utilizado entre las rutas de archivos en la variable de entorno BUILDX_BAKE_FILE.

Esto es útil si las rutas de tus archivos contienen el carácter separador predeterminado o si deseas estandarizar los separadores en diferentes plataformas.

export BUILDX_BAKE_PATH_SEPARATOR=@
export [email protected]

BUILDX_BAKE_GIT_AUTH_HEADER

Establece el esquema de autenticación HTTP al usar una definición de Bake remota en un repositorio Git privado. Esto es equivalente al secreto GIT_AUTH_HEADER, pero facilita la autenticación previa en Bake al cargar el archivo Bake remoto. Los valores admitidos son bearer (predeterminado) y basic.

Uso:

$ export BUILDX_BAKE_GIT_AUTH_HEADER=basic

BUILDX_BAKE_GIT_AUTH_TOKEN

Establece el token de autenticación HTTP cuando se utiliza una definición de Bake remota en un repositorio Git privado. Esto es equivalente al secreto GIT_AUTH_TOKEN, pero facilita la autenticación previa en Bake al cargar el archivo Bake remoto.

Uso:

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

BUILDX_BAKE_GIT_SSH

Te permite especificar una lista de rutas de socket del agente SSH para reenviar a Bake para autenticarte en un servidor Git cuando utilizas una definición de Bake remota en un repositorio privado. Esto es similar a los montajes SSH para compilaciones, pero facilita la autenticación previa en Bake al resolver la definición de compilación.

Por lo general, no es necesario configurar esta variable de entorno porque Bake utilizará el socket del agente SSH_AUTH_SOCK por defecto. Solo necesitas especificar esta variable si deseas usar un socket con una ruta de archivo diferente. Esta variable puede aceptar múltiples rutas utilizando una cadena separada por comas.

Uso:

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

BUILDX_BUILDER

Sobrescribe la instancia del builder configurada. Es lo mismo que la opción de CLI docker buildx --builder.

Uso:

$ export BUILDX_BUILDER=my-builder

BUILDX_CONFIG

Puedes usar BUILDX_CONFIG para especificar el directorio a utilizar para la configuración de compilación, el estado y los registros. El orden de búsqueda para este directorio es el siguiente:

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

Uso:

$ export BUILDX_CONFIG=/usr/local/etc

BUILDX_CPU_PROFILE

Si se especifica, Buildx genera un perfil de CPU pprof en la ubicación especificada.

Note

Esta propiedad solo es útil cuando se desarrolla Buildx. Los datos de perfilado no son relevantes para analizar el rendimiento de una compilación.

Uso:

$ export BUILDX_CPU_PROFILE=buildx_cpu.prof

BUILDX_EXPERIMENTAL

Habilita características de compilación experimentales.

Uso:

$ export BUILDX_EXPERIMENTAL=1

BUILDX_GIT_CHECK_DIRTY

Cuando se establece en true, busca un estado modificado (dirty) en la información del control de código fuente para las atestaciones de procedencia (provenance).

Uso:

$ export BUILDX_GIT_CHECK_DIRTY=1

BUILDX_GIT_INFO

Cuando se establece en false, elimina la información del control de código fuente de las atestaciones de procedencia (provenance).

Uso:

$ export BUILDX_GIT_INFO=0

BUILDX_GIT_LABELS

Añade etiquetas de procedencia, basadas en la información de Git, a las imágenes que compilas. Las etiquetas son:

• com.docker.image.source.entrypoint: Ubicación del Dockerfile relativa a la raíz del proyecto
• org.opencontainers.image.revision: Revisión del commit de Git
• org.opencontainers.image.source: Dirección SSH o HTTPS del repositorio

Ejemplo:

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

Uso:

• Establece BUILDX_GIT_LABELS=1 para incluir las etiquetas entrypoint y revision.
• Establece BUILDX_GIT_LABELS=full para incluir todas las etiquetas.

Si el repositorio está en un estado modificado (dirty), la revisión revision obtiene el sufijo -dirty.

BUILDX_MEM_PROFILE

Si se especifica, Buildx genera un perfil de memoria pprof en la ubicación especificada.

Note

Esta propiedad solo es útil cuando se desarrolla Buildx. Los datos de perfilado no son relevantes para analizar el rendimiento de una compilación.

Uso:

$ export BUILDX_MEM_PROFILE=buildx_mem.prof

BUILDX_METADATA_PROVENANCE

Por defecto, Buildx incluye información de procedencia mínima en el archivo de metadatos a través de la opción --metadata-file. Esta variable de entorno te permite personalizar la información de procedencia incluida en el archivo de metadatos:

• min establece la procedencia mínima (predeterminado).
• max establece la procedencia completa.
• disabled, false o 0 no establece ninguna procedencia.

BUILDX_METADATA_WARNINGS

Por defecto, Buildx no incluye advertencias de compilación en el archivo de metadatos a través de la opción --metadata-file. Puedes establecer esta variable de entorno en 1 o true para incluirlas.

BUILDX_NO_DEFAULT_ATTESTATIONS

Por defecto, BuildKit v0.11 y posteriores añaden atestaciones de procedencia (provenance) a las imágenes que compilas. Establece BUILDX_NO_DEFAULT_ATTESTATIONS=1 para desactivar las atestaciones de procedencia predeterminadas.

Uso:

$ export BUILDX_NO_DEFAULT_ATTESTATIONS=1

BUILDX_NO_DEFAULT_LOAD

Cuando compilas una imagen utilizando el controlador docker, la imagen se carga automáticamente en el almacenamiento de imágenes cuando finaliza la compilación. Establece BUILDX_NO_DEFAULT_LOAD para desactivar la carga automática de imágenes en el almacenamiento local de contenedores.

Uso:

$ export BUILDX_NO_DEFAULT_LOAD=1