istio-traffic-management

## istio-traffic-managementの概要

`istio-traffic-management` は、実運用向けのIstioトラフィックポリシーのマニフェストを生成・整理するための実践ガイドです。サービスメッシュで実際に使うリソース（`VirtualService`、`DestinationRule`、`Gateway`、`ServiceEntry`）と、カナリア、リトライ、サーキットブレーカー、ミラーリング、フォルトインジェクションといったパターンに焦点を当てています。

### このスキルが最適なユーザー

この `istio-traffic-management skill` が向いているのは次のようなチームです。
- Istioベースのクラスタを運用するプラットフォームエンジニア
- カナリアやブルーグリーンのリリースを進めるアプリチーム
- リトライやサーキットブレーカーなどの耐障害ポリシーを設計するSRE
- 生のYAMLを思い出しながら書くより、展開に安全な例を素早く得たいチーム

### どんな仕事に役立つか

`istio-traffic-management` は、「Istioを説明してほしい」ではなく「このサービスとリリース計画に合うトラフィック設定を出したい」という時に使います。目的が明確で、意図を正しいIstioリソースとトラフィック設計に落とし込む必要がある場面で効果的です。

### 汎用的なIstioプロンプトとの違い

一般的なプロンプトは断片的なYAMLを返しがちです。`istio-traffic-management guide` は、正しいリソースの組み合わせと順序立てに強みがあります。
- `VirtualService` でのルーティング選択
- `DestinationRule` でのサブセットとポリシー定義
- `Gateway` による入口（エッジ）処理
- `ServiceEntry` による外部依存の登録

多くのIstioの失敗は「フィールドの間違い」より「リソースの選択ミス」から起きるため、この構造が重要です。

### インストール前に確認すべきこと

このスキルが合うのは次のケースです。
- すでにIstioを使っている、もしくは導入が確定している
- 本番のトラフィック挙動向けのマニフェストパターンが必要
- ルーティングや耐障害ポリシーの初期案を素早く作りたい

次の場合は適合度が下がります。
- Istioを使っていない
- Argo RolloutsやFlaggerなど、コントローラ固有の配信ロジックが必要
- 深いクラスタ診断やライブデバッグが目的（本スキルは構成作成が中心）

## istio-traffic-managementの使い方

### istio-traffic-management skill のインストール方法

リポジトリの `SKILL.md` に専用のインストールコマンドはないため、実際の `istio-traffic-management install` は `wshobson/agents` から追加し、デプロイ情報を読めるエージェントセッションで使います。

一般的なインストール例:

`npx skills add https://github.com/wshobson/agents --skill istio-traffic-management`

インストール後は、`Deployment` 向けのIstioマニフェスト、ロールアウトポリシー、トラフィック実験の準備時に読み込むと効果的です。

### 最初に読むべきファイル

以下から始めてください。
- `SKILL.md`

このスキルは自己完結型に見えます。補助スクリプトや参照フォルダは見当たらないため、主なガイダンスはスキル本体に集約されています。素早い導入に向きますが、環境情報は自分で用意する必要があります。

### このスキルに渡すべき入力

`istio-traffic-management usage` の品質は入力情報に大きく左右されます。最低限、次を用意してください。
- サービス名
- namespace
- 関係するホスト名
- ingressか内部メッシュか
- カナリア、ブルーグリーン、ミラーリング、フォルトインジェクションなどのロールアウト目的
- `version: v1` や `version: v2` のようなサブセットラベル
- 比率、リトライ、タイムアウト、サーキットブレーカー設定
- 対象がKubernetesの `Deployment` か、ゲートウェイルートか、外部サービスか

これらがない場合、汎用的な例しか返せません。

### あいまいな目的を強いプロンプトに変える

弱いプロンプト:
- “Set up Istio traffic management for my app.”

強いプロンプト:
- “Use the `istio-traffic-management` skill to create Istio manifests for a `Deployment` named `payments` in namespace `prod`. We have subsets `v1` and `v2` labeled by `version`. Route 90% to `v1` and 10% to `v2`, expose traffic through an existing ingress `Gateway`, add retries for 5xx with 2 attempts, and define a `DestinationRule` with simple connection pool and outlier detection settings. Return YAML plus a short explanation of why each resource is needed.”

強いほうは、トラフィック意図、サブセット設計、ポリシー範囲が明確になり、出力の精度が上がります。

### Deployment向けのistio-traffic-management最適プロンプト

`istio-traffic-management for Deployment` ではKubernetesとメッシュ両方の情報を含めてください。
1. `Deployment` 名とnamespace
2. ポッドの前に立つService名
3. サブセットに使うPodラベル
4. トラフィックがゲートウェイ経由か内部のみか
5. ロールアウトの具体的挙動
6. リトライ、タイムアウト、mTLS前提などの安全制御
7. 完成マニフェストかパッチだけか

これにより、`DestinationRule` のサブセットが実際のPodラベルと一致しない失敗を防げます。

### 生成が得意な領域

ソース内容から、以下は高い確度で生成できます。
- ホストベース／ヘッダーベースのルーティング
- カナリアのトラフィック分割
- `DestinationRule` の負荷分散やポストルーティングポリシー
- テスト用ミラーリング
- レジリエンステスト向けのフォルトインジェクション
- サーキットブレーカーとリトライの設計

これらはスキルのコンセプトとテンプレートで明示的に扱われています。

### 実務での推奨ワークフロー

実践的な `istio-traffic-management usage` の流れ:
1. リリースや耐障害の目標を平易な言葉で定義
2. サービス、サブセット、ホストを正確に列挙
3. まず目標をIstioリソースにマッピングするよう依頼
4. 各リソースが入口／ルーティング／宛先ポリシーのどこに属するか確認
5. 最終YAMLを依頼
6. ラベル、namespace、ホスト名をクラスタの規約と照合
7. その後にリポジトリやHelm/Kustomize構成へ統合

最初からYAMLを求めるより、概念ズレを早めに検出できます。

### 期待すべきリソースの分担

`istio-traffic-management skill` の良い出力は、通常次のように分離されます。
- `Gateway`: エッジ入口設定
- `VirtualService`: リクエストマッチとルーティング
- `DestinationRule`: サブセット、負荷分散、接続ポリシー、外れ値検知
- `ServiceEntry`: メッシュ外への通信定義

もし説明が曖昧に混ざっている場合は、リソース単位の理由付けを先に求めてください。

### YAML適用前の実務チェック

生成物を使う前に確認すること:
- サブセットラベルが実際のPodラベルと一致するか
- `hosts` がKubernetesサービスDNSやゲートウェイホストに合っているか
- namespace参照が正しいか
- トラフィック比率の合計が正しいか
- リトライ／タイムアウトがアプリ挙動に合うか
- サーキットブレーカーが例の流用になっていないか
- ミラーリング／フォルトインジェクションは安全環境に限定されているか

文法よりも運用上の整合性の方が重要です。

### マニフェストではなく説明を先に求めるべき時

次の条件では、まず説明を求める方が安全です。
- `VirtualService` と `DestinationRule` のどちらが必要か迷っている
- KubernetesのネットワークからIstioに移行中
- ingressルーティングと内部ポリシーが同時に絡む
- YAMLをマージする前にレビュー可能な設計根拠が必要

ここは普通のプロンプトより時間短縮効果が大きい領域です。

## istio-traffic-management skillのFAQ

### istio-traffic-managementは初心者向け？

基本的なKubernetesのServiceやDeploymentを理解していれば有効です。主要なIstioトラフィックリソースが整理されているため、ルーティングとポリシーの混同を避けられます。一方、Kubernetesもサービスメッシュも初めての場合は適しません。

### istio-traffic-management skillが単体で苦手なこと

これは本番向けの完全検証ツールではありません。以下の代替にはなりません。
- クラスタ固有のテスト
- アドミッションポリシー検証
- チャートやオーバーレイの統合作業
- Envoyやコントロールプレーンのライブデバッグ

強力な構成ドラフト支援として扱い、環境での正しさを保証するものではないと考えてください。

### 通常の「Istio YAMLを書いて」より良い？

多くの場合は良いです。`istio-traffic-management` は実際のトラフィック管理タスクとリソース境界を前提にしているため、汎用プロンプトが見落としがちな補助リソースや不適切なデフォルトを避けられます。

### カナリアやブルーグリーンに役立つ？

はい。`istio-traffic-management guide` の最も適合する領域です。サブセット、重み、ingress情報を渡せば、ルーティング設計とポリシーの下書きを素早く作れます。

### 既存のGatewayがある場合でも使える？

使えます。`Gateway` が既存であること、`VirtualService` から参照するだけにしたいことを明示してください。不要なエッジ設定の再生成を避けられます。

### ingressトラフィック専用？

いいえ。エッジと内部のサービス間通信の両方を扱います。内部向けのリトライ、サーキットブレーカー、負荷分散、バージョンルーティングで特に有効です。

### istio-traffic-managementを使うべきでないケース

以下の場合は見送ってください。
- クラスタがIstioを使っていない
- ベンダー固有のサービスメッシュ方言が必要
- 観測性やデバッグが主目的
- 手書きIstioリソースではなく、別コントローラ主導の高度なロールアウトが必要

## istio-traffic-managementを改善する方法

### アーキテクチャ意図だけでなく実デプロイ情報を渡す

`istio-traffic-management` の出力を最速で改善するには、具体的な値を渡すことです。
- 正確なサービス名とnamespace
- 実際のサブセットラベル
- 現在とターゲットのバージョン
- ホスト名とゲートウェイ
- リトライ／タイムアウトの期待値
- north-southかeast-westか

仮定を減らし、YAMLをすぐ使える形に近づけます。

### 最終YAMLの前にリソース計画を依頼する

価値の高いプロンプトの流れ:
1. “Map my goal to the Istio resources needed.”
2. “Explain why each object is needed.”
3. “Now generate the manifests.”

ルーティングと宛先ポリシーの混同を早い段階で防げます。

### 最頻の失敗を防ぐ: サブセットラベルの不一致

`istio-traffic-management for Deployment` では、Podに実際に付いているラベルを明示してください。多くの生成例は `version: v1` と `version: v2` を仮定します。ラベルが違う場合は事前に伝えないと、`DestinationRule` のサブセットが機能しません。

### 例と安全なデフォルトを分離するよう依頼する

本番計画で使う場合は、次を確認するように依頼してください。
- プレースホルダーの値
- 安全なデフォルト値
- トラフィック特性やレイテンシに依存する値

特にリトライ、外れ値検知、接続プールの調整で重要です。

### トラフィック制約を与えてプロンプトを強化する

以下のような制約は効果的です。
- “Do not create a new Gateway.”
- “Keep routing internal only.”
- “Mirror 5% of traffic to v2 without affecting responses.”
- “Use header-based routing for QA users only.”

制約があると、実際のロールアウトに沿った出力になります。

### 正しさだけでなくレビューしやすさを改善する

最初の出力の後、次を依頼してください。
- PRレビュー向けにコメントを短くする
- リソースを別ファイルに分割する
- 移行影響を説明する
- チーム確認が必要な前提を列挙する

YAML生成後の最大の障害である「リポジトリへの統合」を楽にします。

### パターン選定では明確なトレードオフを求める

複数案がある場合は、`istio-traffic-management skill` に比較を求めてください。
- 重み付きカナリア vs ヘッダーベースルーティング
- ミラーリング vs 低リスクのカナリア
- ingressのみのルーティング vs 内部サービスのルーティング
- リトライ重視 vs サーキットブレーカー重視

一括生成よりも意思決定の質が上がります。

### プラットフォーム規約に合わせて検証する

実務に役立つ出力にするため、以下を伝えてください。
- Helm / Kustomize / 生YAMLの利用方針
- 命名規約
- namespace分離ルール
- 既存のゲートウェイとホストパターン
- mTLS前提などのセキュリティ要件

スキルはトラフィック設計に強く、規約情報があると精度が上がります。

### 設計ドラフトに使い、最終強化は手動で行う

`istio-traffic-management` の最適な使い方は、高品質な初稿を速く作ることです。最終的な強化は必ず手動で行ってください。
- クラスタ検証
- 段階的ロールアウトのテスト
- カナリア中のメトリクス確認
- ロールバック計画

スピードを得つつ、トラフィックポリシーを過信しない運用モデルが適切です。