設定ミスのあるメッシュは、大きな音を立てて失敗しないことがよくあります。トラフィックが期待どおりにルーティングされない、あるいは当然得られると思っていたサイドカーが Pod に付かない、といった形です。istioctl には、まさにこのための専用コマンドがあり、分かりにくい症状を引き起こす前に問題を見つけます。このガイドでは、日常的に実行する価値のあるものを説明します。

istioctl analyze：問題になる前に設定の問題を見つける

istioctl analyze
istioctl analyze -n my-namespace
istioctl analyze -A

analyze は、適用しようとしているファイルだけでなく、クラスターの実際の Istio 設定を検査し、本当の問題を報告します。明らかにそのつもりだったのに注入のラベルが付いていない namespace、存在しないホストを参照している VirtualService、2 つのリソース間の矛盾した設定などです。namespace フラグなしで実行すると現在のコンテキストのデフォルトの namespace、-n で特定の namespace、-A でクラスター内のすべての namespace が対象になります。何かが明らかに壊れているときだけでなく、設定を変更するたびに、これを習慣にしてください。問題が症状になる前に、定期的に見つけてくれます。

istioctl validate：適用前にファイルを確認する

istioctl validate -f my-virtualservice.yaml

analyze がクラスターにすでに存在するものを検査するのに対し、validate はマニフェストを適用する前に、スキーマエラーや無効なフィールド値を検出します。Istio 関連のものに対する kubectl apply の前に、プレーンな Kubernetes リソースに kubectl apply --dry-run を実行するのと同じ反射的な動作として、普段から実行してください。

istioctl proxy-status：すべてのサイドカーが同期しているか

istioctl proxy-status

これは、istiod が把握しているすべてのサイドカーを一覧表示し、それぞれが最新の設定を持っているか（SYNCED）、遅れているか（STALE、またはエラーの表示）を示します。STALE のまま止まっているサイドカーは、適用したばかりのルーティングの変更が特定の Pod で反映されないように見えるときの、実際の説明であることが多く、設定自体が間違っていると決めつける前に確認する価値があります。

istioctl proxy-config：この 1 つのサイドカーは実際に何を実行しているか

動作から推測するのではなく、単一の Pod の Envoy 設定を直接調べるには、次のようにします。

istioctl proxy-config routes <pod-name> -n <namespace>
istioctl proxy-config clusters <pod-name> -n <namespace>
istioctl proxy-config listeners <pod-name> -n <namespace>

これは、このライブラリの Envoy のガイドが説明している、実行中の設定を検査するのと同じ基本的な考え方で、Envoy 自身の生の管理 API を直接使うのではなく、Istio 自身のラッパーを通じて行うものです。

app ラベル：見落としやすく、黙って可視化を壊す

特に、単独で取り上げるほど一般的な落とし穴が 1 つあります。Istio（および、次のガイドで説明する Kiali のような、その上に構築されたツール）は、どのワークロードがどれと通信しているかを正確に把握するために、Deployment と Service の app ラベルに依存しています。

metadata:
  labels:
    app: reviews

これを省略しても、何も大きな音を立てて壊れることはありません。Pod は引き続きデプロイされ、サイドカーは引き続き注入され、トラフィックは引き続き流れます。黙って動作しなくなるのは、ワークロードを識別するためにそのラベルに依存するすべてのものです。Kiali のサービスグラフは接続を正しくレンダリングできませんし、app を手がかりにするトラフィック管理とテレメトリの一部の機能は、予測できない動作をします。メッシュがそれ以外は正常に見えるのに、その可観測性ツールが分かりにくい、または不完全な図を表示している場合、下にある Deployment と Service の app ラベルの欠落が、最初に確認する価値があるものの 1 つです。失敗の仕方が、原因を指し示すエラーメッセージを出さないからこそです。

身につける価値のある習慣

設定を変更するたびに istioctl analyze を、新しいものを適用する前に istioctl validate を、そして変更が特定の場所で反映されないように見えるときは istioctl proxy-status を実行します。これらのどれもすべてを検出するわけではありません。Istio の設定の範囲は広いからです。しかし、組み合わせれば、よくある、かつ YAML を眺めているだけでデバッグするのが面倒なエラーを、見つけてくれます。