Virtual Service

トラフィックルーティングに影響を与える設定。

宛先は、ルーティングルールを処理した後にリクエスト/接続が送信されるネットワークアドレス可能なサービスを示します。destination.hostは、サービスレジストリ内のサービスを明確に参照する必要があります。Istioのサービスレジストリは、プラットフォームのサービスレジストリ（例：Kubernetesサービス、Consulサービス）にあるすべてのサービスと、ServiceEntryリソースを介して宣言されたサービスで構成されます。

Kubernetesユーザー向け注記：短縮名（例：「reviews.default.svc.cluster.local」の代わりに「reviews」）を使用する場合、Istioはサービスではなく、ルールの名前空間に基づいて短縮名を解釈します。「default」名前空間にホスト「reviews」を含むルールは、reviewsサービスに関連付けられている実際の名前空間とは関係なく、「reviews.default.svc.cluster.local」として解釈されます。潜在的な設定ミスを回避するために、短縮名よりも常に完全修飾ドメイン名を使用することをお勧めします。

次のKubernetesの例では、すべてのトラフィックをデフォルトでラベル「version: v1」（つまり、サブセットv1）のreviewsサービスのポッドにルーティングし、一部をサブセットv2にルーティングします（Kubernetes環境）。

apiVersion: networking.istio.io/v1
kind: VirtualService
metadata:
  name: reviews-route
  namespace: foo
spec:
  hosts:
  - reviews # interpreted as reviews.foo.svc.cluster.local
  http:
  - match:
    - uri:
        prefix: "/wpcatalog"
    - uri:
        prefix: "/consumercatalog"
    rewrite:
      uri: "/newcatalog"
    route:
    - destination:
        host: reviews # interpreted as reviews.foo.svc.cluster.local
        subset: v2
  - route:
    - destination:
        host: reviews # interpreted as reviews.foo.svc.cluster.local
        subset: v1

および関連付けられたDestinationRule

apiVersion: networking.istio.io/v1
kind: DestinationRule
metadata:
  name: reviews-destination
  namespace: foo
spec:
  host: reviews # interpreted as reviews.foo.svc.cluster.local
  subsets:
  - name: v1
    labels:
      version: v1
  - name: v2
    labels:
      version: v2

次のVirtualServiceは、Kubernetesのproductpage.prod.svc.cluster.localサービスへのすべての呼び出しのタイムアウトを5秒に設定します。このルールにはサブセットが定義されていないことに注意してください。Istioは、サービスレジストリからproductpage.prod.svc.cluster.localサービスのすべてのインスタンスを取得し、サイドカーのロードバランシングプールに格納します。また、このルールはistio-system名前空間で設定されていますが、productpageサービスの完全修飾ドメイン名productpage.prod.svc.cluster.localを使用していることに注意してください。したがって、ルールの名前空間はproductpageサービスの名前解決に影響しません。

apiVersion: networking.istio.io/v1
kind: VirtualService
metadata:
  name: my-productpage-rule
  namespace: istio-system
spec:
  hosts:
  - productpage.prod.svc.cluster.local # ignores rule namespace
  http:
  - timeout: 5s
    route:
    - destination:
        host: productpage.prod.svc.cluster.local

メッシュ外のサービスへのバインドトラフィックのルーティングを制御するには、最初にServiceEntryリソースを使用して、外部サービスをIstioの内部サービスレジストリに追加する必要があります。その後、VirtualServiceを定義して、これらの外部サービスにバインドされたトラフィックを制御できます。たとえば、次のルールはwikipedia.orgのサービスを定義し、HTTPリクエストのタイムアウトを5秒に設定します。

apiVersion: networking.istio.io/v1
kind: ServiceEntry
metadata:
  name: external-svc-wikipedia
spec:
  hosts:
  - wikipedia.org
  location: MESH_EXTERNAL
  ports:
  - number: 80
    name: example-http
    protocol: HTTP
  resolution: DNS
---
apiVersion: networking.istio.io/v1
kind: VirtualService
metadata:
  name: my-wiki-rule
spec:
  hosts:
  - wikipedia.org
  http:
  - timeout: 5s
    route:
    - destination:
        host: wikipedia.org

HTTP/1.1、HTTP2、およびgRPCトラフィックのマッチ条件とルーティングアクションを記述します。使用方法の例については、VirtualServiceを参照してください。

attempts: 2
retryOn: "connect-failure,refused-stream,unavailable,cancelled,503"

委任VirtualServiceを記述します。以下のルーティングルールは、productpageという名前の委任VirtualServiceによってトラフィックを/productpageに転送し、reviewsという名前の委任VirtualServiceによってトラフィックを/reviewsに転送します。

apiVersion: networking.istio.io/v1
kind: VirtualService
metadata:
  name: bookinfo
spec:
  hosts:
  - "bookinfo.com"
  gateways:
  - mygateway
  http:
  - match:
    - uri:
        prefix: "/productpage"
    delegate:
       name: productpage
       namespace: nsA
  - match:
    - uri:
        prefix: "/reviews"
    delegate:
        name: reviews
        namespace: nsB

apiVersion: networking.istio.io/v1
kind: VirtualService
metadata:
  name: productpage
  namespace: nsA
spec:
  http:
  - match:
     - uri:
        prefix: "/productpage/v1/"
    route:
    - destination:
        host: productpage-v1.nsA.svc.cluster.local
  - route:
    - destination:
        host: productpage.nsA.svc.cluster.local

apiVersion: networking.istio.io/v1
kind: VirtualService
metadata:
  name: reviews
  namespace: nsB
spec:
  http:
  - route:
    - destination:
        host: reviews.nsB.svc.cluster.local

Envoyがリクエストを宛先サービスに転送する際、または宛先サービスから応答を返す際に、メッセージヘッダーを操作できます。ヘッダー操作ルールは、特定のルート宛先またはすべての宛先に指定できます。次のVirtualServiceは、すべてのreviewsサービス宛先にルーティングされるリクエストに、値trueを持つtestヘッダーを追加します。また、reviewsサービスのv1サブセット（バージョン）からの応答からのみ、foo応答ヘッダーを削除します。

apiVersion: networking.istio.io/v1
kind: VirtualService
metadata:
  name: reviews-route
spec:
  hosts:
  - reviews.prod.svc.cluster.local
  http:
  - headers:
      request:
        set:
          test: "true"
    route:
    - destination:
        host: reviews.prod.svc.cluster.local
        subset: v2
      weight: 25
    - destination:
        host: reviews.prod.svc.cluster.local
        subset: v1
      headers:
        response:
          remove:
          - foo
      weight: 75

非終端TLSトラフィック（TLS/HTTPS）のルーティングのためのマッチ条件とアクションを記述します。以下のルーティングルールは、“mygateway”という名前のゲートウェイのポート443に到着する非終端TLSトラフィックを、SNI値に基づいてメッシュ内の内部サービスに転送します。

apiVersion: networking.istio.io/v1
kind: VirtualService
metadata:
  name: bookinfo-sni
spec:
  hosts:
  - "*.bookinfo.com"
  gateways:
  - mygateway
  tls:
  - match:
    - port: 443
      sniHosts:
      - login.bookinfo.com
    route:
    - destination:
        host: login.prod.svc.cluster.local
  - match:
    - port: 443
      sniHosts:
      - reviews.bookinfo.com
    route:
    - destination:
        host: reviews.prod.svc.cluster.local

TCPトラフィックのルーティングのためのマッチ条件とアクションを記述します。次のルーティングルールは、mongo.prod.svc.cluster.localのポート27017に到着するトラフィックを、ポート5555の別のMongoサーバーに転送します。

apiVersion: networking.istio.io/v1
kind: VirtualService
metadata:
  name: bookinfo-mongo
spec:
  hosts:
  - mongo.prod.svc.cluster.local
  tcp:
  - match:
    - port: 27017
    route:
    - destination:
        host: mongo.backup.svc.cluster.local
        port:
          number: 5555

HttpMatchRequestは、ルールをHTTPリクエストに適用するために満たす必要がある一連の条件を指定します。たとえば、以下の例では、URLパスが/ratings/v2/で始まり、リクエストに値がjasonであるカスタムend-userヘッダーが含まれているリクエストのみにルールを一致させるように制限します。

apiVersion: networking.istio.io/v1
kind: VirtualService
metadata:
  name: ratings-route
spec:
  hosts:
  - ratings.prod.svc.cluster.local
  http:
  - match:
    - headers:
        end-user:
          exact: jason
      uri:
        prefix: "/ratings/v2/"
      ignoreUriCase: true
    route:
    - destination:
        host: ratings.prod.svc.cluster.local

HTTPMatchRequestは空にできません。**注：**

1. ルートVirtualServiceが正規表現でプロパティ（パス、ヘッダーなど）に一致した場合、委任VirtualServiceは同じプロパティに対して他のマッチを持たない必要があります。
2. 委任VirtualServiceが正規表現でプロパティ（パス、ヘッダーなど）に一致した場合、ルートVirtualServiceは同じプロパティに対して他のマッチを持たない必要があります。

 - match:
   - headers:
       myheader: {}

各ルーティングルールには、1つ以上のサービスバージョンが関連付けられています（ドキュメントの先頭の用語集を参照）。バージョンに関連付けられた重みは、それが受信するトラフィックの割合を決定します。たとえば、次のルールは、“reviews”サービスのトラフィックの25％を“v2”タグを持つインスタンスにルーティングし、残りのトラフィック（つまり、75％）を“v1”にルーティングします。

apiVersion: networking.istio.io/v1
kind: VirtualService
metadata:
  name: reviews-route
spec:
  hosts:
  - reviews.prod.svc.cluster.local
  http:
  - route:
    - destination:
        host: reviews.prod.svc.cluster.local
        subset: v2
      weight: 25
    - destination:
        host: reviews.prod.svc.cluster.local
        subset: v1
      weight: 75

および関連付けられたDestinationRule

apiVersion: networking.istio.io/v1
kind: DestinationRule
metadata:
  name: reviews-destination
spec:
  host: reviews.prod.svc.cluster.local
  subsets:
  - name: v1
    labels:
      version: v1
  - name: v2
    labels:
      version: v2

新しいサブセットを定義することなく、まったく異なる2つのサービス間でトラフィックを分割することもできます。たとえば、次のルールは、reviews.comへのトラフィックの25％をdev.reviews.comに転送します。

apiVersion: networking.istio.io/v1
kind: VirtualService
metadata:
  name: reviews-route-two-domains
spec:
  hosts:
  - reviews.com
  http:
  - route:
    - destination:
        host: dev.reviews.com
      weight: 25
    - destination:
        host: reviews.com
      weight: 75

L4ルーティングルールの重み付けされた宛先。

L4接続マッチ属性。L4接続マッチングのサポートは不完全であることに注意してください。

TLS接続マッチ属性。

HTTPRedirectは、Authority/HostとレスポンスのURIを指定された値で交換できる301リダイレクトレスポンスを呼び出し元に送信するために使用できます。たとえば、次のルールは、ratingsサービスの/v1/getProductRatings APIのリクエストを、bookratingsサービスが提供する/v1/bookRatingsにリダイレクトします。

apiVersion: networking.istio.io/v1
kind: VirtualService
metadata:
  name: ratings-route
spec:
  hosts:
  - ratings.prod.svc.cluster.local
  http:
  - match:
    - uri:
        exact: /v1/getProductRatings
    redirect:
      uri: /v1/bookRatings
      authority: newratings.default.svc.cluster.local
  ...

HTTPDirectResponseは、クライアントに固定されたレスポンスを送信するために使用できます。たとえば、次のルールは、/v1/getProductRatings APIのリクエストに固定された503ステータスと本文を返します。

apiVersion: networking.istio.io/v1
kind: VirtualService
metadata:
  name: ratings-route
spec:
  hosts:
  - ratings.prod.svc.cluster.local
  http:
  - match:
    - uri:
        exact: /v1/getProductRatings
    directResponse:
      status: 503
      body:
        string: "unknown error"
  ...

バイナリレスポンス本文を指定することもできます。これは、gRPCなどのテキスト以外のプロトコルで主に役立ちます。

apiVersion: networking.istio.io/v1
kind: VirtualService
metadata:
  name: ratings-route
spec:
  hosts:
  - ratings.prod.svc.cluster.local
  http:
  - match:
    - uri:
        exact: /v1/getProductRatings
    directResponse:
      status: 503
      body:
        bytes: "dW5rbm93biBlcnJvcg==" # "unknown error" in base64
  ...

HTTPRouteとdirect_responseの両方でヘッダーを追加することをお勧めします（例：返されるContent-Typeを指定する場合）。

apiVersion: networking.istio.io/v1
kind: VirtualService
metadata:
  name: ratings-route
spec:
  hosts:
  - ratings.prod.svc.cluster.local
  http:
  - match:
    - uri:
        exact: /v1/getProductRatings
    directResponse:
      status: 503
      body:
        string: "{\"error\": \"unknown error\"}"
    headers:
      response:
        set:
          content-type: "text/plain"
  ...

HTTPRewriteは、リクエストを宛先に転送する前に、HTTPリクエストの特定の部分を書き換えるために使用できます。Rewriteプリミティブは、HTTPRouteDestinationでのみ使用できます。次の例は、API呼び出し(/ratings)のURLプレフィックスをratingsサービスに書き換えてから実際のAPI呼び出しを行う方法を示しています。

apiVersion: networking.istio.io/v1
kind: VirtualService
metadata:
  name: ratings-route
spec:
  hosts:
  - ratings.prod.svc.cluster.local
  http:
  - match:
    - uri:
        prefix: /ratings
    rewrite:
      uri: /v1/bookRatings
    route:
    - destination:
        host: ratings.prod.svc.cluster.local
        subset: v1

HTTPヘッダー内の特定の文字列の照合方法を記述します。exactおよびprefixの一致は大文字と小文字を区別します。regexの一致は大文字と小文字を区別しません。

HTTPリクエストが失敗した場合に使用するリトライポリシーについて説明します。たとえば、次のルールは、ratings:v1サービスを呼び出す際の最大リトライ回数を3回に設定し、リトライ試行ごとに2秒のタイムアウトを設定します。接続失敗、refused_stream、またはアップストリームサーバーがサービス利用不可（503）で応答した場合に、リトライが試行されます。

apiVersion: networking.istio.io/v1
kind: VirtualService
metadata:
  name: ratings-route
spec:
  hosts:
  - ratings.prod.svc.cluster.local
  http:
  - route:
    - destination:
        host: ratings.prod.svc.cluster.local
        subset: v1
    retries:
      attempts: 3
      perTryTimeout: 2s
      retryOn: gateway-error,connect-failure,refused-stream

特定のサービスのクロスオリジンリソース共有（CORS）ポリシーについて説明します。クロスオリジンリソース共有の詳細については、CORSを参照してください。たとえば、次のルールは、example.comドメインから発信されるHTTP POST/GETを使用するクロスオリジンリクエストを制限し、Access-Control-Allow-Credentialsヘッダーをfalseに設定します。さらに、X-Foo-barヘッダーのみを公開し、1日の有効期限を設定します。

apiVersion: networking.istio.io/v1
kind: VirtualService
metadata:
  name: ratings-route
spec:
  hosts:
  - ratings.prod.svc.cluster.local
  http:
  - route:
    - destination:
        host: ratings.prod.svc.cluster.local
        subset: v1
    corsPolicy:
      allowOrigins:
      - exact: https://example.com
      allowMethods:
      - POST
      - GET
      allowCredentials: false
      allowHeaders:
      - X-Foo-Bar
      maxAge: "24h"

HTTPFaultInjectionは、ルートに指定された宛先にHTTPリクエストを転送する際に挿入する1つ以上の障害を指定するために使用できます。障害の仕様は、VirtualServiceルールの部分です。障害には、ダウンストリームサービスからのHTTPリクエストの中断や、リクエストの転送の遅延などが含まれます。障害ルールには、delayまたはabort、またはその両方が含まれていなければなりません。

注：遅延と中断の障害は、同時に両方指定されている場合でも、互いに独立しています。

HTTPMirrorPolicyは、元の宛先に加えて、HTTPトラフィックをミラーリングする宛先を指定するために使用できます。ミラーリングされたトラフィックはベストエフォートベースであり、サイドカー/ゲートウェイは、元の宛先からの応答を返す前に、ミラーリングされた宛先が応答するのを待ちません。ミラーリングされた宛先に関する統計が生成されます。

PortSelectorは、最終ルーティングの照合または選択に使用されるポートの番号を指定します。

Percentは、[0.0, 100.0]の範囲のパーセンテージを指定します。

HeaderOperationsは、適用するヘッダー操作について説明します。

遅延の指定は、リクエスト転送パスにレイテンシを挿入するために使用されます。次の例では、「reviews」サービスの「v1」バージョンへの1000リクエストのうち1リクエストに5秒の遅延を導入します（ラベルenv: prodを持つすべてのポッドから）。

apiVersion: networking.istio.io/v1
kind: VirtualService
metadata:
  name: reviews-route
spec:
  hosts:
  - reviews.prod.svc.cluster.local
  http:
  - match:
    - sourceLabels:
        env: prod
    route:
    - destination:
        host: reviews.prod.svc.cluster.local
        subset: v1
    fault:
      delay:
        percentage:
          value: 0.1
        fixedDelay: 5s

fixedDelayフィールドは、秒単位の遅延量を示すために使用されます。オプションのpercentageフィールドを使用して、特定の割合のリクエストのみを遅延させることができます。指定されていない場合、リクエストは遅延しません。

中断の仕様は、事前に指定されたエラーコードでリクエストを早期に中断するために使用されます。次の例では、「ratings」サービスの「v1」バージョンへの1000リクエストのうち1リクエストにHTTP 400エラーコードを返します。

apiVersion: networking.istio.io/v1
kind: VirtualService
metadata:
  name: ratings-route
spec:
  hosts:
  - ratings.prod.svc.cluster.local
  http:
  - route:
    - destination:
        host: ratings.prod.svc.cluster.local
        subset: v1
    fault:
      abort:
        percentage:
          value: 0.1
        httpStatus: 400

httpStatusフィールドは、呼び出し元に返すHTTPステータスコードを示すために使用されます。オプションのpercentageフィールドを使用して、特定の割合のリクエストのみを中断することができます。指定されていない場合、リクエストは中断されません。

uint32のラッパーメッセージ。

UInt32ValueのJSON表現はJSON数値です。