AgentSkillsCN

kubectl-envoy-debugging

kubectl + Envoyベースのツールのデバッグと設定確認を支援します（Envoy設定ダンプ、オフラインモード、トラブルシューティング）

中文原作
SKILL.md
--- frontmatter
name: kubectl-envoy-debugging
description: kubectl + Envoyベースのツールのデバッグと設定確認を支援します（Envoy設定ダンプ、オフラインモード、トラブルシューティング）
allowed-tools: ["Bash", "Read", "Write", "Glob"]

kubectl + Envoy デバッグ

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

対象ツール

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

提供機能

Envoy設定のダンプ

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

bash
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設定を確認:

bash
# モック設定ファイル作成例
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パイプライン
  • •オフライン開発

ログレベル指定

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

bash
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起動失敗

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

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

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

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

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

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

モック設定の作成

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

bash
# サービスのポート情報を取得
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

関連ドキュメント