Traefik V3 迁移详情

从 Traefik v2 迁移到 v3 的配置详情

安装配置更改

SwarmMode

在 v3 中，Docker provider 已被拆分为 2 个 providers：

• Docker provider（无 Swarm 支持）
• Swarm provider（仅 Swarm 支持）

v2 Docker provider 与 Swarm 的使用示例

YAML

providers:
  docker:
    swarmMode: true

TOML

[providers.docker]
    swarmMode = true

CLI

--providers.docker.swarmMode=true

此配置现在不受支持，将阻止 Traefik 启动。

修复

在 v3 中，swarmMode 不应与 Docker provider 一起使用，并且要使用 Swarm，应改用 Swarm provider。

Swarm provider 的使用示例

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 provider 的 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

修复

应从 Docker provider 安装配置中删除 tls.caOptional 选项。

Kubernetes Gateway API

实验性通道资源（TLSRoute 和 TCPRoute）

在 v3 中，Kubernetes Gateway API provider 默认不启用对实验性通道 API 资源的支持。

修复

应使用 experimentalChannel 选项来启用对实验性通道 API 资源的支持。

启用实验性通道支持的 Kubernetes Gateway API provider 使用示例

YAML

providers:
  kubernetesGateway:
    experimentalChannel: true

TOML

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

CLI

--providers.kubernetesgateway.experimentalchannel=true

实验性配置

HTTP3

在 v3 中，HTTP/3 不再是实验性功能。 可以在 entry points 上启用它，而无需关联的 experimental.http3 选项（该选项现已被删除）。 它现在不受支持，将阻止 Traefik 启动。

v2 实验性 http3 选项的使用示例

YAML

experimental:
  http3: true

TOML

[experimental]
    http3 = true

CLI

--experimental.http3=true

修复

应从安装配置的实验性部分中删除 http3 选项。 要配置 http3，请查看 entrypoint 配置文档。

Consul provider

namespace

Consul provider 的 namespace 选项在 v2 中已弃用，在 v3 中现已移除。它现在不受支持，将阻止 Traefik 启动。

v2 Consul namespace 选项的使用示例

YAML

consul:
  namespace: foobar

TOML

[consul]
    namespace = "foobar"

CLI

--consul.namespace=foobar

修复

在 v3 中，应使用 namespaces 选项代替 namespace 选项。

Consul namespaces 选项的使用示例

YAML

consul:
  namespaces:
    - foobar

TOML

[consul]
    namespaces = ["foobar"]

CLI

--consul.namespaces=foobar

TLS.CAOptional

Consul provider 的 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

修复

应从 Consul provider 安装配置中删除 tls.caOptional 选项。

ConsulCatalog provider

namespace

ConsulCatalog provider 的 namespace 选项在 v2 中已弃用，在 v3 中现已移除。它现在不受支持，将阻止 Traefik 启动。

v2 ConsulCatalog namespace 选项的使用示例

YAML

consulCatalog:
  namespace: foobar

TOML

[consulCatalog]
    namespace = "foobar"

CLI

--consulCatalog.namespace=foobar

修复

在 v3 中，应使用 namespaces 选项代替 namespace 选项。

ConsulCatalog namespaces 选项的使用示例

YAML

consulCatalog:
  namespaces:
    - foobar

TOML

[consulCatalog]
    namespaces = ["foobar"]

CLI

--consulCatalog.namespaces=foobar

Endpoint.TLS.CAOptional

ConsulCatalog provider 的 endpoint.tls.CAOptional 选项已在 v3 中移除。

Endpoint.TLS.CAOptional 选项的使用示例

YAML

providers:
  consulCatalog:
    endpoint:
      tls:
        caOptional: true

TOML

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

CLI

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

修复

应从 ConsulCatalog provider 安装配置中删除 endpoint.tls.caOptional 选项。

Nomad provider

namespace

Nomad provider 的 namespace 选项在 v2 中已弃用，在 v3 中现已移除。它现在不受支持，将阻止 Traefik 启动。

v2 Nomad namespace 选项的使用示例

YAML

nomad:
  namespace: foobar

TOML

[noamd]
    namespace = "foobar"

CLI

--nomad.namespace=foobar

修复

在 v3 中，应使用 namespaces 选项代替 namespace 选项。

Nomad namespaces 选项的使用示例

YAML

nomad:
  namespaces:
    - foobar

TOML

[noamd]
    namespaces = ["foobar"]

CLI

--nomad.namespaces=foobar

Endpoint.TLS.CAOptional

Nomad provider 的 endpoint.tls.CAOptional 选项已在 v3 中移除。

Endpoint.TLS.CAOptional 选项的使用示例

YAML

providers:
  nomad:
    endpoint:
      tls:
        caOptional: true

TOML

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

CLI

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

修复

应从 Nomad provider 安装配置中删除 endpoint.tls.caOptional 选项。

Rancher v1 Provider

在 v3 中，Rancher v1 provider 已被移除，因为 Rancher v1 不再被积极维护，而 Rancher v2 作为标准 Kubernetes provider 受支持。

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 provider。

此外，应从安装配置中删除所有 Rancher provider 相关的配置。

Marathon provider

Marathon 维护已于 2021 年 10 月 31 日 结束。 在 v3 中，Marathon provider 已被移除。

v2 Marathon provider 配置示例

YAML

providers:
  marathon: {}

TOML

[providers.marathon]

CLI

--providers.marathon=true

此配置现在不受支持，将阻止 Traefik 启动。

修复

应从安装配置中删除所有 Marathon provider 相关的配置。

HTTP Provider

TLS.CAOptional

HTTP provider 的 tls.CAOptional 选项已在 v3 中移除。

TLS.CAOptional 选项的使用示例

YAML

providers:
  http:
    tls:
      caOptional: true

TOML

[providers.http.tls]
    caOptional = true

CLI

--providers.http.tls.caOptional=true

修复

应从 HTTP provider 安装配置中删除 tls.caOptional 选项。

ETCD Provider

TLS.CAOptional

ETCD provider 的 tls.CAOptional 选项已在 v3 中移除。

TLS.CAOptional 选项的使用示例

YAML

providers:
  etcd:
    tls:
      caOptional: true

TOML

[providers.etcd.tls]
    caOptional = true

CLI

--providers.etcd.tls.caOptional=true

修复

应从 ETCD provider 安装配置中删除 tls.caOptional 选项。

Redis Provider

TLS.CAOptional

Redis provider 的 tls.CAOptional 选项已在 v3 中移除。

TLS.CAOptional 选项的使用示例

YAML

providers:
  redis:
    tls:
      caOptional: true

TOML

[providers.redis.tls]
    caOptional = true

CLI

--providers.redis.tls.caOptional=true

修复

应从 Redis provider 安装配置中删除 tls.caOptional 选项。

InfluxDB v1

InfluxDB v1.x 维护已于 2021 年结束。 在 v3 中，InfluxDB v1 metrics provider 已被移除。

Traefik v2 InfluxDB v1 metrics 配置示例

YAML

metrics:
  influxDB: {}

TOML

[metrics.influxDB]

CLI

--metrics.influxDB=true

此配置现在不受支持，将阻止 Traefik 启动。

修复

应从安装配置中删除所有 InfluxDB v1 metrics provider 相关的配置。

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 的默认路径匹配不再支持正则表达式。

修复

有两种可能的修复方法：

• 使用 v2 语法解释默认路径匹配器 PathPrefix。可以通过安装配置 为所有 routers 全局完成此操作，或通过使用 traefik.ingress.kubernetes.io/router.rulesyntax 注解为每个路由器完成此操作。
• 调整路径正则表达式以与 Go 正则表达式语法兼容，并通过 ``traefik.ingress.kubernetes.io/router.pathmatcher 注解将默认路径匹配器更改为使用 PathRegexp 匹配器。

操作变更

Traefik RBAC 更新

在 v3 中，引入了对 TCPServersTransport 的支持。 当使用 KubernetesCRD provider 时，有必要更新 RBAC 和 CRD（参见要求）。

Content-Type 自动检测

在 v3 中，当后端未设置 Content-Type 头时，不再自动检测它。 应使用 ContentType 中间件来启用 Content-Type 头值的自动检测。

可观测性

开放连接指标

在 v3 中，开放连接指标已被全局指标替换，因为它错误地处于 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 头的值。

Tracing

在 v3 中，tracing 功能已彻底修改，现在完全由 OpenTelemetry (OTel) 提供支持。

重要

Traefik v3 不再支持特定供应商的直接输出格式，例如 Instana、Jaeger、Zipkin、Haystack、Datadog 和 Elastic。 相反，它专注于纯 OpenTelemetry 实现，提供统一和标准化的可观测性方法。

以下是两种可能的过渡策略：

1. OTLP 摄取端点： 大多数供应商现在提供 OpenTelemetry Protocol (OTLP) 摄取端点。 你可以将 Traefik v3 与这些端点无缝集成，以继续利用 tracing 功能。

2. 遗留堆栈兼容性： 对于无法立即升级到支持 OTLP 摄取的最新供应商代理的遗留堆栈， 使用具有适当 exporters 配置的 OpenTelemetry (OTel) collectors 是一种可行的解决方案。 这允许与现有基础设施保持兼容。

请查看 OpenTelemetry Tracing provider 文档 获取更多信息。

内部资源可观测性

在 v3 中，内部 routers 或 services（例如：ping@internal）的可观测性默认处于禁用状态。 要启用它，应使用 AccessLogs、Metrics 或 Tracing 的新 addInternals 选项。 请查看可观测性文档以获取更多信息：

• AccessLogs
• Metrics
• Tracing

访问日志

在 v3 中，ServiceURL 字段不再是对象，而是字符串表示形式。如果你对访问日志进行索引，可能需要更新。

路由配置更改

Router 规则匹配器

在 v3 中，为 HTTP 和 TCP routers 引入了一种新的规则匹配器语法。 默认的规则匹配器语法现在是 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

# 安装配置
core:
  defaultRuleSyntax: v2

TOML

# 安装配置
[core]
    defaultRuleSyntax = "v2"

CLI

# 安装配置
--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"

File (YAML)

http:
  routers:
    test:
      ruleSyntax: v2

File (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/[^/]+$`) ## 匹配任何非斜杠字符
match: Host(`example.com`) && PathRegexp(`^/users/[a-zA-Z0-9_-]+/orders/[a-zA-Z0-9_-]+$`) ## 限制为字母数字、连字符和下划线

IPWhiteList

在 v3 中，我们将 IPWhiteList 中间件重命名为 IPAllowList，而未对配置进行任何更改。

已弃用选项的移除

• tracing.datadog.globaltag 选项已被移除。
• tls.caOptional 选项已从 ForwardAuth 中间件以及 HTTP、Consul、Etcd、Redis、ZooKeeper、Consul Catalog 和 Docker providers 中移除。
• Headers 中间件的 sslRedirect、sslTemporaryRedirect、sslHost、sslForceHost 和 featurePolicy 选项已被移除。
• StripPrefix 中间件的 forceSlash 选项已被移除。
• preferServerCipherSuites 选项已被移除。

TCP LoadBalancer terminationDelay 选项

TCP LoadBalancer terminationDelay 选项已弃用。 此选项现在可以直接在 TCPServersTransport 级别配置，请查看此文档。

Kubernetes CRDs API 组 traefik.containo.us

在 v3 中，Kubernetes CRDs API 组 traefik.containo.us 已被移除。 请改用 API 组 traefik.io。

Kubernetes Ingress API 组 networking.k8s.io/v1beta1

在 v3 中，Kubernetes Ingress API 组 networking.k8s.io/v1beta1（自 Kubernetes v1.22 起已移除）的支持已被移除。

请改用 API 组 networking.k8s.io/v1。

Traefik CRD API 版本 apiextensions.k8s.io/v1beta1

在 v3 中，Traefik CRD API 版本 apiextensions.k8s.io/v1beta1（自 Kubernetes v1.22 起已移除）的支持已被移除。

请改用 API 版本为 apiextensions.k8s.io/v1 的 CRD 定义。