kubectl-localmesh 運用操作

このskillは、kubectl-localmesh固有の運用操作を提供します。

提供機能

起動

kubectlプラグインとして起動（推奨、/etc/hosts自動更新あり、sudo必要）:

sudo kubectl localmesh -f services.yaml

直接実行の場合:

# Task経由でビルド済み、またはgo install済み
sudo ./bin/kubectl-localmesh -f services.yaml

# 直接go buildした場合
sudo ./kubectl-localmesh -f services.yaml

/etc/hosts管理オプション

自動更新を無効化:

kubectl localmesh -f services.yaml --update-hosts=false
# または
./kubectl-localmesh -f services.yaml --update-hosts=false

この場合、Hostヘッダーを手動指定:

curl -H "Host: users-api.localhost" http://127.0.0.1:80/

自動更新のメリット:

• ブラウザやcurlで直接ホスト名でアクセス可能
• 設定が簡潔

自動更新のデメリット:

• sudo権限が必要
• /etc/hostsへの書き込み権限が必要

サービスへのアクセス

/etc/hosts更新有効時（デフォルト）:

• HTTP: curl http://billing-api.localhost/health
• gRPC: grpcurl -plaintext users-api.localhost list

ポート80使用時: ポート番号不要 他のポート使用時: http://service.localhost:8080のようにポート指定

/etc/hosts更新無効時:

# HTTPの場合
curl -H "Host: billing-api.localhost" http://127.0.0.1:80/health

# gRPCの場合
grpcurl -plaintext -authority users-api.localhost 127.0.0.1:80 list

停止・クリーンアップ

Ctrl+Cで停止すると、自動的に:

• /etc/hostsエントリを削除
• すべてのport-forwardプロセスを停止
• Envoyプロセスを停止
• 一時ディレクトリを削除

クリーンな終了を確認:

# /etc/hostsにエントリが残っていないか確認
grep "kubectl-localmesh" /etc/hosts

# port-forwardプロセスが残っていないか確認
ps aux | grep "kubectl port-forward"

# Envoyプロセスが残っていないか確認
ps aux | grep envoy

依存関係チェック

起動前に依存関係を確認:

# スクリプトを使用
.claude/skills/kubectl-localmesh-operations/scripts/check-dependencies.sh

# または個別に確認
kubectl version --client
envoy --version
bash --version

必須依存関係:

• kubectl: Kubernetesクラスタへのアクセス
• envoy: ローカルプロキシ（macOS: brew install envoy）
• bash: port-forwardループスクリプト実行

トラブルシューティング

問題: ポート衝突

症状: address already in useエラー

解決:

1. listener_portを変更（services.yaml）
2. または既存プロセスを停止

# ポート80を使用しているプロセスを確認
lsof -i :80

# プロセスを停止
kill <PID>

問題: Envoy起動失敗

症状: Envoyプロセスがすぐに終了する

解決:

1. Envoy設定を確認（kubectl-envoy-debugging skillを使用）
2. デバッグログを確認

# Envoy設定をダンプ
./kubectl-localmesh --dump-envoy-config -f services.yaml > /tmp/envoy-config.yaml

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

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

問題: port-forward接続失敗

症状: error forwarding portエラー

解決:

1. サービスの存在確認
2. ポート名/番号の確認
3. kubeconfigとクラスタ接続確認

# サービスの存在確認
kubectl get svc -n <namespace>

# サービスの詳細とポート確認
kubectl describe svc <service> -n <namespace>

# kubeconfigとクラスタ接続確認
kubectl cluster-info
kubectl get nodes

問題: /etc/hosts更新失敗

症状: permission deniedエラー

解決:

1. sudoで実行
2. または--update-hosts=falseオプションを使用

# sudo権限で実行
sudo ./kubectl-localmesh -f services.yaml

# または/etc/hosts更新を無効化
./kubectl-localmesh -f services.yaml --update-hosts=false

問題: サービスにアクセスできない

症状: connection refusedや503 Service Unavailable

解決手順:

1. kubectl-localmeshが起動しているか確認
2. port-forwardが正常に動作しているか確認
3. Envoyログを確認
4. curlで詳細なHTTPヘッダーを確認

# port-forwardプロセスの確認
ps aux | grep "kubectl port-forward"

# curlで詳細確認
curl -v http://users-api.localhost/

# 期待される出力:
# * Connected to users-api.localhost (127.0.0.1)
# > GET / HTTP/1.1
# > Host: users-api.localhost

使用方法

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

1. 「起動して」

   • 依存関係チェック
   • sudo権限確認
   • 適切なパスで起動

2. 「サービスにアクセスしたい」

   • /etc/hosts設定に応じた方法を案内
   • HTTPまたはgRPCに応じたコマンド例を提供

3. 「動かない」

   • 依存関係チェック
   • トラブルシューティングフローを実行
   • エラーメッセージに応じた解決策を提示

ワークフロー例

初回セットアップ

# 1. 依存関係チェック
.claude/skills/kubectl-localmesh-operations/scripts/check-dependencies.sh

# 2. 設定ファイル確認
cat services.yaml

# 3. Kubernetesクラスタ接続確認
kubectl cluster-info

# 4. 起動
sudo ./bin/kubectl-localmesh -f services.yaml

日常的な使用

# 1. 起動
sudo ./bin/kubectl-localmesh -f services.yaml

# 2. 別ターミナルでサービスにアクセス
curl http://users-api.localhost/health
grpcurl -plaintext users-api.localhost list

# 3. 終了（Ctrl+C）

デバッグセッション

# 1. デバッグモードで起動
sudo ./kubectl-localmesh -f services.yaml -log debug

# 2. 問題を再現
curl http://users-api.localhost/problematic-endpoint

# 3. ログを確認
# （標準出力に詳細なログが表示される）

# 4. 必要に応じてEnvoy設定を確認
./kubectl-localmesh --dump-envoy-config -f services.yaml

参考情報

プロジェクトのCLAUDE.mdに詳細なアーキテクチャと実装詳細があります。

関連Skills

• go-taskfile-workflow: ビルドとテスト
• kubectl-envoy-debugging: Envoy設定の確認とデバッグ
• kubectl-localmesh-macos-localhost: macOSの.localhostドメインの挙動