Docker Build Secrets Rehberi: Güvenli Konteyner İmajı Geliştirme

API anahtarları, veritabanı parolaları ve katmanlarına gömülü kimlik doğrulama belirteçleriyle yanlışlıkla ifşa edilmiş sayısız Docker imajı gördüm. Bu güvenlik ihlalleri genellikle geliştiricilerin özel kaynaklara geçici erişime ihtiyaç duyduğu, ancak istemeden kimlik bilgilerini son imaja işledikleri build süreci sırasında gerçekleşir.

Zorluk şu ki, build sırasında kimlik bilgilerini yönetmek için kullanılan geleneksel yaklaşımlar, örneğin ortam değişkenleri veya build argümanları, geçici kullanım için tasarlanmamıştır. İmaj meta verilerinde veya katmanlarında kalıcı izler bırakırlar ve build tamamlandıktan çok sonra bile süren güvenlik açıkları oluştururlar. Bu da bir ikilem yaratır: Build sırasında özel kaynaklara güvenliği tehlikeye atmadan nasıl kimlik doğrulaması yaparsınız?

Docker build secrets, hassas verileri imaj build’leri sırasında kullanıp son çıktıda iz bırakmadan bu kritik güvenlik sorununu çözer. 

Bu eğitimde, temel kavramlardan gelişmiş CI/CD entegrasyonuna kadar build secrets’ı etkili bir şekilde uygulamayı göstereceğim; böylece konteyner build’leriniz güvenli kalacak.

Docker’a yeniyseniz, şu kurslarımızdan birini almanızı öneririm: Introduction to Docker, Containerization and Virtualization with Docker and Kubernetes veya Intermediate Docker. 

Docker Build Secrets Nedir?

Önce build secrets’ı diğer kimlik bilgisi yönetimi yaklaşımlarından ayıran noktaları anlamakla başlayalım. Docker build secrets, build süreci sırasında erişilebilir olan, ancak imaj katmanlarında veya dosya sisteminde asla saklanmayan geçici hassas bilgilerdir. Yalnızca belirli build adımları boyunca bellekte bulunurlar ve bu adımlar tamamlandığında ortadan kaybolurlar.

Build secrets’a duyulan ihtiyaç, modern uygulama geliştirme iş akışlarından kaynaklanır. 

Build’ler sırasında özel paket depolarına kimlik doğrulaması yapmak, özel Git depolarını klonlamak, lisanslı yazılımları indirmek veya iç API’lere erişmek sıkça gerekebilir. 

Build secrets olmadan geliştiriciler, Dockerfile’lara kimlik bilgilerini gömmek, secret’ları (imaj meta verilerinde kalıcı olan) build argümanlarıyla iletmek veya kimlik bilgileri gömülü aşırı izinli temel imajlar oluşturmak gibi tehlikeli geçici çözümlere başvurur.

Yetersiz secret yönetiminin riskleri büyüktür. Açığa çıkan kimlik bilgileri, üretim sistemlerine yetkisiz erişime, veri ihlallerine, uyumluluk ihlallerine ve ciddi itibar kaybına yol açabilir. Secret sızıntısının yaygın senaryoları arasında paket yöneticileri için API anahtarları, Git işlemleri için SSH anahtarları, iç servisler için kimlik doğrulama belirteçleri ve build zamanlı migrasyonlar için veritabanı kimlik bilgileri yer alır.

Docker BuildKit: Güvenli Build Secrets’ın Temeli

Uygulamaya dalmadan önce, güvenli secret’ları mümkün kılan modern build motoru olan BuildKit’i anlamanız gerekir. BuildKit, klasik build motorunun yerini alan, performans, önbellekleme ve güvenlikte önemli iyileştirmeler sunan Docker’ın yeni nesil derleyicisidir.

BuildKit, build adımları arasındaki bağımlılıkları izleyen grafik tabanlı bir yürütme modeli kullanır. Bu mimari, BuildKit’in secret’ları yalnızca belirli RUN talimatları sırasında var olan geçici dosya sistemleri olarak bağlamasına olanak tanır; böylece bunların hiçbir zaman imaj katmanlarının parçası olmasını engeller. 

Klasik Docker build’lerinden farklı olarak, build bağlamındaki her şeyin build önbelleğinin parçası olduğu yerde, BuildKit secret’ları katman önbelleğini tamamen atlayan özel kaynaklar olarak ele alır.

BuildKit’i etkinleştirmek kolaydır. Docker 23.0 ve sonrasında BuildKit varsayılan derleyicidir. Daha eski sürümler için, build komutlarını çalıştırmadan önce DOCKER_BUILDKIT=1 ortam değişkenini ayarlayın:

export DOCKER_BUILDKIT=1
docker build -t myapp .

Alternatif olarak, Docker daemon’ını yapılandırarak kalıcı olarak etkinleştirin veya her zaman BuildKit kullanan Docker Buildx’i kullanın. Klasik build’ler ile BuildKit etkin build’ler arasındaki temel fark; klasik build’lerde dikkatlice yönetilmediği sürece secret’ların ara katmanlarda kalıcı olabileceği, BuildKit’in ise secret’ların geçici olacağını ve imajın parçası olarak diske yazılmayacağını garanti etmesidir.

BuildKit’in güvenli temeli yerli yerine oturduğuna göre, sağladığı secret türlerini ve her birini nasıl etkili şekilde uygulayacağınızı inceleyelim.

Docker Build Secrets Türleri ve Uygulaması

BuildKit, build’ler sırasında secret’ları ele almak için belirli kullanım senaryolarına yönelik üç birincil mekanizma destekler. Hangi türün ne zaman kullanılacağını bilmek, en iyi güvenlik ve işlevsellik sağlar.

Secret mount’ları: genel amaçlı hassas veriler

Secret mount’ları, build sırasında hassas verileri ele almak için en esnek yaklaşımdır. RUN talimatları sırasında secret’ları belirtilen yollarda dosya olarak bağlamanıza olanak tanır; böylece kimlik bilgileri, katmanlarda kalıcı hale gelmeden build komutlarına sunulur.

Süreç iki adımdan oluşur: secret’ı build komutuna iletmek ve Dockerfile içinde bağlamak. Önce yerelde bir secret dosyası oluşturun veya bir ortam değişkeni kullanın. Ardından build sırasında referans verin:

docker build --secret id=api_key,src=./api_key.txt -t myapp .

Dockerfile’ınızda, secret’a ihtiyaç duyan RUN talimatı sırasında bağlayın:

RUN --mount=type=secret,id=api_key \
    API_KEY=$(cat /run/secrets/api_key) && \
    curl -H "Authorization: Bearer $API_KEY" https://api.example.com/package > /app/data.json

Varsayılan olarak secret’lar /run/secrets/<id> altında bağlanır; ancak target parametresiyle özel hedefler belirtebilirsiniz. 

En iyi uygulamalar arasında, secret’ları yalnızca ihtiyaç duyan belirli RUN komutlarında bağlamak, secret’ları asla imaj dosya sistemine kopyalamamak ve secret gerektiren aşamaları final imajdan ayırmak için çok aşamalı (multi-stage) build’ler kullanmak yer alır. 

Kaynak bir dosya yolu olabilir ya da env kullanarak secret’ları ortam değişkenlerinden iletebilirsiniz: --secret id=token,env=API_TOKEN.

Bir secret’ı dosya yerine ortam değişkeni olarak bağlamak için env seçeneğini kullanın:

RUN --mount=type=secret,id=db_user,env=DB_USER \
    --mount=type=secret,id=db_password,env=DB_PASSWORD \
    ./setup-database.sh

Bir secret’ı hem dosya hem de ortam değişkeni olarak bağlamak için target ve env seçeneklerini birlikte kullanabilirsiniz. 

En iyi uygulamalar arasında, secret’ları yalnızca ihtiyaç duyan belirli RUN komutlarında bağlamak, secret’ları asla imaj dosya sistemine kopyalamamak ve final imajlardan ayrı tutmak için çok aşamalı build’ler kullanmak bulunur.

SSH mount’ları: özel kaynaklara güvenli erişim

SSH mount’ları, özellikle build’ler sırasında özel Git depolarına erişim için SSH tabanlı kimlik doğrulamayı ele alır. SSH anahtarlarını imaja kopyalamak (büyük bir güvenlik riski) yerine, SSH mount’ları build zamanında SSH ajanınıza geçici erişim sağlar.

SSH mount’larını kullanmak için, gerekli anahtarlar yüklü olarak yerelde SSH ajanınızın çalıştığından emin olun. Ardından Dockerfile’da SSH mount’una referans verin:

RUN --mount=type=ssh \
    git clone git@github.com:myorg/private-repo.git /app

İmajı SSH iletmeyi etkinleştirerek build edin:

docker build --ssh default -t myapp .

Farklı anahtarlara sahip birden fazla ana makine için adlandırılmış SSH mount’ları belirtebilirsiniz:

RUN --mount=type=ssh,id=github \
    git clone git@github.com:myorg/repo.git

Ardından build sırasında belirli anahtarlar sağlayın:

docker build --ssh github=$HOME/.ssh/github_key -t myapp .

Bu yaklaşımın, özel anahtarları imajda hiçbir zaman ifşa etmeyerek güvenliği korurken build süreci sırasında özel depolara kimliği doğrulanmış erişim sağladığını göreceksiniz.

Uzak bağlamlar için Git kimlik doğrulaması

Docker build’inizin, build bağlamı olarak veya build sırasında bağımlılıkları çekerken özel Git depolarına erişmesi gerektiğinde, kimlik bilgilerini gömmeden kimlik doğrulaması yapmanız gerekir. Bu durum, özel depo URL’sinden build ederken veya özel kodu çekmek için ADD talimatlarını kullanırken özellikle yaygındır.

BuildKit, Git kimlik doğrulaması için iki ön tanımlı secret sağlar: GIT_AUTH_TOKEN ve GIT_AUTH_HEADER. Bunlar, herhangi bir Dockerfile talimatı yürütülmeden önce derleyiciyi kimlik doğrulayan “pre-flight” secret’lardır; böylece ilk depo getirme işlemi güvence altına alınır.

En yaygın desen, belirteç tabanlı HTTPS kimlik doğrulaması için GIT_AUTH_TOKEN kullanımını içerir:

GIT_AUTH_TOKEN=$(cat ~/.github-token) docker build \
    --secret id=GIT_AUTH_TOKEN \
    https://github.com/myorg/private-repo.git

Bu, özel depoları çeken ADD talimatlarıyla sorunsuz çalışır:

FROM alpine
ADD https://github.com/myorg/private-configs.git /configs

Geçici CI/CD ortamları için, belirteçleri platformunuzun secret deposundan enjekte edin:

- name: Build from private repo
  env:
    GIT_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  run: |
    docker build --secret id=GIT_AUTH_TOKEN https://github.com/myorg/app.git

GIT_AUTH_HEADER secret’ı, standart belirteç kimlik doğrulamasının yeterli olmadığı durumlarda özel kimlik doğrulama şemaları için bir alternatiftir.

Docker Build Secrets Nasıl Kullanılır

Artık build secret türlerini ele aldığımıza göre, bunları gerçek dünyadaki senaryolarda nasıl etkili şekilde uygulayacağımızı inceleyelim.

Build zamanı için secret oluşturma ve yapılandırma

Doğru secret hazırlığı güvenlik açısından kritik önemdedir. Secret’ları Docker build bağlamınızın dışında dosyalarda saklayın, .gitignore ve .dockerignore’a ekleyin ve kısıtlayıcı dosya izinleri (600 veya 400) kullanın.

Birden fazla secret için özel bir dizin oluşturun:

mkdir -p .secrets
echo "my-api-key" > .secrets/api_key
chmod 600 .secrets/*

Ardından build sırasında referans verin:

docker build \
    --secret id=api_key,src=.secrets/api_key \
    --secret id=db_password,src=.secrets/db_password \
    -t myapp .

CI/CD’de yaygın olan ortam değişkeni tabanlı secret’lar için:

docker build \
    --secret id=api_key,env=API_KEY \
    --secret id=db_pass,env=DB_PASSWORD \
    -t myapp .

Çok aşamalı build’lerle entegrasyon

Çok aşamalı build’ler, build secrets ile bir araya geldiğinde güçlüdür. Bağımlılıkları çekmek için erken aşamalarda secret kullanın, ardından yalnızca gerekli artefact’leri son aşamaya kopyalayın:

# Build aşaması - secret’lar burada kullanılır
FROM python:3.11 AS builder
WORKDIR /app
COPY requirements.txt .
RUN --mount=type=secret,id=api_key \
    API_KEY=$(cat /run/secrets/api_key) && \
    curl -H "Authorization: Bearer $API_KEY" https://api.company.com/data.json -o data.json && \
    pip install -r requirements.txt

# Final aşama - secret yok
FROM python:3.11-slim
WORKDIR /app
COPY --from=builder /usr/local/lib/python3.11/site-packages /usr/local/lib/python3.11/site-packages
COPY --from=builder /app/data.json ./data.json
COPY . .
CMD ["python", "app.py"]

Bu, secret’ların yalnızca builder aşaması sırasında var olmasını ve asla final imajda görünmemesini sağlar.

Çok aşamalı build’ler tekil secret’ları zarifçe işler; ancak gerçek dünyadaki uygulamalar sıklıkla daha fazla karmaşıklık gerektirir. 

Birden fazla secret veya karmaşık build gereksinimleri içeren senaryoları nasıl yöneteceğimize bakalım

Birden fazla secret ve karmaşık senaryoların yönetimi

Karmaşık build’ler, aynı RUN talimatı içinde birden fazla secret gerektirebilir. BuildKit, birden fazla secret’ın eşzamanlı bağlanmasını destekler:

RUN --mount=type=secret,id=api_key \
    --mount=type=secret,id=db_password \
    API_KEY=$(cat /run/secrets/api_key) && \
    DB_PASS=$(cat /run/secrets/db_password) && \
    ./configure.sh

Birden çok komutun secret’lara ihtiyaç duyduğu senaryolarda, güvenlik sınırlarını korurken secret mount sayılarını en aza indirmek için komutları tek bir RUN talimatında birleştirin.

Docker Build Secrets Güvenlik En İyi Uygulamaları

Build secrets’ı doğru uygulamak, yerleşik güvenlik pratiklerini takip etmeyi gerektirir. Build süreci boyunca güvenliği korumada en etkili bulduğum örüntüleri paylaşayım.

Secret ifşasını ve sızıntısını önleme

Bir imaj oluşturduktan sonra, katmanları inceleyerek secret’ların sızmadığını doğrulayın:

docker history myapp:latest
docker save myapp:latest | tar -x

Çıkarılan katmanları hassas veri açısından inceleyin. Ayrıca build zamanı secret’ları (geçici, build sırasında kullanılan) ile çalışma zamanı secret’larını (konteynerler çalışırken gereken) ayırt edin. Build secret’larını asla çalışma zamanı kimlik bilgileri için kullanmayın. Bunun yerine Docker secrets, Kubernetes secrets veya çalışma zamanında enjekte edilen ortam değişkenlerini kullanın.

Secret dosyalarını her zaman .gitignore’a ekleyin:

# .gitignore
.secrets/
*.key

Ve build bağlamlarına yanlışlıkla dahil edilmelerini önlemek için .dockerignore’a da ekleyin:

# .dockerignore
.secrets/
*.key
.env

CI/CD ortamlarında secret yönetimi

CI/CD platformları, Docker build secrets ile sorunsuz entegre olan yerel secret yönetimi sunar. GitHub Actions’da:

- name: Build Docker image
  env:
    API_KEY: ${{ secrets.API_KEY }}
  run: |
    docker build \
      --secret id=api_key,env=API_KEY \
      -t myapp .

Temel ilke, secret’ları depolarda saklamak yerine platformun sağladığı secret depolarından yararlanmaktır. CI/CD secret’ları ortam değişkenleri olarak enjekte edilir ve BuildKit bunları doğrudan env kaynak türü aracılığıyla tüketebilir.

Secret izinleri ve erişim kontrolü

Root olmayan kullanıcılar olarak build ederken, secret dosyalarının uygun okuma izinlerine sahip olduğundan emin olun. Dockerfile’ınız USER ile root olmayan bir kullanıcıya geçiş yapıyorsa, secret’ları o kullanıcının erişebileceği konumlara bağlayın:

FROM python:3.11-slim
RUN useradd -m appuser
USER appuser

RUN --mount=type=secret,id=token,uid=1000 \
    cat /run/secrets/token > /dev/null

Güvenlik uyumluluğunu artırmak için secret döndürme (rotation) stratejileri uygulayın. Mümkün olduğunda kısa ömürlü belirteçler kullanın, CI/CD hatlarında otomatik döndürme uygulayın ve secret kullanımına ilişkin denetim günlükleri tutun. 

Maruziyet pencerelerini en aza indirmek için son kullanma tarihli secret’lar ve otomatik yenileme süreçlerini değerlendirin.

Şimdiye kadar tek konteynerli build’lere odaklandık; ancak modern uygulamalar sıklıkla birden fazla servisten oluşur. Docker Compose’un, build secret yeteneklerini çok servisli mimarilere nasıl genişlettiğine bakalım.

Build Secrets’ı Docker Compose ile Entegre Etme

Docker Compose, çok servisli uygulamalarda build secret yönetimini basitleştirir. docker-compose.yml dosyanızda secret’ları üst düzeyde tanımlayın ve servis build yapılandırmalarında referans verin:

services:
  app:
    build:
      context: .
      secrets:
        - api_key
        - db_password
  
secrets:
  api_key:
    file: ./.secrets/api_key
  db_password:
    environment: DB_PASSWORD

Ardından Dockerfile’ınızda secret’ları her zamanki gibi bağlayın:

RUN --mount=type=secret,id=api_key \
    --mount=type=secret,id=db_password \
    ./setup.sh

Compose ile build edin:

docker-compose build

Bu desen, farklı secret’lar gerektiren birden fazla servisi olan uygulamalar için iyi ölçeklenir; secret yönetimini merkezileştirirken servisler arasındaki güvenlik sınırlarını korur.

Projeleriniz genelinde build secrets uygularken kaçınılmaz olarak sorunlarla karşılaşacaksınız. Etkili şekilde sorun gidermenize yardımcı olmak için en yaygın zorlukları ve çözümlerini ele alalım.

Yaygın Zorluklar ve Sorun Giderme

Doğru uygulamaya rağmen zorluklarla karşılaşabilirsiniz. İşte en yaygın sorunlar ve çözümleri.

Sözdizimi hataları ve mount bildirimi sorunları

--mount sözdizimi katıdır. Yaygın hatalar arasında parametreler arasında virgül eksikliği, hatalı parametre adları ve yanlış mount türleri bulunur. Doğru sözdizimi şöyledir:

RUN --mount=type=secret,id=secret_name,target=/path \
    command

Build’ler "secret not found" hatasıyla başarısız olursa, BuildKit’in etkin olduğundan ve Dockerfile’daki ID’nin build komutunuzdaki --secret id ile eşleştiğinden emin olun.

Secret’ların erişilememesi veya bulunamaması

Secret’lara erişilemiyorsa, kaynak dosyanın mevcut ve okunabilir olduğunu doğrulayın:

cat .secrets/api_key
docker build --secret id=api_key,src=.secrets/api_key .

Ortam değişkenleri için, ayarlı olduklarını doğrulayın:

echo $API_KEY
docker build --secret id=api_key,env=API_KEY .

Ortam değişkeni vs. dosya karmaşası

Build secrets ile secret’lar varsayılan olarak her zaman /run/secrets/<id> altında dosya olarak bağlanır. Bunları ortam değişkeni olarak kullanmak için dosya içeriğini okuyun:

RUN --mount=type=secret,id=token \
    export TOKEN=$(cat /run/secrets/token) && \
    curl -H "Authorization: Bearer $TOKEN" https://api.example.com

Secret’lar için asla build argümanlarını (ARG) kullanmayın; bunlar imaj meta verilerinde kalıcıdır.

Kalıcılık ve katman önbellekleme sorunları

Tasarım gereği secret’lar RUN talimatları arasında kalıcı değildir. Aynı secret’a birden fazla RUN komutu ihtiyaç duyuyorsa, ya komutları birleştirin ya da secret’ı yeniden bağlayın:

RUN --mount=type=secret,id=token \
    command1

RUN --mount=type=secret,id=token \
    command2

BuildKit, secret’ların asla katman önbelleğine girmemesini sağlar.

Temel bilgileri ve yaygın sorun gidermeyi öğrendikten sonra, daha sofistike yaklaşımlar gerektiren senaryolarla karşılaşabilirsiniz. Standart uygulamaların ötesine geçen gelişmiş kullanım alanlarını ve uç durumları inceleyelim.

Docker Build Secrets Gelişmiş Kullanımlar

Karmaşık dağıtım senaryolarında, temel uygulamanın ötesinde ek hususları ele almanız gerekir.

Karmaşık CI/CD hatlarında secret’lar

Çok aşamalı CI/CD hatları, farklı aşamalarda secret’lar gerektirebilir. Kimlik bilgilerini paylaşmak yerine aşamaya özgü secret’lar uygulayın. Hangi hat aşamalarının hangi secret’lara erişebileceğini sınırlamak için CI/CD platform özelliklerini kullanın. Maruziyet pencerelerini en aza indirmek için build’lerden sonra secret temizliğini otomatikleştirin.

Docker dışı derleyicilerle secret’lar

Buildah ve Kaniko gibi alternatif derleyiciler, BuildKit’in secret sözdizimine farklı düzeylerde destek verir. Buildah, benzer secret bağlamayı --secret flags ile destekler. Kubernetes ortamları için tasarlanmış Kaniko ise genellikle hacim olarak bağlanan Kubernetes secret’ları gibi farklı mekanizmalar kullanır. Docker dışı derleyiciler kullanırken, uygulamalar önemli ölçüde farklı olduğundan özel dokümantasyonlarına başvurun.

Secret’lar ve güvenlik uyumluluğu

Build secret’lar, denetlenebilir ve geçici kimlik bilgisi erişimi sağlayarak güvenlik uyumluluk çerçeveleriyle uyumludur. 

GDPR uyumluluğu için, secret’ların katmanlara kişisel veriler sızdırmadığından emin olun. SOC2 gereksinimleri secret denetim izlerinden fayda sağlar—secret’ların ne zaman ve kim tarafından kullanıldığını kaydedin. Uyumluluk denetimleri için secret erişim kayıtlarını tutun.

Secret döndürme ve güncelleme

Build’leri aksatmadan secret döndürme süreçleri oluşturun. Sürümlendirilmiş secret dosyaları veya sürümler arasında geçişe izin veren ortam değişkeni adlandırma kuralları kullanın. 

Secret’ların merkezi depolardan yenilendiği CI/CD hatlarında otomatik döndürme uygulayın. Son kullanma tarihli belirteçler için, süresini izleyin ve yenileme süreçlerini otomatikleştirin.

Sonuç: En İyi Uygulamalar ve Öneriler

Docker build secrets, konteynerleştirilmiş uygulama geliştirme için temel bir güvenlik iyileştirmesidir. Bu eğitim boyunca, temel secret mount’larından karmaşık CI/CD entegrasyonuna kadar secret’ları güvenli şekilde nasıl uygulayacağımızı ele aldık.

Özetle: build argümanları veya gömülü kimlik bilgileri yerine her zaman BuildKit’in secret bağlama mekanizmalarını kullanın; secret kullanan aşamaları final imajlardan yalıtmak için çok aşamalı build’ler uygulayın; otomatik iş akışları için CI/CD platformunun secret yönetiminden yararlanın ve secret’ların katmanlara sızmadığını doğrulamak için imajları düzenli olarak denetleyin.

Bu uygulamaları benimseyen kuruluşlar için; build zamanı erişimi gerektiren secret’ları tanımlayan bir secret yönetimi politikasıyla başlayın, otomatik döndürme planları oluşturun, secret’ların imajlarda kalıcı olmadığını doğrulamak için kapsamlı testler uygulayın ve geliştirme ekiplerini doğru secret yönetimi örüntüleri konusunda eğitin. Build secrets’ı kritik bir güvenlik bileşeni olarak ele alarak, saldırı yüzeyinizi önemli ölçüde azaltır ve daha güvenli konteynerleştirilmiş uygulamalar geliştirirsiniz.

Öğrenmeye devam etmek için aşağıdaki kaynaklara göz atmanızı öneririm:

• Docker for Data Science Cheat Sheet
• Bir Docker İmajını Konteyner Olarak Çalıştırma: Uygulamalı Başlangıç Kılavuzu
• Konteynerleri Oluşturmak, Çalıştırmak ve Yönetmek için En İyi 18 Docker Komutu
• Konteynerleştirme: Makine Öğrenimi için Docker ve Kubernetes