traefik

Traefik エージェントスキル

Traefik v3 をリバースプロキシおよびロードバランサーとしてデプロイ、設定、保守するための包括的なリファレンスです。このスキルでは、Traefik Proxy OSS の主要な機能をすべて網羅し、本番環境ですぐに使える YAML 設定例を紹介します。

クイックスタート — 最小構成の Docker デプロイ

本番環境ですぐに使える Docker Compose テンプレートは templates/docker-compose.yml にあります。すぐに試す場合は、次の手順に従ってください。

1 行で実行できるヘルスチェック

bash scripts/traefik-healthcheck.sh           # Text output
bash scripts/traefik-healthcheck.sh --json    # JSON output for agents

# docker-compose.yml
services:
  traefik:
    image: traefik:v3.7
    command:
      # Static configuration via CLI args
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      - "--entrypoints.web.address=:80"
      - "--entrypoints.websecure.address=:443"
      - "--api.dashboard=true"
      - "--api.insecure=false"
    ports:
      - "80:80"
      - "443:443"
      - "8080:8080"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    labels:
      # Dashboard router
      - "traefik.http.routers.dashboard.rule=Host(`traefik.example.com`)"
      - "traefik.http.routers.dashboard.service=api@internal"
      - "traefik.http.routers.dashboard.middlewares=auth"
      - "traefik.http.middlewares.auth.basicauth.users=admin:$$2y$$10$$..."

基本概念

Traefik の設定は 2 つのレイヤーに分かれています。

• 静的設定 — YAML ファイル、CLI 引数、または環境変数を使って起動時に設定します。entryPoint、プロバイダー、API、メトリクス、TLS リゾルバーを定義します。
• 動的設定（ルーティング設定） — 実行時に変更されます。プロバイダー（Docker ラベル、File プロバイダーの YAML、Kubernetes CRD）を使って定義します。

リクエストの流れ：EntryPoint → Router → (Middlewares) → Service → Backend

リファレンスファイル

トピック	読み込むタイミング	ファイル
静的設定	Traefik を初めてセットアップするとき、entryPoint、プロバイダー、またはグローバル設定を追加するとき	references/static-configuration.md
Docker プロバイダー	ルーティング用のコンテナラベルを設定するとき、複数のネットワークを設定するとき、ポート検出について確認するとき	references/docker-provider.md
HTTP ルーティング	Host/Path マッチャーを記述するとき、優先度やルール構文を確認するとき	references/http-routing.md
ミドルウェアカタログ	認証、レート制限、ヘッダー操作、パスの書き換え、エラーページを追加するとき	references/middleware-catalog.md
TLS と ACME	Let's Encrypt、ワイルドカード証明書、DNS-01/HTTP-01 チャレンジ、mTLS を設定するとき	references/tls-acme.md
TCP と UDP のルーティング	HTTP 以外のトラフィックをルーティングするとき、SNI マッチングや TCP の TLS 終端を確認するとき	references/tcp-routing.md
API とダッシュボード	ダッシュボードを保護するとき、API エンドポイントやルートのデバッグについて確認するとき	references/api-dashboard.md
可観測性	Prometheus/OTel メトリクス、アクセスログ、トレース、ヘルスチェックについて確認するとき	references/observability.md
v2 から v3 への移行	破壊的変更、ルール構文の更新、非推奨オプションについて確認するとき	references/migration-v2-to-v3.md
本番環境のパターン	Docker Compose テンプレート、セキュリティ強化、高可用性、監視について確認するとき	references/production-deployment.md
サーバーのトランスポート	バックエンド接続の設定、バックエンドへの mTLS、コネクションプーリング、SPIFFE について確認するとき	references/servers-transport.md
Kubernetes プロバイダー	K8s に Traefik をデプロイするとき — Ingress、CRD（IngressRoute）、Gateway API	references/kubernetes-providers.md
その他のプロバイダー	ECS、Nomad、Consul Catalog、KV ストア、File、HTTP、REST プロバイダーについて確認するとき	references/other-providers.md
コミュニティのパターン	本番環境での知見 — ミドルウェアの順序、パフォーマンス調整、CDN の実 IP、CrowdSec、Authelia、トラブルシューティング	references/community-patterns.md
運用監査	フルスタックの監査手法 — 対象範囲の一覧作成、設定レビュー、実行時状態、ログ分析、分類フレームワーク	references/operational-audit.md
CSP / SPA のデバッグ	エントリーポイントのヘッダー上書きによってクロスオリジン SPA が気付かないうちに動作しなくなる場合 — 診断手順、修正方法、CORS プリフライトのインターセプト	references/csp-spa-debugging.md
プラグインと拡張	Yaegi および WASM プラグイン、プラグイン設定、FastProxy について確認するとき	references/plugins-extend.md

よくある落とし穴

• Traefik が誤ったポートに接続する場合： デフォルトでは、最初に公開されたポートが使用されます。必ず traefik.http.services.<name>.loadbalancer.server.port=XXXX を設定してください
• ラベルでは大文字と小文字が区別されませんが、リソース名は compose ファイル内で統一してください
• @ 文字は、ルーター、サービス、ミドルウェアの名前には使用できません
• ダッシュボードにルートが表示されない場合： API が有効になっていること（api.dashboard: true）と、service=api@internal を使用していることを確認してください
• ACME 証明書が生成されない場合： ACME チャレンジの entryPoint にインターネットからアクセスできることを確認してください（HTTP-01 ではポート 80、TLS-ALPN-01 ではポート 443）
• Docker ネットワーク： コンテナーが複数のネットワークに接続している場合は、正しいネットワークを選ぶために traefik.docker.network=<name> を設定してください
• exposedByDefault=false の場合、traefik.enable=true ラベルが付いていないコンテナーにはルートが設定されません
• ミドルウェアの順序は重要です： middlewares リストの順序が実行順序になります
• ファイルプロバイダーのパス： providers.file.directory を使用すると、Traefik は .yml／.yaml／.toml ファイルを監視し、アルファベット順にマージします
• ログレベル： DEBUG はトラブルシューティング時のみ使用してください。本番環境では非常に大量のログが出力されます
• ルールではシングルクォートは使用できません。バッククォート またはエスケープしたダブルクォート"` を使用してください
• traefik healthcheck には ping entryPoint が必要です： ping entryPoint が静的設定で構成されていない場合、traefik healthcheck CLI コマンド（および docker exec traefik traefik healthcheck）は "please enable ping to use health check" を返します。ping を使わずに設定構文を検証するには、YAML ファイルの場合は python3 -c "import yaml; yaml.safe_load(open('config.yml'))" を使用するか、（insecure API が有効な場合は）実行時 API http://localhost:8080/api/rawdata で現在の設定状態を確認してください。
• 名前付き Docker ボリュームには docker cp が必要です： Traefik の設定が名前付き Docker ボリューム（バインドマウントではない）にある場合、ホスト上でファイルを直接編集することはできません。ファイルをコンテナーに転送するには docker cp <src> traefik:/etc/traefik/<dest> を、取り出すには docker cp traefik:/etc/traefik/<src> <dest> を使用してください。静的設定（traefik.yml）の変更にはコンテナーの再起動が必要です。動的設定（dynamic/*.yml）の変更は、ファイルプロバイダーの監視機能によって即時に反映されます。
• entryPoint レベルとルーターレベルの両方でミドルウェアを宣言すると、二重に実行されます： entryPoint がミドルウェアを適用し（例：http.middlewares: [default@file]）、ルーターも同じミドルウェアを宣言すると、そのミドルウェアは二度実行されます。症状：レート制限のカウントが二倍になる、圧縮処理が重複して CPU を浪費する、デバッグログが分かりにくくなる。診断： 実行時 API（/api/rawdata）を問い合わせ、ルーターの middlewares 配列に重複がないか確認してください。修正： ルーターレベルの宣言からミドルウェアを削除してください。entryPoint ですでに適用されています。entryPoint のミドルウェアだけを正確に適用したい（追加のミドルウェアは不要な）サービスは、middlewares フィールド自体を省略できます。
• YAML の解析エラーによりファイルプロバイダー全体が無効になります： providers.file.directory 内のファイルが 1 つでも YAML 解析エラーになると、Traefik はプロバイダー全体の設定を破棄します。そのディレクトリ内のすべてのファイルから、すべてのミドルウェア、ルーター、サービスが消失します。兆候は、すべてのルーターで同じタイムスタンプに "middleware X does not exist" エラーが一斉に発生することです。Python の yaml.safe_load() だけでは十分に検証できません。Traefik のパーサーは、Python のパーサーを通過するファイル（例：わずかなインデントの違い、末尾の空白、テンプレート変数のような文字列）を拒否する場合があります。復旧： 直ちに、最後に正常だったファイルをバックアップから復元してください（docker cp /tmp/backup.yml traefik:/etc/traefik/dynamic/config.yml）。予防： 編集前に必ず設定のスナップショットを作成し、動的設定の変更は段階的に適用してください（論理的な変更を 1 つ適用 → スモークテストで確認 → 次の変更を適用）。また、編集するファイルはすべてバックアップを保持してください。
• レート制限によって SPA のページ読み込みが失敗する（429 Too Many Requests）： 最新の SPA は初回ページ読み込み時に 50～100 件以上の JS チャンクリクエストを送信します。400 req/s のレート制限ではこれらのリクエストに 429 が返され、ブラウザーのウィンドウが真っ黒になります。診断： docker logs traefik | grep "429" | grep "/assets/" を実行してください。1 秒以内に JS／CSS アセットへの 429 が多数表示される場合は、レート制限が低すぎます。修正： 制限を引き上げてください。Web UI を多用するホームラボ環境では、1000 avg／1500 burst（レート制限）と 100 concurrent（inFlightReq）が妥当です。entryPoint で適用したミドルウェアはサービスごとに上書きできないため、サービスごとに異なる制限が必要な場合は、グローバル制限を引き上げるか、ミドルウェアを entryPoint からルーター単位の適用に移す必要があります。
• entryPoint レベルの headers ミドルウェアはルーターレベルの CSP を上書きします（SPA が気付かれずに動作しなくなります）： entryPoint のミドルウェアはレスポンス経路の最後に実行され、headers ミドルウェアは同じ名前の既存ヘッダーを上書きします（ドキュメント）。entryPoint のチェーンで contentSecurityPolicy を設定すると、ルーターレベルの CSP は上書きされます。ルーターによる上書きはできません。その CSP が connect-src のない汎用設定（default-src 'self'）の場合、ブラウザーは SPA が行うすべてのクロスオリジン fetch／XHR をブロックします。兆候： SPA のページとアセットは読み込まれる（200）が、ログインや API 呼び出しは何も起こらず、バックエンドのログにはそのクライアントからのリクエストがまったく記録されません。診断： curl -D- -o /dev/null https://your-spa/ | grep content-security-policy を実行してください。SPA ページに制限の厳しい CSP が設定されている場合は、entryPoint のミドルウェアが原因か確認してください。修正： entryPoint のデフォルトチェーンから contentSecurityPolicy を削除し、各サービスに個別に調整した CSP を出力させてください。異なるオリジンと通信する SPA にとって、プロキシ全体への default-src 'self' の設定は有害です。診断の全手順と CORS プリフライトの横取りパターンについては、references/csp-spa-debugging.md を参照してください。

このスキルを使用しない場合

• Traefik Hub、Traefik Enterprise、または Traefik Mesh の場合 — これらは API が異なる別製品です
• Traefik プラグイン（Yaegi または WASM）の開発の場合 — このスキルで扱うのは、設定済みのプラグインの使用であり、作成ではありません。プラグインの開発については、https://plugins.traefik.io/create をご覧ください。