Kubectl Envoy Debugging

kubectl + Envoy デバッグ

このskillは、kubectl + Envoyベースのツールのデバッグと設定確認を支援します。

対象ツール

• kubectl port-forward + Envoyを使うローカルプロキシツール
• Envoy設定を動的生成するツール

提供機能

Envoy設定のダンプ

生成されたEnvoy設定をYAML形式で確認:

kubectl localmesh --dump-envoy-config -f services.yaml

# ファイルに保存
kubectl localmesh --dump-envoy-config -f services.yaml > envoy-config.yaml

# または直接実行
./kubectl-localmesh --dump-envoy-config -f services.yaml > envoy-config.yaml

用途:

• Envoy設定の理解
• ルーティング問題のデバッグ
• Envoy設定パターンの学習

オフラインモード（モック設定）

Kubernetesクラスタに接続せずにEnvoy設定を確認:

# モック設定ファイル作成例
cat > mocks.yaml <<EOF
mocks:
  - namespace: users
    service: users-api
    port_name: grpc
    resolved_port: 50051
  - namespace: billing
    service: billing-api
    port_name: http
    resolved_port: 8080
EOF

# モック設定を使ってダンプ
kubectl localmesh --dump-envoy-config -f services.yaml --mock-config mocks.yaml
# または
./kubectl-localmesh --dump-envoy-config -f services.yaml --mock-config mocks.yaml

モック設定形式:

• namespace, service, port_name: サービス識別子
• resolved_port: kubectl呼び出しの代わりに使うポート番号

用途:

• クラスタアクセス不要の設定テスト
• CI/CDパイプライン
• オフライン開発

ログレベル指定

詳細なデバッグログを出力:

sudo kubectl localmesh -f services.yaml -log debug
# または
sudo ./kubectl-localmesh -f services.yaml -log debug

ログレベル:

• debug: 最も詳細（デバッグ情報、内部状態）
• info: 標準（起動、設定読み込み、主要イベント）
• warn: 警告のみ

Envoy設定の検証ポイント

生成されたEnvoy設定をレビューする際のチェックリスト:

1. Listenerの確認

   • listener_portが正しいか
   • 0.0.0.0でリッスンしているか

2. Virtual Hostsの確認

   • 各サービスのhost（例: users-api.localhost）が定義されているか
   • ルーティングルールが正しいか

3. Clustersの確認

   • 各サービスに対応するclusterが存在するか
   • 127.0.0.1:<動的ポート>への接続設定が正しいか
   • HTTP/2設定（http2_protocol_options）がgRPCサービスで有効か

4. Timeoutの確認

   • timeout: 0sでストリーミング対応になっているか

使用方法

ユーザーから以下のような依頼があった場合:

1. 「Envoy設定を確認したい」

   • --dump-envoy-configを使用
   • 出力をファイルに保存して詳細レビュー

2. 「クラスタに接続できない」

   • --mock-configでオフラインモード
   • モック設定ファイルを作成

3. 「動作がおかしい」「ルーティングされない」

   • -log debugで詳細ログ取得
   • Envoy設定をダンプして検証
   • virtual_hostsとclustersの対応を確認

トラブルシューティング

Envoy起動失敗

# 1. 設定をダンプして確認
./kubectl-localmesh --dump-envoy-config -f services.yaml > /tmp/envoy-config.yaml

# 2. Envoy設定を直接検証
envoy --mode validate -c /tmp/envoy-config.yaml

ルーティングが機能しない

# 1. デバッグログで詳細を確認
sudo ./kubectl-localmesh -f services.yaml -log debug

# 2. 別ターミナルでcurlテスト
curl -v http://users-api.localhost/

# 3. Envoy管理インターフェースで状態確認（実装されている場合）
# curl http://localhost:9901/stats

モック設定の作成

実際のクラスタから情報を取得してモック設定を作成:

# サービスのポート情報を取得
kubectl get svc -n users users-api -o jsonpath='{.spec.ports[?(@.name=="grpc")].targetPort}'

# 結果をmocks.yamlに記載
cat > mocks.yaml <<EOF
mocks:
  - namespace: users
    service: users-api
    port_name: grpc
    resolved_port: 50051  # 上記で取得した値
EOF

関連ドキュメント

• プロジェクトのCLAUDE.md: Envoy設定生成ロジックの詳細
• Envoy公式ドキュメント: https://www.envoyproxy.io/docs/envoy/latest/