istioctl
istioctl 完全ガイド — Istio サービスメッシュの運用・管理・トラブルシューティング
はじめに
Istio は Kubernetes 上で動作するオープンソースのサービスメッシュであり、マイクロサービス間のトラフィック管理、セキュリティ、可観測性を提供する。istioctl は Istio の公式 CLI ツールであり、Istio のインストール、設定管理、デバッグ、トラブルシューティングなど、Istio 運用に不可欠な機能を包括的に提供する。
本ドキュメントでは、SRE エンジニアが日常的に使用する istioctl の全機能について、具体的なコマンド例とともに詳細に解説する。
1. istioctl のインストール
1.1 公式インストールスクリプトによるインストール
最も簡単な方法は、Istio の公式インストールスクリプトを使用することである。
# 最新版をダウンロード・インストール
curl -L https://istio.io/downloadIstio | sh -
# 特定バージョンを指定してインストール
curl -L https://istio.io/downloadIstio | ISTIO_VERSION=1.22.0 sh -
# 特定のアーキテクチャを指定
curl -L https://istio.io/downloadIstio | ISTIO_VERSION=1.22.0 TARGET_ARCH=x86_64 sh -
インストール後、PATH を設定する。
# ダウンロードされたディレクトリに移動
cd istio-1.22.0
# PATH に追加
export PATH=$PWD/bin:$PATH
# 恒久的に設定する場合（.bashrc または .zshrc に追加）
echo 'export PATH="$HOME/istio-1.22.0/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
1.2 Homebrew によるインストール（macOS）
brew install istioctl
1.3 バイナリの直接ダウンロード
# Linux (amd64)
curl -LO https://github.com/istio/istio/releases/download/1.22.0/istioctl-1.22.0-linux-amd64.tar.gz
tar xzf istioctl-1.22.0-linux-amd64.tar.gz
sudo mv istioctl /usr/local/bin/
# macOS (arm64)
curl -LO https://github.com/istio/istio/releases/download/1.22.0/istioctl-1.22.0-osx-arm64.tar.gz
tar xzf istioctl-1.22.0-osx-arm64.tar.gz
sudo mv istioctl /usr/local/bin/
1.4 インストールの確認
# バージョン確認
istioctl version
# クライアントのみのバージョン確認（コントロールプレーンに接続不要）
istioctl version --remote=false
# 出力例
# client version: 1.22.0
# control plane version: 1.22.0
# data plane version: 1.22.0 (10 proxies)
1.5 シェル補完の設定
# Bash
istioctl completion bash > /etc/bash_completion.d/istioctl
# Zsh
istioctl completion zsh > "${fpath[1]}/_istioctl"
# Fish
istioctl completion fish > ~/.config/fish/completions/istioctl.fish
2. Istio のインストールと管理
2.1 プロファイルを使用したインストール
Istio は複数の組み込みプロファイルを提供しており、用途に応じて選択できる。
# 利用可能なプロファイルの一覧表示
istioctl profile list
# 出力例:
# Istio configuration profiles:
# ambient
# default
# demo
# empty
# minimal
# openshift
# preview
# remote
各プロファイルの特徴:
| プロファイル | 説明 | 主な用途 |
|---|---|---|
default | 本番環境推奨。istiod と ingress gateway を含む | 本番環境 |
demo | すべてのコンポーネントを含む | 学習・検証 |
minimal | istiod のみ | 最小構成 |
empty | 何もデプロイしない | カスタム構成のベース |
ambient | Ambient メッシュモード | ztunnel ベースの構成 |
preview | 実験的機能を含む | 新機能の検証 |
remote | リモートクラスタ用 | マルチクラスタ |
openshift | OpenShift 向け最適化 | OpenShift 環境 |
# default プロファイルでインストール
istioctl install
# demo プロファイルでインストール
istioctl install --set profile=demo
# minimal プロファイルでインストール
istioctl install --set profile=minimal
# ambient プロファイルでインストール
istioctl install --set profile=ambient
# インストール時に確認プロンプトをスキップ
istioctl install --set profile=demo -y
2.2 プロファイルのカスタマイズ
# プロファイルの詳細設定を確認
istioctl profile dump demo
# 特定のコンポーネント設定のみ表示
istioctl profile dump --config-path components.pilot demo
# 二つのプロファイルの差分を確認
istioctl profile diff default demo
インストール時にカスタマイズを適用する例:
# Ingress Gateway のレプリカ数を変更
istioctl install --set profile=default \
--set values.gateways.istio-ingressgateway.replicaCount=3
# メッシュ全体の設定を変更
istioctl install --set profile=default \
--set meshConfig.accessLogFile=/dev/stdout \
--set meshConfig.accessLogEncoding=JSON
# mTLS を STRICT モードに設定
istioctl install --set profile=default \
--set meshConfig.defaultConfig.holdApplicationUntilProxyStarts=true
# Pilot のリソース制限を設定
istioctl install --set profile=default \
--set values.pilot.resources.requests.cpu=500m \
--set values.pilot.resources.requests.memory=2Gi
2.3 IstioOperator マニフェストを使用したインストール
より複雑な設定は YAML ファイルで管理する。
# istio-config.yaml
apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
metadata:
name: istio-control-plane
namespace: istio-system
spec:
profile: default
meshConfig:
accessLogFile: /dev/stdout
accessLogEncoding: JSON
enableTracing: true
defaultConfig:
tracing:
sampling: 100.0
holdApplicationUntilProxyStarts: true
outboundTrafficPolicy:
mode: REGISTRY_ONLY
components:
pilot:
k8s:
resources:
requests:
cpu: 500m
memory: 2Gi
limits:
cpu: "2"
memory: 4Gi
hpaSpec:
minReplicas: 2
maxReplicas: 5
ingressGateways:
- name: istio-ingressgateway
enabled: true
k8s:
resources:
requests:
cpu: 200m
memory: 256Mi
service:
type: LoadBalancer
hpaSpec:
minReplicas: 2
maxReplicas: 10
egressGateways:
- name: istio-egressgateway
enabled: true
values:
global:
proxy:
resources:
requests:
cpu: 100m
memory: 128Mi
limits:
cpu: "1"
memory: 512Mi
# マニフェストファイルを使用してインストール
istioctl install -f istio-config.yaml
# 複数のオーバーレイファイルを適用
istioctl install -f base-config.yaml -f overlay-production.yaml
# dry-run でマニフェストを確認
istioctl install -f istio-config.yaml --dry-run
2.4 マニフェストの生成
istioctl manifest コマンドを使用して、Kubernetes マニフェストを生成・管理できる。
# マニフェストの生成（YAML 出力）
istioctl manifest generate --set profile=default > istio-manifest.yaml
# カスタム設定でマニフェスト生成
istioctl manifest generate -f istio-config.yaml > istio-manifest.yaml
# 生成されたマニフェストを kubectl で適用（非推奨だが可能）
istioctl manifest generate --set profile=demo | kubectl apply -f -
# マニフェストの差分確認
istioctl manifest diff manifest1.yaml manifest2.yaml
2.5 インストールの検証
# インストール状態の確認
istioctl verify-install
# 特定のプロファイルに対して検証
istioctl verify-install --set profile=demo
# マニフェストファイルに対して検証
istioctl verify-install -f istio-config.yaml
2.6 Istio のアップグレード
インプレースアップグレード
# 新しいバージョンの istioctl で直接アップグレード
istioctl install --set profile=default
# 設定ファイルを使用してアップグレード
istioctl install -f istio-config.yaml
カナリアアップグレード
# リビジョンを指定してカナリーコントロールプレーンをデプロイ
istioctl install --set profile=default --set revision=canary
# カナリーリビジョンの状態確認
kubectl get pods -n istio-system -l istio.io/rev=canary
# 名前空間のラベルをカナリーリビジョンに切り替え
kubectl label namespace my-app istio.io/rev=canary --overwrite
# 名前空間内の Pod を再起動して新しいプロキシに切り替え
kubectl rollout restart deployment -n my-app
# 動作確認後、古いコントロールプレーンを削除
istioctl uninstall --revision=default
2.7 Istio のアンインストール
# 特定のリビジョンをアンインストール
istioctl uninstall --revision=default
# すべての Istio コンポーネントを完全に削除
istioctl uninstall --purge
# 確認プロンプトをスキップ
istioctl uninstall --purge -y
# アンインストール後のクリーンアップ
kubectl delete namespace istio-system
kubectl label namespace default istio-injection-
3. サイドカーインジェクション
3.1 自動サイドカーインジェクション
Istio は Kubernetes の Mutating Admission Webhook を利用して、Pod 作成時に自動的に Envoy サイドカープロキシを注入する。
# 名前空間に自動インジェクションを有効化
kubectl label namespace default istio-injection=enabled
# リビジョンベースのインジェクション（カナリアアップグレード時）
kubectl label namespace default istio.io/rev=stable
# ラベルの確認
kubectl get namespace -L istio-injection
# 自動インジェクションを無効化
kubectl label namespace default istio-injection-
# 特定の Pod でインジェクションを無効化（Pod のアノテーション）
# metadata:
# annotations:
# sidecar.istio.io/inject: "false"
3.2 手動サイドカーインジェクション
自動インジェクションが使用できない場合や、細かい制御が必要な場合に手動インジェクションを使用する。
# デプロイメントマニフェストにサイドカーを注入
istioctl kube-inject -f deployment.yaml | kubectl apply -f -
# ファイルに出力してから適用
istioctl kube-inject -f deployment.yaml -o deployment-injected.yaml
kubectl apply -f deployment-injected.yaml
# 特定のリビジョンを指定してインジェクション
istioctl kube-inject -f deployment.yaml --revision=canary | kubectl apply -f -
# カスタムインジェクション設定を使用
istioctl kube-inject -f deployment.yaml \
--injectConfigFile inject-config.yaml \
--meshConfigFile mesh-config.yaml \
--valuesFile values.yaml
# 既存のデプロイメントからマニフェストを取得してインジェクション
kubectl get deployment my-app -o yaml | istioctl kube-inject -f - | kubectl apply -f -
3.3 サイドカーインジェクションの確認
# Pod 内のコンテナを確認
kubectl get pods -n default -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{range .spec.containers[*]}{.name}{","}{end}{"\n"}{end}'
# istio-proxy コンテナが含まれているか確認
kubectl describe pod my-app-pod -n default | grep -A 5 "istio-proxy"
# インジェクションの状態を詳細に確認
istioctl analyze -n default
3.4 サイドカーリソースのカスタマイズ
Pod のアノテーションを使用して、サイドカーのリソースを個別に設定できる。
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-app
spec:
template:
metadata:
annotations:
# サイドカーの CPU/メモリリクエスト・リミット
sidecar.istio.io/proxyCPU: "200m"
sidecar.istio.io/proxyCPULimit: "1"
sidecar.istio.io/proxyMemory: "256Mi"
sidecar.istio.io/proxyMemoryLimit: "1Gi"
# ログレベル
sidecar.istio.io/logLevel: "warning"
# アクセスログの有効化
sidecar.istio.io/accessLogFile: "/dev/stdout"
# インターセプトするポートの制御
traffic.sidecar.istio.io/includeInboundPorts: "8080,8443"
traffic.sidecar.istio.io/excludeOutboundPorts: "3306,6379"
traffic.sidecar.istio.io/excludeOutboundIPRanges: "10.0.0.0/8"
spec:
containers:
- name: my-app
image: my-app:latest
4. トラブルシューティングと診断
4.1 istioctl analyze -- 設定の分析
istioctl analyze は Istio の設定を分析し、潜在的な問題を検出する強力な診断ツールである。
# 現在のクラスタ全体を分析
istioctl analyze --all-namespaces
# 特定の名前空間を分析
istioctl analyze -n my-namespace
# ローカルファイルを分析（クラスタに適用する前に検証）
istioctl analyze my-virtualservice.yaml
# ローカルファイルとクラスタの設定を組み合わせて分析
istioctl analyze -n my-namespace my-virtualservice.yaml
# 特定のメッセージレベルでフィルタ
istioctl analyze --all-namespaces --output-threshold Error
# 出力形式を指定
istioctl analyze -n my-namespace -o json
istioctl analyze -n my-namespace -o yaml
主要な診断メッセージ
istioctl analyze が検出する主要な問題と対処法を以下に示す。
| メッセージコード | 説明 | 対処法 |
|---|---|---|
IST0101 | 参照先のゲートウェイが見つからない | VirtualService で参照するゲートウェイ名を確認 |
IST0102 | 名前空間にサイドカーインジェクションが設定されていない | kubectl label ns <ns> istio-injection=enabled |
IST0103 | サービスのポート命名規則に違反 | ポート名を http-*, grpc-*, tcp-* 等に変更 |
IST0104 | サービスのセレクタに一致する Pod がない | セレクタのラベルを確認 |
IST0106 | VirtualService のホストが見つからない | ホスト名とサービス名の一致を確認 |
IST0108 | Unknown annotation | アノテーション名のスペルを確認 |
IST0112 | DestinationRule のサブセットが未使用 | 不要なサブセットを削除するか VirtualService で参照 |
IST0113 | Gateway のポートがサービスメッシュ外からアクセス不可 | Gateway のサービスタイプとポート設定を確認 |
IST0116 | Gateway のワイルドカードホストが競合 | ホスト名をより具体的に指定 |
IST0122 | 名前空間スコープの設定がない | Sidecar リソースで egress 設定を追加 |
IST0128 | mTLS ポリシーの不整合 | PeerAuthentication と DestinationRule の設定を統一 |
IST0131 | VirtualService のルーティングルールが未到達 | ルールの優先順位を確認 |
IST0132 | VirtualService の destination ポートが不正 | サービスのポート番号を確認 |
IST0134 | Gateway にバインドされた VirtualService がない | VirtualService を作成するか Gateway を削除 |
IST0139 | AuthorizationPolicy の不整合 | ポリシーのルールとセレクタを確認 |
# 分析結果の例
# Warning [IST0102] (Namespace default) The namespace is not enabled for Istio injection.
# Enable injection by adding "istio-injection=enabled" label.
# Warning [IST0103] (Service default/my-service) The port "svc-port" does not follow
# the naming convention. Rename to "http-svc-port" or "tcp-svc-port".
# Error [IST0101] (VirtualService default/my-vs) Referenced gateway not found:
# "my-gateway"
4.2 proxy-status -- プロキシ同期状態の確認
# すべてのプロキシの同期状態を一覧表示
istioctl proxy-status
# 出力例:
# NAME CLUSTER CDS LDS EDS RDS ECDS ISTIOD
# my-app-7b8d6c9f4-abc12.ns Kubernetes SYNCED SYNCED SYNCED SYNCED istiod-7f8b9c6d-xyz
# my-app-7b8d6c9f4-def34.ns Kubernetes SYNCED SYNCED SYNCED SYNCED istiod-7f8b9c6d-xyz
# gateway-5c6d7e8f-ghi56.ns Kubernetes SYNCED SYNCED SYNCED SYNCED istiod-7f8b9c6d-xyz
# 略称: ps
istioctl ps
# 特定のリビジョンのプロキシのみ表示
istioctl proxy-status --revision=canary
各ステータスの意味:
| ステータス | 意味 |
|---|---|
SYNCED | Envoy は istiod から最新の設定を受信済み |
NOT SENT | istiod はこのプロキシに設定を送信していない（送信する設定がない） |
STALE | istiod は設定を送信したが ACK が返ってきていない（問題の兆候） |
# 特定のプロキシの詳細な同期状態を確認
istioctl proxy-status my-app-7b8d6c9f4-abc12.my-namespace
# JSON 形式で出力
istioctl proxy-status -o json
4.3 proxy-config -- プロキシ設定の詳細確認
proxy-config は Envoy プロキシの設定を詳細に確認するためのコマンドである。
4.3.1 ルーティング設定（routes）
# ルーティング設定の一覧
istioctl proxy-config routes my-app-7b8d6c9f4-abc12.my-namespace
# 特定のルート名でフィルタ
istioctl proxy-config routes my-app-7b8d6c9f4-abc12.my-namespace --name 8080
# JSON 形式で詳細を確認
istioctl proxy-config routes my-app-7b8d6c9f4-abc12.my-namespace -o json
# 出力例（テーブル形式）:
# NAME DOMAINS MATCH VIRTUAL SERVICE
# 8080 my-service.default.svc /* my-vs.default
# 80 backend.prod.svc /api/* backend-vs.prod
# デプロイメント名でも指定可能
istioctl proxy-config routes deploy/my-app -n my-namespace
4.3.2 クラスタ設定（clusters）
# クラスタ（アップストリーム）設定の一覧
istioctl proxy-config clusters my-app-7b8d6c9f4-abc12.my-namespace
# FQDN でフィルタ
istioctl proxy-config clusters my-app-7b8d6c9f4-abc12.my-namespace \
--fqdn "my-service.default.svc.cluster.local"
# ポートでフィルタ
istioctl proxy-config clusters my-app-7b8d6c9f4-abc12.my-namespace --port 8080
# サブセットでフィルタ
istioctl proxy-config clusters my-app-7b8d6c9f4-abc12.my-namespace --subset v1
# 方向でフィルタ（inbound/outbound）
istioctl proxy-config clusters my-app-7b8d6c9f4-abc12.my-namespace --direction inbound
# JSON 形式で出力
istioctl proxy-config clusters my-app-7b8d6c9f4-abc12.my-namespace -o json
# 出力例:
# SERVICE FQDN PORT SUBSET DIRECTION TYPE DESTINATION RULE
# my-service.default.svc.cluster.local 8080 v1 outbound EDS my-dr.default
# my-service.default.svc.cluster.local 8080 v2 outbound EDS my-dr.default
# backend.prod.svc.cluster.local 80 - outbound EDS
4.3.3 リスナー設定（listeners）
# リスナー設定の一覧
istioctl proxy-config listeners my-app-7b8d6c9f4-abc12.my-namespace
# ポートでフィルタ
istioctl proxy-config listeners my-app-7b8d6c9f4-abc12.my-namespace --port 15006
# タイプでフィルタ
istioctl proxy-config listeners my-app-7b8d6c9f4-abc12.my-namespace --type HTTP
# JSON 形式で出力
istioctl proxy-config listeners my-app-7b8d6c9f4-abc12.my-namespace -o json
# 出力例:
# ADDRESS PORT MATCH DESTINATION
# 0.0.0.0 15006 ALL Inline Route: /*
# 0.0.0.0 15001 ALL PassthroughCluster
# 10.96.0.1 443 ALL Cluster: outbound|443||kubernetes.default
# 10.96.128.5 8080 Trans: raw_buffer; App: HTTP Route: 8080
4.3.4 エンドポイント設定（endpoints）
# エンドポイントの一覧
istioctl proxy-config endpoints my-app-7b8d6c9f4-abc12.my-namespace
# クラスタ名でフィルタ
istioctl proxy-config endpoints my-app-7b8d6c9f4-abc12.my-namespace \
--cluster "outbound|8080|v1|my-service.default.svc.cluster.local"
# ステータスでフィルタ
istioctl proxy-config endpoints my-app-7b8d6c9f4-abc12.my-namespace --status healthy
istioctl proxy-config endpoints my-app-7b8d6c9f4-abc12.my-namespace --status unhealthy
# ポートでフィルタ
istioctl proxy-config endpoints my-app-7b8d6c9f4-abc12.my-namespace --port 8080
# JSON 形式で出力
istioctl proxy-config endpoints my-app-7b8d6c9f4-abc12.my-namespace -o json
# 出力例:
# ENDPOINT STATUS OUTLIER CHECK CLUSTER
# 10.244.0.5:8080 HEALTHY OK outbound|8080|v1|my-service.default
# 10.244.0.6:8080 HEALTHY OK outbound|8080|v1|my-service.default
# 10.244.0.7:8080 HEALTHY OK outbound|8080|v2|my-service.default
4.3.5 シークレット設定（secrets）
# TLS 証明書・シークレットの一覧
istioctl proxy-config secret my-app-7b8d6c9f4-abc12.my-namespace
# JSON 形式で出力
istioctl proxy-config secret my-app-7b8d6c9f4-abc12.my-namespace -o json
# 出力例:
# RESOURCE NAME TYPE STATUS VALID CERT SERIAL NUMBER NOT AFTER NOT BEFORE
# default Cert Chain ACTIVE true abc123... 2024-12-31T00:00:00 2024-01-01T00:00:00
# ROOTCA CA ACTIVE true def456... 2025-12-31T00:00:00 2023-01-01T00:00:00
# kubernetes://my-cert Cert Chain ACTIVE true ghi789... 2024-06-30T00:00:00 2024-01-01T00:00:00
4.3.6 ブートストラップ設定（bootstrap）
# ブートストラップ設定の確認
istioctl proxy-config bootstrap my-app-7b8d6c9f4-abc12.my-namespace
# JSON 形式で出力
istioctl proxy-config bootstrap my-app-7b8d6c9f4-abc12.my-namespace -o json
# 出力には以下の情報が含まれる:
# - Envoy の初期設定
# - Admin API のアドレス
# - xDS サーバーへの接続設定
# - 統計情報のタグ設定
# - トレーシング設定
4.3.7 すべての設定を一括取得
# すべての設定を取得
istioctl proxy-config all my-app-7b8d6c9f4-abc12.my-namespace
# JSON 形式で出力
istioctl proxy-config all my-app-7b8d6c9f4-abc12.my-namespace -o json
4.4 describe -- リソースの詳細分析
istioctl describe は Kubernetes リソースに関連する Istio の設定を分かりやすく表示する。
# Pod の Istio 設定を確認
istioctl describe pod my-app-7b8d6c9f4-abc12 -n my-namespace
# 出力例:
# Pod: my-app-7b8d6c9f4-abc12
# Pod Revision: default
# Pod Ports: 8080 (my-app), 15090 (istio-proxy)
# --------------------
# Service: my-service
# Port: http 8080/HTTP targets pod port 8080
# --------------------
# Effective PeerAuthentication:
# Workload mTLS mode: STRICT
# --------------------
# Applied VirtualService: my-vs
# Route to host "my-service" with weight 80%
# Route to host "my-service-canary" with weight 20%
# --------------------
# Applied DestinationRule: my-dr
# Traffic policy: connectionPool, outlierDetection
# Subset v1: labels {version: v1}
# Subset v2: labels {version: v2}
# サービスの Istio 設定を確認
istioctl describe service my-service -n my-namespace
4.5 ztunnel-config -- Ztunnel 設定の確認（Ambient モード）
Ambient モードを使用している場合、ztunnel の設定を確認できる。
# ztunnel のワークロード情報を表示
istioctl ztunnel-config workloads
# 特定のノードの ztunnel ワークロード情報
istioctl ztunnel-config workloads --node node-1
# ztunnel のサービス情報を表示
istioctl ztunnel-config services
# ztunnel のポリシー情報を表示
istioctl ztunnel-config policies
# ztunnel の証明書情報を表示
istioctl ztunnel-config certificates
# すべての ztunnel 設定を表示
istioctl ztunnel-config all
# JSON 形式で出力
istioctl ztunnel-config workloads -o json
5. デバッグとログ管理
5.1 動的ログレベルの変更
istioctl proxy-config log を使用して、稼働中の Envoy プロキシのログレベルを動的に変更できる。
# 現在のログレベルを確認
istioctl proxy-config log my-app-7b8d6c9f4-abc12.my-namespace
# すべてのロガーのレベルを debug に変更
istioctl proxy-config log my-app-7b8d6c9f4-abc12.my-namespace --level debug
# 特定のロガーのみレベルを変更
istioctl proxy-config log my-app-7b8d6c9f4-abc12.my-namespace \
--level "connection:debug,router:debug,http:debug"
# 接続に関するデバッグ
istioctl proxy-config log my-app-7b8d6c9f4-abc12.my-namespace \
--level "connection:trace,upstream:debug"
# mTLS/TLS のデバッグ
istioctl proxy-config log my-app-7b8d6c9f4-abc12.my-namespace \
--level "secret:debug,ssl:debug"
# フィルタ処理のデバッグ
istioctl proxy-config log my-app-7b8d6c9f4-abc12.my-namespace \
--level "filter:debug,rbac:debug,jwt:debug"
# ログレベルを元に戻す
istioctl proxy-config log my-app-7b8d6c9f4-abc12.my-namespace --level warning
# デプロイメント名で指定
istioctl proxy-config log deploy/my-app -n my-namespace --level debug
利用可能なログレベル（低い順）:
| レベル | 説明 |
|---|---|
trace | 最も詳細。開発・デバッグ時のみ使用 |
debug | デバッグ情報。問題調査時に使用 |
info | 一般的な情報 |
warning | 警告（デフォルト） |
error | エラーのみ |
critical | 重大なエラー |
off | ログ出力を無効化 |
主要なロガーカテゴリ:
| カテゴリ | 説明 |
|---|---|
admin | Envoy Admin API |
client | HTTP クライアント |
config | 設定処理 |
connection | ネットワーク接続 |
filter | フィルタチェーン処理 |
http | HTTP プロトコル処理 |
http2 | HTTP/2 プロトコル |
jwt | JWT トークン検証 |
lua | Lua フィルタ |
main | メインスレッド |
pool | コネクションプール |
rbac | RBAC 認可 |
redis | Redis プロキシ |
router | HTTP ルーティング |
runtime | ランタイム設定 |
secret | シークレット・証明書管理 |
ssl | TLS/SSL 処理 |
upstream | アップストリーム接続 |
wasm | WebAssembly フィルタ |
5.2 Istiod のログレベル管理
コントロールプレーン（istiod）のログレベルも動的に変更可能である。
# istiod のログレベルを確認（ControlZ エンドポイント経由）
kubectl -n istio-system port-forward deploy/istiod 9876:9876 &
curl -s http://localhost:9876/scopej | python3 -m json.tool
# istiod の Pod ログを確認
kubectl logs -n istio-system deploy/istiod -f
# 特定のコンポーネントのログをフィルタ
kubectl logs -n istio-system deploy/istiod -f | grep "ads"
kubectl logs -n istio-system deploy/istiod -f | grep "push"
# istiod のログレベルを変更（環境変数）
kubectl set env deploy/istiod -n istio-system \
PILOT_LOG_LEVEL=debug
5.3 bug-report -- バグレポートの生成
istioctl bug-report は Istio の障害調査に必要なすべての情報を自動収集し、圧縮ファイルとして出力する。
# 基本的なバグレポートの生成
istioctl bug-report
# 特定の名前空間のみ含める
istioctl bug-report --include "my-namespace"
# 複数の名前空間を含める
istioctl bug-report --include "namespace1,namespace2"
# 除外する名前空間を指定
istioctl bug-report --exclude "kube-system"
# 期間を指定して収集
istioctl bug-report --start-time "2024-01-01T00:00:00Z" --end-time "2024-01-02T00:00:00Z"
istioctl bug-report --duration 48h
# 出力ディレクトリを指定
istioctl bug-report --dir /tmp/istio-bug-report
# 全クラスタの情報を収集
istioctl bug-report --full-secrets
バグレポートに含まれる情報:
- Istio コントロールプレーンのログ
- すべてのプロキシの設定ダンプ
- Istio のカスタムリソース（VirtualService, DestinationRule, Gateway 等）
- Kubernetes クラスタ情報（ノード、サービス、エンドポイント等）
- イベントログ
- コンポーネントのメトリクス
- 証明書情報
5.4 Envoy アクセスログの活用
# メッシュ全体でアクセスログを有効化
istioctl install --set meshConfig.accessLogFile=/dev/stdout
# JSON 形式のアクセスログを有効化
istioctl install --set meshConfig.accessLogFile=/dev/stdout \
--set meshConfig.accessLogEncoding=JSON
# プロキシのアクセスログをリアルタイム監視
kubectl logs -f my-app-7b8d6c9f4-abc12 -c istio-proxy -n my-namespace
# アクセスログから特定の情報をフィルタ
kubectl logs my-app-7b8d6c9f4-abc12 -c istio-proxy -n my-namespace \
| grep "response_code\":503"
# 特定時間以降のログを表示
kubectl logs my-app-7b8d6c9f4-abc12 -c istio-proxy -n my-namespace --since=1h
6. ダッシュボード
istioctl dashboard コマンドは、Istio 関連の Web UI に対してポートフォワードを設定し、ブラウザで開く便利なコマンドである。
6.1 Kiali
Kiali は Istio のサービスメッシュ可視化ツールであり、トポロジーマップ、トラフィック監視、設定管理を提供する。
# Kiali ダッシュボードを開く
istioctl dashboard kiali
# 特定のポートを指定
istioctl dashboard kiali --port 20001
# バインドアドレスを指定（リモートアクセス時）
istioctl dashboard kiali --address 0.0.0.0
# ブラウザを自動で開かない
istioctl dashboard kiali --browser=false
# 名前空間を指定
istioctl dashboard kiali -n istio-system
Kiali で確認できること:
- サービストポロジーグラフ（リアルタイムのトラフィックフロー）
- サービスの健全性状態
- Istio 設定の検証
- リクエスト成功率・レイテンシ
- TCP/gRPC トラフィックの監視
- 分散トレーシングとの統合
6.2 Grafana
istioctl dashboard grafana
istioctl dashboard grafana --port 3000
Istio が提供する主要な Grafana ダッシュボード: Mesh Dashboard, Service Dashboard, Workload Dashboard, Performance Dashboard, Control Plane Dashboard
6.3 Jaeger
istioctl dashboard jaeger
istioctl dashboard jaeger --port 16686
6.4 Zipkin
istioctl dashboard zipkin
istioctl dashboard zipkin --port 9411
6.5 Prometheus
istioctl dashboard prometheus
istioctl dashboard prometheus --port 9090
Istio の主要な Prometheus メトリクス:
# リクエスト数（レート）
rate(istio_requests_total{destination_service="my-service.default.svc.cluster.local"}[5m])
# リクエスト成功率
sum(rate(istio_requests_total{destination_service="my-service.default.svc.cluster.local",response_code!~"5.*"}[5m])) /
sum(rate(istio_requests_total{destination_service="my-service.default.svc.cluster.local"}[5m]))
# P99 レイテンシ
histogram_quantile(0.99, sum(rate(istio_request_duration_milliseconds_bucket{destination_service="my-service.default.svc.cluster.local"}[5m])) by (le))
# TCP バイト送信
rate(istio_tcp_sent_bytes_total{destination_service="my-service.default.svc.cluster.local"}[5m])
6.6 Envoy Admin UI
istioctl dashboard envoy my-app-7b8d6c9f4-abc12.my-namespace
istioctl dashboard envoy deploy/my-app -n my-namespace
istioctl dashboard envoy my-app-7b8d6c9f4-abc12.my-namespace --port 15000
Envoy Admin UI で確認できること: /config_dump, /clusters, /listeners, /stats, /stats/prometheus, /server_info, /ready, /logging
6.7 ControlZ
istioctl dashboard controlz deploy/istiod -n istio-system
istioctl dashboard controlz deploy/istiod -n istio-system --port 9876
ControlZ で管理できること: ログスコープとログレベルの動的変更、メモリ使用量の監視、環境変数の確認、バージョン情報、シグナル送信
7. Waypoint プロキシ管理（Ambient モード）
Istio Ambient モードは、従来のサイドカーモデルに代わる新しいデータプレーンアーキテクチャである。L4 処理は ztunnel が担当し、L7 処理が必要な場合は Waypoint プロキシを使用する。
7.1 Ambient モードの有効化
istioctl install --set profile=ambient -y
kubectl label namespace default istio.io/dataplane-mode=ambient
kubectl label namespace default istio.io/dataplane-mode-
7.2 Waypoint プロキシの管理
istioctl waypoint apply -n my-namespace
istioctl waypoint apply -n my-namespace --for service
istioctl waypoint apply -n my-namespace --name my-waypoint
istioctl waypoint apply -n my-namespace --service-account my-sa
istioctl waypoint list -n my-namespace
istioctl waypoint list --all-namespaces
istioctl waypoint status -n my-namespace
istioctl waypoint delete -n my-namespace
istioctl waypoint delete -n my-namespace --name my-waypoint
istioctl waypoint delete --all -n my-namespace
7.3 Waypoint プロキシのトラブルシューティング
kubectl get pods -n my-namespace -l gateway.networking.k8s.io/gateway-name=waypoint
kubectl logs -n my-namespace -l gateway.networking.k8s.io/gateway-name=waypoint
istioctl proxy-config all waypoint-pod-name.my-namespace
istioctl ztunnel-config workloads | grep my-app
8. リモートシークレットとマルチクラスタ
8.1 リモートシークレットの作成
istioctl create-remote-secret \
--context=cluster2-context \
--name=cluster2 | kubectl apply -f - --context=cluster1-context
istioctl create-remote-secret \
--context=cluster2-context \
--name=cluster2 \
--service-account=istiod \
--namespace=istio-system
istioctl create-remote-secret \
--context=cluster2-context \
--name=cluster2 \
--server=https://cluster2-api-server:6443
istioctl create-remote-secret \
--context=cluster2-context \
--name=cluster2 > remote-secret-cluster2.yaml
8.2 マルチクラスタのインストールパターン
プライマリ-リモート構成
cat <<EOF | istioctl install -y --context=cluster1-context -f -
apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
spec:
values:
global:
meshID: mesh1
multiCluster:
clusterName: cluster1
network: network1
EOF
cat <<EOF | istioctl install -y --context=cluster2-context -f -
apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
spec:
profile: remote
values:
global:
meshID: mesh1
multiCluster:
clusterName: cluster2
network: network1
remotePilotAddress: <cluster1-istiod-address>
EOF
istioctl create-remote-secret \
--context=cluster2-context \
--name=cluster2 | kubectl apply -f - --context=cluster1-context
マルチプライマリ構成
# 双方向のリモートシークレットを作成
istioctl create-remote-secret \
--context=cluster1-context \
--name=cluster1 | kubectl apply -f - --context=cluster2-context
istioctl create-remote-secret \
--context=cluster2-context \
--name=cluster2 | kubectl apply -f - --context=cluster1-context
8.3 マルチクラスタの検証
istioctl proxy-status --context=cluster1-context
istioctl proxy-status --context=cluster2-context
kubectl get secrets -n istio-system -l istio/multiCluster=true --context=cluster1-context
istioctl proxy-config endpoints my-app-pod.my-namespace --context=cluster1-context \
| grep cluster2
9. オペレーターモード
istioctl operator init
istioctl operator init --watchedNamespaces=istio-system
istioctl operator init --revision=canary
istioctl operator init \
--watchedNamespaces=istio-system \
--operatorNamespace=istio-operator
kubectl get pods -n istio-operator
kubectl get iop -n istio-system
istioctl operator remove
istioctl operator remove --revision=canary
istioctl operator remove --force
注意: Operator を削除しても、既にインストールされた Istio コンポーネントは削除されない。Istio 自体の削除には istioctl uninstall を使用する。
10. Experimental コマンド
istioctl experimental（または istioctl x）は実験的な機能を提供するコマンドグループである。
# 設定の管理
istioctl x config list
istioctl x config validate -f my-config.yaml
# 認可ポリシーの検証
istioctl x authz check my-app-7b8d6c9f4-abc12.my-namespace
istioctl x authz check my-app-7b8d6c9f4-abc12.my-namespace \
--path /api/v1/data --method GET
# リビジョン管理
istioctl x revision list
istioctl x revision tag set prod --revision=1-22-0
istioctl x revision tag list
istioctl x revision tag remove prod
# アップグレード前の事前確認
istioctl x precheck
# VM ワークロードの管理
istioctl x workload entry configure \
--name my-vm --namespace vm-namespace --serviceAccount my-vm-sa
istioctl x workload group create \
--name my-vm-group --namespace vm-namespace --serviceAccount my-vm-sa --labels app=my-vm
# クリーンアップ
istioctl x uninstall --purge
istioctl x uninstall --revision canary
11. 共通フラグリファレンス
| フラグ | 短縮 | 説明 | デフォルト |
|---|---|---|---|
--context | Kubernetes コンテキスト名 | 現在のコンテキスト | |
--kubeconfig | -c | kubeconfig ファイルのパス | ~/.kube/config |
--namespace | -n | 対象の名前空間 | default |
--istioNamespace | -i | Istio コントロールプレーンの名前空間 | istio-system |
--revision | 対象のリビジョン | - | |
--output | -o | 出力形式（json, yaml, table） | table |
--log_output_level | istioctl 自体のログレベル | default:info |
# よく使う環境変数
export ISTIO_NAMESPACE=istio-system
export KUBECONFIG=/path/to/kubeconfig
export ISTIO_VERSION=1.22.0
export TARGET_ARCH=x86_64
12. 運用ワークフローまとめ
12.1 デプロイ前チェックリスト
istioctl verify-install
istioctl proxy-status
kubectl get pods -n istio-system
kubectl get namespace -L istio-injection
istioctl analyze my-virtualservice.yaml my-destinationrule.yaml
kubectl apply -f my-virtualservice.yaml --dry-run=server
istioctl kube-inject -f my-deployment.yaml | kubectl diff -f -
12.2 トラブルシューティングワークフロー
# ステップ 1: 全体の状態確認
istioctl proxy-status
istioctl analyze --all-namespaces
# ステップ 2: 対象 Pod の詳細確認
istioctl describe pod my-app-pod -n my-namespace
istioctl proxy-config routes my-app-pod.my-namespace
istioctl proxy-config clusters my-app-pod.my-namespace \
--fqdn "target-service.target-namespace.svc.cluster.local"
istioctl proxy-config endpoints my-app-pod.my-namespace \
--cluster "outbound|8080||target-service.target-namespace.svc.cluster.local"
# ステップ 3: リスナーの確認
istioctl proxy-config listeners my-app-pod.my-namespace
# ステップ 4: TLS/mTLS の確認
istioctl proxy-config secret my-app-pod.my-namespace
# ステップ 5: 詳細デバッグ
istioctl proxy-config log my-app-pod.my-namespace \
--level "connection:debug,router:debug,http:debug"
kubectl logs my-app-pod -c istio-proxy -n my-namespace --tail=100
# ステップ 6: デバッグ完了後
istioctl proxy-config log my-app-pod.my-namespace --level warning
12.3 カナリアアップグレードワークフロー
# 準備
istioctl version
istioctl x precheck
istioctl analyze --all-namespaces
# カナリーデプロイ
istioctl install --set profile=default --set revision=1-23-0
kubectl get pods -n istio-system -l istio.io/rev=1-23-0
istioctl proxy-status --revision=1-23-0
# テスト名前空間の切り替え
kubectl label namespace staging istio-injection- istio.io/rev=1-23-0 --overwrite
kubectl rollout restart deployment -n staging
istioctl proxy-status --revision=1-23-0
istioctl analyze -n staging
# 本番名前空間の切り替え
kubectl label namespace production istio-injection- istio.io/rev=1-23-0 --overwrite
kubectl rollout restart deployment -n production
istioctl proxy-status
# クリーンアップ
istioctl uninstall --revision=default -y
istioctl verify-install
istioctl proxy-status
istioctl analyze --all-namespaces
12.4 診断情報収集ワークフロー
# 基本情報の収集
istioctl version
kubectl get pods -n istio-system -o wide
istioctl proxy-status
istioctl analyze --all-namespaces 2>&1 | tee /tmp/analyze-output.txt
# 詳細情報の収集
PROBLEM_POD="my-app-7b8d6c9f4-abc12.my-namespace"
istioctl proxy-config all $PROBLEM_POD -o json > /tmp/proxy-config-all.json
istioctl proxy-config routes $PROBLEM_POD -o json > /tmp/proxy-config-routes.json
istioctl proxy-config clusters $PROBLEM_POD -o json > /tmp/proxy-config-clusters.json
istioctl proxy-config endpoints $PROBLEM_POD -o json > /tmp/proxy-config-endpoints.json
istioctl proxy-config listeners $PROBLEM_POD -o json > /tmp/proxy-config-listeners.json
istioctl proxy-config secret $PROBLEM_POD -o json > /tmp/proxy-config-secrets.json
istioctl describe pod $PROBLEM_POD > /tmp/describe-pod.txt
# バグレポートの生成
istioctl bug-report --include "${PROBLEM_POD#*.}" --dir /tmp/istio-bug-report
12.5 日常運用コマンドクイックリファレンス
# 状態確認
istioctl version # バージョン確認
istioctl proxy-status # プロキシ同期状態
istioctl analyze -A # 設定分析
kubectl get pods -n istio-system # コントロールプレーン Pod 一覧
# 設定確認
istioctl describe pod <pod>.<ns> # Pod の Istio 設定
istioctl proxy-config routes <pod>.<ns> # ルーティング設定
istioctl proxy-config clusters <pod>.<ns> # クラスタ設定
istioctl proxy-config endpoints <pod>.<ns> # エンドポイント
istioctl proxy-config listeners <pod>.<ns> # リスナー
istioctl proxy-config secret <pod>.<ns> # シークレット/証明書
# デバッグ
istioctl proxy-config log <pod>.<ns> --level debug # ログレベル変更
istioctl dashboard envoy <pod>.<ns> # Envoy Admin UI
istioctl dashboard kiali # Kiali ダッシュボード
# 管理
istioctl install --set profile=<profile> # インストール
istioctl verify-install # インストール検証
istioctl uninstall --purge # 完全アンインストール
istioctl kube-inject -f <file> # サイドカー注入
istioctl bug-report # バグレポート生成
おわりに
istioctl は Istio サービスメッシュの運用において不可欠なツールである。本ドキュメントで紹介したコマンドと手順を活用することで、Istio の導入からトラブルシューティング、アップグレードまで、サービスメッシュのライフサイクル全体を効果的に管理できる。
特に SRE エンジニアにとっては、以下の点が重要である:
istioctl analyzeを CI/CD パイプラインに組み込み、設定ミスを早期に検出するistioctl proxy-statusを定期的に確認し、プロキシの同期状態を監視するistioctl proxy-configを使いこなし、トラフィックフローの問題を迅速に診断するistioctl bug-reportで障害時の情報収集を自動化する- カナリアアップグレードのワークフローを確立し、安全なバージョンアップを実施する
Istio は継続的に進化しており、Ambient モードのような新しいアーキテクチャも登場している。最新の istioctl のリリースノートとドキュメントを確認し、新機能や改善点を継続的にキャッチアップすることを推奨する。