Istio サービスメッシュ 完全概要

1. Istio とは

Istio は、マイクロサービス間の通信を透過的に制御するオープンソースのサービスメッシュプラットフォーム。アプリケーションコードを変更することなく、トラフィック管理・セキュリティ・可観測性を提供する。

---

2. アーキテクチャ

Istio は データプレーン と コントロールプレーン の2層で構成される。

┌─────────────────────────────────────────────────────┐
│                  コントロールプレーン                     │
│  ┌───────────────────────────────────────────────┐  │
│  │                   istiod                       │  │
│  │  ┌─────────┐  ┌────────┐  ┌───────────────┐  │  │
│  │  │  Pilot   │  │ Citadel│  │    Galley     │  │  │
│  │  │(xDS配信) │  │(証明書) │  │(設定バリデーション)│  │  │
│  │  └─────────┘  └────────┘  └───────────────┘  │  │
│  └───────────────────────────────────────────────┘  │
└──────────────────────┬──────────────────────────────┘
                       │ xDS API (設定配信)
┌──────────────────────▼──────────────────────────────┐
│                   データプレーン                       │
│                                                      │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐       │
│  │  Pod A   │    │  Pod B   │    │  Pod C   │       │
│  │┌────────┐│    │┌────────┐│    │┌────────┐│       │
│  ││ App    ││    ││ App    ││    ││ App    ││       │
│  │└───┬────┘│    │└───┬────┘│    │└───┬────┘│       │
│  │┌───▼────┐│    │┌───▼────┐│    │┌───▼────┐│       │
│  ││ Envoy  ││◄──►││ Envoy  ││◄──►││ Envoy  ││       │
│  ││(Sidecar)││    ││(Sidecar)││    ││(Sidecar)││       │
│  │└────────┘│    │└────────┘│    │└────────┘│       │
│  └──────────┘    └──────────┘    └──────────┘       │
└──────────────────────────────────────────────────────┘

コンポーネント詳細

コンポーネント	役割
istiod	統合コントロールプレーン。Pilot/Citadel/Galley を単一バイナリに統合
Pilot	サービスディスカバリ、Envoy への xDS 設定配信
Citadel	mTLS 証明書の発行・ローテーション（SPIFFE ID ベース）
Galley	設定のバリデーションと変換
Envoy Proxy	各 Pod にサイドカーとして注入。全トラフィックを仲介

Sidecar インジェクション

Namespace にラベルを付与するだけで、Pod 作成時に自動で Envoy サイドカーが注入される。

apiVersion: v1
kind: Namespace
metadata:
  name: my-app
  labels:
    istio-injection: enabled   # この1行で自動注入が有効化

Ambient モード（v1.22+）では、サイドカーなしで ztunnel + waypoint proxy による L4/L7 制御も可能。

---

3. トラフィック管理

Istio のトラフィック管理は主に VirtualService と DestinationRule の2つの CRD で制御する。

3.1 VirtualService — ルーティングルール

apiVersion: networking.istio.io/v1
kind: VirtualService
metadata:
  name: reviews-route
spec:
  hosts:
    - reviews                    # 対象サービス
  http:
    # カナリアリリース: 90% を v1、10% を v2 に
    - route:
        - destination:
            host: reviews
            subset: v1
          weight: 90
        - destination:
            host: reviews
            subset: v2
          weight: 10
    # ヘッダベースルーティング
    - match:
        - headers:
            x-user-type:
              exact: beta-tester
      route:
        - destination:
            host: reviews
            subset: v2

3.2 DestinationRule — 接続先ポリシー

apiVersion: networking.istio.io/v1
kind: DestinationRule
metadata:
  name: reviews-destination
spec:
  host: reviews
  trafficPolicy:
    connectionPool:              # コネクションプール制御
      tcp:
        maxConnections: 100
      http:
        h2UpgradePolicy: DEFAULT
        maxRequestsPerConnection: 10
    outlierDetection:            # サーキットブレーカー
      consecutive5xxErrors: 3
      interval: 30s
      baseEjectionTime: 60s
      maxEjectionPercent: 50
  subsets:                       # バージョン別サブセット定義
    - name: v1
      labels:
        version: v1
    - name: v2
      labels:
        version: v2

3.3 Gateway — 外部トラフィックの入口

apiVersion: networking.istio.io/v1
kind: Gateway
metadata:
  name: my-gateway
spec:
  selector:
    istio: ingressgateway
  servers:
    - port:
        number: 443
        name: https
        protocol: HTTPS
      tls:
        mode: SIMPLE
        credentialName: my-tls-cert   # K8s Secret 参照
      hosts:
        - "api.example.com"

3.4 その他のトラフィック機能

• リトライ: retries: { attempts: 3, perTryTimeout: 2s, retryOn: "5xx" }
• タイムアウト: timeout: 10s
• フォールトインジェクション: テスト用に遅延やエラーを意図的に注入
• ミラーリング: 本番トラフィックのコピーをテスト環境に送信

# フォールトインジェクション例
http:
  - fault:
      delay:
        percentage:
          value: 10          # 10% のリクエストに
        fixedDelay: 5s       # 5秒の遅延を注入
      abort:
        percentage:
          value: 5           # 5% のリクエストに
        httpStatus: 503      # 503 エラーを注入
    route:
      - destination:
          host: ratings

---

4. セキュリティ

Istio はゼロトラスト・ネットワーキングを実現する3つの柱を提供する。

4.1 mTLS（相互TLS認証）

サービス間通信を自動的に暗号化。証明書の発行・ローテーションは Citadel が自動管理する。

apiVersion: security.istio.io/v1
kind: PeerAuthentication
metadata:
  name: default
  namespace: istio-system       # メッシュ全体に適用
spec:
  mtls:
    mode: STRICT                # STRICT | PERMISSIVE | DISABLE
    # STRICT: mTLS 必須（平文拒否）
    # PERMISSIVE: mTLS + 平文の両方を受け入れ（移行期間用）

SPIFFE ID: 各ワークロードには spiffe://<trust-domain>/ns/<namespace>/sa/<service-account> 形式の ID が自動付与される。

4.2 AuthorizationPolicy — アクセス制御

apiVersion: security.istio.io/v1
kind: AuthorizationPolicy
metadata:
  name: allow-frontend-to-backend
  namespace: backend
spec:
  action: ALLOW
  rules:
    - from:
        - source:
            principals:
              - "cluster.local/ns/frontend/sa/frontend-sa"
      to:
        - operation:
            methods: ["GET", "POST"]
            paths: ["/api/v1/*"]
      when:
        - key: request.headers[x-api-key]
          notValues: [""]

4.3 RequestAuthentication — JWT 検証

apiVersion: security.istio.io/v1
kind: RequestAuthentication
metadata:
  name: jwt-auth
spec:
  jwtRules:
    - issuer: "https://accounts.example.com"
      jwksUri: "https://accounts.example.com/.well-known/jwks.json"
      forwardOriginalToken: true
      outputPayloadToHeader: x-jwt-payload

セキュリティの全体像

外部クライアント
     │
     ▼ (TLS終端)
┌─────────┐   mTLS    ┌─────────┐   mTLS    ┌─────────┐
│ Gateway │◄─────────►│Frontend │◄─────────►│ Backend │
│(JWT検証) │           │         │           │(AuthZ)  │
└─────────┘           └─────────┘           └─────────┘
  RequestAuth          PeerAuth              AuthorizationPolicy

---

5. 可観測性（Observability）

Istio は Envoy プロキシを通じて、コード変更なしに3種のテレメトリを自動収集する。

5.1 メトリクス

Envoy が自動生成する主要メトリクス:

メトリクス	内容
istio_requests_total	リクエスト数（ソース、宛先、レスポンスコード別）
istio_request_duration_milliseconds	レイテンシ分布
istio_tcp_sent_bytes_total	TCP 送信バイト数
istio_tcp_connections_opened_total	TCP 接続数

Prometheus + Grafana で可視化するのが一般的。

5.2 分散トレーシング

apiVersion: telemetry.istio.io/v1
kind: Telemetry
metadata:
  name: tracing-config
  namespace: istio-system
spec:
  tracing:
    - providers:
        - name: zipkin
      randomSamplingPercentage: 1.0   # サンプリング率 1%

アプリケーションは x-request-id, x-b3-traceid 等のヘッダを伝播するだけでよい。Jaeger や Zipkin で可視化する。

5.3 アクセスログ

apiVersion: telemetry.istio.io/v1
kind: Telemetry
metadata:
  name: access-log
spec:
  accessLogging:
    - providers:
        - name: envoy
      filter:
        expression: "response.code >= 400"   # エラーのみ記録

5.4 Kiali — サービスメッシュ可視化

Kiali はメッシュ内のサービス間トポロジーをリアルタイムで可視化するダッシュボード。トラフィック量・エラー率・レイテンシが一目で分かる。

---

6. 高度な機能

6.1 ServiceEntry — 外部サービスの登録

apiVersion: networking.istio.io/v1
kind: ServiceEntry
metadata:
  name: external-api
spec:
  hosts:
    - api.external.com
  location: MESH_EXTERNAL
  ports:
    - number: 443
      name: https
      protocol: TLS
  resolution: DNS

メッシュ外のサービスにも Istio のトラフィックポリシー（リトライ、タイムアウト等）を適用可能。

6.2 EnvoyFilter — 低レベルカスタマイズ

apiVersion: networking.istio.io/v1alpha3
kind: EnvoyFilter
metadata:
  name: rate-limit-filter
spec:
  workloadSelector:
    labels:
      app: my-api
  configPatches:
    - applyTo: HTTP_FILTER
      match:
        context: SIDECAR_INBOUND
        listener:
          filterChain:
            filter:
              name: envoy.filters.network.http_connection_manager
      patch:
        operation: INSERT_BEFORE
        value:
          name: envoy.filters.http.local_ratelimit
          typed_config:
            "@type": type.googleapis.com/udpa.type.v1.TypedStruct
            type_url: type.googleapis.com/envoy.extensions.filters.http.local_ratelimit.v3.LocalRateLimit
            value:
              stat_prefix: http_local_rate_limiter
              token_bucket:
                max_tokens: 100
                tokens_per_fill: 100
                fill_interval: 60s

6.3 Sidecar リソース — プロキシスコープの制限

apiVersion: networking.istio.io/v1
kind: Sidecar
metadata:
  name: default
  namespace: my-namespace
spec:
  egress:
    - hosts:
        - "./*"                      # 同一 Namespace
        - "istio-system/*"           # istio-system
        - "database-ns/postgres.database-ns.svc.cluster.local"

不要なサービス情報の配信を抑制し、Envoy のメモリ使用量と設定収束時間を大幅に削減する。大規模クラスタでは必須。

6.4 WasmPlugin — 拡張ロジックの注入

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: custom-auth
spec:
  selector:
    matchLabels:
      app: my-api
  url: oci://registry.example.com/wasm/custom-auth:v1
  phase: AUTHN

---

7. マルチクラスタ・マルチネットワーク

Istio は複数のクラスタにまたがるメッシュをサポートする。

モデル	説明
Primary-Remote	1つの Primary が istiod をホスト、Remote は接続のみ
Multi-Primary	各クラスタに istiod を配置、設定を同期
単一ネットワーク	Pod 間が直接通信可能
マルチネットワーク	East-West Gateway を経由してクラスタ間を接続

Cluster A (Primary)          Cluster B (Remote)
┌─────────────────┐         ┌─────────────────┐
│  istiod          │◄───────►│  (istiod なし)    │
│  App Pods        │         │  App Pods        │
│  E-W Gateway ────┼─────────┼── E-W Gateway   │
└─────────────────┘         └─────────────────┘

---

8. 主要 CRD 一覧

CRD	API Group	用途
VirtualService	networking	ルーティングルール
DestinationRule	networking	接続ポリシー・サブセット
Gateway	networking	外部トラフィック入口
ServiceEntry	networking	外部サービス登録
Sidecar	networking	プロキシスコープ制限
EnvoyFilter	networking	Envoy 低レベル設定
PeerAuthentication	security	mTLS ポリシー
RequestAuthentication	security	JWT 検証
AuthorizationPolicy	security	アクセス制御
Telemetry	telemetry	テレメトリ設定
WasmPlugin	extensions	Wasm 拡張

---

9. 運用のベストプラクティス

1. 段階的導入: PERMISSIVE mTLS から始め、安定したら STRICT に移行
2. Sidecar リソースの活用: 大規模環境では必須。メモリと CPU を大幅に節約
3. リソース制限の設定: Envoy サイドカーに適切な resources.requests/limits を設定
4. カナリアアップグレード: Istio のバージョンアップは Revision（istio.io/rev ラベル）で段階的に実施
5. istioctl analyze: デプロイ前に istioctl analyze で設定の問題を検出
6. Ambient モードの検討: サイドカーのオーバーヘッドが問題なら v1.22+ の Ambient モードを検討

# 設定の検証
istioctl analyze -n my-namespace

# プロキシ状態の確認
istioctl proxy-status

# 特定 Pod の Envoy 設定ダンプ
istioctl proxy-config routes deploy/my-app -n my-namespace

---

以上が Istio の主要機能とアーキテクチャの全容です。トラフィック管理・セキュリティ・可観測性の3本柱を、Envoy サイドカーとコントロールプレーン(istiod)の協調により、アプリケーション非侵入で実現するのが Istio の設計思想です。

---

ServiceEntry が必要な理由

根本的な理由: Istio はデフォルトで全トラフィックを管理下に置く

Istio メッシュ内の Pod から出るトラフィックは、すべて Envoy サイドカーを経由する。Envoy はコントロールプレーン（istiod）から配信された既知のサービス一覧に基づいてルーティングを行う。

ここで問題になるのが、メッシュ外の外部サービス（api.stripe.com, s3.amazonaws.com 等）の扱いです。

メッシュ設定による挙動の違い

meshConfig.outboundTrafficPolicy.mode	未登録の外部宛通信	リスク
ALLOW_ANY（デフォルト）	Envoy がパススルーで通過させる	Istio の機能（リトライ、タイムアウト、mTLS、可観測性）が一切適用されない
REGISTRY_ONLY	ブロックされる（502 エラー）	ServiceEntry で明示登録しないと通信不可

つまり:

• ALLOW_ANY でも外部通信は「できる」が、Istio の恩恵がゼロのブラックボックスになる
• REGISTRY_ONLY では ServiceEntry なしでは外部通信自体ができない

---

ServiceEntry で得られる具体的な価値

1. トラフィック制御が適用される

# 外部APIを登録
apiVersion: networking.istio.io/v1
kind: ServiceEntry
metadata:
  name: stripe-api
spec:
  hosts:
    - api.stripe.com
  location: MESH_EXTERNAL
  ports:
    - number: 443
      name: https
      protocol: TLS
  resolution: DNS
---
# 登録した外部APIにリトライ・タイムアウトを適用
apiVersion: networking.istio.io/v1
kind: DestinationRule
metadata:
  name: stripe-api-dr
spec:
  host: api.stripe.com
  trafficPolicy:
    connectionPool:
      tcp:
        maxConnections: 50
    outlierDetection:
      consecutive5xxErrors: 3
      interval: 30s
      baseEjectionTime: 60s

ServiceEntry なしでは DestinationRule を書いても適用する対象がない。

2. 可観測性が得られる

ServiceEntry で登録すると、外部通信にも Envoy が正しいメトリクスを生成する。

• istio_requests_total{destination_service="api.stripe.com"} — リクエスト数
• istio_request_duration_milliseconds — レイテンシ
• 分散トレーシングの Span にも外部呼び出しが可視化される

未登録の場合、宛先は PassthroughCluster として集約され、どの外部サービスへの通信かの区別がつかない。

3. セキュリティ境界の明示

# REGISTRY_ONLY モードで厳格に制御
# meshConfig:
#   outboundTrafficPolicy:
#     mode: REGISTRY_ONLY

# 許可する外部通信を明示的に宣言
apiVersion: networking.istio.io/v1
kind: ServiceEntry
metadata:
  name: allowed-external
spec:
  hosts:
    - api.stripe.com
    - s3.ap-northeast-1.amazonaws.com
  location: MESH_EXTERNAL
  ports:
    - number: 443
      name: https
      protocol: TLS
  resolution: DNS

これにより「メッシュ内のサービスがどの外部サービスと通信するか」がマニフェストとして宣言され、意図しない外部通信（データ流出、マルウェアの C2 通信等）をブロックできる。

4. Egress の一元管理

複数サービスが同じ外部 API を使う場合、ServiceEntry で一箇所に定義することで、タイムアウト・サーキットブレーカー・TLS 設定を統一管理できる。

---

まとめ

ServiceEntry の本質は「外部エンドポイントを Istio のサービスレジストリに登録し、メッシュ内サービスと同等の制御・観測対象にすること」です。

観点	ServiceEntry なし	ServiceEntry あり
通信可否	ALLOW_ANY なら可 / REGISTRY_ONLY なら不可	常に可
リトライ・タイムアウト	適用不可	DestinationRule で制御可能
サーキットブレーカー	適用不可	適用可能
メトリクス	PassthroughCluster に集約	宛先ごとに分離して計測
トレーシング	外部呼び出しが不明瞭	Span として可視化
アクセス制御	全許可 or 全拒否	宛先単位で許可/拒否
運用管理	暗黙的（誰が何に繋いでいるか不明）	宣言的（Git 管理可能）

---

Istio Waypoint Proxy 詳細ガイド

1. Waypoint とは

Waypoint Proxy は、Istio の Ambient モード（サイドカーレスメッシュ）における L7 処理専用のプロキシ。従来のサイドカーモデルでは各 Pod に Envoy が注入されていたが、Ambient モードではレイヤーを分離する。

従来のサイドカーモデル:
  Pod = [App] + [Envoy Sidecar (L4+L7)]

Ambient モード:
  L4 処理 → ztunnel（ノード共有、DaemonSet）
  L7 処理 → Waypoint Proxy（Namespace/SA 単位でデプロイ）

---

2. Ambient モードのアーキテクチャと Waypoint の位置づけ

                        コントロールプレーン
                        ┌──────────┐
                        │  istiod   │
                        └────┬─────┘
                             │ xDS
              ┌──────────────┼──────────────┐
              ▼              ▼              ▼
┌─────────────────┐  ┌────────────┐  ┌─────────────────┐
│   Node A        │  │  Waypoint  │  │   Node B        │
│ ┌─────────────┐ │  │   Proxy    │  │ ┌─────────────┐ │
│ │  ztunnel    │ │  │  (Envoy)   │  │ │  ztunnel    │ │
│ │  (L4/mTLS)  │ │  │  (L7処理)   │  │ │  (L4/mTLS)  │ │
│ └──────┬──────┘ │  └──────┬─────┘  │ └──────┬──────┘ │
│   ┌────▼────┐   │         │        │   ┌────▼────┐   │
│   │  Pod A  │   │         │        │   │  Pod B  │   │
│   │ (App)   │───┼─────────┘        │   │ (App)   │   │
│   └─────────┘   │  L7が必要な場合     │   └─────────┘   │
│                 │  経由する          │                 │
└─────────────────┘                  └─────────────────┘

2層アーキテクチャ

レイヤー	コンポーネント	処理内容	デプロイ形態
L4（Secure Overlay）	ztunnel	mTLS 暗号化、L4 認可、テレメトリ	各ノードに DaemonSet
L7（Policy Processing）	Waypoint Proxy	HTTP ルーティング、L7 認可、リトライ、ヘッダ操作、JWT 検証等	Namespace/SA 単位で Deployment

重要: L7 ポリシーが不要なワークロード間通信は ztunnel だけで完結し、Waypoint を経由しない。これにより不要なオーバーヘッドを排除できる。

---

3. Waypoint のデプロイモデル

3.1 スコープの種類

Waypoint は どのトラフィックを処理するか のスコープを持つ。

スコープ	対象	ユースケース
Namespace	Namespace 内の全サービス宛トラフィック	Namespace 全体に統一 L7 ポリシーを適用
ServiceAccount	特定 SA のワークロード宛トラフィック	ワークロード単位できめ細かく制御
Service	特定 Service 宛トラフィック	サービス単位で L7 処理を適用

3.2 Namespace スコープの Waypoint

# Namespace に Waypoint をデプロイ
istioctl waypoint apply -n my-namespace

# Namespace に自動的にラベルが付与される
# istio.io/use-waypoint: waypoint

# 等価な手動設定
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: waypoint
  namespace: my-namespace
  labels:
    istio.io/waypoint-for: service   # スコープ
spec:
  gatewayClassName: istio-waypoint
  listeners:
    - name: mesh
      port: 15008
      protocol: HBONE              # HTTP-Based Overlay Network Encapsulation

Namespace に紐付けるラベル:

apiVersion: v1
kind: Namespace
metadata:
  name: my-namespace
  labels:
    istio.io/use-waypoint: waypoint    # Waypoint Gateway 名を指定

3.3 ServiceAccount スコープの Waypoint

istioctl waypoint apply -n my-namespace \
  --name reviews-waypoint \
  --for workload \
  --service-account reviews-sa

# ServiceAccount にラベルを付与
apiVersion: v1
kind: ServiceAccount
metadata:
  name: reviews-sa
  namespace: my-namespace
  labels:
    istio.io/use-waypoint: reviews-waypoint

3.4 Service スコープの Waypoint

istioctl waypoint apply -n my-namespace \
  --name my-svc-waypoint \
  --for service

# Service にラベルを付与して紐付け
apiVersion: v1
kind: Service
metadata:
  name: reviews
  namespace: my-namespace
  labels:
    istio.io/use-waypoint: my-svc-waypoint

---

4. トラフィックフロー詳細

4.1 L4 のみのフロー（Waypoint なし）

Pod A → ztunnel(A) ──HBONE/mTLS──→ ztunnel(B) → Pod B

L4 AuthorizationPolicy のみが適用される場合、Waypoint は介在しない。

4.2 L7 が必要なフロー（Waypoint あり）

Pod A → ztunnel(A) ──HBONE──→ Waypoint Proxy ──HBONE──→ ztunnel(B) → Pod B
                                    │
                               L7ポリシー適用:
                               ・HTTPルーティング
                               ・L7 AuthZ
                               ・リトライ/タイムアウト
                               ・ヘッダ操作
                               ・JWT検証
                               ・レートリミット

4.3 HBONE プロトコル

Waypoint と ztunnel 間は HBONE (HTTP-Based Overlay Network Encapsulation) で通信する。

• HTTP/2 CONNECT over mTLS
• ポート 15008 を使用
• 全トラフィックがトンネル内で暗号化

---

5. Waypoint で利用可能な L7 ポリシー

5.1 L7 AuthorizationPolicy

apiVersion: security.istio.io/v1
kind: AuthorizationPolicy
metadata:
  name: reviews-l7-policy
  namespace: my-namespace
spec:
  targetRefs:                        # Waypoint 経由で適用
    - kind: Service
      group: ""
      name: reviews
  action: ALLOW
  rules:
    - from:
        - source:
            principals:
              - "cluster.local/ns/frontend/sa/frontend-sa"
      to:
        - operation:
            methods: ["GET"]           # L7 フィールド → Waypoint が必要
            paths: ["/api/v1/reviews/*"]
      when:
        - key: request.headers[x-request-id]
          notValues: [""]

L4 vs L7 の判定基準:

フィールド	レイヤー	Waypoint 要否
source.principals, source.namespaces, source.ipBlocks	L4	不要（ztunnel で処理）
operation.methods, operation.paths, request.headers	L7	必要

5.2 VirtualService（HTTPルーティング）

apiVersion: networking.istio.io/v1
kind: VirtualService
metadata:
  name: reviews-routing
  namespace: my-namespace
spec:
  hosts:
    - reviews
  http:
    - match:
        - headers:
            x-user-type:
              exact: canary
      route:
        - destination:
            host: reviews
            subset: v2
    - route:
        - destination:
            host: reviews
            subset: v1
          weight: 90
        - destination:
            host: reviews
            subset: v2
          weight: 10
      retries:
        attempts: 3
        perTryTimeout: 2s
      timeout: 10s

5.3 RequestAuthentication（JWT）

apiVersion: security.istio.io/v1
kind: RequestAuthentication
metadata:
  name: jwt-auth
  namespace: my-namespace
spec:
  targetRefs:
    - kind: Service
      group: ""
      name: reviews
  jwtRules:
    - issuer: "https://auth.example.com"
      jwksUri: "https://auth.example.com/.well-known/jwks.json"

5.4 Telemetry（L7 メトリクス・トレーシング）

apiVersion: telemetry.istio.io/v1
kind: Telemetry
metadata:
  name: waypoint-telemetry
  namespace: my-namespace
spec:
  targetRefs:
    - kind: Gateway
      group: gateway.networking.k8s.io
      name: waypoint
  metrics:
    - providers:
        - name: prometheus
  tracing:
    - providers:
        - name: zipkin
      randomSamplingPercentage: 5.0
  accessLogging:
    - providers:
        - name: envoy

---

6. Waypoint の運用管理

6.1 基本操作

# 一覧表示
istioctl waypoint list -n my-namespace
istioctl waypoint list --all-namespaces

# ステータス確認
istioctl waypoint status -n my-namespace

# 削除
istioctl waypoint delete -n my-namespace --name waypoint
istioctl waypoint delete --all -n my-namespace

6.2 スケーリングとリソース設定

Waypoint は通常の Kubernetes Deployment として管理されるため、標準的な方法でスケール・リソース制御が可能。

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: waypoint
  namespace: my-namespace
  annotations:
    # レプリカ数
    istio.io/waypoint-min-replicas: "2"
    istio.io/waypoint-max-replicas: "10"
spec:
  gatewayClassName: istio-waypoint
  listeners:
    - name: mesh
      port: 15008
      protocol: HBONE
---
# Waypoint Deployment に対して直接 HPA を設定することも可能
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: waypoint-hpa
  namespace: my-namespace
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: waypoint
  minReplicas: 2
  maxReplicas: 10
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70

6.3 リソースリミットの設定

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: waypoint
  namespace: my-namespace
  annotations:
    proxy.istio.io/resources: '{"requests":{"cpu":"200m","memory":"256Mi"},"limits":{"cpu":"1","memory":"1Gi"}}'
spec:
  gatewayClassName: istio-waypoint
  listeners:
    - name: mesh
      port: 15008
      protocol: HBONE

6.4 デバッグ

# Waypoint の Envoy 設定を確認
istioctl pc routes deploy/waypoint -n my-namespace
istioctl pc clusters deploy/waypoint -n my-namespace
istioctl pc listeners deploy/waypoint -n my-namespace

# ログレベル変更
istioctl pc log deploy/waypoint -n my-namespace --level debug

# Waypoint Pod のログ確認
kubectl logs deploy/waypoint -n my-namespace

# ztunnel → Waypoint の接続確認
istioctl ztunnel-config workloads | grep waypoint

---

7. サイドカーモデルとの比較

観点	サイドカーモデル	Ambient + Waypoint
リソース効率	Pod 毎に Envoy（メモリ大）	L4 はノード共有、L7 は必要な場所のみ
起動遅延	サイドカー初期化分の遅延あり	アプリ起動に影響なし
L7 処理の粒度	全 Pod で L7 処理可能	Waypoint 配置箇所のみ
スケーリング	アプリ Pod に連動	Waypoint を独立スケール可能
障害影響	Pod 内で閉じる	Waypoint 障害が複数 Pod に影響
設定の複雑さ	ラベル1つで有効化	Waypoint のライフサイクル管理が必要
アップグレード	全 Pod 再起動が必要	Waypoint のみ再起動

---

8. 設計パターンとベストプラクティス

8.1 段階的導入パターン

Step 1: Namespace を Ambient メッシュに参加（L4 のみ）
  kubectl label ns my-app istio.io/dataplane-mode=ambient

Step 2: L4 AuthorizationPolicy で基本的なアクセス制御

Step 3: L7 が必要なサービスにのみ Waypoint を追加
  istioctl waypoint apply -n my-app

Step 4: L7 ポリシー（HTTP ルーティング、JWT 等）を適用

8.2 Waypoint 配置の判断基準

Waypoint が必要なケース:

• HTTP ヘッダベースのルーティング（カナリア、A/B テスト）
• HTTP メソッド・パスベースの認可
• JWT トークン検証
• リトライ・タイムアウト・サーキットブレーカー
• L7 メトリクス（リクエスト/レスポンスの詳細）
• フォールトインジェクション
• レートリミット

Waypoint が不要なケース:

• 単純な mTLS 暗号化のみ
• ソース IP / Namespace / ServiceAccount ベースの L4 認可
• TCP レベルのテレメトリで十分

8.3 複数 Waypoint の分離パターン

# 高トラフィックサービス用（リソース多め）
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: high-traffic-waypoint
  namespace: my-namespace
  annotations:
    proxy.istio.io/resources: '{"requests":{"cpu":"500m","memory":"512Mi"}}'
spec:
  gatewayClassName: istio-waypoint
  listeners:
    - name: mesh
      port: 15008
      protocol: HBONE
---
# 低トラフィックサービス用（リソース少なめ）
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: low-traffic-waypoint
  namespace: my-namespace
  annotations:
    proxy.istio.io/resources: '{"requests":{"cpu":"100m","memory":"128Mi"}}'
spec:
  gatewayClassName: istio-waypoint
  listeners:
    - name: mesh
      port: 15008
      protocol: HBONE

# サービスごとに異なる Waypoint を紐付け
apiVersion: v1
kind: Service
metadata:
  name: api-gateway
  labels:
    istio.io/use-waypoint: high-traffic-waypoint
---
apiVersion: v1
kind: Service
metadata:
  name: internal-tool
  labels:
    istio.io/use-waypoint: low-traffic-waypoint

8.4 可用性の確保

• Waypoint は最低 2 レプリカ で運用（単一障害点の回避）
• PodDisruptionBudget を設定してローリングアップデート時の可用性を維持
• Pod Anti-Affinity で Waypoint Pod をノード分散配置

apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: waypoint-pdb
  namespace: my-namespace
spec:
  minAvailable: 1
  selector:
    matchLabels:
      gateway.networking.k8s.io/gateway-name: waypoint

---

9. 既知の制約・注意点

1. Gateway API が前提: Waypoint は Kubernetes Gateway API (gateway.networking.k8s.io) の CRD が必要。事前に Gateway API をインストールすること
2. HBONE 対応: Waypoint は HBONE プロトコルでのみ通信する。メッシュ外からの直接アクセスは不可
3. ステートレス: Waypoint 自体はステートレスなので、スケールイン/アウトは安全
4. サイドカーとの併用: 同一メッシュ内でサイドカーモードと Ambient モードの Namespace を混在可能。相互通信も可能
5. パフォーマンス: Waypoint 経由は追加ホップとなるため、サイドカーモデルと比較して若干のレイテンシ増加がある（ただし全体のリソース効率は向上）