Traefik v2'den v3'e Geçişte Dikkat Edilmesi Gerekenler

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.5 dahil olmak üzere mevcut v3 sürümleri, eski ismi hala kullanım dışı (deprecated) bir takma ad olarak kabul etmekte ve listeyi zorunlu tutmaya devam etmektedir; dolayısıyla bu yeniden adlandırma, mevcut yapılandırmayı bozmaz. Yine de yeniden adlandırma işlemini gerçekleştirin: takma adın kaldırılması planlanmıştır ve bu takma ad, kullanım dışı bırakılanlar listesinden sessizce kaldırılacaktır.
• providers.docker.swarmMode=true kaldırılmıştır. Swarm artık 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 bunların arkasındaki outpost, v3 üzerinde aynı şekilde çalışmaya devam eder.
• 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 artık OTLP (OpenTelemetry protokolü) üzerinden dışa aktarım yapmaktadır.
• Headers ara katmanı içindeki kullanım dışı 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 bilmediği bir seçenek olduğunda başlatmayı reddeder. Geride kalan bir pilot veya swarmMode satırı, konteynerin açılışta incompatible deprecated static option found mesajı ile durmasına ve ilgili satırın belirtilmesine neden olur; Traefik'in hiç tanımadığı bir seçenek (yazım hatası veya tls.caOptional) ise konteynerin field not found hatasıyla durmasına yol açar. İmaj etiketini güncellemeden ö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: bu ara katmana başvuran yönlendirici (router), bir rota yerine hata ile yüklenir, panelde işaretlenir ve API üzerinden middleware "offce@docker" does not exist raporlanır. O ana bilgisayar adına (hostname) gelen istekler, yönlendirici ayağa kalkmadığı için 404 hatası alır. ipwhitelist seçeneğinin mevcut v3 sürümünde bu kategoride OLMADIĞINI unutmayın: kullanım dışı 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:

• Eşleştiricilerin (matchers) içindeki değerlerin etrafında ters tırnak (backtick) kullanımı zorunludur. v2 sürümü çift tırnakları da kabul ediyordu; v3 etmez, bu nedenle Host("app.example.com") ifadesi Host(app.example.com) haline gelmelidir.
• PathPrefix artık düzenli ifadeleri veya {id} tarzı yer tutucuları anlamaz. 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 alı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) yapısını ister. Bunun istisnaları, hala bir isim ve bir değer alan Header, HeaderRegexp, Query ve QueryRegexp ifadeleridir.
• 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ı eşleşmeyi sağlayan Host kullanılmalıdır.
• İki yeni eşleştirici eklenmiştir: QueryRegexp ve bir kural içindeki istemci adresini eşleştirmek için ClientIP.

İ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 bunu kullanır, bu da çoğu etiketin hiçbir kural düzenlemesi gerektirmeden taşınabileceği anlamına gelir.

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ümle değiştirin (örneğin traefik:v2.11) 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 docker compose up -d <service> ile tek bir servisi yeniden oluşturmak henüz alışkanlık haline gelmediyse, Docker Compose temel rehberi, bu taşıma sürecinin dayandığı işlemleri kapsamaktadı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 ve ardından v3'e kuralları varsayılan olarak v2 sözdizimi ile işlemesini söyleyin. traefik.yml içerisinde:

core:
  defaultRuleSyntax: v2

Veya compose command: listesindeki bir flag 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: middleware isim değişikliklerini hazırlayın. Compose dosyalarınızda eski isimleri aratı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ş ile birlikte hayata geçecektir. (Eğer bir tanesi gözden kaçarsa, mevcut v3 sürümü eski ismi hala kullanım dışı (deprecated) bir takma ad olarak kabul eder; bu yüzden kural listesi çalışmaya devam eder. Bunu gece yarısı yerine bir sonraki geçişte düzeltin.)

Adım 4: imaj etiketini değiştirin. Traefik imajını güncel v3 sürümüne (yazıldığı tarih itibarıyla traefik:v3.5) ayarlayın ve 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 de yeniden oluşturduğu için bu yönlendiriciler (routers) sorunsuz ayağa kalkar. Sağlıklı bir log kaydında field not found satırı ve does not exist satırı bulunmaz.

Bu adımın açtığı kesinti penceresi konusunda kendinize karşı dürüst olun. v3'ün tanımadığı bir middleware ismine (yazım hatası veya kaldırılmış bir seçenek) referans veren bir yönlendirici, yeni Traefik başladığı andan uygulama container'ı yeniden oluşturulana kadar devre dışı kalır. Tek bir sunucuda bu, docker compose up -d komutunun listeyi işlemesi için gereken birkaç saniyedir. Eğer bir rota gerçekten kesintiye uğrayamazsa, geçişten önce o yönlendiricinin middlewares etiketinden yeniden adlandırılan middleware'i kaldırın ve geçişten sonra tekrar ekleyin. Bu arada, o rotanın bir dakikalığına IP izin listesi olmadan çalışıp çalışamayacağına önceden karar verin.

Adım 5: kuralları servis servis taşıyın. 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 kuralını henüz yeniden yazamıyorsanız, o yönlendiriciye traefik.http.routers.app.ruleSyntax=v2 etiketini verin ve devam edin.

Adım 6: uyumluluk modunu kapatın. Tüm kurallar v3 sözdizimine geçtiğinde, defaultRuleSyntax ve tüm ruleSyntax etiketlerini silin, Traefik'i yeniden başlatın ve dashboard üzerinde tüm yönlendiricilerin 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 seçenekler bir varış noktası değil, 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 güvenilirliği

Her servis v3 üzerinde yönlendirme yapana ve gerçek yük altında test edilene kadar v2 compose dosyasını, statik yapılandırmasını ve acme.json yedeğini saklayın. Geri alma işlemi, geçiş öncesi commit'e dönüp docker compose up -d komutunu çalıştırmak anlamına gelir. Bu işlem sadece imaj etiketiyle değil, dosyanın tamamıyla yapılmalıdır; çünkü v3'e özel etiketler v2 altında, v2 etiketlerinin v3 altında hatalı olduğu gibi hatalı çalışacaktır: ipallowlist v2 içinde mevcut değildir ve bir PathRegexp eşleştiricisi de orada ayrıştırılamayacaktır. Eğer süreç sırasında acme.json kaybolduysa veya zarar 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ılmış 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ı, backtick yerine tırnak işareti kullanımı veya kaldırılmış olan Headers, HeadersRegexp ve HostHeader eşleştiricileri.

Traefik v3'te ipWhiteList'e ne oldu?

İsmi ipAllowList olarak değiştirildi, yapılandırma içeriği aynı kaldı. Bu nedenle traefik.http.middlewares.office.ipwhitelist.sourcerange=10.0.0.0/24 gibi bir v2 etiketi, içinde ipallowlist geçen aynı satıra dönüşür. v3.5 dahil olmak üzere mevcut v3 sürümleri, eski ismi hala kullanım dışı (deprecated) bir takma ad olarak kabul etmektedir. Bu yüzden ismi değiştirilmemiş bir etiket, izin listesini sessizce uygulamaya devam eder. Bunu bir erteleme sebebi olarak değil, geçici bir durum olarak görün; takma adın kaldırılması planlanmaktadır. Traefik'in tanımadığı bir middleware ismi ise sessiz kalmaz; yönlendirici hatası verir ve 404 döndürür. Hata panoda (dashboard) görünür ve o ana makine adına gelen istekler 404 hatası 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. Varsayılanı geri çevirdikten sonra geride kalanlar için yönlendirici bazında ruleSyntax=v2 etiketini kullanın. Her ikisini de geçici olarak değerlendirin: Traefik bunları v3.4 sürümünde kullanım dışı bıraktı ve bir sonraki ana sürümde tamamen kaldıracak.

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 sadece binary değiştiği için sertifikalar yeniden oluşturulmaz. Yine de başlamadan önce dosyayı güvenli bir yere kopyalayın. Çünkü bir geri alma (rollback) işlemi veya acme.json dosyasını kaybeden silinmiş bir volume, 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 vermektedir.

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

Neredeyse her zaman statik yapılandırmada v3'te kaldırılmış bir seçeneğin kalması nedeniyledir; Traefik tanımadığı seçeneklerle başlamayı reddeder. Bilinen kalıntılar (pilot, providers.docker.swarmMode, experimental.http3) için günlük kaydı incompatible deprecated static option found der ve sorunun kaynağını belirtir. Traefik'in hiç bilmediği tls.caOptional gibi durumlar için ise düğüm bilgisiyle birlikte field not found hatasını verir. Her birini silin veya değiştirin, ardından container'ı tekrar başlatın.