Migracja Traefik v2 do v3: co przestanie działać

Co zmienia się między Traefik v2 a v3

Migracja z Traefik v2 do v3 polega głównie na zmianie nazw; najbardziej znaną jest zmiana middleware ipWhiteList na ipAllowList. Poza tym v3 zaostrza składnię reguł routera (PathPrefix traci funkcje regex, kilka matcherów zostało przemianowanych lub usuniętych), całkowicie usuwa niektóre providery i opcje, a reszta pozostaje bez zmian: entrypoints, konfiguracja certyfikatów ACME, workflow etykiet Docker oraz Twoje acme.json działają nadal. Wersja v3 zawiera również tryb kompatybilności, który utrzymuje działanie składni reguł z v2, dzięki czemu można najpierw zaktualizować plik binarny, a następnie przepisywać reguły dla każdej usługi pojedynczo, zamiast ryzykować wszystko jednego wieczoru.

Ten przewodnik zakłada konfigurację Docker Compose opartą na etykietach z przewodnika po reverse proxy Traefik. Ta strona jest natywna dla v3; niniejszy tekst dotyczy serwera, który nadal używa tagu traefik:v2.

Zmiany nazw i usunięcia

• ipWhiteList to teraz ipAllowList, zarówno dla middleware HTTP, jak i TCP. Opcje wewnątrz pozostają bez zmian, więc sourcerange zachowuje swoje dokładne znaczenie. Bieżące wydania v3, w tym v3.7, nadal akceptują starą nazwę jako przestarzały alias i wymuszają listę, logując ostrzeżenie o wycofaniu, więc ta zmiana nazwy nie powoduje awarii. Należy jednak dokonać zmiany: stara nazwa jest przestarzała, a v2.11 już rozpoznaje ipAllowList, więc zmianę można wprowadzić przed aktualizacją.
• providers.docker.swarmMode=true zostało usunięte. Swarm posiada własnego dostawcę, konfigurowanego jako providers.swarm.endpoint.
• Sekcja pilot została całkowicie usunięta.
• experimental.http3 zostało usunięte. HTTP/3 włącza się bezpośrednio w punkcie wejścia (entrypoint).
• tls.caOptional zostało usunięte z dostawców oraz z middleware forwardAuth. Jeśli ten middleware obsługuje własną instancję Authentik SSO, usunięcie linii caOptional stanowi pełną migrację, ponieważ adres forwardAuth, zaufane nagłówki i stojący za nimi outpost działają w v3 identycznie.
• Dostawca metryk InfluxDB v1, dostawca Rancher oraz dostawca Marathon zostały usunięte.
• Śledzenie (tracing) przeniesiono do OpenTelemetry. Dedykowane backendy śledzenia, w tym integracje Jaeger i Zipkin, zostały usunięte, a v3 eksportuje dane za pomocą OTLP (protokół OpenTelemetry).
• Przestarzałe opcje ssl* wewnątrz middleware headers (sslRedirect, sslHost i pozostałe) zostały usunięte. Zastąpiono je przekierowaniami w punktach wejścia oraz middleware redirectScheme.

Te usunięcia mają większe znaczenie, niż się wydaje, ponieważ Traefik odmawia uruchomienia, gdy statyczna konfiguracja zawiera opcję usuniętą lub nieznaną. Pozostała linia pilot, swarmMode, experimental.http3 lub dostawca tls.caOptional zatrzymuje kontener podczas startu: Traefik najpierw loguje linię wskazującą na pozostałość (na przykład opcja dostawcy Docker tls.CAOptional została usunięta w v3), a następnie kończy działanie z błędem incompatible deprecated install configuration option found. Wydania do v3.4 określają ten ostatni komunikat jako incompatible deprecated static option found. Opcja, której Traefik nigdy nie obsługiwał, na przykład z powodu literówki, zatrzymuje go z błędem field not found oraz informacją o węźle. Należy oczyścić statyczną konfigurację przed zmianą tagu obrazu.

Nazwa middleware, której Traefik nie rozpoznaje (literówka lub nazwa, która została usunięta, a nie zastąpiona aliasem), powoduje inny błąd: router odwołujący się do niej ładuje się z błędem zamiast trasy, dashboard oznacza go, a API zgłasza middleware "offce@docker" does not exist. Żądania do tej nazwy hosta otrzymują 404, ponieważ router nie został uruchomiony. Należy zauważyć, że ipwhitelist NIE znajduje się w tej kategorii w bieżącej wersji v3: pozostaje jako przestarzały alias, więc etykieta z niezmienioną nazwą nadal działa bez zakłóceń.

Zmiana składni reguł

Reguły to miejsce, w którym odbywa się właściwe przepisywanie ruchu. Zmiany w wersji v3:

• Cytowanie nie uległo zmianie. Obie wersje przyjmują wartości reguł w odwrotnych apostrofach lub w cudzysłowach z użyciem znaku ucieczki, natomiast odrzucają pojedyncze apostrofy. Zapisy Host(app.example.com) oraz Host("app.example.com") z cudzysłowem z ucieczką pozostają poprawne.
• PathPrefix nie obsługuje już wyrażeń regularnych ani symboli zastępczych typu {id}. Reguła v2, taka jak PathPrefix(/api/{version:v[0-9]+}), musi zostać zamieniona na matcher PathRegexp zapisany zgodnie ze składnią wyrażeń regularnych języka Go.
• Matchery przyjmują teraz pojedynczą wartość. Wersja v2 pozwalała na Host(app.example.com,www.example.com); wersja v3 wymaga zapisu Host(app.example.com) || Host(www.example.com). Wyjątkami są Header, HeaderRegexp, Query oraz QueryRegexp, które nadal przyjmują nazwę oraz wartość.
• Headers oraz HeadersRegexp zostały przemianowane na Header oraz HeaderRegexp.
• HostHeader zostało usunięte. Należy użyć Host, które w wersji v3 odpowiada za to samo.
• Dodano dwa nowe matchery: PathRegexp oraz QueryRegexp. ClientIP, służący do dopasowywania adresu klienta wewnątrz reguły, istniał już w wersji v2.11 i został przeniesiony bez zmian.

Dobra wiadomość: prosta reguła Host(app.example.com) zapisana z użyciem odwrotnych apostrofów jest już poprawną składnią v3. Większość małych konfiguracji Compose korzysta dokładnie z takiego zapisu, co oznacza, że większość etykiet migruje bez konieczności edycji reguł.

Audyt etykiet przed rozpoczęciem

Można oszacować skalę migracji za pomocą jednego wyszukiwania, ponieważ każda zmiana etykiety powodująca błędy pozostawia wzorzec, który można wykryć za pomocą grep:

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

Każde trafienie to jedna linia do edycji. ipwhitelist zmienia się w ipallowlist. HostHeader zmienia się w Host. Headers zmienia się w Header. Symbol zastępczy {...} wewnątrz PathPrefix staje się dopasowaniem PathRegexp. Przecinek wewnątrz Host() staje się dwoma dopasowaniami Host() połączonymi za pomocą ||. Brak trafień oznacza, że etykiety są już zgodne ze składnią v3, a migracja ogranicza się do konfiguracji statycznej oraz tagu obrazu. Ekran pełen trafień to również dobry moment na rozważenie, czy jest to nadal właściwy serwer proxy dla danej maszyny, a porównanie Traefik z Nginx i Caddy pozwala zestawić koszt przepisania konfiguracji z wymaganiami pozostałych dwóch rozwiązań dla każdej aplikacji.

Co pozostaje bez zmian

Punkty wejścia (entrypoints) wraz z przekierowaniem z HTTP na HTTPS, resolvery ACME obsługujące oba typy wyzwań, exposedByDefault, etykiety routerów i usług, loadbalancer.server.port, oraz pulpit nawigacyjny (dashboard) działają w wersji v3 tak samo jak w v2. Certyfikaty również zostają zachowane, ponieważ v3 odczytuje plik acme.json zapisany przez v2. Przed rozpoczęciem prac należy wykonać kopię zapasową tego pliku, ponieważ wycofanie zmian (rollback) prowadzące do jego utraty skutkuje przekroczeniem limitu częstotliwości wydawania certyfikatów przez Let's Encrypt:

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

Ścieżka migracji

Krok 1: przypnij aktualnie używane wersje. Zmień każdy tag traefik:latest lub traefik:v2 na konkretną wersję, na której obecnie pracujesz, na przykład traefik:v2.11, a następnie zatwierdź cały katalog compose w git. Każdy kolejny krok stanie się odwracalny za pomocą polecenia checkout. Jeśli odtwarzanie pojedynczej usługi za pomocą docker compose up -d <service> nie jest jeszcze czynnością automatyczną, przewodnik po podstawach Docker Compose omawia operacje, na których opiera się ta migracja.

Krok 2: wyczyść konfigurację statyczną i włącz tryb kompatybilności. Usuń każdą opcję usuniętą w wersji v3 (pilot, swarmMode, tls.caOptional, experimental.http3), a następnie skonfiguruj v3 tak, aby domyślnie traktowała reguły zgodnie ze składnią v2. W pliku traefik.yml:

core:
  defaultRuleSyntax: v2

Lub jako flagę na liście command: w pliku compose: --core.defaultRuleSyntax=v2. Tryb kompatybilności obejmuje tylko składnię reguł. Nie przywraca usuniętych opcji i nie zmienia automatycznie nazw middleware.

Krok 3: zastosuj zmiany nazw middleware, pozostając jeszcze na wersji v2.11. Przeszukaj pliki compose pod kątem starych nazw: grep -rn ipwhitelist docker-compose*.yml. Edytuj każdą etykietę ipwhitelist na ipallowlist i odtwórz te usługi za pomocą docker compose up -d. Wersja v2.11 zawiera już middleware IPAllowList, więc zmienione etykiety działają przed przełączeniem, a ostrzeżenie o wycofaniu IPWhiteList znika z logów v2. Wersje starsze niż v2.11 nie rozpoznają nowej nazwy, więc jeśli w kroku 1 przypięto starszą wersję v2, najpierw przejdź do traefik:v2.11. (Jeśli jakaś nazwa zostanie pominięta, obecna wersja v3 nadal honoruje starą nazwę jako przestarzały alias, więc lista zachowuje swoje działanie; popraw to w kolejnym kroku, zamiast w środku nocy).

Krok 4: zmień tag obrazu. Ustaw obraz Traefik na aktualną wersję v3, traefik:v3.7 (stan na 11 października 2026, v3.7.14 to najnowsza poprawka), a następnie:

docker compose up -d
docker compose logs -f traefik

Ponieważ tryb kompatybilności jest włączony, reguły v2 nadal pasują, a ponieważ zmiany nazw middleware weszły w życie już w wersji v2.11, routery uruchamiają się poprawnie. Poprawny log nie zawiera linii field not found ani does not exist.

Oceń realnie okno serwisowe, które otwiera ten krok. Router odwołujący się do nazwy middleware, której v3 nie rozpoznaje (literówka lub usunięta opcja), przestaje działać w momencie uruchomienia nowego Traefik, aż do momentu poprawienia etykiet i odtworzenia kontenera aplikacji. Jeśli trasa nie może zostać przerwana, usuń podejrzany middleware z etykiety middlewares routera przed przełączeniem i dodaj go ponownie po nim. Zdecyduj wcześniej, czy trasa może funkcjonować bez niego przez minutę przerwy.

Krok 5: migruj reguły usługa po usłudze. Pracuj nad jedną aplikacją na raz: przepisz jej regułę na składnię v3, odtwórz tylko tę usługę za pomocą docker compose up -d app i przetestuj ją przed przejściem dalej. Jeśli usługa posiada regułę, której jeszcze nie można przepisać, nadaj temu pojedynczemu routerowi etykietę obejścia traefik.http.routers.app.ruleSyntax=v2 i kontynuuj pracę.

Krok 6: wyłącz tryb kompatybilności. Gdy każda reguła używa składni v3, usuń defaultRuleSyntax oraz wszelkie etykiety ruleSyntax, zrestartuj Traefik i potwierdź, że każdy router nadal jest widoczny jako aktywny w panelu sterowania. Nie przyzwyczajaj się do trybu kompatybilności: Traefik oznaczył obie opcje jako przestarzałe w wersji v3.4 i usunie je w kolejnej głównej wersji, więc stanowią one jedynie rozwiązanie przejściowe, a nie docelowe.

Przed i po: etykiety jednej usługi

Oto aplikacja zawierająca wszystkie istotne zmiany jednocześnie: wielowartościowy Host, symbol zastępczy PathPrefix oraz middleware ipWhiteList. Blok v2:

  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

Oraz ta sama usługa po migracji do v3:

  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

Zmieniono dwie etykiety. Reguła rozdzieliła wielowartościowy Host na dwa dopasowania połączone za pomocą || i zamieniła symbol zastępczy na PathRegexp, a etykieta middleware zamieniła ipwhitelist na ipallowlist. Punkt wejścia (entrypoint), resolver certyfikatów, powiązanie routera z middleware oraz port usługi pozostały bez zmian.

Testowanie każdej usługi za pomocą panelu sterowania

Po każdej zmianie należy otworzyć stronę routerów HTTP w panelu sterowania. Każdy router powinien być oznaczony kolorem zielonym. Router z ikoną błędu wskazuje konkretny problem, zazwyczaj jest to middleware, który nie istnieje pod nową nazwą lub reguła, której v3 nie potrafi przetworzyć. Następnie należy potwierdzić działanie z zewnątrz, sprawdzając każdą nazwę hosta z osobna:

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

Kod 200 lub standardowe przekierowanie aplikacji oznacza, że routing oraz TLS działają poprawnie. Kod 404 zwrócony przez Traefik oznacza, że router nie został uruchomiony; należy wrócić do panelu sterowania i odczytać treść błędu. W trakcie pracy warto mieć otwarte docker compose logs -f traefik w drugim terminalu, ponieważ każdy błąd parsowania pojawia się tam w momencie restartu kontenera.

Weryfikacja wycofywania zmian

Należy zachować plik compose w wersji v2, jego statyczną konfigurację oraz kopię zapasową acme.json, dopóki każda usługa nie będzie kierować ruchu w wersji v3 i nie zostanie przetestowana w warunkach rzeczywistych. Wycofanie zmian oznacza powrót do commita sprzed migracji i uruchomienie docker compose up -d. Operacja musi obejmować cały plik, a nie tylko tag obrazu, ponieważ składnia przeznaczona wyłącznie dla v3 jest niepoprawna w v2 w taki sam sposób, w jaki składnia v2 była niepoprawna w v3: dopasowanie PathRegexp nie zostanie tam poprawnie zinterpretowane. Zmienione etykiety ipallowlist działają w wersji v2.11, ale nie w starszych wydaniach v2, które nie rozpoznają nowej nazwy. Jeśli w trakcie procesu plik acme.json został utracony lub uszkodzony, należy przywrócić kopię zapasową przed uruchomieniem v2. Zapobiegnie to wyczerpaniu limitu Let's Encrypt poprzez ponowne wystawianie pięciu certyfikatów jednocześnie podczas wycofywania zmian.

FAQ

Czy muszę przepisywać każdą regułę routera dla Traefik v3?

Nie. Zwykła reguła Host(app.example.com) zapisana w grawisach jest poprawna w obu wersjach, co obejmuje większość konfiguracji Compose. Przepisanie jest konieczne tylko wtedy, gdy reguła wykorzystywała funkcje dostępne wyłącznie w v2: wyrażenia regularne lub symbole zastępcze wewnątrz Path i PathPrefix, kilka nazw hostów w jednym Host() lub usunięte dopasowania Headers, HeadersRegexp i HostHeader.

Co stało się z ipWhiteList w Traefik v3?

Zmieniono nazwę na ipAllowList, przy czym konfiguracja wewnątrz pozostała bez zmian, więc etykieta z v2, taka jak traefik.http.middlewares.office.ipwhitelist.sourcerange=10.0.0.0/24, staje się tą samą linią z ipallowlist w środku. Wersja v2.11 już akceptuje nową nazwę, więc można ją zmienić przed aktualizacją. Bieżące wydania v3, w tym v3.7, nadal akceptują starą nazwę jako przestarzały alias, więc nieprzemianowana etykieta nadal wymusza listę dozwolonych, generując jedynie ostrzeżenie w dzienniku. Należy traktować to jako rozwiązanie tymczasowe, a nie powód do zaniechania zmiany: przestarzałe nazwy to te, które wydanie może usunąć, a nazwa middleware, której Traefik faktycznie nie rozpoznaje, powoduje głośny błąd, błąd routera i kod 404. Pulpit nawigacyjny pokazuje błąd, a żądania do tego hosta zwracają 404.

Czy Traefik v3 nadal potrafi odczytać składnię reguł v2?

Tak. Ustaw core.defaultRuleSyntax: v2 w konfiguracji statycznej, aby zachować składnię v2 jako domyślną podczas migracji, i używaj etykiety ruleSyntax=v2 dla poszczególnych routerów po przywróceniu domyślnych ustawień. Obie opcje należy traktować jako tymczasowe: Traefik oznaczył je jako przestarzałe w v3.4 i usunie je w następnej głównej wersji.

Czy moje certyfikaty Let's Encrypt przetrwają aktualizację?

Tak. Traefik v3 nadal odczytuje plik acme.json zapisany przez v2, więc certyfikaty nie są odnawiane tylko z powodu zmiany pliku binarnego. Przed rozpoczęciem warto skopiować plik w bezpieczne miejsce, ponieważ wycofanie zmian lub usunięcie wolumenu, w którym znajduje się acme.json, wymusi jednoczesne ponowne wydanie wszystkich certyfikatów, a Let's Encrypt pozwala tylko na pięć duplikatów certyfikatów tygodniowo dla tego samego zestawu nazw hostów.

Dlaczego Traefik v3 nie uruchamia się po aktualizacji?

Prawie zawsze dlatego, że konfiguracja statyczna nadal zawiera opcję usuniętą w v3, a Traefik odmawia uruchomienia przy nierozpoznanych opcjach. W przypadku znanych pozostałości (pilot, providers.docker.swarmMode, experimental.http3 oraz tls.caOptional dostawców) dziennik wskazuje winowajcę, a następnie wyświetla incompatible deprecated install configuration option found (incompatible deprecated static option found w v3.4 i starszych); dla wszystkiego, czego v3 nigdy nie znało, na przykład literówki, wyświetla field not found wraz z węzłem. Usuń lub zastąp każdą z nich, a następnie uruchom kontener ponownie.