* 目次 [#zb984e20]
#contents
* WSL2 + Podman 環境を快適にする Flatnet CLI を公開しました [#i534ab7c]
WSL2 で Podman を使っていて、こんな悩みはありませんか？
- 社内 LAN からコンテナにアクセスできない
- NAT が何重にもなっていて、ポートフォワードが面倒
- コンテナの IP アドレスを毎回調べるのが大変
- 複数のコンポーネントの状態を一目で確認したい
これらの問題を解決するために、''Flatnet'' というプロジェクトを開発しています。そして今回、その管理ツールである ''Flatnet CLI'' を公開しました。
https://github.com/khayashi4337/flatnet
** Flatnet とは [#k380b275]
Flatnet は、WSL2 + Podman 環境の「NAT 地獄」を解消するためのツールセットです。
従来の構成:
社内LAN → Windows → WSL2 → コンテナ（3段NAT）
Flatnet を使った構成:
社内LAN → Gateway → コンテナ（フラットに到達）
Windows 上で動作する Gateway が、社内 LAN からのリクエストを WSL2 内のコンテナに直接ルーティングします。クライアント側は HTTP でアクセスするだけ。特別なソフトウェアのインストールは不要です。
*** なぜこの設計がすごいのか [#mb2e01c4]
**** CNI（Container Network Interface）について説明します。 [#m95ca373]
Docker ではネットワーク方式（NAT など）がソースコードに組み込まれていたため、カスタマイズが困難でした。一方、Docker の後継と言える Podman では、ネットワーク部分が''プラグイン方式''になっています。
これにより、Podman 本体のソースコードを一切触ることなく、自分が意図したネットワーク構成を実現できます。
**** ''従来のやり方（Docker 時代）:'' [#y57144f5]
- コンテナランタイムのソースコードを改造する必要がある
- 改造は大変で、バージョンアップのたびに壊れるリスクがある
- 独自機能を維持し続けるコストが高い
**** ''CNI のやり方（Podman / Kubernetes）:'' [#ydfaa93b]
- 設定ファイルとバイナリの2つを置くだけ
- Podman 本体には一切手を加えない
- 同じプラグインが Kubernetes でもそのまま使える
- バージョンアップの影響を受けにくい
つまり、''「本体を汚さずに、好きな機能を差し込める」'' という拡張性の高い設計になっています。
** Flatnet CLI でできること [#cf063b88]
Flatnet CLI は、この Flatnet システムを管理するためのコマンドラインツールです。
*** システム状態の確認 [#pa2f6f0a]
$ flatnet status
╭─────────────────────────────────────────────────────╮
│ Flatnet System Status │
├─────────────────────────────────────────────────────┤
│ Gateway ● Running 10.100.1.1:8080 │
│ CNI Plugin ● Ready 10.100.x.0/24 (5 IPs) │
│ Healthcheck ● Running 5 healthy, 0 unhealthy │
│ Prometheus ● Running :9090 │
│ Grafana ● Running :3000 │
│ Loki ● Running :3100 │
╰─────────────────────────────────────────────────────╯
Containers: 5 running
一目でシステム全体の状態がわかります。Gateway、CNI Plugin、モニタリングスタック、すべてのステータスを統合表示。
*** システム診断 [#na78525c]
$ flatnet doctor
Running system diagnostics...
Gateway
[✓] Gateway Connectivity
[✓] Gateway API
Network
[✓] Windows host reachable
[✓] Container network connectivity
Monitoring
[✓] Prometheus
[!] Grafana (port 3000 not responding)
→ Start Grafana: podman start grafana
[✓] Loki
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Summary: 7 passed, 1 warnings, 0 failed
問題があれば、解決方法まで提案してくれます。「動かない」で終わらず、「どうすれば動くか」がわかる。
*** コンテナ一覧 [#v24f048d]
$ flatnet ps
CONTAINER ID NAME IMAGE FLATNET IP STATUS
a1b2c3d4e5f6 web nginx:latest 10.100.1.10 Up 2 hours
b2c3d4e5f6a7 api myapp:v1 10.100.1.11 Up 1 hour
c3d4e5f6a7b8 forgejo codeberg/forgejo:9 10.100.1.12 Up 3 hours
Podman の ps コマンドとの違いは、''Flatnet IP'' が表示されること。このIPアドレスを使えば、社内LANから直接アクセスできます。
*** 統合ログビューア [#m7d888e1]
# Gateway のログを確認
$ flatnet logs gateway --since 1h
# コンテナのログを確認
$ flatnet logs myapp --follow
# エラーだけ抽出
$ flatnet logs gateway --grep error
Gateway、CNI Plugin、各コンテナのログを統一されたインターフェースで確認できます。Loki が動いていればそこから取得し、なければ Podman にフォールバック。
*** セルフアップグレード [#gde9b108]
$ flatnet upgrade
Current version: 0.1.0
Latest version: 0.2.0
Downloading flatnet v0.2.0...
[########################################] 100%
Download complete.
Upgraded successfully to v0.2.0!
GitHub Releases から最新版をダウンロードして自動更新。パッケージマネージャ不要。
** インストール [#pb336f7a]
ワンライナーでインストールできます。
curl -fsSL https://raw.githubusercontent.com/khayashi4337/flatnet/master/scripts/install-cli.sh | bash
これだけで ~/.local/bin/flatnet にインストールされます。
*** インストール時に得た知見 [#scc3f220]
- 1. CRLF 問題 — Windows リポジトリの .sh は CRLF になりがちで、WSL2 実行時にエラー。.gitattributes で *.sh eol=lf にしておくべき
- 2. sudo ハング — wsl bash -c "sudo ..." はパスワード入力待ちで止まる。対話が必要なコマンドはユーザーに直接実行してもらう
- 3. nginx include の重複エラー — 共通 include と location ブロックで同じディレクティブを定義すると duplicate エラー。共通ファイルにはヘッダー系のみ置く
- 4. OpenResty 起動前の準備 — C:\flatnet\logs ディレクトリの事前作成が必要
- 5. 管理者権限スクリプト — Start-Process -Verb RunAs で実行可能だが出力キャプチャ不可。結果はファイル存在確認で検証
** 実装について [#baf3c3b5]
Flatnet CLI は Rust で書かれています。
|ライブラリ|用途|h
|clap|コマンドライン引数のパース|
|tokio|非同期ランタイム|
|reqwest|HTTP クライアント|
|serde|JSON シリアライズ|
|colored + tabled|ターミナル出力の装飾|
シングルバイナリで配布されるため、依存関係のインストールは不要です。
** CI/CD との連携 [#n22d2021]
flatnet doctor は CI/CD パイプラインでも使えます。
# エラーがあれば非ゼロで終了
flatnet doctor --quiet
# JSON 出力でスクリプトから利用
flatnet doctor --json | jq '.summary.failed'
デプロイ前のヘルスチェックや、デプロイ後の検証に便利です。
** 今後の予定 [#y99b8504]
Flatnet プロジェクトは現在も開発中です。
|Phase|内容|状態|h
|Phase 1|Gateway 基盤 - NAT 越えの基本機能|完了|
|Phase 2|CNI Plugin - コンテナの自動 IP 割り当て|進行中|
|Phase 3|マルチホスト - 複数の WSL2 ホスト間通信|予定|
|Phase 4|本番運用準備|予定|
** まとめ [#ideb23c2]
Flatnet CLI を使えば、WSL2 + Podman 環境の管理が格段に楽になります。
- ''一目でわかる'': システム全体の状態を統合表示
- ''問題解決'': 診断機能で問題を特定し、解決策を提案
- ''統一インターフェース'': ログ、コンテナ、アップグレードを一つのツールで
ぜひ試してみてください。
curl -fsSL https://raw.githubusercontent.com/khayashi4337/flatnet/master/scripts/install-cli.sh | bash
flatnet status
** リンク [#d6fecc4c]
- [[GitHub リポジトリ>https://github.com/khayashi4337/flatnet]]
- [[ドキュメント>https://github.com/khayashi4337/flatnet/tree/master/docs/cli]]
- [[チュートリアル>https://github.com/khayashi4337/flatnet/blob/master/docs/cli/getting-started.md]]
フィードバックや Issue は GitHub でお待ちしています。
