Mixed Version Proxy

FEATURE STATE: Kubernetes v1.28 [alpha](disabled by default)

Kubernetes 1.35には、APIサーバーが他の ピア APIサーバーにリソースリクエストをプロキシできるようにするアルファ機能が含まれています。 また、クライアントがディスカバリを通じてクラスター全体で提供されるリソースの全体像を取得することもできます。 これは、1つのクラスター内で異なるバージョンのKubernetesを実行する複数のAPIサーバーがある場合に役立ちます(例えば、Kubernetesの新しいリリースへの長期間にわたるロールアウト中など)。

これにより、クラスター管理者は、より安全にアップグレードできる高可用性クラスターを設定できます:

  1. 重要なタスクでリソースの包括的なリストを表示するためにディスカバリに依存するコントローラーが、常にすべてのリソースの完全なビューを取得できるようにします。この完全なクラスター全体のディスカバリを ピア集約ディスカバリ と呼びます。
  2. (アップグレード中に行われる)リソースリクエストを正しいkube-apiserverに転送します。このプロキシにより、ユーザーはアップグレードプロセスに起因する予期しない404 Not Foundエラーを見ることがなくなります。このメカニズムは Mixed Version Proxy と呼ばれます。

ピア集約ディスカバリとMixed Version Proxyの有効化

APIサーバーを起動する際に、UnknownVersionInteroperabilityProxyフィーチャーゲートが有効になっていることを確認してください:

kube-apiserver \
--feature-gates=UnknownVersionInteroperabilityProxy=true \
# この機能に必要なコマンドライン引数
--peer-ca-file=<kube-apiserver CA証明書へのパス>
--proxy-client-cert-file=<アグリゲータープロキシ証明書へのパス>,
--proxy-client-key-file=<アグリゲータープロキシ鍵へのパス>,
--requestheader-client-ca-file=<アグリゲーターCA証明書へのパス>,
# requestheader-allowed-namesは、任意のCommon Nameを許可するために空白に設定できます
--requestheader-allowed-names=<プロキシクライアント証明書を検証するための有効なCommon Names>,

# この機能のオプションフラグ
--peer-advertise-ip=`ピアがリクエストをプロキシするために使用するこのkube-apiserverのIP`
--peer-advertise-port=`ピアがリクエストをプロキシするために使用するこのkube-apiserverのポート`

# …その他のフラグは通常通り

APIサーバー間のプロキシトランスポートと認証

  • ソースkube-apiserverは、既存のAPIサーバークライアント認証フラグ--proxy-client-cert-fileと--proxy-client-key-fileを再利用して、ピア(宛先kube-apiserver)によって検証される自身のIDを提示します。宛先APIサーバーは、--requestheader-client-ca-fileコマンドライン引数を使用して指定した設定に基づいてピア接続を検証します。

  • 宛先サーバーのサービング証明書を認証するには、ソースAPIサーバーに--peer-ca-fileコマンドライン引数を使用して認証局バンドルを設定する必要があります。

ピアAPIサーバー接続の設定

ピアがリクエストをプロキシするために使用するkube-apiserverのネットワークロケーションを設定するには、kube-apiserverに--peer-advertise-ipと--peer-advertise-portコマンドライン引数を使用するか、APIサーバー設定ファイルでこれらのフィールドを指定します。 これらのフラグが指定されていない場合、ピアはkube-apiserverの--advertise-addressまたは--bind-addressコマンドライン引数の値を使用します。 それらも設定されていない場合、ホストのデフォルトインターフェースが使用されます。

ピア集約ディスカバリ

この機能を有効にすると、ディスカバリリクエストはデフォルトで包括的なディスカバリドキュメント(クラスター内のすべてのapiserverによって提供されるすべてのリソースをリストする)を提供するように自動的に有効になります。

ピア集約されていないディスカバリドキュメントをリクエストしたい場合は、ディスカバリリクエストに次のAcceptヘッダーを追加することでそれを示すことができます:

application/json;g=apidiscovery.k8s.io;v=v2;as=APIGroupDiscoveryList;profile=nopeer

Mixed version proxying

Mixed version proxyingを有効にすると、アグリゲーションレイヤーは次の処理を行う特別なフィルターをロードします:

  • APIサーバーがそのAPIを提供できない場合(APIが導入される前のバージョンであるか、そのAPIサーバーでAPIが無効になっているため)、リソースリクエストがAPIサーバーに到達すると、そのAPIサーバーはリクエストされたAPIを提供できるピアAPIサーバーにリクエストを送信しようとします。これは、ローカルサーバーが認識しないAPIグループ/バージョン/リソースを識別し、リクエストを処理できるピアAPIサーバーにそれらのリクエストをプロキシしようとすることで実現されます。
  • ピアAPIサーバーが応答に失敗した場合、ソース APIサーバーは503(「Service Unavailable」)エラーで応答します。

内部での動作

APIサーバーがリソースリクエストを受信すると、最初にどのAPIサーバーがリクエストされたリソースを提供できるかを確認します。 この確認は、ピア集約されていないディスカバリドキュメントを使用して行われます。

  • リクエストを受信したAPIサーバーから取得したピア集約されていないディスカバリドキュメントにリソースがリストされている場合(例えば、GET /api/v1/pods/some-pod)、リクエストはローカルで処理されます。

  • リクエスト内のリソース(例えば、GET /apis/resource.k8s.io/v1beta1/resourceclaims)が、リクエストを処理しようとしているAPIサーバー(処理APIサーバー)から取得したピア集約されていないディスカバリドキュメントに見つからない場合、おそらくresource.k8s.io/v1beta1 APIがより新しいKubernetesバージョンで導入され、処理APIサーバー がそれをサポートしていない古いバージョンを実行しているためです。その場合、処理APIサーバー はすべてのピアAPIサーバーからピア集約されていないディスカバリドキュメントを確認して、関連するAPIグループ/バージョン/リソース(この場合はresource.k8s.io/v1beta1/resourceclaims)を提供するピアAPIサーバーを取得します。処理APIサーバー は、リクエストされたリソースを認識している一致するピアkube-apiserverの1つにリクエストをプロキシします。

  • そのAPIグループ/バージョン/リソースを認識しているピアがいない場合、処理APIサーバーは自身のハンドラーチェーンにリクエストを渡し、最終的に404(「Not Found」)レスポンスを返すはずです。

  • 処理APIサーバーがピアAPIサーバーを識別して選択したが、そのピアが応答に失敗した場合(ネットワーク接続の問題、またはリクエストの受信とコントローラーがピアの情報をコントロールプレーンに登録する間のデータ競合などの理由)、処理APIサーバーは503(「Service Unavailable」)エラーで応答します。

最終更新 March 02, 2026 at 12:12 PM PST: Fix italic underscore spacing and replace ディスカバリー with ディスカバリ (aa2267659d)