Traefik v2からv3へのマイグレーション¶

Traefik v2からv3への移行時に一部の設定を変更する必要があります。

静的設定¶

Docker および Docker Swarm¶

SwarmMode¶

v3では、Dockerプロバイダが2つに分割されました。

Dockerプロバイダ(Swarm非対応)
Swarmプロバイダ(Swarmサポートのみ)

v2の設定例

File(YAML)File(TOML)CLI

providers:
docker:
    swarmMode: true

[providers.docker]
    swarmMode=true

--providers.docker.swarmMode=true

上記設定は現在サポートされておらず、Traefikの起動を妨げます。

対処法:

v3でSwarmを使用するには、DockerプロバイダのswarmModeではなくSwarmプロバイダを使用する必要があります。

v3の設定例

File(YAML)File(TOML)CLI

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

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

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

TLS.CAOptional¶

Dockerプロバイダのtls.CAOptionalオプションは、TLSクライアント認証がサーバー側のオプションであるため、v3で削除されました。(参照: https://pkg.go.dev/crypto/tls#ClientAuthType)

v2の設定例

File(YAML)File(TOML)CLI

providers:
docker:
    tls: 
    caOptional: true

[providers.docker.tls]
    caOptional=true

--providers.docker.tls.caOptional=true

対処法:

Dockerプロバイダの静的設定から tls.caOptional オプションを削除する必要があります。

Kubernetes Gateway API¶

Experimental Channel Resources (TLSRoute and TCPRoute)¶

v3では、Kubernetes Gateway APIプロバイダはデフォルトでexperimentalチャネルAPIリソースのサポートを有効にしません。

対処法:

experimentalチャネルAPIリソースのサポートを有効にしたい場合、experimentalChannelオプションを指定します。

v3の設定例

File(YAML)File(TOML)CLI

providers:
kubernetesGateway:
    experimentalChannel: true

[providers.kubernetesGateway]
    experimentalChannel = true

--providers.kubernetesgateway.experimentalchannel=true

実験的機能の設定¶

HTTP3¶

v3では、HTTP/3はもはや実験的な機能ではありません。これは、関連する experimental.http3 オプションなしでエントリーポイントで有効にすることができます。これは現在サポートされておらず、Traefikの起動を妨げます。

v2の設定例

File(YAML)File(TOML)CLI

experimental:
    http3: true

[experimental]
    http3=true

--experimental.http3=true

改善策

静的設定のexperimentalセクションからhttp3オプションを削除する必要があります。http3を設定するには、エントリポイント設定のドキュメントを参照してください。

Consul プロバイダ¶

namespace¶

Consulプロバイダーの名前空間オプションは、v2で非推奨となり、v3で削除されました。これは現在サポートされておらず、Traefikの起動を妨げます。

v2の設定例

File(YAML)File(TOML)CLI

consul:
namespace: foobar

[consul]
    namespace=foobar

--consul.namespace=foobar

改善策

v3では、namespaceオプションの代わりにnamespacesオプションを使用します。

v3の設定例

File(YAML)File(TOML)CLI

consul:
namespaces:
    - foobar

[consul]
    namespaces=["foobar"]

--consul.namespaces=foobar

TLS.CAOptional¶

Consulプロバイダのtls.CAOptionalオプションは、TLSクライアント認証がサーバー側のオプションであるため、v3で削除されました。(参照: https://pkg.go.dev/crypto/tls#ClientAuthType)

v2の設定例

File(YAML)File(TOML)CLI

providers:
docker:
    tls: 
    caOptional: true

[providers.docker.tls]
    caOptional=true

--providers.docker.tls.caOptional=true

対処法:

Consulプロバイダの静的設定から tls.caOptional オプションを削除する必要があります。

ConsulCatalog プロバイダ¶

Nomad プロバイダ¶

Rancher v1 プロバイダ¶

Marathon プロバイダ¶

HTTP プロバイダ¶

ETCD プロバイダ¶

Redis プロバイダ¶

InfluxDB v1¶

Pilot¶

動的設定¶

オペレーション¶

オブザーバビリティ¶

gRPCメトリクス¶

v3では、gRPCリクエストの報告されるステータスコードはGrpc-Statusヘッダの値になりました。

トレース¶

v3では、トレース機能が刷新され、OpenTelemetry (OTel)のみで動作するようになりました。

重要

Traefik v3 は、Instana, Jaeger, Zipkin, Haystack, Datadog, Elastic などの特定のベンダーの直接出力フォーマットをサポートしなくなりました。

その代わりに、純粋な OpenTelemetry の実装にフォーカスし、オブザーバビリティのための統一され標準化されたアプローチを提供します。

ここでは、2つの移行戦略を紹介します：

OTLP インジェスト・エンドポイント：現在、ほとんどのベンダーが OpenTelemetry Protocol (OTLP) インジェストエンドポイントを提供しています。Traefik v3をこれらのエンドポイントとシームレスに統合することで、トレース機能を継続的に活用することができます。
レガシースタックの互換性： OTLPインジェストをサポートする最新のベンダーエージェントにすぐにアップグレードできないレガシースタックでは、適切なエクスポータ設定とOpenTelemetry (OTel)コレクタを使用することが実行可能なソリューションです。これにより、既存のインフラストラクチャとの互換性を維持することができます。

詳細については、OpenTelemetry Tracing provider documentionを確認してください。

内部リソースの監視機能¶

v3では、内部ルーターやサービス（例：ping@internal）の監視機能はデフォルトで無効になっています。これを有効にするには、AccessLogs、Metrics、Tracingの新しいaddInternalsオプションを使う必要があります。詳しくはオブザーバビリティのドキュメントをご覧ください：

IPWhiteList¶

v3では、IPWhiteListミドルウェアをIPAllowListに名称変更しましたが、構成は何も変更していません。

gRPC メトリクス¶

v3では、gRPCリクエストの報告されるステータスコードはGrpc-Statusヘッダーの値になりました。

非推奨オプションの削除¶

pilotオプションは、静的設定から削除されました。
tracing.datadog.globaltagオプションは削除されました。
Consul、Consul Catalog、Nomadの各プロバイダーからnamespaceオプションが削除されました。
ForwardAuthミドルウェア、および HTTP、Consul、Etcd、Redis、ZooKeeper、Marathon、Consul Catalog、Dockerの各プロバイダーからtls.caOptionalオプションが削除されました。
Headersミドルウェアから sslRedirect、sslTemporaryRedirect、sslHost、sslForceHost、featurePolicyオプションが削除されました。
StripPrefixミドルウェアからforceSlashオプションが削除されました。
preferServerCipherSuitesオプションが削除されました。

Matcher¶

HeadersおよびHeadersRegexpmatcherはそれぞれ HeaderおよびHeaderRegexpに名称が変更されました。
QueryRegexpが導入され、正規表現を用いたクエリ値のマッチングが可能になりました。
HeaderRegexp、HostRegexp、PathRegexp、QueryRegexp、HostSNIRegexpの各matcherは、Go言語のregexp構文を使用するようになりました。
すべてのmatcherは、1つの値を取るようになり(但しHeaders、HeaderRegexp、Query、QueryRegexp は 2つ取ります)、以前の動作と同様に論理演算子を使用して明示的に結合する必要があります。
Queryは、値を持たないクエリ値(例: /search?mobile)にマッチする単一の値を取ることができます。
HostHeaderは削除されました。代わりにHostを使用してください。

Content-Typeの自動検出¶

v3では、バックエンドによって設定されていない場合、Content-Typeヘッダは自動検出されなくなりました。ContentTypeミドルウェアを使用して、Content-Typeヘッダー値の自動検出を有効にする必要があります。

HTTP/3¶

v3では、HTTP/3は実験的な機能ではなくなりました。experimental.http3オプションは、静的設定から削除されました。

TCP ServersTransport¶

v3では、TCPServersTransportのサポートが導入されました。そのため、KubernetesCRDプロバイダを使用する場合、RBAC および CRD マニフェストを更新する必要があります。

TCP LoadBalancerのTerminationDelayオプション¶

TCP LoadBalancerのterminationDelayオプションは削除されました。このオプションは、TCPServersTransportレベルで直接設定できるようになったので、こちらのドキュメントを参照してください。

Rancher v1¶

v3では、Rancher v1プロバイダーは削除されました。Rancher v1は活発にメンテナンスされておらず、v2は標準の Kubernetesプロバイダーとしてサポートされているからです。

Rancher 2.xはKubernetesを必要とし、Traefikがクエリするためのメタデータエンドポイントを持ちません。そのため、Rancher 2.xのユーザーはKubernetesのCRDプロバイダーを直接利用する必要があります。

Marathonプロバイダ¶

v3では、Marathonプロバイダが削除されました。

InfluxDB v1¶

v3では、InfluxDB v1.xのメンテナンスが2021年に終了したため、InfluxDB v1のメトリクスプロバイダは削除されています。

Kubernetes CRDs APIグループ traefik.containo.us¶

v3では、Kubernetes CRDsのAPIグループtraefik.containo.usは削除されました。代わりにAPIグループtraefik.ioを使用してください。

2024/ 5/19: 更新
2023/ 5/20: 更新