What is kubectl-envoy-debugging?

This Claude skill streamlines the debugging and configuration of kubectl and Envoy-based service mesh tools. It enables developers to dump complex Envoy configurations into readable YAML, utilize an offline mock mode for testing without active cluster access, and perform comprehensive troubleshooting of routing, listeners, and clusters to ensure seamless service communication.

When should I use kubectl-envoy-debugging?

kubectl-envoy-debugging is useful in the following scenarios: • Troubleshooting routing issues: Dump and review generated Envoy YAML configurations to verify virtual hosts, clusters, and listener port mappings. • Offline development and CI/CD: Use mock configuration files to validate Envoy settings and logic in environments where a Kubernetes cluster is unavailable. • Deep-dive log analysis: Enable granular debug logging to trace internal states and identify the root cause of intermittent service connectivity failures. • Configuration validation: Export generated configs to run 'envoy --mode validate', ensuring that dynamic settings are syntactically correct before deployment. • Learning and Auditing: Analyze how Kubernetes service definitions are translated into Envoy routing rules to optimize local mesh performance.

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形式で確認:

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設定をレビューする際のチェックリスト:

Listenerの確認
- listener_portが正しいか
- 0.0.0.0でリッスンしているか
Virtual Hostsの確認
- 各サービスのhost（例: users-api.localhost）が定義されているか
- ルーティングルールが正しいか
Clustersの確認
- 各サービスに対応するclusterが存在するか
- 127.0.0.1:<動的ポート>への接続設定が正しいか
- HTTP/2設定（http2_protocol_options）がgRPCサービスで有効か
Timeoutの確認
- timeout: 0sでストリーミング対応になっているか

使用方法

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

「Envoy設定を確認したい」
- --dump-envoy-configを使用
- 出力をファイルに保存して詳細レビュー
「クラスタに接続できない」
- --mock-configでオフラインモード
- モック設定ファイルを作成
「動作がおかしい」「ルーティングされない」
- -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

kubectl-envoy-debugging

When & Why to Use This Skill

Use Cases