Migracja Traefik v2 do v3 co się zmienia

Co zmienia się między Traefik v2 a v3

Migracja z Traefik v2 do v3 polega głównie na zmianie nazw. Najważniejszą zmianą jest zmiana nazwy middleware ipWhiteList na ipAllowList. Poza tym v3 wprowadza bardziej rygorystyczną składnię reguł routera (PathPrefix traci funkcje regex, niektóre matchery zostają zmienione lub usunięte). Niektóre dostawcy oraz opcje zostali całkowicie usunięci. Pozostałe funkcje pozostają niezmienione: entrypoints, konfiguracja certyfikatów ACME, workflow etykiet Docker oraz acme.json działają bez zmian. v3 zawiera również tryb kompatybilności, który pozwala na używanie składni reguł z v2. Umożliwia to najpierw aktualizację pliku binarnego, a następnie stopniową zmianę reguł dla każdego serwisu z osobna.

Niniejszy poradnik zakłada użycie konfiguracji Docker Compose opartej na etykietach, opisanej w przewodniku po reverse proxy Traefik. Tamta strona dotyczy wersji v3; niniejsza strona dotyczy systemów nadal korzystających z tagu traefik:v2.

Zmiany nazw i usunięcia

• ipWhiteList to teraz ipAllowList dla middleware HTTP oraz TCP. Opcje wewnątrz nie uległy zmianie, więc sourcerange zachowuje swoje dotychczasowe znaczenie. Aktualne wydania v3, w tym v3.5, nadal akceptują starą nazwę jako przestarzały alias i nadal wymuszają listę, więc ta zmiana nie powoduje awarii. Należy jednak dokonać zmiany nazwy: alias zostanie usunięty i zniknie z listy przestarzałych bez powiadomienia.
• providers.docker.swarmMode=true został usunięty. Swarm posiada własny provider konfigurowany jako providers.swarm.endpoint.
• Sekcja pilot została całkowicie usunięta.
• experimental.http3 został usunięty. HTTP/3 jest teraz włączane bezpośrednio w entrypoint.
• tls.caOptional został usunięty z providerów oraz z middleware forwardAuth.
• Usunięto provider metryk InfluxDB v1, provider Rancher oraz provider Marathon.
• Tracing został przeniesiony do OpenTelemetry. Dedykowane backendy tracingowe, w tym integracje Jaeger i Zipkin, zostały usunięte; v3 eksportuje teraz OTLP (OpenTelemetry protocol).
• Przestarzałe opcje ssl* wewnątrz middleware headers (sslRedirect, sslHost i pozostałe) zostały usunięte. Zostały one zastąpione przez redirekcje w entrypoint oraz middleware redirectScheme.

Powyższe usunięcia są istotne, ponieważ Traefik nie uruchomi się, jeśli jego konfiguracja statyczna zawiera nieznaną opcję. Pozostawiona linia pilot lub swarmMode zatrzymuje kontener podczas uruchamiania z komunikatem incompatible deprecated static option found wskazującym na tę linię; opcja, której Traefik nigdy nie rozpoznawał (literówka lub tls.caOptional), powoduje błąd field not found. Należy oczyścić konfigurację statyczną przed zmianą tagu obrazu.

Middleware o nazwie, której Traefik nie rozpoznaje (literówka lub nazwa usunięta zamiast nadania aliasu), powoduje inny błąd: router odwołujący się do niej ładuje się z błędem zamiast trasy, dashboard ją oznacza, a API raportuje middleware "offce@docker" does not exist. Zapytania do tej nazwy hosta zwracają błąd 404, ponieważ router nie został uruchomiony. Należy pamiętać, że w obecnej wersji v3 ipwhitelist NIE należy do tej kategorii: zachowuje się jako przestarzały alias, więc nieprzemieniona etykieta nadal działa bez zakłóceń.

Zmiany w składni reguł

Reguły służą do modyfikacji żądań. Zmiany w wersji v3:

• Wartości wewnątrz matcherów muszą być ujęte w backticks. Wersja v2 akceptowała również podwójne cudzysłowy; wersja v3 tego nie obsługuje, zatem Host("app.example.com") musi zostać zmienione na Host(app.example.com).
• PathPrefix nie obsługuje już wyrażeń regularnych ani placeholderów w stylu {id}. Reguła z wersji v2, taka jak PathPrefix(/api/{version:v[0-9]+}), musi zostać zmieniona na matcher PathRegexp zapisany w 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 zmienione na Header oraz HeaderRegexp.
• HostHeader zostało usunięte. Należy użyć Host, który w wersji v3 dopasowuje te same elementy.
• Wprowadzono dwa nowe matchery: QueryRegexp oraz ClientIP do dopasowywania adresu klienta wewnątrz reguły.

Informacja dodatkowa: zwykła reguła Host(app.example.com) zapisana przy użyciu backticks jest już poprawną składnią v3. Większość małych konfiguracji Compose korzysta właśnie z tego formatu, co oznacza, że większość etykiet zostanie przeniesiona bez konieczności edycji reguł.

Przeprowadź audyt etykiet przed rozpoczęciem prac

Możliwe jest określenie rozmiaru migracji za pomocą jednej operacji wyszukiwania. Każda zmiana niszczącej etykiety pozostawia wzorzec wykrywalny przez grep:

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

Każde trafienie oznacza jedną linię wymagającą edycji. ipwhitelist zmienia się w ipallowlist. HostHeader zmienia się w Host. Headers zmienia się w Header. Placeholder {...} wewnątrz PathPrefix zmienia się w matcher PathRegexp. Przecinek wewnątrz Host() zmienia się w dwa matchery Host() połączone przez ||. Brak trafień oznacza, że etykiety są już zgodne ze składnią v3, a migracja ogranicza się do statycznej konfiguracji oraz tagu obrazu.

Elementy niezmienne

Entrypointy oraz przekierowania HTTP-to-HTTPS, resolvery ACME dla obu typów wyzwań, exposedByDefault, etykiety routera i usługi, loadbalancer.server.port oraz dashboard działają w v3 w taki sam sposób, jak w v2. Certyfikaty również zostają zachowane, ponieważ v3 odczytuje te same pliki acme.json, które zostały utworzone przez v2. Przed rozpoczęciem należy wykonać kopię zapasową plików, ponieważ przywrócenie poprzedniej wersji z utratą tych plików spowoduje przekroczenie limitu powtórzeń (duplicate-certificate rate limit) usługi Let's Encrypt:

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

Ścieżka migracji

Krok 1: utrwal aktualną wersję. Zmień każdy tag traefik:latest lub traefik:v2 na dokładną wersję, której obecnie używasz, na przykład traefik:v2.11, a następnie zatwierdź (commit) cały katalog compose w repozytorium git. Każdy kolejny krok można będzie cofnąć za pomocą polecenia checkout. Jeśli proces ponownego tworzenia pojedynczej usługi za pomocą docker compose up -d <service> nie jest jeszcze opanowany, podstawowy przewodnik po Docker Compose opisuje operacje niezbędne do przeprowadzenia tej migracji.

Krok 2: wyczyść statyczną konfigurację i włącz tryb kompatybilności. Usuń wszystkie opcje usunięte w v3 (pilot, swarmMode, tls.caOptional, experimental.http3), a następnie ustaw w v3 domyślne traktowanie reguł jako składni v2. W traefik.yml:

core:
  defaultRuleSyntax: v2

Lub jako flagę w liście compose command:: --core.defaultRuleSyntax=v2. Tryb kompatybilności dotyczy wyłącznie składni reguł. Nie przywraca on usuniętych opcji ani nie zmienia nazw middleware.

Krok 3: przygotuj zmiany nazw middleware. Przeszukaj pliki compose pod kątem starych nazw: grep -rn ipwhitelist docker-compose*.yml. Zmień każdą etykietę ipwhitelist na ipallowlist, ale nie wprowadzaj zmian jeszcze, ponieważ nowa nazwa nie istnieje w v2. Edycje te zostaną zastosowane jednocześnie z przełączeniem w następnym kroku. (Jeśli pomylisz jedną nazwę, obecna wersja v3 nadal będzie obsługiwać starą nazwę jako przestarzały alias, więc lista nadal będzie wymuszać poprawki; napraw błąd w kolejnym etapie, zamiast robić to o 2:00 nad ranem.)

Krok 4: zmień tag obrazu. Ustaw obraz Traefik na aktualną wersję v3, czyli traefik:v3.5 w momencie pisania tego tekstu, a następnie:

docker compose up -d
docker compose logs -f traefik

Ponieważ tryb kompatybilności jest włączony, reguły v2 nadal będą działać, a ponieważ up -d również odtworzył usługi, których etykiety middleware zostały zmienione, routery zostaną uruchomione poprawnie. Poprawny log nie zawiera linii field not found ani linii does not exist.

Należy uwzględnić czas przestoju wynikający z tego kroku. 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 ponownego utworzenia kontenera aplikacji; na jednym urządzeniu zajmuje to tyle, ile docker compose up -d potrzebuje na przetworzenie listy. Jeśli trasa nie może zostać przerwana, usuń zmienione middleware z etykiety middlewares danego routera przed przełączeniem, a następnie dodaj je ponownie po migracji. Zdecyduj wcześniej, czy dana trasa może działać bez listy dozwolonych adresów IP przez czas trwania przerwy.

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

Krok 6: wyłącz tryb kompatybilności. Gdy wszystkie reguły będą w składni v3, usuń defaultRuleSyntax oraz wszelkie etykiety ruleSyntax, zrestartuj Traefik i sprawdź, czy wszystkie routery nadal wyświetlają status zielony w dashboardzie. Nie należy pracować z włączonym trybem kompatybilności: Traefik uznał obie opcje za przestarzałe w wersji v3.4 i usunie je w następnej wersji głównej, więc służą one jedynie jako rozwiązanie przejściowe.

Przed i po: etykiety usługi

Poniżej znajduje się aplikacja zawierająca wszystkie kluczowe zmiany jednocześnie: wielowartościowy Host, placeholder 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

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 podzieliła wielowartościowy Host na dwa dopasowania połączone operatorem || i zastąpiła placeholder przez PathRegexp. Etykieta middleware została zmieniona z ipwhitelist na ipallowlist. Entrypoint, resolver certyfikatów, połączenie routera z middleware oraz port usługi pozostały bez zmian.

Przetestuj każdą usługę za pomocą dashboardu

Po każdej zmianie należy otworzyć stronę HTTP routers w dashboardzie. Każdy router powinien być oznaczony kolorem zielonym. Router z emblematem błędu wskazuje dokładną przyczynę; zazwyczaj jest to middleware o zmienionej nazwie lub reguła, której v3 nie może przetworzyć. Następnie należy potwierdzić działanie, sprawdzając każdą nazwę hosta pojedynczo:

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

Status 200 lub standardowe przekierowanie aplikacji oznacza, że routing oraz TLS działają poprawnie. Status 404 od Traefik oznacza, że router nie został uruchomiony; należy wrócić do dashboardu i sprawdzić komunikat błędu. Podczas pracy należy pozostawić otwarte docker compose logs -f traefik w drugim terminalu, ponieważ każdy błąd parsowania zostanie tam zarejestrowany natychmiast po restarcie kontenera.

Rollback honesty

Należy zachować plik compose v2, jego statyczną konfigurację oraz kopię zapasową acme.json do momentu, aż wszystkie usługi będą obsługiwać ruch w wersji v3 i zostaną poddane testom. Rollback polega na pobraniu commita sprzed migracji i uruchomieniu docker compose up -d. Należy użyć pełnego pliku, a nie tylko tagu obrazu. Etykiety przeznaczone wyłącznie dla v3 są nieprawidłowe w wersji v2, analogicznie do błędów etykiet v2 w wersji v3: ipallowlist nie istnieje w v2, a matcher PathRegexp nie zostanie tam poprawnie przetworzony. Jeśli acme.json uległ utracie lub uszkodzeniu, należy przywrócić kopię zapasową przed uruchomieniem v2. Zapobiegnie to wyczerpaniu limitów Let's Encrypt poprzez jednoczesne ponowne wystawianie pięciu certyfikatów.

FAQ

Czy każda reguła routera musi zostać przepisana dla Traefik v3?

Nie. Zwykła reguła Host(app.example.com) zapisana przy użyciu backticków jest poprawna w obu wersjach, co obejmuje większość konfiguracji Compose. Przepisanie jest wymagane tylko wtedy, gdy reguła wykorzystuje funkcje dostępne wyłącznie w v2: wyrażenia regularne lub placeholdery wewnątrz Path i PathPrefix, wiele nazw hostów wewnątrz jednego Host(), cudzysłowy zamiast backticków lub usunięte matchery Headers, HeadersRegexp i HostHeader.

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

Została zmieniona na ipAllowList. Konfiguracja wewnątrz pozostaje bez zmian, więc etykieta v2 typu traefik.http.middlewares.office.ipwhitelist.sourcerange=10.0.0.0/24 staje się tą samą linią z ipallowlist w środku. Aktualne wydania v3, w tym v3.5, nadal akceptują starą nazwę jako przestarzały alias, więc niezmieniona etykieta nadal cicho wymusza listę dozwoloną. Należy traktować to jako rozwiązanie tymczasowe, a nie powód do pominięcia zmiany nazwy: alias ma zostać usunięty. W przypadku użycia nazwy middleware, której Traefik nie rozpoznaje, wystąpi błąd routera i kod 404. Dashboard wyświetli błąd, a żądania do danej nazwy hosta zwrócą 404.

Czy Traefik v3 nadal odczytuje składnię reguł z v2?

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

Czy certyfikaty Let's Encrypt przetrwają aktualizację?

Tak. Traefik v3 nadal odczytuje plik acme.json utworzony przez v2, więc certyfikaty nie są wystawiane ponownie tylko z powodu zmiany binariów. Przed rozpoczęciem należy skopiować plik w bezpieczne miejsce, ponieważ wycofanie zmian lub usunięcie wolumenu skutkujące utratą acme.json wymusza jednoczesne ponowne wystawienie wszystkich certyfikatów. Let's Encrypt zezwala na tylko pięć duplikatów certyfikatów tygodniowo dla tego samego zestawu nazw hostów.

Dlaczego Traefik v3 nie uruchamia się po aktualizacji?

Najczęściej powodem jest obecność opcji usuniętej w v3 w konfiguracji statycznej; Traefik nie uruchamia się, jeśli napotyka nieznane opcje. W przypadku powszechnie znanych pozostałości (pilot, providers.docker.swarmMode, experimental.http3) logi wyświetlają incompatible deprecated static option found i wskazują winowajcę; w przypadku parametrów całkowicie nieznanych przez v3, takich jak tls.caOptional, logi wyświetlają field not found wraz z węzłem. Należy usunąć lub zastąpić każdy z tych parametrów, a następnie ponownie uruchomić kontener.