Args de compilação do Docker: O guia definitivo para profissionais de dados

Implicações de segurança e mitigação de riscos

Embora os argumentos de compilação ofereçam flexibilidade, eles também apresentam possíveis riscos de segurança que você precisa entender para manter suas imagens do Docker seguras.

Vetores de fuga de argumentos

Os argumentos de construção não são tão particulares quanto você imagina. Os valores dos args de compilação podem vazar por vários vetores que muitos desenvolvedores ignoram. Primeiro, ohistórico da imagem do Docker expõe todos os seus args de compilação, o que significa que qualquer pessoa com acesso à sua imagem pode executar docker history para ver os valores que você usou durante o tempo de compilação, incluindo informações potencialmente confidenciais, como chaves ou tokens de API.

docker history flaskapp:dev

Imagem 4 - Histórico do Docker

As camadas intermediárias também podem vazar argumentos de compilação. Mesmo que você use uma compilação em vários estágios e não copie a camada que contém informações confidenciais, os valores de arg de compilação permanecerão no cache da camada na máquina de compilação. Isso significa que qualquer pessoa com acesso ao daemon do Docker no seu servidor de compilação poderia extrair essas informações.

Os registros de CI/CD representam outro risco significativo. A maioria dos sistemas de CI/CD registra todo o comando de compilação, incluindo quaisquer argumentos de compilação passados na linha de comando.

Por exemplo, todo esse comando, incluindo API_KEY, ficará visível nos registros de CI/CD:

docker build --build-arg API_KEY=secret123 -t myapp:latest .

Esses registros geralmente são acessíveis a um grupo mais amplo de desenvolvedores ou até mesmo armazenados em sistemas de terceiros, o que aumenta a superfície de exposição de valores confidenciais.

Alternativas seguras

Para informações confidenciais, você deve usar o recurso secrets do Docker BuildKit em vez de args de compilação. O BuildKit permite que você monte segredos durante o processo de compilação sem persisti-los na imagem final ou no histórico.

Aqui está um exemplo de Dockerfile que usa os segredos do Docker BuildKit:

FROM python:3.13-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .

# Use secret mount instead of build arg
RUN --mount=type=secret,id=api_key \
    cat /run/secrets/api_key > api_key.txt

EXPOSE 5000
CMD ["python", "app.py"]

Para criar essa imagem com um segredo, primeiro crie o arquivo api_key.txt:

echo "my-secret-api-key" > api_key.txt

E, em seguida, crie a imagem com o segredo:

DOCKER_BUILDKIT=1 docker build \
  --secret id=api_key,src=api_key.txt \
  -t flaskapp:secure .

Imagem 5 - Criação de imagens com os segredos do BuildKit

Para a configuração que precisa estar disponível em tempo de execução, as variáveis de ambiente continuam sendo a abordagem preferida. Eles podem ser definidos ao iniciar um contêiner sem serem incorporados à imagem:

# Set environment variables at runtime
docker run -e API_KEY=secret123 -p 5000:5000 flaskapp:latest

Para lidar com segurança com configurações confidenciais na produção, considere o uso de plataformas de orquestração de contêineres, como o Kubernetes, que fornecem métodos seguros, como o Secrets, para gerenciar informações confidenciais. O Docker Swarm também oferece recursos semelhantes com seu gerenciamento de segredos.

> O Docker não é a única plataforma de conteinerização. Leia sobre o Podman para descobrir qual ferramenta é mais adequada para você.

Lembre-se de que a regra geral é: use args de compilação para configuração de tempo de compilação que não seja sensível, use segredos do BuildKit para necessidades sensíveis de tempo de compilação e use variáveis de ambiente ou segredos da plataforma de orquestração para configuração de tempo de execução.

Integração com ecossistemas de contêineres

Agora que você já sabe o básico, vamos explorar como aproveitar os argumentos de compilação em ecossistemas Docker mais amplos e ferramentas de compilação modernas.

Docker Compose

O Docker Compose facilita a definição e o compartilhamento de argumentos de compilação em seus aplicativos com vários contêineres.

Se você quiser acompanhar o processo, aqui está uma estrutura de projeto completa para dois serviços simples do Flask:

flask-project/
├── docker-compose.yml         # Main compose configuration
├── .env                       # Environment variables for compose
├── web/
│   ├── Dockerfile             # Web service Dockerfile
│   ├── app.py                 # Flask application
│   └── requirements.txt       # Python dependencies
├── api/
│   ├── Dockerfile             # API service Dockerfile
│   ├── app.py                 # API Flask application  
│   └── requirements.txt       # API dependencies

Vou examinar rapidamente o conteúdo do arquivo, um por um:

web/app.py

from flask import Flask, render_template

app = Flask(__name__)


@app.route("/")
def index():
    return render_template("index.html", title="Flask Web App")


@app.route("/about")
def about():
    return "About page - Web Service"


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=5000, debug=True)

web/requirements.txt

flask==3.1.0

web/Dockerfile

# Web service Dockerfile
ARG PYTHON_VERSION=3.13

FROM python:${PYTHON_VERSION}-slim

# Redeclare the build arg to use it after FROM
ARG PYTHON_VERSION
ARG ENVIRONMENT=production

# Set environment variables
ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1
ENV FLASK_ENV=${ENVIRONMENT}

WORKDIR /app

# Copy and install requirements
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy application code
COPY . .

# Create a simple template folder and file if not exists
RUN mkdir -p templates && \
    echo "<html><body><h1>Hello from Web Service</h1><p>Python version: ${PYTHON_VERSION}</p><p>Environment: ${ENVIRONMENT}</p></body></html>" > templates/index.html

EXPOSE 5000

CMD ["python", "app.py"]

api/app.py

from flask import Flask, jsonify

app = Flask(__name__)


@app.route("/api/health")
def health():
    return jsonify({"status": "healthy"})


@app.route("/api/data")
def get_data():
    return jsonify(
        {"message": "Hello from the API service", "items": ["item1", "item2", "item3"]}
    )


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=8000, debug=True)

api/requirements.txt

flask==3.1.0

api/Dockerfile

ARG PYTHON_VERSION=3.13

FROM python:${PYTHON_VERSION}-slim

# Redeclare the build arg to use it after FROM
ARG PYTHON_VERSION
ARG ENVIRONMENT=production

# Set environment variables
ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1
ENV FLASK_ENV=${ENVIRONMENT}

WORKDIR /app

# Copy and install requirements
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy application code
COPY . .

# Add metadata label based on build args
LABEL python.version="${PYTHON_VERSION}" \
      app.environment="${ENVIRONMENT}"

EXPOSE 8000

CMD ["python", "app.py"]

.env

PYTHON_VERSION=3.10
ENVIRONMENT=development

docker-compose.yml

services:
  web:
    build:
      context: ./web
      dockerfile: Dockerfile
      args:
        PYTHON_VERSION: ${PYTHON_VERSION:-3.13}
        ENVIRONMENT: ${ENVIRONMENT:-development}
    ports:
      - "5000:5000"
    depends_on:
      - api
    
  api:
    build:
      context: ./api
      dockerfile: Dockerfile
      args:
        PYTHON_VERSION: ${PYTHON_VERSION:-3.13}
        ENVIRONMENT: ${ENVIRONMENT:-production}
    ports:
      - "8000:8000"

Em resumo, essa é uma maneira muito simples de iniciar dois aplicativos em ambientes isolados, ambos ao mesmo tempo, ambos com um conjunto específico de args de compilação.

Você pode usar esse comando para executar a configuração de vários contêineres:

docker compose up --build

Imagem 6 - Criar argumentos com o Docker Compose

Após alguns segundos, você verá os dois serviços em execução:

Imagem 7 - Criar argumentos com o Docker Compose (2)

É uma configuração bastante detalhada para aplicativos tão simples quanto esses dois, mas você já entendeu o panorama geral: os argumentos de compilação são definidos no arquivo compose e referenciados em Dockerfiles individuais.

Além disso, você também pode passar valores de variáveis do seu ambiente para args de compilação, o que é útil para pipelines de CI/CD:

services:
  web:
    build:
      context: .
      args:
        - PYTHON_VERSION=${PYTHON_VERSION:-3.10}

E para substituir esses valores ao executar docker-compose, você pode usar variáveis de ambiente:

PYTHON_VERSION=3.10 docker-compose up --build

Essa abordagem permite que você mantenha compilações consistentes em toda a sua equipe e, ao mesmo tempo, ofereça flexibilidade quando necessário.

Recursos do BuildKit

O BuildKit, o mecanismo de compilação moderno do Docker, sobrecarrega seu processo de compilação com recursos que tornam o uso de args de compilação muito mais avançado. Ao ativar o BuildKit (configurando DOCKER_BUILDKIT=1), você desbloqueia alguns novos recursos.

O cache em linha melhora o desempenho da compilação ao aproveitar o cache de compilação da imagem remota. Você pode especificar uma imagem de origem para usar como cache com o sinalizador --cache-from, e o BuildKit usará de forma inteligente as camadas dessa imagem:

DOCKER_BUILDKIT=1 docker build \
  --build-arg PYTHON_VERSION=3.10 \
  --cache-from flaskapp:dev \
  -t flaskapp:latest .

Outro recurso valioso do BuildKit são as saídas determinísticas, que garantem que suas compilações sejam reproduzíveis. Isso é fundamental quando você quer exatamente a mesma imagem, independentemente de quando ou onde ela for construída:

# Build with deterministic output
DOCKER_BUILDKIT=1 docker build \
  --build-arg PYTHON_VERSION=3.10 \
  --build-arg BUILD_DATE=2025-05-01 \
  --output type=docker,name=flaskapp:stable \
  .

A redação secreta do BuildKit nos registros protege as informações confidenciais durante as compilações. 

Ao contrário dos args de compilação comuns, que aparecem nos registros de compilação, o BuildKit oculta automaticamente os valores dos segredos:

# Create a file with the API key
echo "my-api-key-value" > ./api-key.txt

# Build with secret (value won't appear in logs)
DOCKER_BUILDKIT=1 docker build \
  --secret id=api_key,src=./api-key.txt \
  -t flaskapp:secure .

No seu Dockerfile, você acessaria esse segredo com:

RUN --mount=type=secret,id=api_key \
    cat /run/secrets/api_key > /app/config/api_key.txt

Esses recursos do BuildKit trabalham em conjunto com os args de compilação para criar um sistema de compilação mais seguro, eficiente e reproduzível que pode se adaptar a praticamente qualquer fluxo de trabalho de conteinerização.

Práticas recomendadas para adoção corporativa

A implementação de argumentos de compilação do Docker em grandes equipes exige abordagens padronizadas, pelo menos se você quiser minimizar a confusão e maximizar os benefícios de segurança e desempenho.

Ao adotar argumentos de compilação em ambientes corporativos, comece com a validação adequada dos argumentos. 

Sempre forneça valores padrão sensatos para cada argumento de compilação para garantir que as compilações não falhem inesperadamente quando os argumentos não forem passados. Você também deve adicionar verificações de validação no seu Dockerfile para verificar se os args críticos de compilação atendem aos seus requisitos.

Aqui está um exemplo que valida a versão do Python:

ARG PYTHON_VERSION=3.9
# Validate Python version
RUN if [[ ! "$PYTHON_VERSION" =~ ^3\.[0-9]+$ ]]; then \
      echo "Invalid Python version: ${PYTHON_VERSION}. Must be 3.x"; \
      exit 1; \
    fi

A otimização do cache de camadas é fundamental para reduzir os tempos de compilação nos pipelines de CI/CD. 

Ordene as instruções do seu Dockerfile para maximizar os acessos ao cache, colocando o conteúdo que raramente muda (como a instalação de dependências) antes do conteúdo que muda com frequência (como o código do aplicativo). 

Ao usar args de compilação que podem mudar com frequência, coloque-os após operações estáveis para evitar invalidar todo o cache:

FROM python:3.13-slim

WORKDIR /app

# Dependencies change less frequently - good cache utilization
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Build args that might change often come AFTER stable operations
ARG BUILD_NUMBER
ARG COMMIT_SHA
# Now these args won't invalidate the dependency cache

O gerenciamento de metadados por meio de args de compilação melhora a rastreabilidade e a conformidade. Use args de compilação para injetar metadados de tempo de compilação como rótulos:

ARG BUILD_DATE
ARG VERSION
ARG COMMIT_SHA
ARG BUILD_URL

LABEL org.opencontainers.image.created="${BUILD_DATE}" Can you please provide me with access to this document?
      org.opencontainers.image.version="${VERSION}" \
      org.opencontainers.image.revision="${COMMIT_SHA}" \
      org.opencontainers.image.url="${BUILD_URL}"

Esses rótulos padronizados seguem a especificação da Open Container Initiative (OCI), o que significa que suas imagens serão compatíveis com diferentes ferramentas de gerenciamento de contêineres.

A documentação é frequentemente negligenciada, mas é fundamental para a adoção corporativa. 

Crie uma seção clara em README que documente todos os args de compilação disponíveis, sua finalidade, valores padrão e exemplos de uso. Inclua quais argumentos de compilação são obrigatórios ou opcionais e documente as interações entre os diferentes argumentos. Considere adicionar essas informações aos arquivos de configuração do pipeline de CI/CD também como comentários, para ajudar os desenvolvedores a entender quais valores precisam fornecer:

# Example documented CI configuration
build_job:
  script:
    # BUILD_NUMBER: Unique identifier for this build (required)
    # ENVIRONMENT: Target deployment environment [dev|staging|prod] (required)
    # PYTHON_VERSION: Python version to use (optional, default: 3.9)
    - docker build
      --build-arg BUILD_NUMBER=${CI_PIPELINE_ID}
      --build-arg ENVIRONMENT=${DEPLOY_ENV}
      --build-arg PYTHON_VERSION=${PYTHON_VERSION:-3.9}
      -t myapp:${CI_PIPELINE_ID} .

Para uma adoção realmente de nível empresarial, considere a implementação de um esquema de argumento de construção que possa ser versionado e validado. Essa abordagem permite que você desenvolva sua configuração de compilação ao longo do tempo, mantendo a compatibilidade com versões anteriores.

Análise comparativa: Args de compilação vs. Variáveis de ambiente

Se quiser criar imagens do Docker seguras e flexíveis que sigam as práticas recomendadas, você deverá entender quando usar argumentos de compilação e quando usar variáveis de ambiente.

Aqui está uma tabela que você pode consultar a qualquer momento:

A principal diferençaA principal diferença está em seu tempo e propósito. Os argumentos de compilação configuram o próprio processo de compilação, enquanto as variáveis de ambiente configuram o aplicativo em execução. Por exemplo, você usaria um arg de compilação para selecionar qual imagem de base usar (ARG PYTHON_VERSION=3.10), mas usaria uma variável de ambiente para informar ao seu aplicativo qual porta escutar (ENV PORT=8080).

De uma perspectiva de segurança, args de compilação representam um risco maior para informações confidenciais porque permanecem no histórico da imagem.

Considere este fluxo de trabalho para lidar com diferentes tipos de configuração:

# Build-time configuration (non-sensitive)
ARG PYTHON_VERSION=3.13
FROM python:${PYTHON_VERSION}-slim

# Build-time secrets (use BuildKit secrets)
RUN --mount=type=secret,id=build_key \
    cat /run/secrets/build_key > /tmp/key && \
    # Use the secret for build operations
    rm /tmp/key

# Runtime configuration (non-sensitive)
ENV LOG_LEVEL=info

# Runtime secrets (should be injected at runtime, not here)
# This would be provided at runtime with:
# docker run -e API_KEY=secret123 myimage

Na prática, um padrão comum é converter os args de compilação selecionados em variáveis de ambiente quando eles precisam estar disponíveis em tempo de execução:

ARG APP_VERSION=1.0.0
# Make the version available at runtime
ENV APP_VERSION=${APP_VERSION}

Para aplicativos corporativos, a separação permite que diferentes equipes gerenciem diferentes aspectos do ciclo de vida do aplicativo. As equipesde DevOpspodem modificar os argumentos de compilação para a construção da imagem, enquanto os operadores podem ajustar as variáveis de ambiente durante a implementação sem reconstruir as imagens.

Resumindo os argumentos de compilação do Docker

Os args de compilação do Docker não são apenas mais um recurso técnico - eles são a ferramenta que você usa para criar imagens que funcionam de forma consistente em toda a sua equipe e ambientes. 

Eu mostrei a você como usá-los em projetos simples em Python, mantendo suas informações confidenciais seguras. Você também viu como integrar args de compilação com ferramentas como o Docker Compose.

Pense nos argumentos de compilação como a base de uma estratégia flexível de conteinerização. Comece aos poucos, parametrizando sua versão do Python em seu próximo projeto. Quando isso parecer confortável, tente adicionar lógica condicional para diferentes ambientes. Antes que perceba, você criará compilações sofisticadas em vários estágios que sua equipe pode personalizar sem modificar o Dockerfile.

Você está pronto para se aprofundar? Estes cursos da DataCamp são a próxima parada que você deve fazer:

• Introdução ao Docker
• Docker intermediário
• Conceitos de virtualização e de contêineres
• Containerização e virtualização com Docker e Kubernetes
• CI/CD para machine learning