SSD Nodes Learn Hosting plans →
Rehberler Matt ConnorYazan Matt Connor

Traefik v2'den v3'e Gecis: Dikkat Edilmesi Gerekenler

Traefik v3, static config icindeki swarmMode ve pilot ayarlarini desteklemez. Incompatible deprecated install configuration hatasini cozmek ve kurallari tasimak icin izleyin.

Traefik v2 ve v3 arasındaki değişiklikler

Traefik v2'den v3'e geçiş süreci büyük oranda yeniden adlandırma işlemlerinden ibarettir; en bilinen değişiklik ipWhiteList middleware bileşeninin ipAllowList olarak değiştirilmesidir. Bunun ötesinde v3, router kural sözdizimini sıkılaştırır (PathPrefix artık regex özelliklerini desteklemez, bazı eşleştiriciler yeniden adlandırılmış veya kaldırılmıştır), bazı sağlayıcıları ve seçenekleri tamamen devre dışı bırakır; ancak diğer tüm bileşenler çalışmaya devam eder: entrypoints, ACME sertifika kurulumu, Docker labels iş akışı ve acme.json ayarlarınız olduğu gibi korunur. v3 ayrıca v2 kural sözdizimini çalışır durumda tutan bir uyumluluk modu ile gelir; böylece ikili dosyayı (binary) önce yükseltebilir ve kuralları tek bir riskli gece yerine her servis için ayrı ayrı yeniden yazabilirsiniz.

Bu kılavuz, Traefik reverse proxy kılavuzu içerisindeki etiket tabanlı Docker Compose kurulumunu temel alır. Söz konusu sayfa v3 ile uyumludur; bu kılavuz ise hala traefik:v2 etiketini çalıştıran sistemler içindir.

Yeniden adlandırmalar ve kaldırmalar

  • ipWhiteList, hem HTTP hem de TCP ara katmanı (middleware) için artık ipAllowList olarak kullanılmaktadır. İçindeki seçenekler değişmemiştir, bu nedenle sourcerange tam olarak aynı anlamı korur. v3.7 dahil olmak üzere mevcut v3 sürümleri, eski ismi hala kullanımdan kaldırılmış bir takma ad olarak kabul etmekte ve listeyi zorunlu tutmaya devam ederek bu konuda bir uyarı günlüğü oluşturmaktadır; dolayısıyla bu yeniden adlandırma, geçiş sırasında herhangi bir kesintiye neden olmaz. Yine de yeniden adlandırma işlemini yapın: eski isim kullanımdan kaldırılmıştır ve v2.11 zaten ipAllowList ifadesini anladığından, yükseltme öncesinde bu değişiklik canlıya alınabilir.
  • providers.docker.swarmMode=true kaldırılmıştır. Swarm, providers.swarm.endpoint olarak yapılandırılan kendi sağlayıcısına (provider) sahiptir.
  • pilot bölümü tamamen kaldırılmıştır.
  • experimental.http3 kaldırılmıştır. HTTP/3 doğrudan giriş noktasında (entrypoint) etkinleştirilir.
  • tls.caOptional, sağlayıcılardan ve forwardAuth ara katmanından kaldırılmıştır. Eğer bu ara katman kendi kendine barındırılan bir Authentik SSO önünde yer alıyorsa, caOptional satırını silmek geçiş için yeterlidir; çünkü forwardAuth adresi, güvenilen başlıklar ve arkalarındaki outpost, v3 üzerinde aynı şekilde çalışır.
  • InfluxDB v1 metrik sağlayıcısı, Rancher sağlayıcısı ve Marathon sağlayıcısı kaldırılmıştır.
  • İzleme (tracing) özelliği OpenTelemetry'ye taşınmıştır. Jaeger ve Zipkin entegrasyonları dahil olmak üzere özel izleme arka uçları kaldırılmış olup, v3 bunun yerine OTLP (OpenTelemetry protokolü) dışa aktarmaktadır.
  • Headers ara katmanı içindeki kullanımdan kaldırılmış ssl* seçenekleri (sslRedirect, sslHost ve diğerleri) kaldırılmıştır. Bunların yerini giriş noktası yönlendirmeleri ve redirectScheme ara katmanı almıştır.

Bu kaldırmalar göründüğünden daha önemlidir, çünkü Traefik, statik yapılandırmasında kaldırılmış veya tanımadığı bir seçenek bulunduğunda başlatmayı reddeder. Geride kalan bir pilot, swarmMode, experimental.http3 veya sağlayıcı tls.caOptional satırı, konteyneri açılışta durdurur: Traefik önce geride kalanı belirten bir günlük satırı oluşturur (örneğin, Docker sağlayıcısı tls.CAOptional seçeneği v3'te kaldırılmıştır), ardından incompatible deprecated install configuration option found hatasıyla başarısız olur. v3.4'e kadar olan sürümler bu son mesajı incompatible deprecated static option found olarak ifade eder. Yazım hatası gibi Traefik'in hiç bilmediği bir seçenek, onu field not found ve düğüm hatasıyla durdurur. İmaj etiketine dokunmadan önce statik yapılandırmayı temizleyin.

Traefik'in gerçekten tanımadığı bir ara katman ismi (yazım hatası veya takma ad yerine kaldırılmış bir isim) farklı bir şekilde başarısız olur: ona başvuran yönlendirici (router) bir rota yerine hata ile yüklenir, kontrol paneli bunu işaretler ve API middleware "offce@docker" does not exist raporlar. Yönlendirici hiç ayağa kalkmadığı için o ana bilgisayar adına (hostname) gelen istekler 404 hatası alır. ipwhitelist ifadesinin mevcut v3 üzerinde bu kategoride OLMADIĞINI unutmayın: kullanımdan kaldırılmış bir takma ad olarak varlığını sürdürür, bu nedenle yeniden adlandırılmamış bir etiket sessizce çalışmaya devam eder.

Kural sözdizimi değişiklikleri

Kurallar, gerçek yeniden yazma işlemlerinin gerçekleştiği yerdir. v3 sürümündeki değişiklikler şunlardır:

  • Tırnak kullanımı bunlardan biri değildir. Her iki sürüm de kural değerlerini ters tırnak (backtick) veya kaçış karakteriyle kullanılan çift tırnak içinde kabul eder, tek tırnakları ise reddeder. Bu nedenle Host(app.example.com) ve kaçış karakterli çift tırnak içeren Host("app.example.com") ifadeleri geçerliliğini korur.
  • PathPrefix artık düzenli ifadeleri veya {id} tarzı yer tutucuları desteklememektedir. PathPrefix(/api/{version:v[0-9]+}) gibi bir v2 kuralı, Go düzenli ifade sözdizimiyle yazılmış bir PathRegexp eşleştiricisine dönüştürülmelidir.
  • Eşleştiriciler artık tek bir değer almaktadır. v2 sürümünde Host(app.example.com,www.example.com) kullanımına izin verilirken, v3 sürümünde Host(app.example.com) || Host(www.example.com) yapısı beklenmektedir. Bunun istisnaları, hala bir isim ve bir değer alan Header, HeaderRegexp, Query ve QueryRegexp eşleştiricileridir.
  • Headers ve HeadersRegexp, Header ve HeaderRegexp olarak yeniden adlandırılmıştır.
  • HostHeader kaldırılmıştır. v3 sürümünde aynı işlevi gören Host kullanılmalıdır.
  • İki yeni eşleştirici eklenmiştir: PathRegexp ve QueryRegexp. Bir kural içerisinde istemci adresini eşleştirmek için kullanılan ClientIP, v2.11 sürümünde zaten mevcuttu ve hiçbir değişiklik yapılmadan korunmuştur.

İyi haber: Ters tırnaklarla yazılmış basit bir Host(app.example.com) kuralı, halihazırda geçerli bir v3 sözdizimidir. Çoğu küçük Compose kurulumu tam olarak bu yapıyı kullandığından, etiketlerin büyük bir kısmı kural düzenlemesi gerektirmeden taşınabilir.

Başlamadan önce etiketlerinizi denetleyin

Her bir bozucu etiket değişikliği grep ile bulunabilecek bir desen bıraktığı için, tek bir arama ile taşıma işleminizin boyutunu ölçebilirsiniz:

grep -rnE 'ipwhitelist|HostHeader|Headers\(|PathPrefix\(`[^`]*\{|Host\(`[^`]*`,' docker-compose*.yml

Her bir eşleşme, düzenlenmesi gereken bir satırdır. ipwhitelist, ipallowlist haline gelir. HostHeader, Host haline gelir. Headers, Header haline gelir. PathPrefix içindeki bir {...} yer tutucusu, bir PathRegexp eşleştiricisine dönüşür. Host() içindeki bir virgül, || ile birleştirilmiş iki Host() eşleştiricisi haline gelir. Sıfır eşleşme, etiketlerinizin halihazırda geçerli v3 sözdizimine sahip olduğu anlamına gelir ve taşıma işlemi, statik yapılandırma ile imaj etiketine indirgenir. Ekranın eşleşmelerle dolu olması, bu proxy'nin sunucu için hala doğru tercih olup olmadığını sorgulamak için de uygun bir andır; Traefik'in Nginx ve Caddy ile karşılaştırması, bu yeniden yazma maliyetini diğer iki seçeneğin uygulama başına sizden talep ettikleriyle kıyaslamanızı sağlar.

Aynı kalanlar

Entrypoint'ler ve bunların HTTP'den HTTPS'e yönlendirmeleri, her iki challenge türüne sahip ACME resolver'lar, exposedByDefault, router ve service etiketleri, loadbalancer.server.port ve dashboard, v3 sürümünde v2'deki gibi çalışmaya devam eder. Sertifikalarınız da taşınabilir; çünkü v3, v2 tarafından yazılan acme.json dosyasını okumaya devam eder. Yine de başlamadan önce dosyanın yedeğini alın; çünkü bu dosyayı kaybeden bir geri dönüş (rollback), doğrudan Let's Encrypt mükerrer sertifika hız sınırına (rate limit) takılmanıza neden olur:

cp ./letsencrypt/acme.json ./letsencrypt/acme.json.v2-backup

Taşıma süreci

Adım 1: mevcut sürümünüzü sabitleyin. Tüm traefik:latest veya traefik:v2 etiketlerini halihazırda kullandığınız sürüme (örneğin traefik:v2.11) güncelleyin ve tüm compose dizinini git deposuna commit edin. Sonraki her adım, bir checkout işlemi ile geri alınabilir hale gelecektir. Eğer tek bir servisi docker compose up -d <service> ile yeniden oluşturmak henüz alışkanlık haline gelmediyse, Docker Compose temel kılavuzu bu taşıma sürecinin dayandığı işlemleri açıklamaktadır.

Adım 2: statik yapılandırmayı temizleyin ve uyumluluk modunu açın. v3 sürümünde kaldırılan tüm seçenekleri (pilot, swarmMode, tls.caOptional, experimental.http3) kaldırın, ardından v3'e kuralları varsayılan olarak v2 sözdizimi ile işlemesini söyleyin. traefik.yml dosyasında:

core:
  defaultRuleSyntax: v2

Veya compose command: listesindeki bir bayrak olarak: --core.defaultRuleSyntax=v2. Uyumluluk modu yalnızca kural sözdizimini kapsar. Kaldırılan seçenekleri geri getirmez ve middleware isimlerini sizin yerinize yeniden adlandırmaz.

Adım 3: v2.11 sürümündeyken middleware isimlerini güncelleyin. Compose dosyalarınızda eski isimleri aratın: grep -rn ipwhitelist docker-compose*.yml. Her ipwhitelist etiketini ipallowlist olarak düzenleyin ve ilgili servisleri docker compose up -d ile yeniden oluşturun. v2.11 sürümü halihazırda IPAllowList middleware bileşenini içerdiğinden, yeniden adlandırılan etiketler geçiş öncesinde çalışır ve IPWhiteList kullanım dışı bırakma uyarısı v2 loglarınızdan temizlenir. v2.11 öncesi sürümler yeni ismi tanımaz; bu nedenle 1. adımda daha eski bir v2 sürümü sabitlediyseniz, önce traefik:v2.11 sürümüne geçin. (Eğer gözden kaçan bir yapılandırma olursa, mevcut v3 sürümü eski ismi kullanım dışı bir alias olarak kabul etmeye devam eder, bu nedenle liste kısıtlamaları uygulamayı sürdürür; bu düzeltmeyi gece yarısı yapmak yerine bir sonraki aşamada gerçekleştirin.)

Adım 4: imaj etiketini değiştirin. Traefik imajını güncel v3 sürümüne ayarlayın; 11 Ekim 2026 itibarıyla bu traefik:v3.7 (v3.7.14 en güncel yamadır), ardından:

docker compose up -d
docker compose logs -f traefik

Uyumluluk modu açık olduğu için v2 kurallarınız eşleşmeye devam eder ve middleware isimleri v2.11 üzerinde zaten güncellendiği için router'lar sorunsuz ayağa kalkar. Sağlıklı bir log kaydında field not found veya does not exist satırı bulunmaz.

Bu adımın oluşturduğu kesinti penceresi konusunda gerçekçi olun. v3'ün tanımadığı bir middleware ismine (yazım hatası veya kaldırılmış bir seçenek) referans veren bir router, yeni Traefik başlayana kadar devre dışı kalır; bu durumu düzeltmek için etiketleri düzenleyip uygulama container'ını yeniden oluşturmanız gerekir. Eğer bir rota kesinlikle kesintiye uğrayamamalıysa, geçiş öncesinde o router'ın middlewares etiketinden şüpheli middleware bileşenini kaldırın ve geçiş sonrasında tekrar ekleyin; bu rota için arada geçen bir dakikalık sürede middleware olmadan çalışmanın kabul edilebilir olup olmadığına önceden karar verin.

Adım 5: kuralları servis bazında taşıyın. Her uygulamayı tek tek ele alın: kuralını v3 sözdizimine göre yeniden yazın, sadece o servisi docker compose up -d app ile yeniden oluşturun ve bir sonrakine geçmeden önce test edin. Eğer bir servisin kuralını henüz yeniden yazamıyorsanız, o router'a traefik.http.routers.app.ruleSyntax=v2 etiketini ekleyerek geçici bir çözüm sağlayın ve devam edin.

Adım 6: uyumluluk modunu kapatın. Tüm kurallar v3 sözdizimine geçtiğinde, defaultRuleSyntax ayarını ve tüm ruleSyntax etiketlerini silin, Traefik'i yeniden başlatın ve dashboard üzerinde tüm router'ların yeşil göründüğünü doğrulayın. Uyumluluk modu açıkken kalıcı olmayın: Traefik her iki seçeneği de v3.4 sürümünde kullanım dışı bıraktı ve bir sonraki ana sürümde tamamen kaldıracak; bu nedenle bunlar bir varış noktası değil, yalnızca bir köprüdür.

Öncesi ve sonrası: bir servisin etiketleri

Aşağıda, tüm önemli değişiklikleri aynı anda barındıran bir uygulama örneği yer almaktadır: çok değerli bir Host, bir PathPrefix yer tutucu ve bir ipWhiteList ara katman yazılımı. v2 bloğu:

  app:
    image: app:1.4
    restart: unless-stopped
    networks:
      - proxy
    labels:
      - traefik.enable=true
      - traefik.http.routers.app.rule=Host(`app.example.com`,`www.example.com`) && PathPrefix(`/api/{version:v[0-9]+}`)
      - traefik.http.routers.app.entrypoints=websecure
      - traefik.http.routers.app.tls.certresolver=le
      - traefik.http.routers.app.middlewares=office
      - traefik.http.middlewares.office.ipwhitelist.sourcerange=10.0.0.0/24
      - traefik.http.services.app.loadbalancer.server.port=8080

Aynı servisin v3 sürümüne geçirilmiş hali:

  app:
    image: app:1.4
    restart: unless-stopped
    networks:
      - proxy
    labels:
      - traefik.enable=true
      - traefik.http.routers.app.rule=(Host(`app.example.com`) || Host(`www.example.com`)) && PathRegexp(`^/api/v[0-9]+`)
      - traefik.http.routers.app.entrypoints=websecure
      - traefik.http.routers.app.tls.certresolver=le
      - traefik.http.routers.app.middlewares=office
      - traefik.http.middlewares.office.ipallowlist.sourcerange=10.0.0.0/24
      - traefik.http.services.app.loadbalancer.server.port=8080

İki etiket değişti. Kural, çok değerli Host ifadesini || ile birleştirilen iki eşleştiriciye böldü ve yer tutucuyu PathRegexp ile değiştirdi; ara katman yazılımı etiketi ise ipwhitelist ifadesini ipallowlist ile değiştirdi. Giriş noktası, sertifika çözümleyici, yönlendiriciden ara katman yazılımına bağlantı ve servis portu değişmedi.

Her servisi dashboard ile test edin

Her değişiklikten sonra dashboard üzerindeki HTTP routers sayfasını açın. Tüm yönlendiriciler yeşil renkte olmalıdır. Hata rozeti içeren bir yönlendirici, sorunun tam kaynağını belirtir; bu genellikle yeni ismiyle bulunamayan bir middleware veya v3 sürümünün ayrıştıramadığı bir kuraldır. Ardından, her seferinde bir hostname olacak şekilde dışarıdan doğrulama yapın:

curl -sI https://app.example.com/api/v1/status

Bir 200 veya uygulamanızın normal yönlendirmesi, hem yönlendirmenin hem de TLS'in çalıştığı anlamına gelir. Traefik'ten gelen bir 404, yönlendiricinin ayağa kalkmadığını gösterir; dashboard'a geri dönün ve hatayı okuyun. Çalışırken ikinci bir terminalde docker compose logs -f traefik dosyasını açık tutun, çünkü her ayrıştırma hatası bir container yeniden başladığı anda buraya düşer.

Geri alma dürüstlüğü

v2 compose dosyasını, statik yapılandırmasını ve acme.json yedeğini, tüm servisler v3 üzerinde yönlendirme yapana ve gerçek yük altında test edilene kadar saklayın. Geri alma işlemi, geçiş öncesi commit'e dönmeyi ve docker compose up -d komutunu çalıştırmayı gerektirir. Bu işlem sadece image etiketini değil, dosyanın tamamını kapsamalıdır; çünkü v3'e özgü sözdizimi v2 altında, v2 sözdiziminin v3 altında hatalı olduğu gibi hatalı çalışacaktır: bir PathRegexp eşleştiricisi orada ayrıştırılamaz. Yeniden adlandırılan ipallowlist etiketleri v2.11 üzerinde sorunsuz çalışır ancak yeni ismi tanımayan daha eski v2 sürümlerinde çalışmaz. Eğer acme.json geçiş sırasında kaybolduysa veya hasar gördüyse, v2'yi başlatmadan önce yedek kopyayı geri yükleyin. Böylece geri alma işlemi, beş sertifikayı aynı anda yeniden düzenleyerek Let's Encrypt hız sınırınızı tüketmemiş olur.

FAQ

Traefik v3 için tüm yönlendirici kurallarını yeniden yazmam gerekiyor mu?

Hayır. Backtick işaretleri ile yazılan basit bir Host(app.example.com) kuralı her iki sürümde de geçerlidir ve çoğu Compose kurulumunu kapsar. Yeniden yazma işlemi yalnızca kuralın v2'ye özgü özellikler kullandığı durumlarda gereklidir: Path ve PathPrefix içindeki regex veya yer tutucular, tek bir Host() içinde birden fazla ana makine adı veya kaldırılmış olan Headers, HeadersRegexp ve HostHeader eşleştiricileri.

Traefik v3'te ipWhiteList'e ne oldu?

ipAllowList olarak yeniden adlandırıldı ve içindeki yapılandırma değişmedi. Bu nedenle traefik.http.middlewares.office.ipwhitelist.sourcerange=10.0.0.0/24 gibi bir v2 etiketi, içinde ipallowlist bulunan aynı satıra dönüşür. v2.11 sürümü yeni ismi zaten kabul etmektedir, bu yüzden yükseltme yapmadan önce yeniden adlandırma işlemini gerçekleştirebilirsiniz. v3.7 dahil olmak üzere mevcut v3 sürümleri, eski ismi hala kullanımdan kaldırılmış bir takma ad olarak kabul eder; bu nedenle yeniden adlandırılmamış bir etiket, günlük kaydında yalnızca bir uyarı vererek izin listesini uygulamaya devam eder. Bunu bir erteleme nedeni olarak değil, geçici bir durum olarak değerlendirin: kullanımdan kaldırılan isimler bir sürümde tamamen çıkarılabilir. Traefik'in tanımadığı bir ara yazılım ismi ise doğrudan hata verir; yönlendirici hatası oluşur ve 404 döner. Hata gösterge panelinde görünür ve o ana makine adına yapılan istekler 404 ile sonuçlanır.

Traefik v3 hala v2 kural sözdizimini okuyabilir mi?

Evet. Geçiş sürecinde v2 sözdizimini varsayılan olarak tutmak için statik yapılandırmada core.defaultRuleSyntax: v2 ayarını yapın ve varsayılanı geri değiştirdikten sonra geride kalanlar için yönlendirici bazlı ruleSyntax=v2 etiketini kullanın. Her ikisini de geçici olarak değerlendirin: Traefik bunları v3.4 sürümünde kullanımdan kaldırdı ve bir sonraki ana sürümde tamamen kaldıracaktır.

Let's Encrypt sertifikalarım yükseltmeden sonra geçerli kalacak mı?

Evet. Traefik v3, v2 tarafından yazılan acme.json dosyasını okumaya devam eder, bu nedenle ikili dosya değişti diye sertifikalar yeniden oluşturulmaz. Yine de başlamadan önce dosyayı güvenli bir yere kopyalayın; çünkü bir geri alma işlemi veya acme.json dosyasını kaybeden silinmiş bir birim, tüm sertifikaların aynı anda yeniden oluşturulmasını zorunlu kılar. Let's Encrypt, aynı ana makine adı kümesi için haftada yalnızca beş kopya sertifikaya izin verir.

Traefik v3 yükseltmeden sonra neden başlamıyor?

Neredeyse her zaman statik yapılandırmanın v3'te kaldırılmış bir seçenek içermesi nedeniyledir; Traefik tanımadığı seçeneklerle başlamayı reddeder. Bilinen kalıntılar (pilot, providers.docker.swarmMode, experimental.http3 ve sağlayıcıların tls.caOptional ayarları) için günlük kaydı hatalı olanı belirtir ve ardından incompatible deprecated install configuration option found (v3.4 ve öncesinde incompatible deprecated static option found) mesajını verir. Yazım hatası gibi v3'ün hiç bilmediği durumlar için ise düğüm ile birlikte field not found mesajını verir. Her birini silin veya değiştirin, ardından container'ı tekrar başlatın.