WSL2 + Podman 環境を快適にする Flatnet CLI を公開しましたの編集

[ トップ ] [ 編集 | 差分 | バックアップ | 添付 | リロード ] [ 新規 | 一覧 | 単語検索 | 最終更新 | ヘルプ ]

* 目次 [#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 で書かれています。

シングルバイナリで配布されるため、依存関係のインストールは不要です。

** 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 でお待ちしています。

spamではない場合はチェックをいれてください。タイムスタンプを変更しない