Traefik V3 마이그레이션 세부 사항

출처: Traefik V3 마이그레이션 세부 사항 (Traefik V3 Migration Details)

본문

Traefik v2에서 v3로 마이그레이션하기 위한 구성 세부 사항

설치 구성 변경

SwarmMode

v3에서 Docker 프로바이더는 두 개의 프로바이더로 분리됐어요:

• Docker 프로바이더 (Swarm 지원 없음)

• Swarm 프로바이더 (Swarm 지원 전용)

v2 Docker 프로바이더를 Swarm과 함께 쓴 예시

파일 (YAML)

providers:
  docker:
    swarmMode: true

파일 (TOML)

[providers.docker]
    swarmMode=true

CLI

--providers.docker.swarmMode=true

이 구성은 이제 지원되지 않으며 Traefik이 시작되지 않게 할 거예요.

해결 방법

v3에서는 swarmMode를 Docker 프로바이더와 함께 쓰면 안 돼요. Swarm을 쓰려면 Swarm 프로바이더를 대신 사용해야 합니다.

Swarm 프로바이더의 사용 예시

파일 (YAML)

providers:
  swarm:
    endpoint: "tcp://127.0.0.1:2377"

파일 (TOML)

[providers.swarm]
    endpoint="tcp://127.0.0.1:2377"

CLI

--providers.swarm.endpoint=tcp://127.0.0.1:2377

TLS.CAOptional

Docker 프로바이더의 tls.CAOptional 옵션은 v3에서 제거됐어요. TLS 클라이언트 인증은 서버 측 옵션이기 때문이죠 (https://pkg.go.dev/crypto/tls#ClientAuthType 참고).

TLS.CAOptional 옵션의 사용 예시

파일 (YAML)

providers:
  docker:
    tls: 
      caOptional: true

파일 (TOML)

[providers.docker.tls]
    caOptional=true

CLI

--providers.docker.tls.caOptional=true

해결 방법 tls.caOptional 옵션은 Docker 프로바이더 설치 구성에서 제거해야 해요.

Kubernetes Gateway API

실험 채널 리소스 (TLSRoute와 TCPRoute)

v3에서 Kubernetes Gateway API 프로바이더는 기본적으로 실험 채널 API 리소스 지원을 활성화하지 않아요.

해결 방법 실험 채널 API 리소스 지원을 활성화하려면 experimentalChannel 옵션을 사용해야 해요.

실험 채널 지원이 활성화된 Kubernetes Gateway API 프로바이더의 사용 예시

파일 (YAML)

providers:
  kubernetesGateway:
    experimentalChannel: true

파일 (TOML)

[providers.kubernetesGateway]
    experimentalChannel = true
  # ...

CLI

--providers.kubernetesgateway.experimentalchannel=true

실험 구성

HTTP3

v3에서 HTTP/3는 더 이상 실험적 기능이 아니에요. 연관된 experimental.http3 옵션 없이도 엔트리포인트에서 활성화할 수 있으며, 그 옵션은 이제 제거됐어요. 이제 지원되지 않으며 Traefik이 시작되지 않게 할 거예요.

v2 실험적 http3 옵션의 사용 예시

파일 (YAML)

experimental:
  http3: true

파일 (TOML)

[experimental]
    http3=true

CLI

--experimental.http3=true

해결 방법 http3 옵션은 설치 구성의 실험 섹션에서 제거해야 해요. http3를 구성하려면 엔트리포인트 구성 문서를 확인하세요.

Consul 프로바이더

namespace

Consul 프로바이더의 namespace 옵션은 v2에서 폐기(deprecated)됐고 v3에서 제거됐어요. 이제 지원되지 않으며 Traefik이 시작되지 않게 할 거예요.

v2 Consul namespace 옵션의 사용 예시

파일 (YAML)

consul:
  namespace: foobar

파일 (TOML)

[consul]
    namespace=foobar

CLI

--consul.namespace=foobar

해결 방법 v3에서는 namespace 옵션 대신 namespaces 옵션을 사용해야 해요.

Consul namespaces 옵션의 사용 예시

파일 (YAML)

consul:
  namespaces:
    - foobar

파일 (TOML)

[consul]
    namespaces=["foobar"]

CLI

--consul.namespaces=foobar

TLS.CAOptional

Consul 프로바이더의 tls.CAOptional 옵션은 v3에서 제거됐어요. TLS 클라이언트 인증은 서버 측 옵션이기 때문이죠 (https://pkg.go.dev/crypto/tls#ClientAuthType 참고).

TLS.CAOptional 옵션의 사용 예시

파일 (YAML)

providers:
  consul:
    tls: 
      caOptional: true

파일 (TOML)

[providers.consul.tls]
    caOptional=true

CLI

--providers.consul.tls.caOptional=true

해결 방법 tls.caOptional 옵션은 Consul 프로바이더 설치 구성에서 제거해야 해요.

ConsulCatalog 프로바이더

namespace

ConsulCatalog 프로바이더의 namespace 옵션은 v2에서 폐기됐고 v3에서 제거됐어요. 이제 지원되지 않으며 Traefik이 시작되지 않게 할 거예요.

v2 ConsulCatalog namespace 옵션의 사용 예시

파일 (YAML)

consulCatalog:
  namespace: foobar

파일 (TOML)

[consulCatalog]
    namespace=foobar

CLI

--consulCatalog.namespace=foobar

해결 방법 v3에서는 namespace 옵션 대신 namespaces 옵션을 사용해야 해요.

ConsulCatalog namespaces 옵션의 사용 예시

파일 (YAML)

consulCatalog:
  namespaces:
    - foobar

파일 (TOML)

[consulCatalog]
    namespaces=["foobar"]

CLI

--consulCatalog.namespaces=foobar

Endpoint.TLS.CAOptional

ConsulCatalog 프로바이더의 endpoint.tls.CAOptional 옵션은 v3에서 제거됐어요. TLS 클라이언트 인증은 서버 측 옵션이기 때문이죠 (https://pkg.go.dev/crypto/tls#ClientAuthType 참고).

Endpoint.TLS.CAOptional 옵션의 사용 예시

파일 (YAML)

providers:
  consulCatalog:
    endpoint:
      tls: 
        caOptional: true

파일 (TOML)

[providers.consulCatalog.endpoint.tls]
    caOptional=true

CLI

--providers.consulCatalog.endpoint.tls.caOptional=true

해결 방법 endpoint.tls.caOptional 옵션은 ConsulCatalog 프로바이더 설치 구성에서 제거해야 해요.

Nomad 프로바이더

namespace

Nomad 프로바이더의 namespace 옵션은 v2에서 폐기됐고 v3에서 제거됐어요. 이제 지원되지 않으며 Traefik이 시작되지 않게 할 거예요.

v2 Nomad namespace 옵션의 사용 예시

파일 (YAML)

nomad:
  namespace: foobar

파일 (TOML)

[nomad]
    namespace=foobar

CLI

--nomad.namespace=foobar

해결 방법 v3에서는 namespace 옵션 대신 namespaces 옵션을 사용해야 해요.

Nomad namespaces 옵션의 사용 예시

파일 (YAML)

nomad:
  namespaces:
    - foobar

파일 (TOML)

[nomad]
    namespaces=["foobar"]

CLI

--nomad.namespaces=foobar

Endpoint.TLS.CAOptional

Nomad 프로바이더의 endpoint.tls.CAOptional 옵션은 v3에서 제거됐어요. TLS 클라이언트 인증은 서버 측 옵션이기 때문이죠 (https://pkg.go.dev/crypto/tls#ClientAuthType 참고).

Endpoint.TLS.CAOptional 옵션의 사용 예시

파일 (YAML)

providers:
  nomad:
    endpoint:
      tls: 
        caOptional: true

파일 (TOML)

[providers.nomad.endpoint.tls]
    caOptional=true

CLI

--providers.nomad.endpoint.tls.caOptional=true

해결 방법 endpoint.tls.caOptional 옵션은 Nomad 프로바이더 설치 구성에서 제거해야 해요.

Rancher v1 프로바이더

v3에서 Rancher v1 프로바이더는 제거됐어요. Rancher v1이 더 이상 적극적으로 유지보수되지 않고, Rancher v2는 표준 Kubernetes 프로바이더로 지원되기 때문이죠.

Traefik v2 Rancher v1 구성의 예시

파일 (YAML)

providers:
  rancher: {}

파일 (TOML)

[providers.rancher]

CLI

--providers.rancher=true

이 구성은 이제 지원되지 않으며 Traefik이 시작되지 않게 할 거예요.

해결 방법

Rancher 2.x는 Kubernetes가 필요하고 Traefik이 쿼리할 자체 메타데이터 엔드포인트가 없어요. 따라서 Rancher 2.x 사용자는 Kubernetes CRD 프로바이더를 직접 활용해야 합니다.

또한 Rancher 프로바이더 관련 모든 구성은 설치 구성에서 제거해야 해요.

Marathon 프로바이더

Marathon 유지보수는 2021년 10월 31일에 종료됐어요. v3에서 Marathon 프로바이더는 제거됐습니다.

v2 Marathon 프로바이더 구성의 예시

파일 (YAML)

providers:
  marathon: {}

파일 (TOML)

[providers.marathon]

CLI

--providers.marathon=true

이 구성은 이제 지원되지 않으며 Traefik이 시작되지 않게 할 거예요.

해결 방법

Marathon 프로바이더 관련 모든 구성은 설치 구성에서 제거해야 해요.

HTTP 프로바이더

TLS.CAOptional

HTTP 프로바이더의 tls.CAOptional 옵션은 v3에서 제거됐어요. TLS 클라이언트 인증은 서버 측 옵션이기 때문이죠 (https://pkg.go.dev/crypto/tls#ClientAuthType 참고).

TLS.CAOptional 옵션의 사용 예시

파일 (YAML)

providers:
  http:
    tls: 
      caOptional: true

파일 (TOML)

[providers.http.tls]
    caOptional=true

CLI

--providers.http.tls.caOptional=true

해결 방법 tls.caOptional 옵션은 HTTP 프로바이더 설치 구성에서 제거해야 해요.

ETCD 프로바이더

TLS.CAOptional

ETCD 프로바이더의 tls.CAOptional 옵션은 v3에서 제거됐어요. TLS 클라이언트 인증은 서버 측 옵션이기 때문이죠 (https://pkg.go.dev/crypto/tls#ClientAuthType 참고).

TLS.CAOptional 옵션의 사용 예시

파일 (YAML)

providers:
  etcd:
    tls: 
      caOptional: true

파일 (TOML)

[providers.etcd.tls]
    caOptional=true

CLI

--providers.etcd.tls.caOptional=true

해결 방법 tls.caOptional 옵션은 ETCD 프로바이더 설치 구성에서 제거해야 해요.

Redis 프로바이더

TLS.CAOptional

Redis 프로바이더의 tls.CAOptional 옵션은 v3에서 제거됐어요. TLS 클라이언트 인증은 서버 측 옵션이기 때문이죠 (https://pkg.go.dev/crypto/tls#ClientAuthType 참고).

TLS.CAOptional 옵션의 사용 예시

파일 (YAML)

providers:
  redis:
    tls: 
      caOptional: true

파일 (TOML)

[providers.redis.tls]
    caOptional=true

CLI

--providers.redis.tls.caOptional=true

해결 방법 tls.caOptional 옵션은 Redis 프로바이더 설치 구성에서 제거해야 해요.

InfluxDB v1

InfluxDB v1.x 유지보수는 2021년에 종료됐어요. v3에서 InfluxDB v1 메트릭 프로바이더는 제거됐습니다.

Traefik v2 InfluxDB v1 메트릭 구성의 예시

파일 (YAML)

metrics:
  influxDB: {}

파일 (TOML)

[metrics.influxDB]

CLI

--metrics.influxDB=true

이 구성은 이제 지원되지 않으며 Traefik이 시작되지 않게 할 거예요.

해결 방법

InfluxDB v1 메트릭 프로바이더 관련 모든 구성은 설치 구성에서 제거해야 해요.

Pilot

Traefik Pilot은 2022년 10월 4일부터 더 이상 제공되지 않아요.

v2 Pilot 구성의 예시

파일 (YAML)

pilot:
  token: foobar

파일 (TOML)

[pilot]
    token=foobar

CLI

--pilot.token=foobar

v2에서 Pilot 구성은 폐기됐고 효과가 없었어요. 이제 지원되지 않으며 Traefik이 시작되지 않게 할 거예요.

해결 방법

Pilot 관련 모든 구성은 설치 구성에서 제거해야 해요.

Kubernetes Ingress 경로 매칭

v3에서 Kubernetes Ingress 기본 경로 매칭은 더 이상 정규식을 지원하지 않아요.

해결 방법

두 단계의 해결 방법이 가능해요:

• 기본 경로 매처 PathPrefix를 v2 문법으로 해석하기. 이는 설치 구성으로 모든 라우터에 전역적으로, 또는 traefik.ingress.kubernetes.io/router.rulesyntax 주석으로 라우터별로 할 수 있어요.

• 경로 정규식을 Go regex 문법과 호환되게 수정하고, traefik.ingress.kubernetes.io/router.pathmatcher 주석으로 기본 경로 매처를 PathRegexp 매처로 바꾸기.

운영 변경

Traefik RBAC 갱신

v3에서 TCPServersTransport 지원이 도입됐어요. KubernetesCRD 프로바이더를 쓸 때 RBAC와 CRD를 갱신해야 합니다 (요구 사항 참고).

Content-Type 자동 감지

v3에서 Content-Type 헤더는 백엔드가 설정하지 않을 때 더 이상 자동 감지되지 않아요. Content-Type 헤더 값 자동 감지를 활성화하려면 ContentType 미들웨어를 사용해야 합니다.

관측성(Observability)

열린 연결 메트릭

v3에서 열린 연결(open connections) 메트릭은 전역 메트릭으로 대체됐어요. 이전에는 잘못해서 HTTP 레벨에 있었고 오해를 불러일으키는 정보를 제공했기 때문이죠. 이전에는 entryPoint, router, service 레벨에서 생성됐지만, 이제 전역 메트릭으로 대체됐습니다. traefik_entrypoint_open_connections, traefik_router_open_connections, traefik_service_open_connections에 해당하는 메트릭은 이제 traefik_open_connections입니다.

구성 리로드 실패 메트릭

v3에서 traefik_config_reloads_failure_total과 traefik_config_last_reload_failure 메트릭은 구현할 수 없었기 때문에 제거됐어요.

gRPC 메트릭

v3에서 gRPC 요청의 보고되는 상태 코드는 이제 Grpc-Status 헤더의 값입니다.

트레이싱

v3에서 트레이싱 기능은 개편됐고 이제 OpenTelemetry(OTel)로만 구동됩니다.

중요

Traefik v3는 Instana, Jaeger, Zipkin, Haystack, Datadog, Elastic 같은 특정 벤더의 직접 출력 형식을 더 이상 지원하지 않아요. 대신 순수 OpenTelemetry 구현에 집중해서, 관측성을 위한 통일되고 표준화된 접근을 제공합니다.

두 가지 전환 전략이 가능해요:

• OTLP 수집 엔드포인트: 대부분의 벤더가 이제 OTLP(OpenTelemetry Protocol) 수집 엔드포인트를 제공해요. Traefik v3를 이런 엔드포인트와 매끄럽게 통합해서 트레이싱 기능을 계속 활용할 수 있습니다.

• 레거시 스택 호환: OTLP 수집을 지원하는 최신 벤더 에이전트로 즉시 업그레이드할 수 없는 레거시 스택의 경우, 적절한 exporters 구성을 곁들인 OTel(OpenTelemetry) 수집기를 사용하는 게 실행 가능한 해결책입니다. 이로써 기존 인프라와의 지속적인 호환성을 유지할 수 있어요.

자세한 내용은 OpenTelemetry Tracing 프로바이더 문서를 확인하세요.

내부 리소스 관측성

v3에서 내부 라우터나 서비스(예: ping@internal)의 관측성은 기본적으로 비활성화돼 있어요. 활성화하려면 AccessLogs, Metrics 또는 Tracing에 새 addInternals 옵션을 사용해야 합니다. 자세한 내용은 관측성 문서를 확인하세요:

• AccessLogs

• Metrics

• Tracing

접근 로그

v3에서 ServiceURL 필드는 더 이상 객체가 아니라 문자열 표현입니다. 접근 로그를 인덱싱한다면 갱신이 필요할 수 있어요.

라우팅 구성 변경

라우터 규칙 매처

v3에서 HTTP와 TCP 라우터를 위한 새 규칙 매처 문법이 도입됐어요. 기본 규칙 매처 문법은 이제 v3이지만, 하위 호환성을 위해 구성할 수 있습니다. v2 규칙 매처 문법은 폐기됐고 그 지원은 다음 메이저 버전에서 제거될 거예요. 이 때문에 새 문법으로 마이그레이션하는 걸 권합니다.

기본적으로 defaultRuleSyntax 설치 옵션은 자동으로 v3으로 설정돼서, 기본 규칙이 새 것임을 뜻해요.

새 V3 문법의 주목할 만한 변경

Headers와 HeadersRegexp 매처는 각각 Header와 HeaderRegexp로 이름이 바뀌었어요.

PathPrefix는 이제 정규식을 사용해 경로 접두사를 매칭하지 않아요.

Path와 PathPrefix는 더 이상 경로 매개변수 플레이스홀더(예: {id}, {name})를 지원하지 않아요. Path(/route/{id}) 같은 플레이스홀더를 쓰는 라우트는 v3 문법에서 매칭되지 않을 거예요. 동적 경로 세그먼트에는 PathRegexp를 대신 사용하세요.

QueryRegexp가 쿼리 값을 정규식으로 매칭하기 위해 도입됐어요.

HeaderRegexp, HostRegexp, PathRegexp, QueryRegexp, HostSNIRegexp 매처는 이제 Go regexp 문법을 사용해요.

모든 매처는 이제 단일 값을 받아요 (Header, HeaderRegexp, Query, QueryRegexp는 값을 두 개 받는 예외) 그리고 이전 동작을 재현하려면 논리 연산자로 명시적으로 결합해야 합니다.

Query는 단일 값을 받아서 값이 없는 쿼리 값(예: /search?mobile)을 매칭할 수 있어요.

HostHeader는 제거됐고, 대신 Host를 사용하세요.

해결 방법

설치 구성에서 기본 문법 구성하기 기본 규칙 매처 문법은 이 기본값에서 스스로 제외하지 않은 모든 라우터에 기대되는 문법이에요. 설치 구성에서 구성할 수 있습니다.

기본 규칙 매처 문법의 구성 예시

파일 (YAML)

# install configuration
core:
  defaultRuleSyntax: v2

파일 (TOML)

# install configuration
[core]
    defaultRuleSyntax="v2"

CLI

# install configuration
--core.defaultRuleSyntax=v2

라우터별로 문법 구성하기 규칙 문법은 라우터별로도 구성할 수 있어요. 이로써 이질적인 라우터 구성을 가질 수 있고 마이그레이션을 쉽게 해 줍니다.

문법 구성이 있는 라우터 예시

Docker & Swarm

labels:
  - "traefik.http.routers.test.ruleSyntax=v2"

Kubernetes

apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: test.route
  namespace: default

spec:
  routes:
    - match: PathPrefix(`/foo`, `/bar`)
      syntax: v2
      kind: Rule

Consul Catalog

- "traefik.http.routers.test.ruleSyntax=v2"

파일 (YAML)

http:
  routers:
    test:
      ruleSyntax: v2

파일 (TOML)

[http.routers]
  [http.routers.test]
    ruleSyntax = "v2"

경로 플레이스홀더를 PathRegexp로 마이그레이션하기 v2에서 Path와 PathPrefix는 {id} 같은 경로 매개변수 플레이스홀더를 지원해서 동적 경로 세그먼트를 매칭했어요. v3에서는 더 이상 지원되지 않으며 PathRegexp를 대신 사용해야 합니다.

경로 플레이스홀더가 있는 라우트 마이그레이션하기 v2 문법 (v3에서 더 이상 동작하지 않음):

match: Host(`example.com`) && Path(`/products/{id}`)

PathRegexp를 쓰는 v3 문법:

match: Host(`example.com`) && PathRegexp(`^/products/[^/]+$`)

여러 플레이스홀더가 있는 더 복잡한 패턴의 경우:

v2 문법:

match: Host(`example.com`) && Path(`/users/{userId}/orders/{orderId}`)

v3 문법:

match: Host(`example.com`) && PathRegexp(`^/users/[^/]+/orders/[^/]+$`) ## matches any non-slash characters
match: Host(`example.com`) && PathRegexp(`^/users/[a-zA-Z0-9_-]+/orders/[a-zA-Z0-9_-]+$`) ## restricts to alphanumeric, hyphens, and underscores

IPWhiteList

v3에서 IPWhiteList 미들웨어를 구성의 어떤 것도 바꾸지 않고 IPAllowList로 이름을 바꿨어요.

폐기된 옵션 제거

• tracing.datadog.globaltag 옵션이 제거됐어요.

• tls.caOptional 옵션이 ForwardAuth 미들웨어와 HTTP, Consul, Etcd, Redis, ZooKeeper, Consul Catalog, Docker 프로바이더에서 제거됐어요.

• Headers 미들웨어의 sslRedirect, sslTemporaryRedirect, sslHost, sslForceHost, featurePolicy 옵션이 제거됐어요.

• StripPrefix 미들웨어의 forceSlash 옵션이 제거됐어요.

• preferServerCipherSuites 옵션이 제거됐어요.

TCP LoadBalancer terminationDelay 옵션

TCP LoadBalancer의 terminationDelay 옵션이 폐기됐어요. 이 옵션은 이제 TCPServersTransport 레벨에서 직접 구성할 수 있어요. 이 문서를 확인하세요.

Kubernetes CRDs API Group traefik.containo.us

v3에서 Kubernetes CRDs API Group traefik.containo.us가 제거됐어요. 대신 API Group traefik.io를 사용하세요.

Kubernetes Ingress API Group networking.k8s.io/v1beta1

v3에서 Kubernetes Ingress API Group networking.k8s.io/v1beta1(Kubernetes v1.22부터 제거됨) 지원이 제거됐어요. 대신 API Group networking.k8s.io/v1을 사용하세요.

Traefik CRD API Version apiextensions.k8s.io/v1beta1

v3에서 Traefik CRD API Version apiextensions.k8s.io/v1beta1(Kubernetes v1.22부터 제거됨) 지원이 제거됐어요. 대신 API Version apiextensions.k8s.io/v1으로 CRD 정의를 사용하세요.

더 알아보기 (Learn more)

• Traefik 공식 문서