Come utilizzare gli argomenti di build Docker per personalizzare una build di immagini

Il meccanismo “build arguments” di Docker consente di definire variabili di ambiente a cui è possibile fare riferimento Dockerfiledurante il processo di creazione dell’immagine. A differenza delle normali ENVistruzioni, gli argomenti di assembly non sono presenti nell’immagine di output finale. Sono per quando vuoi personalizzare il processo di compilazione invece dei contenitori generati.

Definizione degli argomenti di costruzione

Definisci argomenti di build all’interno delle tue istruzioni per l’uso Dockerfile:ARG

ARG EXAMPLE_VAR

ARG DEMO_VAR

RUN echo $EXAMPLE_VAR

I due argomenti EXAMPLE_VARe DEMO_VARvengono aggiunti alla build Dockerfile sopra.

Imposta gli argomenti disponibili con un --build-argflag per docker build. Ripeti il ​​flag più volte per coprire tutti gli argomenti definiti nel tuo Dockerfile:

docker build -t example-image:latest

–build-arg ESEMPIO_VAR=valore1

–build-arg DEMO_VAR=valore2

.

La creazione di un esempio Dockerfilecon questo comando verrà passata value1al tuo terminale in fase di compilazione. La variabile EXAMPLE_VARdiventa disponibile nell’ambiente di compilazione con un valore di value1. Il componente del valore flag --build-argè facoltativo; ometterlo selezionerà automaticamente il valore della variabile nell’ambiente della shell locale.

Poiché gli argomenti build non sono archiviati nell’immagine compilata, vedrai una stringa vuota quando eseguita echo $EXAMPLE_VARall’interno di contenitori compilati da example-image:latest. Le variabili a cui fare riferimento eseguendo i contenitori devono essere aggiunte usando ENVle istruzioni di compilazione --envo i -eflag.

Sebbene non siano nell’immagine finale, gli argomenti di build influiscono comunque sulla cache di build di Docker. La modifica del valore di un argomento tra le build può causare errori nella cache per le istruzioni che seguono il primo riferimento alla variabile. L’operatore di definizione ARGnon è responsabile dell’invalidazione della cache.

FROM alpine:latest

ESEMPIO ARG_VAR

# La cache non è invalidata: arg non è stato utilizzato

ESEGUI il comando di esempio

# La cache di build non può essere utilizzata da questo momento in poi

RUN echo $EXAMPLE_VAR

Costruisci valori di default dell’argomento

All’istruzione ARGpuò essere assegnato un valore predefinito da utilizzare quando il --build-argflag corrispondente non è specificato:

ARG EXAMPLE_VAR=demo

Docker preferirà sempre il valore fornito dal --build-argflag quando disponibile. Se manca, EXAMPLE_VARverrà installato demonell’ambiente di compilazione. Ciò riduce il numero di flag che devono essere specificati durante la creazione di un’immagine con argomenti di cui raramente viene eseguito l’override.

Dove possono essere usati argomenti di costruzione?

Gli argomenti di build possono essere referenziati nelle istruzioni di Dockerfile che li seguono. Funzionano con la maggior parte dei tipi di istruzioni, inclusi RUNi comandi eseguiti in contenitori di build intermedi. Gli argomenti sono referenziati allo stesso modo delle variabili di ambiente, usando $EXAMPLE_VARla sintassi.

ARGLe istruzioni sono uniche in quanto influiscono in modo significativo sull’assemblaggio, ma possono essere utilizzate prima delle FROMistruzioni. È consentito fare riferimento ad argomenti assembly all’interno FROMdi un’istruzione, consentendo di selezionare un’immagine di base diversa a seconda della configurazione dell’utente:

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.

Gli argomenti di build sono accessibili dalla stringa in cui sono definiti. Qualsiasi istruzione seguente può fare riferimento al valore degli argomenti build creati sopra di essa nel Dockerfile. Devi aggiungere ARGle istruzioni per tutti gli argomenti di build che utilizzerai. Fare riferimento a un argomento prima che sia stato definito o utilizzarlo --build-argsenza un argomento corrispondente ARGrisulterà in una stringa vuota.

Gli argomenti di compilazione non funzionano in diversi passaggi di compilazione. Ogni fase si comporta come una nuova build con il proprio set di argomenti di build. ARGle istruzioni incluse nei passaggi precedenti non influiscono su quelli successivi a meno che non vengano ripetute in ogni passaggio:

FROM php:latest

ARG BUILD_VERSION

DA compositore: più recente

ARG BUILD_VERSION

Entrambe le fasi definiscono in modo esplicito BUILD_VERSIONun argomento, quindi il valore impostato con --build-argverrà assegnato a ciascuna di esse.

Le considerazioni sulla fase di assemblaggio si applicano anche quando si utilizza una ARGpreistruzione FROM. Questi argomenti esistono al di fuori di qualsiasi fase di costruzione; sono comuni a tutte le FROMaffermazioni, ma non possono essere referenziate seguendo le istruzioni. Se vuoi riutilizzare FROMl’argomento build -level all’interno di uno stage, itera l’ ARGistruzione per ottenere il suo valore:

# Only applies to FROM instructions

ARG BASE_IMAGE_VERSION=alpino

DA my-app-base:2-${BASE_IMAGE_VERSION}

# Fare riferimento all’argomento build esterno

ARG BASE_IMAGE_VERSION

# Funziona come previsto

RUN echo $BASE_IMAGE_VERSION

A parte questi problemi speciali, gli argomenti si comportano in modo simile alle variabili d’ambiente sotto tutti gli altri aspetti. Puoi ridefinire i loro valori con le istruzioni ARGe ENV, interpolarli in stringhe e usarli nelle espressioni di espansione del modulo ${EXAMPLE_VAR:-demo}. Viene scelto democome valore quando EXAMPLE_VARla variabile non è impostata.

Argomenti di costruzione predefiniti

Docker supporta alcuni argomenti di build per impostazione predefinita, anche se non includi le loro ARGistruzioni nel tuo Dockerfile. Sono correlati alle impostazioni del proxy e funzionano ogni volta --build-argche viene utilizzato il flag corrispondente. Le variabili sono anche escluse docker historydall’output per evitare di rivelare le informazioni potenzialmente sensibili a cui sono destinate – maggiori informazioni su questo comando e le sue implicazioni di seguito.

Gli assembly elaborati dal back-end BuildKit possono anche accedere a molti altri argomenti di compilazione predefiniti. Vengono forniti con valori inseriti automaticamente. L’elenco include TARGETOS, TARGETARCH, TARGETPLATFORM, e BUILDOS, BUILDARCH, e BUILDPLATFORM, nonché alcuni altri. Le variabili descrivono le caratteristiche dell’ambiente di compilazione e della piattaforma a cui si rivolge la nuova immagine.

Quando usare gli argomenti build?

Gli argomenti build possono essere usati per inserire la configurazione nelle build di un’immagine Docker. Questo è un modo per modificare dinamicamente l’immagine finale senza scrivere più Dockerfile.

Questo meccanismo può essere utilizzato per modificare l’immagine di base di un assembly, modificare i comandi RUNeseguiti dalle istruzioni e fornire opzioni modificabili dall’utente che forniscono opzioni di personalizzazione dell’immagine. Gli argomenti di compilazione hanno senso per la maggior parte dei valori che vengono utilizzati solo durante il processo di compilazione e che non si desidera codificare nel proprio Dockerfile.

In alcune situazioni, dovrebbero essere utilizzati approcci alternativi. Sebbene convenienti, gli argomenti di assembly non sono l’ideale per dati sensibili come token e chiavi di autenticazione. Poiché ARGsi tratta di un’istruzione Dockerfile, le variabili e i loro valori sono visibili quando controlli l’immagine con il docker historycomando. In questo modo, chiunque abbia accesso alla tua immagine può visualizzare le chiavi utilizzate durante la compilazione.

Le credenziali utilizzate per autenticare il processo di compilazione rispetto ai registri dei pacchetti e ai repository di controllo del codice sorgente vengono fornite al meglio sotto forma di segreti di compilazione BuildKit. Sono progettati per gestire informazioni riservate e vengono montati come file nell’ambiente di compilazione anziché diventare istruzioni di immagine.

Riepilogo

Gli argomenti di compilazione consentono di personalizzare le build di immagini Docker utilizzando una combinazione di istruzioni Dockerfile e argomenti della riga di comando in fase di compilazione. A differenza delle variabili di ambiente, gli argomenti di build non sono disponibili per i contenitori in esecuzione, sebbene siano ancora visibili nella cronologia dei livelli dell’immagine.

L’argomento build è la scelta giusta per le opzioni configurabili dall’utente non sensibili che influiscono sul processo di build. Utilizzare invece una variabile di ambiente se si desidera mostrare il valore nell’immagine finale. BuildKit Secrets è la migliore terza opzione per tutti i dati preziosi a cui la tua build ha bisogno di accedere.