Traefik v2'den v3'e geçerken dikkat edilecekler

Traefik v2 ve v3 arasındaki farklar

Traefik v2'den v3'e geçiş temel olarak bir yeniden adlandırma işlemidir; en bilinen değişiklik ipWhiteList middleware bileşeninin ipAllowList olarak değiştirilmesidir. Bunun dışında v3, router kural sözdizimini sıkılaştırmıştır (PathPrefix regex özelliklerini kaybetmiştir, çeşitli matcher bileşenleri yeniden adlandırılmış veya kaldırılmıştır), bazı provider ve seçenekleri tamamen kaldırmıştır; ancak entrypoints, ACME sertifika kurulumu, Docker labels iş akışı ve acme.json gibi diğer tüm özellikler çalışmaya devam eder. v3 ayrıca v2 kural sözdizimini destekleyen bir uyumluluk modu ile birlikte gelir; bu sayede binary yükseltmesi yapıldıktan sonra kurallar riskli bir akşam yerine her seferinde bir servis olacak şekilde yeniden yazılabilir.

Bu kılavuz, Traefik reverse proxy kılavuzu içindeki label tabanlı Docker Compose kurulumunu temel alır. İlgili sayfa v3 uyumludur; bu sayfa ise hala traefik:v2 etiketiyle çalışan sistemler içindir.

Yeniden adlandırmalar ve kaldırmalar

• Hem HTTP hem de TCP middleware bileşenleri için ipWhiteList artık ipAllowList olarak adlandırılmaktadır. İçerideki seçenekler değişmemiştir, bu nedenle sourcerange aynı anlama gelmeye devam eder. v3.5 dahil mevcut v3 sürümleri, eski ismi kullanımdan kaldırılmış bir takma ad (alias) olarak kabul etmeye ve listeyi uygulamaya devam etmektedir; bu nedenle bu yeniden adlandırma herhangi bir kesintiye yol açmaz. Yine de yeniden adlandırın: takma adın kaldırılması planlanmaktadır ve bu işlem sessizce gerçekleşecektir.
• providers.docker.swarmMode=true kaldırıldı. Swarm, providers.swarm.endpoint olarak yapılandırılan kendi sağlayıcısına (provider) sahiptir.
• pilot bölümü tamamen kaldırıldı.
• experimental.http3 kaldırıldı. HTTP/3 doğrudan entrypoint üzerinden etkinleştirilir.
• tls.caOptional hem sağlayıcılardan hem de forwardAuth middleware bileşeninden kaldırıldı.
• InfluxDB v1 metrics provider, Rancher provider ve Marathon provider kaldırıldı.
• Tracing özelliği OpenTelemetry'ye taşındı. Jaeger ve Zipkin entegrasyonları dahil olmak üzere özel tracing backend bileşenleri kaldırıldı; v3 bunun yerine OTLP (OpenTelemetry protocol) dışa aktarır.
• headers middleware içindeki kullanımdan kaldırılmış ssl* seçenekleri (sslRedirect, sslHost ve diğerleri) kaldırıldı. Bunların yerini entrypoint yönlendirmeleri ve redirectScheme middleware bileşeni aldı.

Bu kaldırmalar göründüğünden daha önemlidir; çünkü Traefik, statik yapılandırmasında tanımadığı bir seçenek bulunduğunda başlamayı reddeder. Artık mevcut olmayan bir pilot veya swarmMode satırı, konteynerin açılışta ilgili satırı belirten bir incompatible deprecated static option found mesajı ile durmasına neden olur; Traefik'in hiç duymadığı bir seçenek (yazım hatası veya tls.caOptional) ise bunun yerine field not found mesajı ile durmasına neden olur. Image tag değerini değiştirmeden önce statik yapılandırmayı temizleyin.

Traefik'in gerçekten tanımadığı bir middleware ismi (yazım hatası veya takma ad yerine doğrudan kaldırılmış bir isim) farklı şekilde hata verir: Bu isme referans veren router bir rota yerine hata ile yüklenir, dashboard bunu işaretler ve API middleware "offce@docker" does not exist raporlar. Router devreye girmediği için o hostname'e gelen istekler 404 hatası alır. Mevcut v3 sürümünde ipwhitelist'nın bu kategoride olmadığını unutmayın: Kullanımdan kaldırılmış bir takma ad olarak varlığını sürdürür, bu nedenle yeniden adlandırılmamış etiketler sorunsuz çalışmaya devam eder.

Kural sözdizimi değişiyor

Kurallar, asıl yeniden yazma işleminin gerçekleştiği yerdir. v3 sürümündeki değişiklikler:

• Matcher içindeki değerlerin etrafında backtick kullanımı zorunludur. v2 çift tırnağı kabul ediyordu; v3 kabul etmemektedir, bu nedenle Host("app.example.com") ifadesi Host(app.example.com) şeklinde yazılmalıdır.
• PathPrefix artık düzenli ifadeleri (regular expressions) veya {id} tarzı yer tutucuları (placeholders) anlamamaktadır. v2 sürümündeki PathPrefix(/api/{version:v[0-9]+}) gibi bir kural, Go düzenli ifade sözdizimi ile yazılmış bir PathRegexp matcher ifadesine dönüştürülmelidir.
• Matcher'lar artık tek bir değer almaktadır. v2 sürümü Host(app.example.com,www.example.com) kullanımına izin veriyordu; v3 sürümü ise Host(app.example.com) || Host(www.example.com) kullanımını gerektirmektedir. İstisnalar olan Header, HeaderRegexp, Query ve QueryRegexp, hala bir isim ve bir değer almaktadır.
• 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ın.
• İki yeni matcher eklenmiştir: kural içindeki istemci adresini eşleştirmek için QueryRegexp ve ClientIP.

İyi haber: Backtick kullanılarak yazılmış düz bir Host(app.example.com) kuralı, halihazırda geçerli bir v3 sözdizimidir. Çoğu küçük Compose kurulumu tam olarak bunu kullanmaktadır; bu da çoğu etiketin (label) kural düzenlemesi gerektirmeden taşınabileceği anlamına gelir.

Başlamadan önce etiketlerinizi denetleyin

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

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

Her eşleşme, düzenlenmesi gereken bir satır demektir. ipwhitelist, ipallowlist olur. HostHeader, Host olur. Headers, Header olur. PathPrefix içindeki bir {...} yer tutucusu, PathRegexp eşleştiricisine dönüşür. Host() içindeki bir virgül, || ile birleştirilmiş iki Host() eşleştiricisine dönüşür. Sıfır eşleşme, etiketlerinizin halihazırda geçerli v3 sözdizimine sahip olduğu anlamına gelir; bu durumda taşıma işlemi, statik konfigürasyon ve imaj etiketi ile sınırlı kalır.

Değişmeyenler

Entrypoint'ler ve HTTP-to-HTTPS yönlendirmeleri, her iki challenge türüne sahip ACME resolver'ları, exposedByDefault, router ve service etiketleri, loadbalancer.server.port ve dashboard, v2'de olduğu gibi v3'te de çalışmaya devam eder. Sertifikalarınız da geçerliliğini korur; çünkü v3, v2 tarafından yazılan acme.json dosyasını okumaya devam eder. İşleme başlamadan önce dosyayı yedekleyin; dosyanın kaybolduğu bir geri yükleme işlemi, doğrudan Let's Encrypt duplicate-certificate hız sınırına (rate limit) yol açar:

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

Göç yolu

Adım 1: mevcut sürümü sabitleyin. Tüm traefik:latest veya traefik:v2 etiketlerini kullandığınız tam sürümle değiştirin (örneğin traefik:v2.11) ve tüm compose dizinini git'e commit edin. Sonraki her adım, bir checkout işlemi ile geri alınabilir hale gelecektir. Eğer docker compose up -d <service> ile tek bir servisi yeniden oluşturmak henüz alışkanlık haline gelmediyse, Docker Compose temelleri kılavuzu bu göç işleminin dayandığı operasyonları kapsamaktadır.

Adım 2: statik konfigürasyonu 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özdizimiyle işlemesini söyleyin. traefik.yml içinde:

core:
  defaultRuleSyntax: v2

Veya compose command: listesinde bir flag olarak: --core.defaultRuleSyntax=v2. Uyumluluk modu yalnızca kural sözdizimini kapsar. Kaldırılmış seçenekleri geri getirmez ve middleware isimlerini sizin için değiştirmez.

Adım 3: middleware yeniden adlandırmalarını hazırlayın. Compose dosyalarınızda eski isimleri arayın: grep -rn ipwhitelist docker-compose*.yml. Her ipwhitelist etiketini ipallowlist olarak düzenleyin, ancak değişikliği henüz uygulamayın; çünkü yeni isim v2 sürümünde mevcut değildir. Bu düzenlemeler, bir sonraki adımdaki geçişle birlikte uygulanacaktır. (Eğer bir tanesi gözden kaçarsa, mevcut v3 eski ismi kullanımdan kaldırılmış bir takma ad olarak tanımaya devam eder, bu nedenle liste zorunluluğu sürer; hatayı gece yarısı düzeltmek yerine bir sonraki turda düzeltin.)

Adım 4: image tag'ini değiştirin. Traefik imajını mevcut v3 sürümüne, yazım anında traefik:v3.5 sürümüne ayarlayın, 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 up -d middleware etiketlerini yeniden adlandırdığınız servisleri yeniden oluşturduğu için router'lar sorunsuz çalışır. Sağlıklı bir log dosyasında field not found satırı ve does not exist satırı bulunmaz.

Bu adımın yarattığı zaman aralığı konusunda dürüst olun. v3'ün gerçekten tanımadığı bir middleware ismine (yazım hatası veya kaldırılmış bir seçenek) referans veren bir router, yeni Traefik başladığı andan uygulama konteynerinin yeniden oluşturulmasına kadar devre dışıdır; bu, tek bir makinede docker compose up -d için listenin işlenmesi gereken birkaç saniye kadardır. Eğer bir rota kesinlikle kesintiye uğramamalıysa, geçişten önce o router'ın middlewares etiketinden yeniden adlandırılmış middleware'i kaldırın ve geçişten sonra tekrar ekleyin; ayrıca o rotanın aradaki bir dakika boyunca IP izin listesi olmadan çalışıp çalışamayacağına önceden karar verin.

Adım 5: kuralları servis servis göç ettirin. Her seferinde bir uygulama üzerinde ç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 devam etmeden önce test edin. Eğer bir servisin henüz yeniden yazamadığınız bir kuralı varsa, o tek router'a traefik.http.routers.app.ruleSyntax=v2 kaçış etiketi verin ve ilerlemeye devam edin.

Adım 6: uyumluluk modunu kapatın. Tüm kurallar v3 sözdizimine sahip olduğunda, defaultRuleSyntax ve tüm ruleSyntax etiketlerini silin, Traefik'i yeniden başlatın ve her router'ın dashboard üzerinde hala yeşil göründüğünü onaylayın. Uyumluluk modu açık bir şekilde kalmayın: Traefik, her iki seçeneği de v3.4 sürümünde kullanımdan kaldırmıştır ve bir sonraki ana sürümde tamamen silecektir; bu seçenekler bir köprüdür, varış noktası değildir.

Önce ve sonra: bir servisin etiketleri

Aşağıda, tüm yaygın değişiklikleri aynı anda içeren bir uygulama örneği verilmiştir: çok değerli bir Host, bir PathPrefix yer tutucusu ve bir ipWhiteList middleware bileşeni. 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 taşınmış 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 değerini || ile birleştirilmiş iki eşleştiriciye ayırdı ve yer tutucuyu PathRegexp ile değiştirdi; middleware etiketi ise ipwhitelist değerini ipallowlist ile değiştirdi. Entrypoint, sertifika çözücü, router-to-middleware bağlantısı ve servis portu değişmedi.

Her servisi dashboard üzerinden test edin

Her geçişten sonra, dashboard'un HTTP routers sayfasını açın. Tüm router'lar yeşil görünmelidir. Hata rozeti olan bir router, sorunun kaynağını belirtir; bu genellikle yeni ismiyle mevcut olmayan 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 kontrol sağlayın:

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

Bir 200 veya uygulamanızın normal yönlendirmesi, hem routing hem de TLS işlemlerinin başarıyla çalıştığını gösterir. Traefik'ten gelen bir 404, router'ın başlatılamadığı anlamına gelir; dashboard'a geri dönerek hata mesajını inceleyin. Çalışırken ikinci bir terminalde docker compose logs -f traefik sayfasını açık tutun; bir konteyner yeniden başladığında tüm ayrıştırma hataları anında buraya düşer.

Rollback dürüstlüğü

Tüm servisler v3 üzerinde yönlendirme yapana ve gerçek verilerle test edilene kadar v2 compose dosyasını, statik konfigürasyonu ve acme.json yedeğini saklayın. Rollback işlemi, migrasyon öncesi commit'in çekilmesi ve docker compose up -d komutunun çalıştırılması anlamına gelir. İşlem sadece image tag'ini değil, dosyanın tamamını kapsamalıdır; çünkü v3'e özel etiketler, v2 altında v2 etiketlerinin v3 altında hatalı olmasıyla aynı şekilde hatalı sonuç verir: ipallowlist v2 içerisinde mevcut değildir ve PathRegexp matcher'ı orada ayrıştırılamaz. Eğer süreç sırasında acme.json kaybolursa veya zarar görürse, v2 başlatılmadan önce yedek kopyayı geri yükleyin; böylece rollback işlemi Let's Encrypt rate limit sınırını beş sertifikanın aynı anda yeniden oluşturulmasıyla tüketmez.

FAQ

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

Hayır. Backtick kullanılarak yazılan düz bir Host(app.example.com) kuralı her iki sürümde de geçerlidir; bu durum çoğu Compose kurulumunu kapsar. Yeniden yazma işlemi yalnızca şu durumlarda gereklidir: kuralın sadece v2'ye özgü özellikler kullanması; Path ve PathPrefix içinde regex veya placeholder kullanımı, tek bir Host() içinde birden fazla hostname kullanımı, backtick yerine tırnak işareti kullanımı veya kaldırılan Headers, HeadersRegexp ve HostHeader matcher'ları.

Traefik v3'te ipWhiteList ne oldu?

ipAllowList olarak yeniden adlandırıldı. İçerideki yapılandırma değişmediği için, 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. v3.5 dahil mevcut v3 sürümleri, eski ismi hala kullanımdan kaldırılmış bir takma ad (alias) olarak kabul eder; bu nedenle değiştirilmemiş bir etiket, izin listesini sessizce uygulamaya devam eder. Bu durumu yeniden adlandırmayı atlamak için bir sebep değil, ödünç alınmış bir zaman olarak değerlendirin: takma adın kaldırılması planlanmaktadır. Traefik'in tanımadığı bir middleware ismi kullanılırsa, sistem hata verir ve bir router hatası ile 404 döndürür. Dashboard hatayı gösterir ve o hostname'e yapılan istekler 404 döndürü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; varsayılan ayarı eski haline döndürdükten sonra ise tekil gecikenler için her router için ruleSyntax=v2 etiketini kullanın. Her ikisini de geçici olarak kabul edin: Traefik bunları v3.4 sürümünde kullanımdan kaldırmış olup bir sonraki ana sürümde tamamen kaldıracaktır.

Let's Encrypt sertifikalarım yükseltme sırasında korunacak mı?

Evet. Traefik v3, v2 tarafından yazılan acme.json dosyasını okumaya devam eder; bu nedenle sadece binary değiştiği için sertifikalar yeniden oluşturulmaz. Yine de işleme başlamadan önce dosyayı güvenli bir yere kopyalayın; çünkü bir geri dönüş (rollback) veya acme.json verisinin kaybolmasına neden olan silinmiş bir volume, tüm sertifikaların aynı anda yeniden oluşturulmasına neden olur. Let's Encrypt, aynı hostname seti için haftada yalnızca beş mükerrer sertifikaya izin verir.

Yükseltme sonrası Traefik v3 neden başlamıyor?

Neredeyse her zaman, statik yapılandırmanın hala v3 tarafından kaldırılmış bir seçenek içermesi nedeniyle oluşur; Traefik tanımadığı seçeneklerle çalışmayı reddeder. Bilinen kalıntılar (pilot, providers.docker.swarmMode, experimental.http3) için loglarda incompatible deprecated static option found ifadesi yer alır ve suçlu belirtilir; tls.caOptional gibi v3'ün daha önce hiç duymadığı bir şey için ise düğüm (node) ile birlikte field not found ifadesi yer alır. Her birini silin veya değiştirin, ardından konteyneri tekrar başlatın.