第14章 GRPCRoute [gateway.networking.k8s.io/v1]

hostnames

array (string)

hostnames は、GRPC Host ヘッダーと照合して、要求を処理するための GRPCRoute を選択するためのホスト名のセットを定義します。2 つの例外を除き、これは RFC 1123 のホスト名の定義と一致します。

1.IP は許可されていません。2. ホスト名の前にワイルドカードラベル (*.) を付けることができます。ワイルドカードラベルは、最初のラベルとして単独で表示される必要があります。

リスナーと GRPCRoute の両方でホスト名が指定されている場合、GRPCRoute をリスナーにアタッチするには、少なくとも 1 つの交差するホスト名が存在する必要があります。以下に例を示します。

* リスナーのホスト名は test.example.com で、ホスト名が指定されていないか、少なくとも test.example.com または *.example.com のいずれかが指定された GRPCRoutes と一致します。* リスナーのホスト名は *.example.com で、ホスト名が指定されていないか、リスナーのホスト名と一致するホスト名が 1 つ以上指定された GRPCRoutes と一致します。たとえば、test.example.com と \*.example.com はどちらも一致します。一方で、example.com と test.example.net は一致しません。

ワイルドカードラベル (*.) が接頭辞として追加されているホスト名は、接尾辞一致として解釈されます。つまり、*.example.com に一致すると、test.example.com と foo.test.example.com の両方に一致しますが、example.com には一致しません。

リスナーと GRPCRoute の両方にホスト名が指定されている場合、リスナーのホスト名と一致しない GRPCRoute のホスト名はすべて無視する必要があります。たとえば、リスナーが *.example.com を指定し、GRPCRoute が test.example.com と test.example.net を指定した場合、test.example.net は一致とみなされてはなりません。

リスナーと GRPCRoute の両方にホスト名が指定されており、どちらも上記の条件に一致しない場合は、実装で GRPCRoute が受け入れられてはなりません。実装は、対応する RouteParentStatus で 'Accepted' 条件を False ステータスで報告する必要があります。

HTTPRoute または GRPCRoute タイプの Route (A) がリスナーにアタッチされ、そのリスナーにすでに他のタイプの Route (B) がアタッチされ、A と B のホスト名の共通部分が空ではない場合、実装では次の条件に従った順番で、これらの 2 つのルートのうち 1 つだけを受け入れる必要があります。

* 作成タイムスタンプに基づく古い方のルート。* "{namespace}/{name}" のアルファベット順で最初に表示されるルート。

拒否されたルートは、対応する RouteParentStatus で 'Accepted' 条件を 'False' ステータスで報告する必要があります。

サポート: Core

parentRefs

array

ParentRefs は、ルートの割り当て先となるリソース (通常はゲートウェイ) を参照します。割り当てを完了するには、参照先の親リソースでこれを許可する必要があることに注意してください。つまり、ゲートウェイの場合は、ゲートウェイがこの種類のルートおよび namespace からの割り当てを許可する必要があります。サービスの場合は、サービスが "producer" ルートと同じ namespace に存在するか、メッシュ実装が参照先のサービスの "consumer" ルートをサポートして許可する必要があることを意味します。ReferenceGrant は、サービスへの ParentRef の管理には適用できません。ルートとは異なる namespace にサービスの "producer" ルートを作成することはできません。

"Core" サポートを備えた親リソースには 2 つの kind があります。

* ゲートウェイ (ゲートウェイ適合プロファイル) * サービス (メッシュ適合プロファイル、ClusterIP サービスのみ)

この API は、今後拡張され、追加の kind の親リソースをサポートする可能性があります。

ParentRefs はそれぞれ 区別される 必要があります。これは次のいずれかを意味します。

* 異なるオブジェクトを選択します。この場合、parentRef エントリーはそれぞれ区別されるエントリーです。フィールドに関して言えば、これは、group、kind、namespace、name を使用して定義されるマルチパートキーが、ルート内のすべての parentRef エントリー間で一意である必要があることを意味します。* 異なるオブジェクトは選択しませんが、同じオブジェクトを選択する各 ParentRef は、使用するオプションフィールドごとに、同じオプションフィールドのセットを異なる値に設定する必要があります。1 つの ParentRef がオプションフィールドの組み合わせを設定する場合、すべて同じ組み合わせを設定する必要があります。

例:

* 1 つの ParentRef が sectionName を設定する場合、同じオブジェクトを参照するすべての ParentRef も sectionName を設定する必要があります。* 1 つの ParentRef が port を設定する場合、同じオブジェクトを参照するすべての ParentRef も port を設定する必要があります。* 1 つの ParentRef が sectionName と port を設定する場合、同じオブジェクトを参照するすべての ParentRef も sectionName と port を設定する必要があります。

実装によって折りたたまれる可能性のある複数の区別されるオブジェクトを個別に参照できます。たとえば、一部の実装では、互換性のあるゲートウェイリスナーをマージすることを選択することがあります。その場合は、それらのリソースに割り当てられたルートのリストもマージする必要があります。

namespace の境界をまたぐ ParentRef には、特定のルールがあることに注意してください。namespace 間の参照は、参照先の namespace 内の何かによって明示的に許可されている場合にのみ有効です。たとえば、ゲートウェイには AllowedRoutes フィールドがあり、ReferenceGrant は他の種類の namespace 間参照を有効にする一般的な方法を提供します。

parentRefs[]

object

ParentReference は、このリソース (通常はルート) の親とみなされる API オブジェクト (通常はゲートウェイ) を識別します。"Core" サポートを備えた親リソースには 2 つの kind があります。

* ゲートウェイ (ゲートウェイ適合プロファイル) * サービス (メッシュ適合プロファイル、ClusterIP サービスのみ)

この API は、今後拡張され、追加の kind の親リソースをサポートする可能性があります。

API オブジェクトはクラスター内で有効である必要があります。この参照を有効にするには、Group と Kind がクラスターに登録されている必要があります。

rules

array

rules は、GRPC マッチャー、フィルター、およびアクションのリストです。

rules[]

object

GRPCRouteRule は、条件 (一致) に基づいて gRPC 要求を一致させ、それを処理 (フィルター) し、要求を API オブジェクト (backendRefs) に転送するためのセマンティクスを定義します。

group

string

group は参照先のグループです。指定されていない場合は、"gateway.networking.k8s.io" が推論されます。コア API グループ ("Service" kind の参照先など) を設定するには、Group を明示的に "" (空の文字列) に設定する必要があります。

サポート: Core

kind

string

kind は参照先の kind です。

"Core" サポートを備えた親リソースには 2 つの kind があります。

* ゲートウェイ (ゲートウェイ適合プロファイル) * サービス (メッシュ適合プロファイル、ClusterIP サービスのみ)

その他のリソースのサポートは実装によって異なります。

name

string

name は参照先の名前です。

サポート: Core

namespace

string

namespace は参照先の namespace です。指定されていない場合は、ルートのローカル namespace を参照します。

namespace の境界をまたぐ ParentRef には固有のルールがあることに注意してください。namespace 間の参照は、参照先の namespace 内の何かによって明示的に許可されている場合にのみ有効です。たとえば、Gateway には AllowedRoutes フィールドがあり、ReferenceGrant は他の種類の namespace 間参照を有効にする一般的な方法を提供します。

サポート: Core

port

integer

port は、このルートがターゲットとするネットワークポートです。親リソースのタイプに応じて、解釈が異なる場合があります。

親リソースがゲートウェイの場合、これは指定されたポートでリッスンし、この種類のルートもサポートする (そしてこのルートを選択する) すべてのリスナーをターゲットとします。ルートで指定されたネットワーク動作を、ポートが変更される可能性のあるリスナーではなく特定のポートに適用する必要がある場合以外で Port を設定することは推奨されません。Port と SectionName の両方を指定する場合、選択したリスナーの名前とポートは、指定された両方の値と一致する必要があります。

実装では、他の親リソースをサポートすることを選択できます。他のタイプの親リソースをサポートする実装では、ポートが解釈されるかどうか、どのように解釈されるかを明確に文書化する必要があります。

ステータスの目的上、親リソースが割り当てを部分的に受け入れる限り、割り当ては成功したとみなされます。たとえば、ゲートウェイリスナーは、ルートの種類、namespace、またはホスト名によって、どのルートを割り当てられるかを制限できます。2 つのゲートウェイリスナーのうち 1 つが参照ルートからの割り当てを受け入れた場合、ルートは正常に割り当て済みであるとみなされる必要があります。ゲートウェイリスナーがこのルートからの割り当てを受け入れない場合、ゲートウェイからルートへの割り当てが解除されたとみなされる必要があります。

サポート: Extended

sectionName

string

SectionName は、ターゲットリソース内のセクションの名前です。次のリソースでは、SectionName は次のように解釈されます。

* ゲートウェイ: リスナー名。Port (実験的機能) と SectionName の両方を指定する場合、選択したリスナーの名前とポートは、指定された両方の値と一致する必要があります。* サービス: ポート名。Port (実験的機能) と SectionName の両方を指定する場合、選択したリスナーの名前とポートは、指定された両方の値と一致する必要があります。

実装では、ルートを他のリソースに割り当てることもサポートできます。その場合は、SectionName がどのように解釈されるかを明確に文書化する必要があります。

指定されていない場合 (空の文字列)、リソース全体が参照されます。ステータスの目的上、親リソース内の少なくとも 1 つのセクションが割り当てを受け入れると、割り当ては成功したとみなされます。たとえば、ゲートウェイリスナーは、ルートの種類、namespace、またはホスト名によって、どのルートを割り当てられるかを制限できます。2 つのゲートウェイリスナーのうち 1 つが参照ルートからの割り当てを受け入れた場合、ルートは正常に割り当て済みであるとみなされる必要があります。ゲートウェイリスナーがこのルートからの割り当てを受け入れない場合、ゲートウェイからルートへの割り当てが解除されたとみなされる必要があります。

サポート: Core

backendRefs

array

backendRefs は、一致する要求を送信するバックエンドを定義します。

失敗の動作は、指定された BackendRef の数と無効な BackendRef の数により異なります。

BackendRefs 内の すべて のエントリーが無効で、このルートルールにフィルターがまったく指定されていない場合、このルールに一致する すべて のトラフィックは UNAVAILABLE ステータスを受け取る必要があります。

1 つの GRPCBackendRef が無効になるルールは、GRPCBackendRef の定義を参照してください。

GRPCBackendRef が無効な場合、無効なバックエンドにルーティングされるはずであった要求に対して UNAVAILABLE ステータスを返す必要があります。複数のバックエンドが指定されており、その一部が無効な場合、無効なバックエンドにルーティングされるはずであった割合の要求は、UNAVAILABLE ステータスを受け取る必要があります。

たとえば、2 つのバックエンドが同じ重みで指定され、そのうちの 1 つが無効な場合、トラフィックの 50 パーセントは UNAVAILABLE ステータスを受信する必要があります。実装では、その 50 パーセントを決定する方法を選択できます。

サポート: Kubernetes Service は Core

サポート: その他のリソースは実装固有

重みのサポート: Core

backendRefs[]

object

GRPCBackendRef は、GRPCRoute が gRPC 要求を転送する方法を定義します。

ローカル namespace とは異なる namespace を指定する場合、その namespace の所有者が参照を受け入れるためには、参照先 namespace に ReferenceGrant オブジェクトが必要であることに注意してください。詳細は、ReferenceGrant ドキュメントを参照してください。

filters

array

フィルターは、このルールに一致する要求に適用されるフィルターを定義します。

複数の動作の順序付けの効果は現在指定されていません。これは、アルファ段階でのフィードバックに基づき、今後変更される可能性があります。

このレベルでの適合レベルは、フィルタータイプに基づき定義されます。

- すべてのコアフィルターは、GRPCRoute をサポートするすべての実装でサポートされる必要があります。- 実装者は拡張フィルターをサポートすることが推奨されます。- 実装固有のカスタムフィルターでは、実装をまたいだ API は保証されていません。

フィルターに明示的に指定されていない限り、同じフィルターを複数回指定することはサポートされません。

実装がフィルターの組み合わせをサポートできない場合は、その制限を明確に文書化する必要があります。互換性のないフィルターやサポート対象外のフィルターが指定され、Accepted 条件のステータスが False に設定されると、実装では IncompatibleFilters を理由としてこの設定エラーを指定します。

サポート: Core

filters[]

object

GRPCRouteFilter は、要求または応答のライフサイクル中に完了する必要がある処理手順を定義します。GRPCRouteFilters は、ゲートウェイ実装で実行される可能性のある処理を表現するための拡張ポイントとなることを意図されています。例としては、要求または応答の変更、認証ストラテジーの実装、帯域制限、トラフィックシェーピングなどが挙げられます。API の保証/適合性は、フィルタータイプに基づき定義されます。

matches

array

matches は、着信 gRPC 要求にルールを一致させるために使用する条件を定義します。match はそれぞれ独立しています。つまり、いずれか の match が満たされると、ルールが一致します。

たとえば、次の matches 設定を見てみましょう。

matches: - method: service: foo.bar headers: values: version: 2 - method: service: foo.bar.v2

次の 2 つの条件のいずれかを満たすと、要求はこのルールに一致するとみなされます。

- foo.bar のサービスであり、ヘッダー version: 2 が含まれる。- foo.bar.v2 のサービスである。

複数の match 条件を AND で結合して指定する方法は、GRPCRouteMatch のドキュメントを参照してください。

matches が指定されていない場合、実装はすべての gRPC 要求に一致する必要があります。

GRPCRoutes から生成されたプロキシーまたはロードバランサーのルーティング設定では、以下に示す条件に基づき優先順位付けをする必要があり、同順位の場合は次の条件を使用して決定します。GRPCRoutes と HTTPRoutes の間でマージを行ってはなりません。以下の項目が最も多いルールが優先される必要があります。

* 一致する非ワイルドカードのホスト名の文字。* 一致するホスト名の文字。* 一致するサービスの文字。* 一致するメソッドの文字。* 一致するヘッダー。

複数のルートをまたいで同点が存在する場合は、以下に示す条件に基づき一致の優先順位を決定する必要があり、同順位の場合は次の条件を使用して決定します。

* 作成タイムスタンプに基づく古い方のルート。* "{namespace}/{name}" のアルファベット順で最初に表示されるルート。

優先権が与えられたルート内でまだ同順位が存在する場合、上記の基準を満たす最初のマッチングルールに matching の優先権を付与する必要があります。

matches[]

object

GRPCRouteMatch は、要求を特定のアクションに一致させるために使用される述語を定義します。複数の一致タイプは AND を使用して結合されます。つまり、すべての条件が満たされた場合にのみ match は true と評価されます。

たとえば、以下の match は、サービスが foo であり、かつ version: v1 ヘッダーが含まれている場合にのみ gRPC 要求と一致します。

matches: - method: type: Exact service: "foo" headers: - name: "version" value "v1"

filters

array

このレベルで定義されたフィルターは、ここで定義されたバックエンドに要求が転送される場合にのみ実行される必要があります。

サポート: 実装固有 (より広範なフィルターのサポートが必要な場合は、GRPCRouteRule の Filters フィールドを使用します。)

filters[]

object

GRPCRouteFilter は、要求または応答のライフサイクル中に完了する必要がある処理手順を定義します。GRPCRouteFilters は、ゲートウェイ実装で実行される可能性のある処理を表現するための拡張ポイントとなることを意図されています。例としては、要求または応答の変更、認証ストラテジーの実装、帯域制限、トラフィックシェーピングなどが挙げられます。API の保証/適合性は、フィルタータイプに基づき定義されます。

group

string

group は参照先のグループです。たとえば "gateway.networking.k8s.io" です。指定されていないか空の文字列の場合、core API グループが推論されます。

kind

string

kind は、参照先の Kubernetes リソースの種類です。たとえば、"Service" があります。

指定されていない場合のデフォルトは "Service" です。

ExternalName サービスは、クラスターの外部に存在する可能性のある CNAME DNS レコードを参照する可能性があるため、準拠の観点から判断することが困難です。また、転送先としても安全ではない可能性があります (詳細は、CVE-2021-25740 を参照してください)。実装では、ExternalName サービスをサポートしないでください。

サポート: Core (ExternalName 以外のタイプのサービス)

サポート: 実装固有 (ExternalName タイプのサービス)

name

string

name は参照先の名前です。

namespace

string

namespace はバックエンドの namespace です。指定しない場合は、ローカル namespace が推論されます。

ローカル namespace とは異なる namespace を指定する場合、その namespace の所有者が参照を受け入れるためには、参照先 namespace に ReferenceGrant オブジェクトが必要であることに注意してください。詳細は、ReferenceGrant ドキュメントを参照してください。

サポート: Core

port

integer

port は、このリソースに使用する宛先ポート番号を指定します。参照先が Kubernetes サービスの場合は port が必要です。この場合、ポート番号はターゲットポートではなく、サービスポート番号です。その他のリソースの場合、宛先ポートは参照先リソースまたはこのフィールドから導出される可能性があります。

weight

integer

weight は、参照先のバックエンドに転送される要求の割合を指定します。重み/(この BackendRefs リスト内のすべての重みの合計) で計算されます。ゼロ以外の値の場合、実装がサポートする精度に応じて、ここで定義された正確な割合から僅かな誤差が発生する可能性があります重みはパーセンテージではありません。重みの合計が 100 になる必要はありません。

バックエンドが 1 つだけ指定され、その重みが 0 より大きい場合、トラフィックの 100% がそのバックエンドに転送されます。重みが 0 に設定されている場合、このエントリーに対してトラフィックは転送されません。指定しない場合、重みはデフォルトで 1 になります。

このフィールドのサポートは、使用されるコンテキストにより異なります。

extensionRef

object

ExtensionRef は、"filter" 動作に対するオプションの実装固有の拡張機能です。たとえば、"networking.example.net" グループ内の "myroutefilter" リソースがあります。ExtensionRef は、コアフィルターおよび拡張フィルターには使用しないでください。

サポート: 実装固有

このフィルターは同じルール内で複数回使用できます。

requestHeaderModifier

object

RequestHeaderModifier は、要求ヘッダーを変更するフィルターのスキーマを定義します。

サポート: Core

requestMirror

object

RequestMirror は、要求をミラーリングするフィルターのスキーマを定義します。要求は指定された宛先に送信されますが、その宛先からの応答は無視されます。

このフィルターは同じルール内で複数回使用できます。すべての実装が複数のバックエンドへのミラーリングをサポートできるわけではないことに注意してください。

サポート: Extended

responseHeaderModifier

object

ResponseHeaderModifier は、応答ヘッダーを変更するフィルターのスキーマを定義します。

サポート: Extended

type

string

type は適用するフィルターのタイプを識別します。他の API フィールドと同様に、タイプは次の 3 つの準拠レベルに分類されます。

- コア: このパッケージの "サポート: Core" で定義されたフィルタータイプとそれに対応する設定 (例: "RequestHeaderModifier")。GRPCRoute をサポートするすべての実装は、コアフィルターをサポートする必要があります。

- 拡張: このパッケージの "サポート: Extended" で定義されたフィルタータイプとそれに対応する設定 (例: "RequestMirror")。実装者は拡張フィルターをサポートすることが推奨されます。

- 実装固有: 特定のベンダーによって定義およびサポートされているフィルター。将来的には、複数の実装をまたいで動作が収束するフィルターを、拡張またはコア適合レベルに含めることが検討される予定です。このようなフィルターのフィルター固有の設定は、ExtensionRef フィールドを使用して指定されます。カスタムフィルターの場合、Type は "ExtensionRef" に設定する必要があります。

実装者は、実装固有の動作でコア API を拡張するために、カスタム実装タイプを定義することが推奨されます。

カスタムフィルタータイプへの参照を解決できない場合は、フィルターをスキップしてはなりません。代わりに、そのフィルターによって処理されるはずだった要求は、HTTP エラー応答を受信する必要があります。

group

string

group は参照先のグループです。たとえば "gateway.networking.k8s.io" です。指定されていないか空の文字列の場合、core API グループが推論されます。

kind

string

kind は参照先の kind です。たとえば、"HTTPRoute" や "Service" があります。

name

string

name は参照先の名前です。

add

array

Add は、アクションの前に、指定されたヘッダー (名前、値) を要求に追加します。ヘッダー名に関連付けられている既存の値に追加されます。

入力: GET /foo HTTP/1.1 my-header: foo

設定: add: - name: "my-header" value: "bar,baz"

出力: GET /foo HTTP/1.1 my-header: foo,bar,baz

add[]

object

HTTPHeader は、RFC 7230 で定義されている HTTP ヘッダー名と値を表します。

remove

array (string)

アクションの前に、HTTP 要求から指定されたヘッダーを削除します。Remove の値は、HTTP ヘッダー名のリストです。ヘッダー名では、大文字と小文字が区別されないことに注意してください (https://datatracker.ietf.org/doc/html/rfc2616#section-4.2 を参照)。

入力: GET /foo HTTP/1.1 my-header1: foo my-header2: bar my-header3: baz

設定: remove: ["my-header1", "my-header3"]

出力: GET /foo HTTP/1.1 my-header2: bar

set

array

Set は、アクションの前に指定されたヘッダー (名前、値) を使用して要求を上書きします。

入力: GET /foo HTTP/1.1 my-header: foo

設定: set: - name: "my-header" value: "bar"

出力: GET /foo HTTP/1.1 my-header: bar

set[]

object

HTTPHeader は、RFC 7230 で定義されている HTTP ヘッダー名と値を表します。

name

string

name は、一致させる HTTP ヘッダーの名前です。名前の一致では、大文字と小文字を区別しないでください。(https://tools.ietf.org/html/rfc7230#section-3.2 を参照)。

複数のエントリーが同じヘッダー名を指定している場合、同じ名前を持つ最初のエントリーが一致とみなされる必要があります。同じヘッダー名を持つ後続のエントリーは無視する必要があります。ヘッダー名では大文字と小文字が区別されないため、"foo" と "Foo" は同じとみなされます。

value

string

value は、一致させる HTTP ヘッダーの値です。

name

string

name は、一致させる HTTP ヘッダーの名前です。名前の一致では、大文字と小文字を区別しないでください。(https://tools.ietf.org/html/rfc7230#section-3.2 を参照)。

複数のエントリーが同じヘッダー名を指定している場合、同じ名前を持つ最初のエントリーが一致とみなされる必要があります。同じヘッダー名を持つ後続のエントリーは無視する必要があります。ヘッダー名では大文字と小文字が区別されないため、"foo" と "Foo" は同じとみなされます。

value

string

value は、一致させる HTTP ヘッダーの値です。

backendRef

object

BackendRef は、ミラーリングされた要求が送信されるリソースを参照します。

ミラーリングされた要求は、この BackendRef 内に存在するエンドポトの数に関係なく、この BackendRef 内の単一の宛先エンドポイントにのみ送信する必要があります。

参照先が見つからない場合、この BackendRef は無効であり、ゲートウェイから削除する必要があります。コントローラーは、ルートステータスの "ResolvedRefs" 条件が status: False に設定されていることを確認し、基礎となる実装でこのバックエンドを設定しないようにする必要があります。

ReferenceGrant が許可しない 既存 オブジェクトへの namespace 間の参照がある場合、コントローラーは、ルートの "ResolvedRefs" 条件が status: False (理由は "RefNotPermitted") に設定されていることを確認して、基礎となる実装でこのバックエンドを設定しないようにする必要があります。

どちらのエラーでも、ResolvedRefs 条件のメッセージを使用して、問題の詳細を提供する必要があります。

サポート : Kubernetes Service は Extended

サポート: その他のリソースは実装固有

fraction

object

Fraction は、BackendRef にミラーリングする必要がある要求の割合を表します。

Fraction と Percent のいずれか 1 つだけを指定できます。どちらのフィールドも指定されていない場合は、要求の 100% がミラーリングされます。

percent

integer

percent は、BackendRef にミラーリングする必要がある要求のパーセンテージを表します。最小値は 0 (要求の 0% を示す)、最大値は 100 (要求の 100% を示す) です。

Fraction と Percent のいずれか 1 つだけを指定できます。どちらのフィールドも指定されていない場合は、要求の 100% がミラーリングされます。

group

string

group は参照先のグループです。たとえば "gateway.networking.k8s.io" です。指定されていないか空の文字列の場合、core API グループが推論されます。

kind

string

kind は、参照先の Kubernetes リソースの種類です。たとえば、"Service" があります。

指定されていない場合のデフォルトは "Service" です。

ExternalName サービスは、クラスターの外部に存在する可能性のある CNAME DNS レコードを参照する可能性があるため、準拠の観点から判断することが困難です。また、転送先としても安全ではない可能性があります (詳細は、CVE-2021-25740 を参照してください)。実装では、ExternalName サービスをサポートしないでください。

サポート: Core (ExternalName 以外のタイプのサービス)

サポート: 実装固有 (ExternalName タイプのサービス)

name

string

name は参照先の名前です。

namespace

string

namespace はバックエンドの namespace です。指定しない場合は、ローカル namespace が推論されます。

ローカル namespace とは異なる namespace を指定する場合、その namespace の所有者が参照を受け入れるためには、参照先 namespace に ReferenceGrant オブジェクトが必要であることに注意してください。詳細は、ReferenceGrant ドキュメントを参照してください。

サポート: Core

port

integer

port は、このリソースに使用する宛先ポート番号を指定します。参照先が Kubernetes サービスの場合は port が必要です。この場合、ポート番号はターゲットポートではなく、サービスポート番号です。その他のリソースの場合、宛先ポートは参照先リソースまたはこのフィールドから導出される可能性があります。

denominator

integer

numerator

integer

add

array

Add は、アクションの前に、指定されたヘッダー (名前、値) を要求に追加します。ヘッダー名に関連付けられている既存の値に追加されます。

入力: GET /foo HTTP/1.1 my-header: foo

設定: add: - name: "my-header" value: "bar,baz"

出力: GET /foo HTTP/1.1 my-header: foo,bar,baz

add[]

object

HTTPHeader は、RFC 7230 で定義されている HTTP ヘッダー名と値を表します。

remove

array (string)

アクションの前に、HTTP 要求から指定されたヘッダーを削除します。Remove の値は、HTTP ヘッダー名のリストです。ヘッダー名では、大文字と小文字が区別されないことに注意してください (https://datatracker.ietf.org/doc/html/rfc2616#section-4.2 を参照)。

入力: GET /foo HTTP/1.1 my-header1: foo my-header2: bar my-header3: baz

設定: remove: ["my-header1", "my-header3"]

出力: GET /foo HTTP/1.1 my-header2: bar

set

array

Set は、アクションの前に指定されたヘッダー (名前、値) を使用して要求を上書きします。

入力: GET /foo HTTP/1.1 my-header: foo

設定: set: - name: "my-header" value: "bar"

出力: GET /foo HTTP/1.1 my-header: bar

set[]

object

HTTPHeader は、RFC 7230 で定義されている HTTP ヘッダー名と値を表します。

name

string

name は、一致させる HTTP ヘッダーの名前です。名前の一致では、大文字と小文字を区別しないでください。(https://tools.ietf.org/html/rfc7230#section-3.2 を参照)。

複数のエントリーが同じヘッダー名を指定している場合、同じ名前を持つ最初のエントリーが一致とみなされる必要があります。同じヘッダー名を持つ後続のエントリーは無視する必要があります。ヘッダー名では大文字と小文字が区別されないため、"foo" と "Foo" は同じとみなされます。

value

string

value は、一致させる HTTP ヘッダーの値です。

name

string

name は、一致させる HTTP ヘッダーの名前です。名前の一致では、大文字と小文字を区別しないでください。(https://tools.ietf.org/html/rfc7230#section-3.2 を参照)。

複数のエントリーが同じヘッダー名を指定している場合、同じ名前を持つ最初のエントリーが一致とみなされる必要があります。同じヘッダー名を持つ後続のエントリーは無視する必要があります。ヘッダー名では大文字と小文字が区別されないため、"foo" と "Foo" は同じとみなされます。

value

string

value は、一致させる HTTP ヘッダーの値です。

extensionRef

object

ExtensionRef は、"filter" 動作に対するオプションの実装固有の拡張機能です。たとえば、"networking.example.net" グループ内の "myroutefilter" リソースがあります。ExtensionRef は、コアフィルターおよび拡張フィルターには使用しないでください。

サポート: 実装固有

このフィルターは同じルール内で複数回使用できます。

requestHeaderModifier

object

RequestHeaderModifier は、要求ヘッダーを変更するフィルターのスキーマを定義します。

サポート: Core

requestMirror

object

RequestMirror は、要求をミラーリングするフィルターのスキーマを定義します。要求は指定された宛先に送信されますが、その宛先からの応答は無視されます。

このフィルターは同じルール内で複数回使用できます。すべての実装が複数のバックエンドへのミラーリングをサポートできるわけではないことに注意してください。

サポート: Extended

responseHeaderModifier

object

ResponseHeaderModifier は、応答ヘッダーを変更するフィルターのスキーマを定義します。

サポート: Extended

type

string

type は適用するフィルターのタイプを識別します。他の API フィールドと同様に、タイプは次の 3 つの準拠レベルに分類されます。

- コア: このパッケージの "サポート: Core" で定義されたフィルタータイプとそれに対応する設定 (例: "RequestHeaderModifier")。GRPCRoute をサポートするすべての実装は、コアフィルターをサポートする必要があります。

- 拡張: このパッケージの "サポート: Extended" で定義されたフィルタータイプとそれに対応する設定 (例: "RequestMirror")。実装者は拡張フィルターをサポートすることが推奨されます。

- 実装固有: 特定のベンダーによって定義およびサポートされているフィルター。将来的には、複数の実装をまたいで動作が収束するフィルターを、拡張またはコア適合レベルに含めることが検討される予定です。このようなフィルターのフィルター固有の設定は、ExtensionRef フィールドを使用して指定されます。カスタムフィルターの場合、Type は "ExtensionRef" に設定する必要があります。

実装者は、実装固有の動作でコア API を拡張するために、カスタム実装タイプを定義することが推奨されます。

カスタムフィルタータイプへの参照を解決できない場合は、フィルターをスキップしてはなりません。代わりに、そのフィルターによって処理されるはずだった要求は、HTTP エラー応答を受信する必要があります。

group

string

group は参照先のグループです。たとえば "gateway.networking.k8s.io" です。指定されていないか空の文字列の場合、core API グループが推論されます。

kind

string

kind は参照先の kind です。たとえば、"HTTPRoute" や "Service" があります。

name

string

name は参照先の名前です。

add

array

Add は、アクションの前に、指定されたヘッダー (名前、値) を要求に追加します。ヘッダー名に関連付けられている既存の値に追加されます。

入力: GET /foo HTTP/1.1 my-header: foo

設定: add: - name: "my-header" value: "bar,baz"

出力: GET /foo HTTP/1.1 my-header: foo,bar,baz

add[]

object

HTTPHeader は、RFC 7230 で定義されている HTTP ヘッダー名と値を表します。

remove

array (string)

アクションの前に、HTTP 要求から指定されたヘッダーを削除します。Remove の値は、HTTP ヘッダー名のリストです。ヘッダー名では、大文字と小文字が区別されないことに注意してください (https://datatracker.ietf.org/doc/html/rfc2616#section-4.2 を参照)。

入力: GET /foo HTTP/1.1 my-header1: foo my-header2: bar my-header3: baz

設定: remove: ["my-header1", "my-header3"]

出力: GET /foo HTTP/1.1 my-header2: bar

set

array

Set は、アクションの前に指定されたヘッダー (名前、値) を使用して要求を上書きします。

入力: GET /foo HTTP/1.1 my-header: foo

設定: set: - name: "my-header" value: "bar"

出力: GET /foo HTTP/1.1 my-header: bar

set[]

object

HTTPHeader は、RFC 7230 で定義されている HTTP ヘッダー名と値を表します。

name

string

name は、一致させる HTTP ヘッダーの名前です。名前の一致では、大文字と小文字を区別しないでください。(https://tools.ietf.org/html/rfc7230#section-3.2 を参照)。

複数のエントリーが同じヘッダー名を指定している場合、同じ名前を持つ最初のエントリーが一致とみなされる必要があります。同じヘッダー名を持つ後続のエントリーは無視する必要があります。ヘッダー名では大文字と小文字が区別されないため、"foo" と "Foo" は同じとみなされます。

value

string

value は、一致させる HTTP ヘッダーの値です。

name

string

name は、一致させる HTTP ヘッダーの名前です。名前の一致では、大文字と小文字を区別しないでください。(https://tools.ietf.org/html/rfc7230#section-3.2 を参照)。

複数のエントリーが同じヘッダー名を指定している場合、同じ名前を持つ最初のエントリーが一致とみなされる必要があります。同じヘッダー名を持つ後続のエントリーは無視する必要があります。ヘッダー名では大文字と小文字が区別されないため、"foo" と "Foo" は同じとみなされます。

value

string

value は、一致させる HTTP ヘッダーの値です。

backendRef

object

BackendRef は、ミラーリングされた要求が送信されるリソースを参照します。

ミラーリングされた要求は、この BackendRef 内に存在するエンドポトの数に関係なく、この BackendRef 内の単一の宛先エンドポイントにのみ送信する必要があります。

参照先が見つからない場合、この BackendRef は無効であり、ゲートウェイから削除する必要があります。コントローラーは、ルートステータスの "ResolvedRefs" 条件が status: False に設定されていることを確認し、基礎となる実装でこのバックエンドを設定しないようにする必要があります。

ReferenceGrant が許可しない 既存 オブジェクトへの namespace 間の参照がある場合、コントローラーは、ルートの "ResolvedRefs" 条件が status: False (理由は "RefNotPermitted") に設定されていることを確認して、基礎となる実装でこのバックエンドを設定しないようにする必要があります。

どちらのエラーでも、ResolvedRefs 条件のメッセージを使用して、問題の詳細を提供する必要があります。

サポート : Kubernetes Service は Extended

サポート: その他のリソースは実装固有

fraction

object

Fraction は、BackendRef にミラーリングする必要がある要求の割合を表します。

Fraction と Percent のいずれか 1 つだけを指定できます。どちらのフィールドも指定されていない場合は、要求の 100% がミラーリングされます。

percent

integer

percent は、BackendRef にミラーリングする必要がある要求のパーセンテージを表します。最小値は 0 (要求の 0% を示す)、最大値は 100 (要求の 100% を示す) です。

Fraction と Percent のいずれか 1 つだけを指定できます。どちらのフィールドも指定されていない場合は、要求の 100% がミラーリングされます。

group

string

group は参照先のグループです。たとえば "gateway.networking.k8s.io" です。指定されていないか空の文字列の場合、core API グループが推論されます。

kind

string

kind は、参照先の Kubernetes リソースの種類です。たとえば、"Service" があります。

指定されていない場合のデフォルトは "Service" です。

ExternalName サービスは、クラスターの外部に存在する可能性のある CNAME DNS レコードを参照する可能性があるため、準拠の観点から判断することが困難です。また、転送先としても安全ではない可能性があります (詳細は、CVE-2021-25740 を参照してください)。実装では、ExternalName サービスをサポートしないでください。

サポート: Core (ExternalName 以外のタイプのサービス)

サポート: 実装固有 (ExternalName タイプのサービス)

name

string

name は参照先の名前です。

namespace

string

namespace はバックエンドの namespace です。指定しない場合は、ローカル namespace が推論されます。

ローカル namespace とは異なる namespace を指定する場合、その namespace の所有者が参照を受け入れるためには、参照先 namespace に ReferenceGrant オブジェクトが必要であることに注意してください。詳細は、ReferenceGrant ドキュメントを参照してください。

サポート: Core

port

integer

port は、このリソースに使用する宛先ポート番号を指定します。参照先が Kubernetes サービスの場合は port が必要です。この場合、ポート番号はターゲットポートではなく、サービスポート番号です。その他のリソースの場合、宛先ポートは参照先リソースまたはこのフィールドから導出される可能性があります。

denominator

integer

numerator

integer

add

array

Add は、アクションの前に、指定されたヘッダー (名前、値) を要求に追加します。ヘッダー名に関連付けられている既存の値に追加されます。

入力: GET /foo HTTP/1.1 my-header: foo

設定: add: - name: "my-header" value: "bar,baz"

出力: GET /foo HTTP/1.1 my-header: foo,bar,baz

add[]

object

HTTPHeader は、RFC 7230 で定義されている HTTP ヘッダー名と値を表します。

remove

array (string)

アクションの前に、HTTP 要求から指定されたヘッダーを削除します。Remove の値は、HTTP ヘッダー名のリストです。ヘッダー名では、大文字と小文字が区別されないことに注意してください (https://datatracker.ietf.org/doc/html/rfc2616#section-4.2 を参照)。

入力: GET /foo HTTP/1.1 my-header1: foo my-header2: bar my-header3: baz

設定: remove: ["my-header1", "my-header3"]

出力: GET /foo HTTP/1.1 my-header2: bar

set

array

Set は、アクションの前に指定されたヘッダー (名前、値) を使用して要求を上書きします。

入力: GET /foo HTTP/1.1 my-header: foo

設定: set: - name: "my-header" value: "bar"

出力: GET /foo HTTP/1.1 my-header: bar

set[]

object

HTTPHeader は、RFC 7230 で定義されている HTTP ヘッダー名と値を表します。

name

string

name は、一致させる HTTP ヘッダーの名前です。名前の一致では、大文字と小文字を区別しないでください。(https://tools.ietf.org/html/rfc7230#section-3.2 を参照)。

複数のエントリーが同じヘッダー名を指定している場合、同じ名前を持つ最初のエントリーが一致とみなされる必要があります。同じヘッダー名を持つ後続のエントリーは無視する必要があります。ヘッダー名では大文字と小文字が区別されないため、"foo" と "Foo" は同じとみなされます。

value

string

value は、一致させる HTTP ヘッダーの値です。

name

string

name は、一致させる HTTP ヘッダーの名前です。名前の一致では、大文字と小文字を区別しないでください。(https://tools.ietf.org/html/rfc7230#section-3.2 を参照)。

複数のエントリーが同じヘッダー名を指定している場合、同じ名前を持つ最初のエントリーが一致とみなされる必要があります。同じヘッダー名を持つ後続のエントリーは無視する必要があります。ヘッダー名では大文字と小文字が区別されないため、"foo" と "Foo" は同じとみなされます。

value

string

value は、一致させる HTTP ヘッダーの値です。

headers

array

Headers は gRPC 要求ヘッダーマッチャーを指定します。一致する値が複数ある場合は、AND を使用して結合されます。つまり、ルートを選択するには、要求が指定されたすべてのヘッダーと一致する必要があります。

headers[]

object

GRPCHeaderMatch は、gRPC 要求ヘッダーを照合して gRPC ルートを選択する方法を説明します。

method

object

method は、gRPC 要求サービス/メソッドマッチャーを指定します。このフィールドを指定しない場合は、すべてのサービスとメソッドが一致します。

name

string

Name は、一致させる gRPC ヘッダーの名前です。

複数のエントリーが同じヘッダー名を指定している場合、同じ名前を持つ最初のエントリーのみが一致として考慮される必要があります。同じヘッダー名を持つ後続のエントリーは無視する必要があります。ヘッダー名では大文字と小文字が区別されないため、"foo" と "Foo" は同じとみなされます。

type

string

type は、ヘッダーの値と一致させる方法を指定します。

value

string

value は、一致させる gRPC ヘッダーの値です。

method

string

照合するメソッドの値。空にする、または省略すると、すべてのサービスに一致します。

サービスとメソッドの少なくとも 1 つは空でない文字列にする必要があります。

service

string

照合するサービスの値。空にする、または省略すると、いずれのサービスにも一致します。

サービスとメソッドの少なくとも 1 つは空でない文字列にする必要があります。

type

string

type は、サービスやメソッドとの照合方法を指定します。サポート: コア (指定されたサービスと方法に正確に一致)

サポート: 実装固有 (指定されたメソッドに正確に一致、サービスは指定されていない)

サポート: 実装固有 (RegularExpression)

parents

array

parents は、ルートに関連付けられている親リソース (通常はゲートウェイ) のリストと、各親に対するルートのステータスです。このルートが親に割り当てられる場合、親を管理するコントローラーは、ルートを最初に確認したときにこのリストにエントリーを追加し、ルートまたはゲートウェイが変更された場合にはエントリーを適切に更新する必要があります。

この API の実装によって解決できない親参照は、このリストに追加されないことに注意してください。この API の実装では、対象のゲートウェイ/親リソースのルートステータスのみ設定できます。

このリストには最大 32 個のゲートウェイが表示されます。リストが空の場合、ルートはどのゲートウェイにも割り当てられていないことを意味します。

parents[]

object

RouteParentStatus は、関連付けられた親に対するルートのステータスを記述します。

conditions

array

conditions は、ゲートウェイに対するルートのステータスを記述します。ルートの可用性は、ゲートウェイ自体のステータス条件とリスナーのステータスにも左右されることに注意してください。

ルートの ParentRef が、このタイプのルートをサポートする既存のゲートウェイを指定し、そのゲートウェイのコントローラーが十分なアクセス権を持っている場合、そのゲートウェイのコントローラーは、ルートがゲートウェイによって受け入れられたか拒否されたか、およびその理由を示すために、ルートに "Accepted" 条件を設定する必要があります。

ルートのルールの少なくとも 1 つがゲートウェイに実装されている場合、ルートは "Accepted" とみなされる必要があります。

コントローラーの可視性が不足しているために "Accepted" 条件が設定されないケースが多数あります。これには次のような場合が含まれます。

* ルートが存在しない親を参照している場合。* コントローラーがサポートしていないルートタイプの場合。* コントローラーがアクセスできない namespace にルートが配置されている場合。

conditions[]

object

condition には、この API Resource の現在の状態のある側面の詳細が含まれます。

controllerName

string

ControllerName は、このステータスを書き込んだコントローラーの名前を示すドメイン/パスの文字列です。これは、GatewayClass の controllerName フィールドに対応します。

例: "example.net/gateway-controller"

このフィールドの形式は DOMAIN "/" PATH です。この場合の DOMAIN と PATH は有効な Kubernetes 名です (https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names)。

コントローラーはステータスを書き込むときにこのフィールドに値を入力する必要があります。コントローラーは、ControllerName が設定されたステータスのエントリーが不要になったときにクリーンアップされるようにする必要があります。

parentRef

object

ParentRef は、この RouteParentStatus 構造体がステータスを記述する、仕様内の ParentRef に対応します。

lastTransitionTime

string

lastTransitionTime は、ある状態から別の状態に最後に遷移した時間です。これは、基本的な条件が変更された時点となります。不明な場合には、API フィールドが変更された時点を使用することも可能です。

message

string

message は、遷移の詳細を示す人が判読できるメッセージです。空の文字列の場合もあります。

observedGeneration

integer

observedGeneration は、それをベースに条件が設定された .metadata.generation を表します。たとえば、.metadata.generation が現在 12 で、.status.conditions[x].observedGeneration が 9 の場合、インスタンスの現在の状態に対して条件が古くなっています。

reason

string

reason には、条件の最後の遷移の理由を示すプログラムによる識別子が含まれます。特定の条件タイプのプロデューサーは、このフィールドの期待値と意味、および値が保証された API と見なされるかどうかを定義できます。値は CamelCase 文字列である必要があります。このフィールドには空白を指定できません。

status

string

条件のステータス、True、False、Unknown のいずれか。

type

string

CamelCase または foo.example.com/CamelCase の条件のタイプ。

group

string

group は参照先のグループです。指定されていない場合は、"gateway.networking.k8s.io" が推論されます。コア API グループ ("Service" kind の参照先など) を設定するには、Group を明示的に "" (空の文字列) に設定する必要があります。

サポート: Core

kind

string

kind は参照先の kind です。

"Core" サポートを備えた親リソースには 2 つの kind があります。

* ゲートウェイ (ゲートウェイ適合プロファイル) * サービス (メッシュ適合プロファイル、ClusterIP サービスのみ)

その他のリソースのサポートは実装によって異なります。

name

string

name は参照先の名前です。

サポート: Core

namespace

string

namespace は参照先の namespace です。指定されていない場合は、ルートのローカル namespace を参照します。

namespace の境界をまたぐ ParentRef には固有のルールがあることに注意してください。namespace 間の参照は、参照先の namespace 内の何かによって明示的に許可されている場合にのみ有効です。たとえば、Gateway には AllowedRoutes フィールドがあり、ReferenceGrant は他の種類の namespace 間参照を有効にする一般的な方法を提供します。

サポート: Core

port

integer

port は、このルートがターゲットとするネットワークポートです。親リソースのタイプに応じて、解釈が異なる場合があります。

親リソースがゲートウェイの場合、これは指定されたポートでリッスンし、この種類のルートもサポートする (そしてこのルートを選択する) すべてのリスナーをターゲットとします。ルートで指定されたネットワーク動作を、ポートが変更される可能性のあるリスナーではなく特定のポートに適用する必要がある場合以外で Port を設定することは推奨されません。Port と SectionName の両方を指定する場合、選択したリスナーの名前とポートは、指定された両方の値と一致する必要があります。

実装では、他の親リソースをサポートすることを選択できます。他のタイプの親リソースをサポートする実装では、ポートが解釈されるかどうか、どのように解釈されるかを明確に文書化する必要があります。

ステータスの目的上、親リソースが割り当てを部分的に受け入れる限り、割り当ては成功したとみなされます。たとえば、ゲートウェイリスナーは、ルートの種類、namespace、またはホスト名によって、どのルートを割り当てられるかを制限できます。2 つのゲートウェイリスナーのうち 1 つが参照ルートからの割り当てを受け入れた場合、ルートは正常に割り当て済みであるとみなされる必要があります。ゲートウェイリスナーがこのルートからの割り当てを受け入れない場合、ゲートウェイからルートへの割り当てが解除されたとみなされる必要があります。

サポート: Extended

sectionName

string

SectionName は、ターゲットリソース内のセクションの名前です。次のリソースでは、SectionName は次のように解釈されます。

* ゲートウェイ: リスナー名。Port (実験的機能) と SectionName の両方を指定する場合、選択したリスナーの名前とポートは、指定された両方の値と一致する必要があります。* サービス: ポート名。Port (実験的機能) と SectionName の両方を指定する場合、選択したリスナーの名前とポートは、指定された両方の値と一致する必要があります。

実装では、ルートを他のリソースに割り当てることもサポートできます。その場合は、SectionName がどのように解釈されるかを明確に文書化する必要があります。

指定されていない場合 (空の文字列)、リソース全体が参照されます。ステータスの目的上、親リソース内の少なくとも 1 つのセクションが割り当てを受け入れると、割り当ては成功したとみなされます。たとえば、ゲートウェイリスナーは、ルートの種類、namespace、またはホスト名によって、どのルートを割り当てられるかを制限できます。2 つのゲートウェイリスナーのうち 1 つが参照ルートからの割り当てを受け入れた場合、ルートは正常に割り当て済みであるとみなされる必要があります。ゲートウェイリスナーがこのルートからの割り当てを受け入れない場合、ゲートウェイからルートへの割り当てが解除されたとみなされる必要があります。

サポート: Core