SKILL.md
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エラー
解決:
listener_portを変更（services.yaml）- または既存プロセスを停止
# ポート80を使用しているプロセスを確認
lsof -i :80
# プロセスを停止
kill <PID>問題: Envoy起動失敗
症状: Envoyプロセスがすぐに終了する
解決:
- Envoy設定を確認（
kubectl-envoy-debuggingskillを使用） - デバッグログを確認
# 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エラー
解決:
- サービスの存在確認
- ポート名/番号の確認
- kubeconfigとクラスタ接続確認
# サービスの存在確認
kubectl get svc -n <namespace>
# サービスの詳細とポート確認
kubectl describe svc <service> -n <namespace>
# kubeconfigとクラスタ接続確認
kubectl cluster-info
kubectl get nodes問題: /etc/hosts更新失敗
症状: permission deniedエラー
解決:
- sudoで実行
- または
--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
解決手順:
- kubectl-localmeshが起動しているか確認
- port-forwardが正常に動作しているか確認
- Envoyログを確認
- 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使用方法
ユーザーから以下のような依頼があった場合:
- 「起動して」
- 依存関係チェック - sudo権限確認 - 適切なパスで起動
- 「サービスにアクセスしたい」
- /etc/hosts設定に応じた方法を案内 - HTTPまたはgRPCに応じたコマンド例を提供
- 「動かない」
- 依存関係チェック - トラブルシューティングフローを実行 - エラーメッセージに応じた解決策を提示
ワークフロー例
初回セットアップ
# 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ドメインの挙動