AgentSkillsCN

kubectl-localmesh-operations

提供 kubectl-localmesh 特有的运维操作（启动、/etc/hosts 管理、服务访问、依赖关系检查）。

SKILL.md
--- frontmatter
name: kubectl-localmesh-operations
description: kubectl-localmesh固有の運用操作（起動、/etc/hosts管理、サービスアクセス、依存関係チェック）を提供します
allowed-tools: ["Bash", "Read"]

kubectl-localmesh 運用操作

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

提供機能

起動

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

bash
sudo kubectl localmesh -f services.yaml

直接実行の場合:

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

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

/etc/hosts管理オプション

自動更新を無効化:

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

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

bash
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更新無効時:

bash
# 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プロセスを停止
  • •一時ディレクトリを削除

クリーンな終了を確認:

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

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

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

依存関係チェック

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

bash
# スクリプトを使用
.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. •または既存プロセスを停止
bash
# ポート80を使用しているプロセスを確認
lsof -i :80

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

問題: Envoy起動失敗

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

解決:

  1. •Envoy設定を確認（kubectl-envoy-debugging skillを使用）
  2. •デバッグログを確認
bash
# 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とクラスタ接続確認
bash
# サービスの存在確認
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オプションを使用
bash
# 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ヘッダーを確認
bash
# 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. •

    「動かない」

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

ワークフロー例

初回セットアップ

bash
# 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

日常的な使用

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

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

# 3. 終了（Ctrl+C）

デバッグセッション

bash
# 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ドメインの挙動