Como usar os argumentos de compilação do Docker para personalizar uma compilação de imagem

O mecanismo de “argumentos de compilação” do Docker permite definir variáveis ​​de ambiente que podem ser referenciadas Dockerfiledurante o processo de compilação da imagem. Ao contrário das instruções normais ENV, os argumentos do assembly não estão presentes na imagem de saída final. Eles são para quando você deseja personalizar o processo de construção em vez dos contêineres gerados.

Definindo argumentos de construção

Você define argumentos de construção dentro de suas instruções de uso Dockerfile:ARG

ARG EXAMPLE_VAR

ARG DEMO_VAR

RUN echo $EXAMPLE_VAR

Os dois argumentos EXAMPLE_VARe DEMO_VARsão adicionados à compilação do Dockerfile acima.

Você define os argumentos disponíveis com um --build-argsinalizador para docker build. Repita o sinalizador várias vezes para cobrir todos os argumentos definidos em seu Dockerfile:

docker build -t example-image:latest

–build-arg EXAMPLE_VAR=valor1

–build-arg DEMO_VAR=valor2

.

A criação de uma amostra Dockerfilecom este comando será passada value1para o seu terminal no momento da compilação. A variável EXAMPLE_VARfica disponível no ambiente de compilação com um valor de value1. O componente do valor do sinalizador --build-argé opcional; a omissão dele selecionará automaticamente o valor da variável em seu ambiente shell local.

Como os argumentos de compilação não são armazenados na imagem criada, você verá uma string vazia quando executado echo $EXAMPLE_VARdentro de contêineres criados a partir do example-image:latest. As variáveis ​​que devem ser referenciadas por contêineres em execução devem ser adicionadas usando ENVinstruções de compilação --envou -esinalizadores.

Embora não estejam na imagem final, os argumentos de compilação ainda afetam o cache de compilação do Docker. Alterar o valor de um argumento entre compilações pode causar falhas de cache para instruções que seguem a primeira referência de variável. ARGO operador de definição não é responsável pela invalidação do cache.

FROM alpine:latest

ARG EXAMPLE_VAR

# Cache não é invalidado—arg não foi usado

Comando-exemplo RUN

# Build cache não pode ser usado a partir deste ponto

RUN echo $EXAMPLE_VAR

Valores padrão do argumento de compilação

A instrução ARGpode receber um valor padrão para uso quando o --build-argsinalizador correspondente não for especificado:

ARG EXAMPLE_VAR=demo

O Docker sempre preferirá o valor fornecido pelo --build-argsinalizador quando disponível. Se estiver faltando, EXAMPLE_VARele será instalado demono ambiente de compilação. Isso reduz o número de sinalizadores que devem ser especificados ao criar uma imagem com argumentos que raramente são substituídos.

Onde os argumentos de construção podem ser usados?

Os argumentos de compilação podem ser referenciados nas instruções do Dockerfile que os seguem. Eles funcionam com a maioria dos tipos de instruções, incluindo RUNcomandos executados em contêineres de compilação intermediários. Os argumentos são referenciados da mesma forma que as variáveis ​​de ambiente, usando $EXAMPLE_VARsintaxe.

ARGAs instruções são exclusivas porque afetam significativamente a montagem, mas podem ser usadas antes das FROMinstruções. É permitido fazer referência a argumentos de assembly dentro de FROMuma instrução, permitindo que uma imagem base diferente seja selecionada dependendo da configuração do usuário:

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.

Os argumentos de construção são acessíveis a partir da string na qual são definidos. Qualquer instrução a seguir pode se referir ao valor dos argumentos de compilação criados acima dela no Dockerfile. Você deve adicionar ARGinstruções para quaisquer argumentos de construção que você usará. Fazer referência a um argumento antes que ele tenha sido definido ou usá-lo --build-argsem um argumento correspondente ARGresultará em uma string vazia.

Os argumentos de compilação não funcionam em diferentes etapas de compilação. Cada estágio funciona como uma nova compilação com seu próprio conjunto de argumentos de compilação. ARGas instruções incluídas nas etapas anteriores não afetam as posteriores, a menos que sejam repetidas em cada etapa:

FROM php:latest

ARG BUILD_VERSION

DO compositor: mais recente

ARG BUILD_VERSION

Ambos os estágios definem explicitamente BUILD_VERSIONum argumento, então o valor definido com --build-argserá dado a cada um deles.

As considerações do estágio de montagem também se aplicam quando você usa uma ARGpré – FROMinstrução. Esses argumentos existem fora de qualquer estágio de construção; eles são comuns a todas as FROMinstruções, mas não podem ser referenciados seguindo as instruções. Se você quiser reutilizar FROMo argumento -level build dentro de um estágio, itere a ARGinstrução para obter seu valor:

# Only applies to FROM instructions

ARG BASE_IMAGE_VERSION=alpino

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

# Referencia o argumento de construção externo

ARG BASE_IMAGE_VERSION

# Funciona como esperado

RUN echo $BASE_IMAGE_VERSION

Além desses problemas especiais, os argumentos se comportam de maneira semelhante às variáveis ​​de ambiente em todos os outros aspectos. Você pode redefinir seus valores com as instruções ARGe ENV, interpolá-los em strings e usá-los em expressões de expansão do formulário ${EXAMPLE_VAR:-demo}. Este é escolhido democomo o valor quando EXAMPLE_VARa variável não está definida.

Argumentos de compilação predefinidos

O Docker oferece suporte a alguns argumentos de compilação por padrão, mesmo que você não inclua suas ARGinstruções em seu Dockerfile. Eles estão relacionados às configurações de proxy e funcionam sempre que o --build-argsinalizador correspondente é usado. As variáveis ​​também são excluídas da docker historysaída para evitar revelar as informações potencialmente confidenciais a que se destinam – mais sobre este comando e suas implicações abaixo.

Os assemblies processados ​​pelo back-end do BuildKit também podem acessar vários outros argumentos de compilação predefinidos. Eles vêm com valores inseridos automaticamente. A lista inclui TARGETOS, TARGETARCH, TARGETPLATFORM, e BUILDOS, BUILDARCH, e BUILDPLATFORM, bem como alguns outros. As variáveis ​​descrevem as características do ambiente de construção e da plataforma que a nova imagem tem como alvo.

Quando usar argumentos de construção?

Os argumentos de compilação podem ser usados ​​para injetar configuração em compilações de uma imagem do Docker. Essa é uma maneira de alterar dinamicamente a imagem final sem gravar vários Dockerfiles.

Esse mecanismo pode ser usado para alterar a imagem base de um assembly, alterar os comandos que as RUNinstruções executam e fornecer opções modificáveis ​​pelo usuário que fornecem opções de personalização de imagem. Os argumentos de compilação fazem sentido para a maioria dos valores que são usados ​​apenas durante o processo de compilação e que você não deseja codificar em seu Dockerfile.

Em algumas situações, abordagens alternativas devem ser usadas. Embora convenientes, os argumentos de montagem não são ideais para dados confidenciais, como tokens e chaves de autenticação. Como ARGesta é uma instrução do Dockerfile, as variáveis ​​e seus valores ficam visíveis quando você verifica a imagem com o docker historycomando. Dessa forma, qualquer pessoa com acesso à sua imagem pode visualizar as chaves usadas durante a compilação.

As credenciais usadas para autenticar o processo de compilação em relação aos registros de pacotes e repositórios de controle do código-fonte são melhor fornecidas na forma de segredos de compilação do BuildKit. Eles são projetados para lidar com informações confidenciais e são montados como arquivos no ambiente de compilação, em vez de se tornarem instruções de imagem.

Resumo

Os argumentos de compilação permitem que você personalize compilações de imagens do Docker usando uma combinação de instruções do Dockerfile e argumentos de linha de comando no momento da compilação. Ao contrário das variáveis ​​de ambiente, os argumentos de compilação não estão disponíveis para contêineres em execução, embora ainda estejam visíveis no histórico de camadas da imagem.

O argumento build é a escolha certa para opções configuráveis ​​pelo usuário não confidenciais que afetam o processo de compilação. Em vez disso, use uma variável de ambiente se quiser mostrar o valor na imagem final. O BuildKit Secrets é a melhor terceira opção para quaisquer dados valiosos que sua compilação precisa acessar.