traefik/traefik-migration-tool

traefik-migration-tool

镜像概述和主要用途

概述：traefik-migration-tool 是一款用于将 Traefik v1 迁移至 Traefik v2 的专用工具，旨在简化升级过程中的配置迁移工作，降低手动调整成本。

主要用途：帮助用户自动迁移 Traefik v1 环境中的关键配置组件（包括 Kubernetes Ingress 资源、Let's Encrypt 证书配置文件及静态配置文件）至 Traefik v2 版本，确保升级后服务配置的兼容性和可用性。

核心功能和特性

• ⛵ Kubernetes 资源迁移：将 Traefik v1 的 Ingress 资源迁移为 Traefik v2 的 IngressRoute 资源。
• 🔒 证书文件迁移：将 Traefik v1 的 acme.json 文件（Let's Encrypt 证书配置）迁移至 Traefik v2 兼容格式。
• 🖹 静态配置迁移：将 traefik.toml 文件中包含的 Traefik v1 静态配置迁移至 Traefik v2 配置文件格式。

使用场景和适用范围

适用场景

• 从 Traefik v1 升级至 Traefik v2 的用户，需要迁移现有配置以适应 v2 版本的新架构和配置模型。
• 在 Kubernetes 环境中使用 Traefik v1 Ingress 控制器，需迁移 Ingress 资源至 v2 的 IngressRoute 自定义资源。
• 使用 Let's Encrypt 自动证书管理（通过 acme.json）的 Traefik v1 用户，需迁移证书配置至 v2 格式。
• 依赖 traefik.toml 进行静态配置（如全局设置、入口点、提供商等）的 Traefik v1 用户，需更新配置文件至 v2 规范。

适用范围

• 支持主流操作系统（Linux、Windows、macOS）及多种架构。
• 支持通过 Docker 容器化运行，适用于容器化部署环境。

安装与使用方法

从二进制文件安装

1. 下载二进制文件：从 https://github.com/traefik/traefik-migration-tool/releases 下载对应操作系统/架构的最新版本压缩包。
2. 解压文件：解压下载的压缩包，获取 traefik-migration-tool 可执行文件。
3. 配置环境变量：将 traefik-migration-tool 所在路径添加至系统 PATH，以便全局调用。

使用 Docker 镜像

基本命令格式

sh
docker run --rm -v ${PWD}:/data traefik/traefik-migration-tool <迁移选项>

参数说明

• --rm：容器退出后自动删除。
• -v ${PWD}:/data：将当前工作目录（${PWD}）挂载至容器内的 /data 目录，用于工具读取和写入迁移文件（如 traefik.toml、acme.json 等）。
• <迁移选项>：需指定具体的迁移命令及参数（详见 命令文档）。

示例：迁移 traefik.toml 配置

sh
# 将当前目录下的 traefik.toml（v1 配置）迁移至 traefik-v2.toml（v2 配置）
docker run --rm -v ${PWD}:/data traefik/traefik-migration-tool toml --input /data/traefik.toml --output /data/traefik-v2.toml

限制与不支持的功能

不支持的 Kubernetes Ingress 注解

迁移 Ingress 资源时，以下 Traefik v1 注解暂不支持转换，需手动调整：

• ingress.kubernetes.io/preserve-host
• ingress.kubernetes.io/session-cookie-name
• ingress.kubernetes.io/affinity
• ingress.kubernetes.io/buffering
• ingress.kubernetes.io/circuit-breaker-expression
• ingress.kubernetes.io/max-conn-amount
• ingress.kubernetes.io/max-conn-extractor-func
• ingress.kubernetes.io/responseforwarding-flushinterval
• ingress.kubernetes.io/load-balancer-method
• ingress.kubernetes.io/auth-realm
• ingress.kubernetes.io/service-weights
• ingress.kubernetes.io/error-pages

命令文档

详细命令参数及使用说明，请参考 https://github.com/traefik/traefik-migration-tool/blob/master/docs/traefik-migration-tool.md%E3%80%82