第17章 HTTPRoute [gateway.networking.k8s.io/v1]

hostnames

array (string)

hostnames は、要求の処理に使用される HTTPRoute を選択するために、HTTP ホストヘッダーと一致するホスト名のセットを定義します。実装では、一致を実行するときに HTTP ホストヘッダーに指定されたポート値を無視する必要があり、(適用可能なヘッダー変更設定がない場合) このヘッダーを変更せずにバックエンドに転送する必要があります。

hostnames の有効な値は、RFC 1123 のホスト名の定義によって決定されますが、次の 2 つの例外があります。

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

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

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

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

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

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

複数の HTTPRoute が共通するホスト名 (重複するワイルドカード一致と完全一致のホスト名など) を指定している場合、次の数が最も多い HTTPRoute のルールが優先されます。

* 一致する非ワイルドカードのホスト名の文字。* 一致するホスト名の文字。

複数のルートで同じ数になる場合、HTTPRouteMatches の一致優先ルールが適用されます。

サポート: 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 は、HTTP マッチャー、フィルター、およびアクションのリストです。

rules[]

object

HTTPRouteRule は、条件 (一致) に基づいて HTTP 要求を一致させ、それを処理 (フィルター) し、要求を 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 内の すべて のエントリーが無効で、このルートルールにフィルターがまったく指定されていない場合、このルールに一致する すべて のトラフィックは 500 ステータスコードを受け取る必要があります。

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

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

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

HTTPBackendRef が ready 状態のエンドポイントを持たないサービスを参照する場合、実装ではそのバックエンドへの要求に対して代わりに 503 を返す必要があります。実装でこれを行うことを選択した場合、500 応答に関する上記のすべてのルールは、503 を返す応答にも適用される必要があります。

サポート: Kubernetes Service は Core

サポート: Kubernetes ServiceImport の Extended

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

重みのサポート: Core

backendRefs[]

object

HTTPBackendRef は、HTTPRoute が HTTP 要求を転送する方法を定義します。

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

filters

array

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

可能な場合、実装では指定された順序でフィルターを実装する必要があります。

実装では、サポートできないフィルターの組み合わせや順序を拒否し、この順序を厳密に実装することを選択できます。実装でフィルター順序の厳密な解釈を選択する場合、その動作を明確に文書化する必要があります。

無効なフィルターの組み合わせまたは順序を拒否するには、実装ではこの設定のルートルールを無効とみなす必要があります。ルート内のすべてのルートルールが無効な場合、ルート全体が無効とみなされます。ルートルールの一部のみが無効な場合、実装ではルートに対して "PartiallyInvalid" 条件を設定する必要があります。

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

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

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

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

サポート: Core

filters[]

object

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

matches

array

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

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

matches: - path: value: "/foo" headers: - name: "version" value: "v2" - path: value: "/v2/foo"

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

- パスの接頭辞が /foo であり、ヘッダー version: v2 が含まれている - パスの接頭辞が /v2/foo である

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

matches が指定されていない場合、デフォルトは "/" /の接頭辞パス一致であり、すべての HTTP 要求に一致する効果があります。

HTTPRoutes から生成されたプロキシーまたはロードバランサーのルーティング設定では、以下に示す条件に基づき matches を優先する必要があり、同順位の場合は次の条件を使用して決定します。適用可能なルートで指定されたすべてのルールにおいて、次の条件を満たす一致が優先されます。

* "完全な" パス一致。* 文字数が最も多い "接頭辞" パスの一致。* メソッドの一致。* 文字数が最も多いヘッダーの一致。* 数が最も多いクエリーパラメーターの一致。

注記: RegularExpression パスマッチの優先順位は実装によって異なります。

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

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

HTTPRoute 内で依然として同順位が存在する場合、上記の基準を満たす一致を持つ最初の一致ルール (リスト順) に一致の優先順位を付与する必要があります。

要求に一致するルールが要求の送信元の親に正常に割り当てられていない場合は、HTTP 404 ステータスコードを返す必要があります。

matches[]

object

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

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

match:

path: value: "/foo" headers: - name: "version" value "v1"

timeouts

object

timeouts は、HTTP 要求に対して設定できるタイムアウトを定義します。

サポート: Extended

filters

array

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

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

filters[]

object

HTTPRouteFilter は、要求または応答のライフサイクル中に完了する必要がある処理手順を定義します。HTTPRouteFilter は、ゲートウェイ実装で実行される可能性のある処理を表現するための拡張ポイントとなることを意図されています。例としては、要求または応答の変更、認証ストラテジーの実装、帯域制限、トラフィックシェーピングなどが挙げられます。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

requestRedirect

object

RequestRedirect は、HTTP リダイレクトを使用して要求に応答するフィルターのスキーマを定義します。

サポート: Core

responseHeaderModifier

object

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

サポート: Extended

type

string

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

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

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

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

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

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

この列挙には値が追加される可能性があることに注意してください。実装では、不明な値によってクラッシュが発生しないようにする必要があります。

ここで不明な値を指定すると、実装によってルートの Accepted Condition が UnsupportedValue の理由で status: False に設定されます。

urlRewrite

object

URLRewrite は、転送中に要求を変更するフィルターのスキーマを定義します。

サポート: Extended

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

hostname

string

hostname は、応答の Location ヘッダーの値で使用されるホスト名です。空の場合、要求の Host ヘッダー内のホスト名が使用されます。

サポート: Core

path

object

path は、受信要求のパスを変更するために使用されるパラメーターを定義します。変更されたパスは、Location ヘッダーの構築に使用されます。空の場合、要求パスはそのまま使用されます。

サポート: Extended

port

integer

Port は、応答の Location ヘッダーの値で使用されるポートです。

ポートが指定されていない場合は、次のルールを使用してリダイレクトポートを導出する必要があります。

* リダイレクトスキームが空でない場合、リダイレクトポートはリダイレクトスキームに関連付けられた既知のポートである必要があります。具体的には、"http" はポート 80、"https" はポート 443 です。リダイレクトスキームに既知のポートがない場合は、ゲートウェイのリスナーポートを使用する必要があります。* リダイレクトスキームが空の場合、リダイレクトポートはゲートウェイリスナーポートである必要があります。

次の場合、実装で 'Location' ヘッダーにポート番号を追加しないでください。

* HTTP (リスナープロトコルまたは Scheme フィールドで決定)、および ポート 80 を使用する Location ヘッダー。* HTTPS (リスナープロトコルまたは Scheme フィールドで決定)、および ポート 443 を使用する Location ヘッダー。

サポート: Extended

scheme

string

scheme は、応答の Location ヘッダーの値で使用されるスキームです。空の場合、要求のスキームが使用されます。

スキームリダイレクトはリダイレクトのポートに影響を与える可能性があります。詳細は、このフィルターの port フィールドのドキュメントを参照してください。

この列挙には値が追加される可能性があることに注意してください。実装では、不明な値によってクラッシュが発生しないようにする必要があります。

ここで不明な値を指定すると、実装によってルートの Accepted Condition が UnsupportedValue の理由で status: False に設定されます。

サポート: Extended

statusCode

integer

statusCode は、応答で使用される HTTP ステータスコードです。

この列挙には値が追加される可能性があることに注意してください。実装では、不明な値によってクラッシュが発生しないようにする必要があります。

ここで不明な値を指定すると、実装によってルートの Accepted Condition が UnsupportedValue の理由で status: False に設定されます。

サポート: Core

replaceFullPath

string

replaceFullPath は、書き換えまたはリダイレクト中に要求の完全パスを置き換える値を指定します。

replacePrefixMatch

string

replacePrefixMatch は、書き換えまたはリダイレクト中に要求の接頭辞一致を置き換える値を指定します。たとえば、接頭辞一致が "/foo" で、ReplacePrefixMatch が "/xyz" である "/foo/bar" への要求は、"/xyz/bar" に変更されます。

これは、PathPrefix 一致タイプの動作と一致することに注意してください。これは完全パス要素に一致します。パス要素は、/ の区切り文字で分割されたパス内のラベルリストを指します。指定すると、末尾の / は無視されます。たとえば、パス /abc、/abc/、/abc/def はすべて接頭辞 /abc と一致しますが、パス /abcd は一致しません。

ReplacePrefixMatch は PathPrefix HTTPRouteMatch とのみ互換性があります。同じ HTTPRouteRule で他の HTTPRouteMatch タイプを使用すると、実装によってルートの Accepted Condition が status: False に設定されます。

要求パス | 接頭辞一致 | 接頭辞の置き換え | 変更されたパス

type

string

type はパス修飾子のタイプを定義します。今後のリリースでタイプが追加される可能性があります。

この列挙には値が追加される可能性があることに注意してください。実装では、不明な値によってクラッシュが発生しないようにする必要があります。

ここで不明な値を指定すると、実装によってルートの Accepted Condition が UnsupportedValue の理由で status: False に設定されます。

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 ヘッダーの値です。

hostname

string

hostname は、転送中にホストヘッダー値を置き換えるために使用される値です。

サポート: Extended

path

object

path はパスの書き換えを定義します。

サポート: Extended

replaceFullPath

string

replaceFullPath は、書き換えまたはリダイレクト中に要求の完全パスを置き換える値を指定します。

replacePrefixMatch

string

replacePrefixMatch は、書き換えまたはリダイレクト中に要求の接頭辞一致を置き換える値を指定します。たとえば、接頭辞一致が "/foo" で、ReplacePrefixMatch が "/xyz" である "/foo/bar" への要求は、"/xyz/bar" に変更されます。

これは、PathPrefix 一致タイプの動作と一致することに注意してください。これは完全パス要素に一致します。パス要素は、/ の区切り文字で分割されたパス内のラベルリストを指します。指定すると、末尾の / は無視されます。たとえば、パス /abc、/abc/、/abc/def はすべて接頭辞 /abc と一致しますが、パス /abcd は一致しません。

ReplacePrefixMatch は PathPrefix HTTPRouteMatch とのみ互換性があります。同じ HTTPRouteRule で他の HTTPRouteMatch タイプを使用すると、実装によってルートの Accepted Condition が status: False に設定されます。

要求パス | 接頭辞一致 | 接頭辞の置き換え | 変更されたパス

type

string

type はパス修飾子のタイプを定義します。今後のリリースでタイプが追加される可能性があります。

この列挙には値が追加される可能性があることに注意してください。実装では、不明な値によってクラッシュが発生しないようにする必要があります。

ここで不明な値を指定すると、実装によってルートの Accepted Condition が UnsupportedValue の理由で status: False に設定されます。

extensionRef

object

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

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

サポート: 実装固有

requestHeaderModifier

object

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

サポート: Core

requestMirror

object

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

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

サポート: Extended

requestRedirect

object

RequestRedirect は、HTTP リダイレクトを使用して要求に応答するフィルターのスキーマを定義します。

サポート: Core

responseHeaderModifier

object

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

サポート: Extended

type

string

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

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

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

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

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

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

この列挙には値が追加される可能性があることに注意してください。実装では、不明な値によってクラッシュが発生しないようにする必要があります。

ここで不明な値を指定すると、実装によってルートの Accepted Condition が UnsupportedValue の理由で status: False に設定されます。

urlRewrite

object

URLRewrite は、転送中に要求を変更するフィルターのスキーマを定義します。

サポート: Extended

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

hostname

string

hostname は、応答の Location ヘッダーの値で使用されるホスト名です。空の場合、要求の Host ヘッダー内のホスト名が使用されます。

サポート: Core

path

object

path は、受信要求のパスを変更するために使用されるパラメーターを定義します。変更されたパスは、Location ヘッダーの構築に使用されます。空の場合、要求パスはそのまま使用されます。

サポート: Extended

port

integer

Port は、応答の Location ヘッダーの値で使用されるポートです。

ポートが指定されていない場合は、次のルールを使用してリダイレクトポートを導出する必要があります。

* リダイレクトスキームが空でない場合、リダイレクトポートはリダイレクトスキームに関連付けられた既知のポートである必要があります。具体的には、"http" はポート 80、"https" はポート 443 です。リダイレクトスキームに既知のポートがない場合は、ゲートウェイのリスナーポートを使用する必要があります。* リダイレクトスキームが空の場合、リダイレクトポートはゲートウェイリスナーポートである必要があります。

次の場合、実装で 'Location' ヘッダーにポート番号を追加しないでください。

* HTTP (リスナープロトコルまたは Scheme フィールドで決定)、および ポート 80 を使用する Location ヘッダー。* HTTPS (リスナープロトコルまたは Scheme フィールドで決定)、および ポート 443 を使用する Location ヘッダー。

サポート: Extended

scheme

string

scheme は、応答の Location ヘッダーの値で使用されるスキームです。空の場合、要求のスキームが使用されます。

スキームリダイレクトはリダイレクトのポートに影響を与える可能性があります。詳細は、このフィルターの port フィールドのドキュメントを参照してください。

この列挙には値が追加される可能性があることに注意してください。実装では、不明な値によってクラッシュが発生しないようにする必要があります。

ここで不明な値を指定すると、実装によってルートの Accepted Condition が UnsupportedValue の理由で status: False に設定されます。

サポート: Extended

statusCode

integer

statusCode は、応答で使用される HTTP ステータスコードです。

この列挙には値が追加される可能性があることに注意してください。実装では、不明な値によってクラッシュが発生しないようにする必要があります。

ここで不明な値を指定すると、実装によってルートの Accepted Condition が UnsupportedValue の理由で status: False に設定されます。

サポート: Core

replaceFullPath

string

replaceFullPath は、書き換えまたはリダイレクト中に要求の完全パスを置き換える値を指定します。

replacePrefixMatch

string

replacePrefixMatch は、書き換えまたはリダイレクト中に要求の接頭辞一致を置き換える値を指定します。たとえば、接頭辞一致が "/foo" で、ReplacePrefixMatch が "/xyz" である "/foo/bar" への要求は、"/xyz/bar" に変更されます。

これは、PathPrefix 一致タイプの動作と一致することに注意してください。これは完全パス要素に一致します。パス要素は、/ の区切り文字で分割されたパス内のラベルリストを指します。指定すると、末尾の / は無視されます。たとえば、パス /abc、/abc/、/abc/def はすべて接頭辞 /abc と一致しますが、パス /abcd は一致しません。

ReplacePrefixMatch は PathPrefix HTTPRouteMatch とのみ互換性があります。同じ HTTPRouteRule で他の HTTPRouteMatch タイプを使用すると、実装によってルートの Accepted Condition が status: False に設定されます。

要求パス | 接頭辞一致 | 接頭辞の置き換え | 変更されたパス

type

string

type はパス修飾子のタイプを定義します。今後のリリースでタイプが追加される可能性があります。

この列挙には値が追加される可能性があることに注意してください。実装では、不明な値によってクラッシュが発生しないようにする必要があります。

ここで不明な値を指定すると、実装によってルートの Accepted Condition が UnsupportedValue の理由で status: False に設定されます。

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 ヘッダーの値です。

hostname

string

hostname は、転送中にホストヘッダー値を置き換えるために使用される値です。

サポート: Extended

path

object

path はパスの書き換えを定義します。

サポート: Extended

replaceFullPath

string

replaceFullPath は、書き換えまたはリダイレクト中に要求の完全パスを置き換える値を指定します。

replacePrefixMatch

string

replacePrefixMatch は、書き換えまたはリダイレクト中に要求の接頭辞一致を置き換える値を指定します。たとえば、接頭辞一致が "/foo" で、ReplacePrefixMatch が "/xyz" である "/foo/bar" への要求は、"/xyz/bar" に変更されます。

これは、PathPrefix 一致タイプの動作と一致することに注意してください。これは完全パス要素に一致します。パス要素は、/ の区切り文字で分割されたパス内のラベルリストを指します。指定すると、末尾の / は無視されます。たとえば、パス /abc、/abc/、/abc/def はすべて接頭辞 /abc と一致しますが、パス /abcd は一致しません。

ReplacePrefixMatch は PathPrefix HTTPRouteMatch とのみ互換性があります。同じ HTTPRouteRule で他の HTTPRouteMatch タイプを使用すると、実装によってルートの Accepted Condition が status: False に設定されます。

要求パス | 接頭辞一致 | 接頭辞の置き換え | 変更されたパス

type

string

type はパス修飾子のタイプを定義します。今後のリリースでタイプが追加される可能性があります。

この列挙には値が追加される可能性があることに注意してください。実装では、不明な値によってクラッシュが発生しないようにする必要があります。

ここで不明な値を指定すると、実装によってルートの Accepted Condition が UnsupportedValue の理由で status: False に設定されます。

headers

array

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

headers[]

object

HTTPHeaderMatch は、HTTP 要求ヘッダーを照合して HTTP ルートを選択する方法を記述します。

method

string

method は、HTTP メソッドのマッチャーを指定します。指定すると、このルートは、要求に指定されたメソッドがある場合にのみ照合されます。

サポート: Extended

path

object

path は、HTTP 要求パスマッチャーを指定します。このフィールドが指定されていない場合、デフォルトで "/" パスの接頭辞一致が提供されます。

queryParams

array

queryParams は、HTTP クエリーパラメーターマッチャーを指定します。一致する値が複数ある場合は、AND を使用して結合されます。つまり、ルートを選択するには、要求が指定されたすべてのクエリーパラメーターと一致する必要があります。

サポート: Extended

queryParams[]

object

HTTPQueryParamMatch は、HTTP クエリーパラメーターを照合して HTTP ルートを選択する方法を記述します。

name

string

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

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

HTTP 要求でヘッダーが繰り返されている場合、それがどのように表現されるかは実装固有の動作になります。通常、プロキシーは、繰り返されたヘッダーの処理に関する RFC ( https://www.rfc-editor.org/rfc/rfc7230.html#section-3.2.2) のガイダンスに従う必要がありますが、"Set-Cookie" には特別な処理が必要です。

type

string

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

サポート: Core (Exact)

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

RegularExpression HeaderMatchType には実装固有の適合性があるため、実装は POSIX、PCRE、またはその他の正規表現の方言をサポートできます。実装のドキュメントを参照して、サポートされている方言を確認してください。

value

string

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

type

string

type は、パスの値と照合する方法を指定します。

サポート: Core (Exact, PathPrefix)

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

value

string

照合する HTTP パスの値。

name

string

name は、一致させる HTTP クエリーパラメーターの名前です。これは、文字列の完全一致である必要があります。(https://tools.ietf.org/html/rfc7230#section-2.7.3 を参照)。

複数のエントリーが同じクエリーパラメーター名を指定している場合、同じ名前を持つ最初のエントリーのみが一致として考慮される必要があります。同じクエリーパラメーター名を持つ後続のエントリーは、無視する必要があります。

HTTP 要求でクエリーパラメーターを繰り返す場合、データプレーンごとに機能が異なるため、動作は意図的に未定義のままになります。ただし、この動作はゲートウェイ API 以外の他の負荷分散コンテキストで予想されるため、データプレーンがサポートしている場合は、実装をパラメーターの最初の値と一致させることが 推奨されます。

ユーザーは、実装における潜在的な違いを防ぐために、繰り返しのクエリーパラメーターに基づいてトラフィックをルーティングしないでください。

type

string

type は、クエリーパラメーターの値と照合する方法を指定します。

サポート: Extended (Exact)

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

RegularExpression QueryParamMatchType には実装固有の適合性があるため、実装は POSIX、PCRE、またはその他の正規表現の方言をサポートできます。実装のドキュメントを参照して、サポートされている方言を確認してください。

value

string

value は、一致する HTTP クエリーパラメーターの値です。

backendRequest

string

BackendRequest は、ゲートウェイからバックエンドへの個別要求のタイムアウトを指定します。これは、ゲートウェイからの要求送信が最初に開始されてから、完全な応答をバックエンドから受信するまでの時間をカバーします。

タイムアウトをゼロに設定する (例:"0s") と、タイムアウトが完全に無効になるはずです。タイムアウトを完全に無効にできない実装では、代わりに継続時間がゼロの場合を、タイムアウトに設定できる最長時間として解釈する必要があります。

要求タイムアウトの対象となるゲートウェイとクライアント間の HTTP トランザクション全体で、ゲートウェイから宛先バックエンドへの呼び出しが複数回発生することがあります。たとえば、自動再試行がサポートされている場合が該当します。

BackendRequest の値は、GEP-2257 で定義されている Gateway API Duration の文字列である必要があります。このフィールドが指定されていない場合、その動作は実装固有です。指定されている場合、BackendRequest の値は要求タイムアウトの値以下である必要があります (要求タイムアウトには BackendRequest タイムアウトが含まれるため)。

サポート: Extended

request

string

request は、ゲートウェイが HTTP 要求に応答するまでの最大時間を指定します。この時間に達するまでにゲートウェイが応答できなかった場合、ゲートウェイはタイムアウトエラーを返す必要があります。

たとえば、HTTPRoute で rules.timeouts.request フィールドの値を 10s に設定した場合、クライアント要求の完了にかかる時間が 10 秒を超えるとタイムアウトが発生します。

タイムアウトをゼロに設定する (例:"0s") と、タイムアウトが完全に無効になるはずです。タイムアウトを完全に無効にできない実装では、代わりに継続時間がゼロの場合を、タイムアウトに設定できる最長時間として解釈する必要があります。

このタイムアウトは、可能な限り要求応答トランザクション全体をカバーすることを目的としていますが、実装では、クライアントによってトランザクションが開始された直後ではなく、要求ストリーム全体が受信された後にタイムアウトを開始することを選択できます。

request の値は、GEP-2257 で定義されている Gateway API Duration の文字列です。このフィールドが指定されていない場合、要求タイムアウトの動作は実装によって異なります。

サポート: Extended

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