Docker Build Args: Veri Profesyonelleri için Kapsamlı Rehber

Güvenlik Etkileri ve Risk Azaltma

Build argümanları esneklik sağlasa da, Docker imajlarınızı güvenli tutmak için anlamanız gereken potansiyel güvenlik risklerini de beraberinde getirirler.

Argüman sızıntısı vektörleri

Build arg'lar düşündüğünüz kadar gizli değildir. Birçok geliştiricinin gözden kaçırdığı birkaç vektör üzerinden build arg değerleri sızabilir. İlk olarak, Docker imaj geçmişi tüm build arg'larınızı ortaya çıkarır; yani imajınıza erişimi olan herkes build sırasında kullandığınız değerleri, API anahtarları veya belirteçler gibi hassas bilgiler dahil, görmek için docker history çalıştırabilir.

docker history flaskapp:devAltyapı:

Görsel 4 - Docker history

Ara katmanlar da build argümanlarını sızdırabilir. Çok aşamalı bir build kullansanız ve hassas bilgileri içeren katmanı kopyalamasanız bile, build arg değerleri build makinesindeki katman önbelleğinde kalır. Bu, build sunucunuzdaki Docker daemon'ına erişimi olan herkesin bu bilgileri potansiyel olarak çıkarabileceği anlamına gelir.

CI/CD günlükleri de önemli bir risk oluşturur. Çoğu CI/CD sistemi, komut satırında geçirilen build arg'lar dahil olmak üzere tüm build komutunu günlüğe kaydeder.

Örneğin, API_KEY dahil bu komutun tamamı CI/CD günlüklerinde görünecektir:

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

Bu günlükler genellikle daha geniş bir geliştirici grubunun erişimine açıktır veya üçüncü taraf sistemlerde saklanır; bu da hassas değerlerin maruz kalma yüzeyini artırır.

Güvenli alternatifler

Hassas bilgiler için build arg'lar yerine Docker BuildKit'in secrets özelliğini kullanmalısınız. BuildKit, build süreci sırasında sırları mount etmenize ve bunları nihai imajda veya geçmişte kalıcı hale getirmemenize olanak tanır.

İşte Docker BuildKit secrets kullanan örnek bir Dockerfile:

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"]Altyapı:

Bu imajı bir sır ile build etmek için önce api_key.txt dosyasını oluşturun:

echo "my-secret-api-key" > api_key.txtAltyapı:

Ardından imajı sır ile build edin:

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

Görsel 5 - BuildKit secrets ile imaj oluşturma

Çalışma zamanında erişilebilir olması gereken yapılandırmalar için ortam değişkenleri tercih edilen yaklaşımdır. İmajın içine gömmeden konteyneri başlatırken ayarlanabilirler:

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

Üretimde hassas yapılandırmaları güvenli bir şekilde ele almak için, hassas bilgileri yönetmek üzere Secrets gibi güvenli yöntemler sağlayan Kubernetes gibi konteyner orkestrasyon platformlarını kullanmayı düşünün. Docker Swarm da sır yönetimiyle benzer yetenekler sunar.

> Docker tek konteynerleştirme platformu değildir. Podman hakkında okuyarak hangisinin size daha uygun olduğunu öğrenin.

Unutmayın, temel kural şudur: hassas olmayan build zamanı yapılandırma için build arg'ları kullanın; hassas build zamanı ihtiyaçlar için BuildKit secrets kullanın; çalışma zamanı yapılandırması için ise ortam değişkenleri veya orkestrasyon platformu sırlarını kullanın.

Konteyner Ekosistemleriyle Entegrasyon

Artık temeller geride kaldığına göre, build arg'ları daha geniş Docker ekosistemlerinde ve modern build araçlarında nasıl değerlendirebileceğimize bakalım.

Docker Compose

Docker Compose, çok konteynerli uygulamalarınız genelinde build arg'ları tanımlamayı ve paylaşmayı kolaylaştırır.

Takip etmek isterseniz, iki basit Flask servisi için tam proje yapısı şu şekildedir:

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 dependenciesAltyapı:

Dosya içeriklerini kısaca tek tek üzerinden geçeceğim:

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)Altyapı:

web/requirements.txt

flask==3.1.0Altyapı:

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"]Altyapı:

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)Altyapı:

api/requirements.txt

flask==3.1.0Altyapı:

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"]Altyapı:

.env

PYTHON_VERSION=3.10
ENVIRONMENT=developmentAltyapı:

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"Altyapı:

Özetle, bu, birbirinden izole ortamlarda iki uygulamayı aynı anda, belirli bir build arg setiyle başlatmanın gerçekten basit bir yoludur.

Çok konteynerli kurulumu çalıştırmak için bu komutu kullanabilirsiniz:

docker compose up --buildAltyapı:

Görsel 6 - Docker Compose ile build arg'lar

Birkaç saniye sonra her iki servisin de çalıştığını göreceksiniz:

Görsel 7 - Docker Compose ile build arg'lar (2)

Bu iki uygulama kadar basit olanlar için oldukça detaylı bir kurulum, ancak büyük resim net—build arg'lar compose dosyasında ayarlanır ve bireysel Dockerfile'larda referans verilir.

Ayrıca, ortamınızdan build arg'lara değişken değerleri de geçirebilirsiniz; bu, CI/CD boru hatları için kullanışlıdır:

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

docker-compose çalıştırırken bu değerleri geçersiz kılmak için ortam değişkenlerini kullanabilirsiniz:

PYTHON_VERSION=3.10 docker-compose up --buildAltyapı:

Bu yaklaşım, ihtiyaç duyulduğunda esneklik sunarken ekibiniz genelinde tutarlı build'ler sürdürmenizi sağlar.

BuildKit özellikleri

Docker'ın modern build motoru BuildKit, build sürecinizi build arg'ları çok daha güçlü kılan özelliklerle hızlandırır. BuildKit'i etkinleştirdiğinizde (DOCKER_BUILDKIT=1 ayarlayarak) birkaç yeni yetenek açılır.

Inline cache, uzak imajın build önbelleğinden yararlanarak build performansını artırır. --cache-from bayrağıyla önbellek olarak kullanılacak bir kaynak imaj belirtebilir ve BuildKit bu imajın katmanlarını akıllıca kullanır:

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

Bir diğer değerli BuildKit özelliği de belirlenebilir çıktı (deterministic outputs) olup build'lerinizin tekrarlanabilir olmasını sağlar. Nerede veya ne zaman build edildiğinden bağımsız olarak tam olarak aynı imajı istediğinizde bu kritik öneme sahiptir:

# 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 \
  .Altyapı:

BuildKit'in günlüklerde sırları maskelemesi (secret redaction) build'ler sırasında hassas bilgileri korur. 

Build arg'ların aksine, ki bunların değerleri build günlüklerinde görünür, BuildKit sırların değerlerini otomatik olarak gizler:

# 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 .Altyapı:

Dockerfile'ınızda bu sırrı şöyle erişirsiniz:

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

Bu BuildKit özellikleri, neredeyse her türlü konteynerleştirme iş akışına uyum sağlayabilen daha güvenli, verimli ve tekrarlanabilir bir build sistemi oluşturmak için build arg'larla birlikte çalışır.

Kurumsal Benimseme için En İyi Uygulamalar

Docker build arg'larını büyük ekipler genelinde uygulamak, en azından kafa karışıklığını en aza indirmek ve güvenlik ile performans faydalarını en üst düzeye çıkarmak için standartlaştırılmış yaklaşımlar gerektirir.

Kurumsal ortamlarda build arg'ları benimserken uygun argüman doğrulamasıyla başlayın. 

Her build argümanı için makul varsayılan değerler sağlayarak, argümanlar iletilmediğinde build'lerin beklenmedik şekilde başarısız olmasını önleyin. Ayrıca kritik build arg'ların gereksinimlerinizi karşıladığını doğrulamak için Dockerfile içinde doğrulama kontrolleri eklemelisiniz.

Python sürümü doğrulayan bir örnek şöyledir:

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; \
    fiAltyapı:

Katman önbelleklemesini optimize etmek, CI/CD boru hatlarında build sürelerini azaltmak için kritik öneme sahiptir. 

Dockerfile yönergelerinizi, nadiren değişen içerikleri (bağımlılık kurulumu gibi) daha sık değişen içeriklerden (uygulama kodu gibi) önce yerleştirerek önbellek isabetlerini en üst düzeye çıkaracak şekilde sıralayın. 

Sık değişebilecek build arg'ları kullanırken, tüm önbelleği geçersiz kılmamak için bunları istikrarlı işlemlerden sonra yerleştirin:

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 cacheAltyapı:

Build arg'lar aracılığıyla metaveri yönetimi, izlenebilirliği ve uyumluluğu artırır. Build zamanı metaveriyi etiketler olarak enjekte etmek için build arg'ları kullanın:

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}"Altyapı:

Bu standartlaştırılmış etiketler Open Container Initiative (OCI) spesifikasyonunu takip eder; bu da imajlarınızın farklı konteyner yönetim araçlarıyla uyumlu olacağı anlamına gelir.

Dokümantasyon sıklıkla göz ardı edilir, ancak kurumsal benimseme için kritiktir. 

Tüm mevcut build arg'ları, amaçlarını, varsayılan değerlerini ve kullanım örneklerini belgeleyen net bir README bölümü oluşturun. Hangi build arg'ların zorunlu hangilerinin isteğe bağlı olduğunu ve farklı argümanlar arasındaki etkileşimleri dahil edin. Geliştiricilerin hangi değerleri sağlamaları gerektiğini anlamalarına yardımcı olmak için bu bilgileri CI/CD boru hattı yapılandırma dosyalarınıza yorum olarak eklemeyi de düşünün:

# 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} .Altyapı:

Gerçek anlamda kurumsal düzeyde benimseme için, sürümlendirilebilen ve doğrulanabilen bir build argüman şeması uygulamayı düşünün. Bu yaklaşım, geriye dönük uyumluluğu korurken build yapılandırmanızı zaman içinde evrimleştirmenize olanak tanır.

Karşılaştırmalı Analiz: Build Arg'lar vs. Ortam Değişkenleri

En iyi uygulamalara uygun, güvenli ve esnek Docker imajları oluşturmak istiyorsanız, build arg'ları ne zaman ve ortam değişkenlerini ne zaman kullanmanız gerektiğini anlamalısınız.

İstediğiniz zaman başvurabileceğiniz bir tablo şöyledir:

Temel fark zamanlama ve amaçta yatar. Build arg'lar bizzat build sürecini yapılandırırken, ortam değişkenleri çalışan uygulamayı yapılandırır. Örneğin, hangi taban imajın kullanılacağını seçmek için build arg kullanırsınız (ARG PYTHON_VERSION=3.10), ancak uygulamanıza hangi portu dinleyeceğini söylemek için ortam değişkeni kullanırsınız (ENV PORT=8080).

Güvenlik açısından, build arg'lar daha yüksek risk taşır; çünkü imaj geçmişinde kalırlar. 

Farklı türdeki yapılandırmaları ele almak için şu iş akışını düşünün:

# 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 myimageAltyapı:

Pratikte, bazı build arg'ları çalışma zamanında kullanılmaları gerektiğinde ortam değişkenlerine dönüştürmek yaygın bir desendir:

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

Kurumsal uygulamalarda bu ayrım, uygulamanın yaşam döngüsünün farklı yönlerinin farklı ekiplerce yönetilmesine olanak tanır. DevOps ekipleri imaj inşası için build arg'ları değiştirebilirken, operasyon ekipleri imajları yeniden build etmeden dağıtım sırasında ortam değişkenlerini ayarlayabilir.

Docker Build Arg'larını Özetleme

Docker build arg'ları yalnızca bir teknik özellik değildir - ekipleriniz ve ortamlarınız genelinde tutarlı şekilde çalışan imajlar oluşturmak için başlıca aracınızdır. 

Onları basit Python projelerinde nasıl kullanacağınızı, hassas bilgilerinizi güvende tutarken nasıl yöneteceğinizi anlattım. Ayrıca build arg'ları Docker Compose gibi araçlarla nasıl entegre edeceğinizi gördünüz.

Build arg'ları, esnek bir konteynerleştirme stratejisinin temeli olarak düşünün. Bir sonraki projenizde Python sürümünü parametreleştirerek küçük başlayın. Buna alıştıktan sonra farklı ortamlar için koşullu mantık eklemeyi deneyin. Farkına varmadan, ekibinizin Dockerfile'ı değiştirmeden özelleştirebileceği gelişmiş çok aşamalı build'ler oluşturuyor olacaksınız.

Daha derine inmeye hazır mısınız? DataCamp'teki şu kurslar bir sonraki en iyi durağınız olacaktır:

• Introduction to Docker
• Intermediate Docker
• Containerization and Virtualization Concepts
• Containerization and Virtualization with Docker and Kubernetes
• CI/CD for Machine Learning