はじめに
ingress-nginxがもうすぐメンテナンス終了するため、自宅KubernetesのIngress実装をTraefikに変更しました。
デフォルトでいろいろできて便利なのですが、一部プラグインを使わないと実現できない挙動があったのでTraefikプラグインを作ってみました。
プラグイン開発を通してTraefikプラグインの注意点や知見がいくつか得られたので、ブログ記事として記録しておこうと思います。
環境
- Ubuntu 24.04.3上で実行しているKubernetes 1.34.3(microk8s)
- Traefik v3.6.6
- Go 1.25.5
作ったもの
HTTPリクエストのbodyの内容が設定された条件にマッチしたら、そのリクエストを弾くプラグインを作りました。
plugins.traefik.io
フィルター条件は以下の4つのパラメーターで設定します。
- path: リクエストパス（完全一致）
- method: HTTPメソッド（完全一致）
- bodyPath: JSONボディ内の検査対象パス（XPath形式）
- bodyValueCondition: 値の一致条件（正規表現）
条件は複数設定可能で、どれか一つでも条件にマッチしたリクエストはバックエンドには到達せず、Traefik側で403 Forbiddenを返します。
Traefikプラグインを公開する際の注意点・知見
外部ライブラリは全てvendorする必要がある
Traefikプラグインが実行される際の方式にはいくつか種類がありますが、今回はYaegiを使う方式にしました。
YaegiはTraefikに組み込まれているGo言語のインタプリタです。
Yaegiを使ってプラグインを実行する際、go.modに書かれている外部ライブラリを自動でインストールする機能は無いため、必要になる外部ライブラリのファイルを全て同梱する必要があります。
プロジェクトのrootディレクトリで go mod vendor を実行すると、外部の依存ライブラリのファイルがvendorディレクトリ内に保存されるので、これらをコミットしておきます。
コードの再配布ということになるので、公開前にライセンスの確認や通知ファイルの適切な配置ができているかをチェックしてください。
プラグインカタログへの掲載方法
topicとしてtraefik-pluginが設定されたPublicのGitHubリポジトリが掲載対象となります。
Traefikのクローラーが1日に1回、traefik-pluginのtopicが設定されたリポジトリをクローリングし、条件を満たした場合にカタログに掲載されます。
詳細な条件は公式ドキュメントの「Troubleshooting」のセクションに記載されています。
plugins.traefik.io
クローラーのチェックがエラーになった場合の対応
Traefikのクローラーによってリポジトリが検出された後、.traefik.ymlのtestDataの値を使ってプラグインのテストが行われます。
テストがエラーになった場合は、GitHubリポジトリにissueが作成されます。
issueの中にエラーの内容が書かれているのでその情報を元にプラグインを修正し、修正後にissueをcloseすると再度クローラーによるチェックが行われます。(close後即座に行われるわけではなく、1日に1回のクロールを待つ必要があります)
issueをcloseしない限りクローラーによるチェックは行われないので、忘れずにcloseする必要があります。
また、クロールの頻度は1日に1回しかないので、リリース完了まで気長に対応する必要があります。
ローカルやCIでプラグインのテストをする方法
ローカルモードの設定をすることで、プラグインの公開前に実際のTraefikを使ってプラグインの動作確認ができます。
plugins.traefik.io
コンテナを使ってテストする場合は、以下のようなコマンドでプラグインを実行できます。
docker run -d \ --name traefik-test \ -p 8080:8080 \ -p 10081:80 \ -v $PWD/traefik.yml:/etc/traefik/traefik.yml \ -v $PWD/routes.yml:/etc/traefik/conf/routes.yml \ -v $PWD:/plugins-local/src/github.com/kadoshita/traefik-plugin-filter-json-body \ traefik:v3
/plugins-local/src以下のマウント先ディレクトリは、実際のプラグインのパッケージ名に合わせて変更する必要があります。
実際に動く設定は、今回作成したプラグインのGitHubリポジトリを参考にしてください。
github.com
プラグインカタログに表示されるStar数はGitHubリポジトリについているStar数のようなので、Star付けていただけると喜びます。
おわりに
Traefikはプラグインの機能があり、Goでコードを書いて気軽に拡張できるのが良いなと思いました。
他にもリッチなダッシュボードがあったり、Kubernetesとの親和性が高い点も良いなと感じました。
元々Ingressで複雑なことはあまりしていなかったので、シュッと置き換えができた点も良かったです。
今回作ったプラグインは使っていく中で品質を高めていけたらいいなと思います。
もしTraefikで、特定の条件にマッチするリクエストを弾く設定をしたい場合は、ぜひ使ってみてください。
