Kubernetes 1.37: SIG-API Machineryの変更内容

はじめに

Kubernetes v1.37 がリリースされました 🎉

引き続き List/Watch 系のパフォーマンス改善が入っています。1.32 から入っていた etcd に保存されているものの、デコードできないオブジェクト処理用の AllowUnsafeMalformedObjectDeletion もベータに昇格し、デフォルト有効になりました。ほかにも、ベータデフォルト有効で追加された Webhook Server へのリクエストの偏りを抑制する WebhookRoundTripLoadBalancing など、運用しやすくなりそうな機能が色々あります。

それでは、API 周りの変更を担当する SIG-API Machinery の変更点を CHANGELOG からピックアップします。(📝 が付いた文章は、CHANGELOG の公式内容ではなく筆者の補足です)

SIG, KEPについてはこちらを参照ください。

✨ Features (機能追加)

List/Watch改善系

• EtcdRangeStream FeatureGate をデフォルトで有効にし、ベータに昇格させました。 (#140085)

  📝 api-serverの再起動時など、大きなクラスタで watch cache を初期化する際に、etcd からページ分割ではなく RangeStream RPC で受け取ることで初期化時間を短縮するための機能です。
  詳しくは KEP-5966: etcd RangeStream を参照してください。

• ConcurrentWatchObjectDecode FeatureGate をベータに昇格させ、デフォルトで有効にしました。 (#139679)

  📝 watch オブジェクトのデコードを並列化し、API サーバーの watch が詰まるのを改善するための機能です。元は conversion webhook の遅延が背景にありましたが、こちらでも watch cacheの初期化速度も向上したようです。

• WatchCacheInitializationPostStartHook を GA に昇格させました。 (#139452)

  📝 watch cache の初期化が終わるまでapi-server を Ready にしないための機能です。

• アルファの FeatureGate ConsistentListFromCacheSkipTimeoutFallback を追加しました。有効にすると、タイムアウト期間内に watch キャッシュから処理できない consistent な LIST リクエストに対して、 kube-apiserver はストレージにフォールバックする代わりに HTTP 429 を返します。 (#138701)

  📝 1.34でGAした ConsistentListFromCache の拡張機能で、今までは consistency が必要な LIST では cache が etcd の最新リビジョンまで追いつくまで待機、間に合わなければetcdへ問い合わせるという挙動でした。
  今回の ConsistentListFromCacheSkipTimeoutFallback では、etcd への不可を下げるため、タイム・アウトした場合でも etcd に直接問い合わせず、 429 を返してクライアント側でリトライさせる挙動になっています。

• WatchList リクエストに対する圧縮レスポンスのベータサポートを追加しました。クライアントが Accept-Encoding: gzip を送信すると、API サーバーは gzip 圧縮されたレスポンスを返します。この動作はデフォルトで有効であり、 WatchListCompression FeatureGate で無効化できます。通常の watch リクエストは影響を受けません。 (#140140)

  📝 1.34 からデフォルト有効な WatchList の拡張機能で、 この元の方は informer の初期 LIST を watch のストリームとして受けることで apiserver の負荷を抑える機能でした。
  今回の WatchListCompression では、このストリームを gzip 圧縮することでレイテンシを下げるという機能です。

• Accept-Encoding: gzip を送信するクライアント向けに WatchList レスポンスを gzip 圧縮する WatchListCompression FeatureGate（ベータ、デフォルト有効）を追加しました。通常の Watch リクエストは影響を受けません。 (#139308)

• CBORServingAndStorage FeatureGate が有効な場合に、ディスカバリエンドポイントおよび構造化エラーレスポンスにおける CBOR エンコーディングのサポートを追加しました。 (#139632)

  📝 CBORServingAndStorage は v1.32 から引き続きアルファ・デフォルト無効です。(client-go 側の ClientsAllowCBOR と ClientsPreferCBOR も同様)

Admission

• ⭐ --enable-aggregator-routing=true を設定した kube-apiserver では、コネクションキャッシングで同時リクエストが単一のバックエンドエンドポイントにルーティングされるのを防ぐため、admission webhook エンドポイント間でリクエストを均等にロードバランスさせます。クラスタ管理者は WebhookRoundTripLoadBalancing FeatureGate（ベータ、デフォルト有効）でこの動作を一時的にオプトアウトできます。 (#139237)

  📝 Webhook Server として複数の Pod を使っていた場合、今までは一度 Pod に接続されると、ホスト名をキーにしたプールから残っている接続が使い回されてリクエストが偏っていました。
  今回の変更では、リクエストごとに都度ホスト名から Pod IP をランダムに解決するようになりました。

• 宣言的バリデーションタグ +k8s:dependentRequired("siblingJSONName") を追加しました。タグ付けされたフィールドが設定されている場合、指定された同階層のフィールド（sibling）も設定が必要です。 (#139164)

• ManifestBasedAdmissionControlConfig FeatureGate をベータに昇格し、デフォルトで有効にしました。 (#140559)

  📝 Admission Webhook や ValidatingAdmissionPolicy / MutatingAdmissionPolicy を、API オブジェクトとしてではなく、kube-apiserver が起動時に読むファイルとして定義できる機能です。

  詳しくは KEP-5793: Manifest Based Admission Control Configを参照してください。

• ValidatingAdmissionPolicy および MutatingAdmissionPolicy で既に除外されている tokenreviews や subjectaccessreviews などの auth/authz 仮想リソースを、admission webhook でもスキップするように更新しました。 ExcludeAdmissionWebhookVirtualResources FeatureGate（ベータ、デフォルト有効）を追加し、以前の動作に戻すオプトアウトオプションを提供しています。 (#140019)

Staleオブジェクトの処理

• ⭐ AllowUnsafeMalformedObjectDeletion FeatureGate をベータに昇格させ、デフォルトで有効にしました。ストレージから読み取れないオブジェクトに対する List エラーに、最初の根本原因が含まれるようになりました。 (#140785)

  📝 etcd には残っているものの、APIサーバから読めなくなったオブジェクトの検出 & 削除機能 AllowUnsafeMalformedObjectDeletion がデフォルト有で効になりました。1.32 からアルファとして追加されていたものです。

  以前は 破損オブジェクトは単に 500 エラーが返っていましたが、以下のように分かりやすいエラーが返るようになりました。削除では、 delete と unsafe-delete-ignore-read-errors 権限を持つユーザが ignoreStoreReadErrorWithClusterBreakingPotential オプションを使って実行できます。(１つ下の変更で dry-run も併用できるようになりました)

  $ kubectl get secret my-secret -n default
  Error from server (InternalError): Internal error occurred: StorageError: corrupt object, Code: 7, Key: /registry/secrets/default/my-secret, ResourceVersion: 0, AdditionalErrorMsg: data from the storage is not transformable revision=0: no matching prefix found
  
  # ignoreStoreReadErrorWithClusterBreakingPotential optionで削除
  $ kubectl delete --raw '/api/v1/namespaces/default/secrets/my-secret?ignoreStoreReadErrorWithClusterBreakingPotential=true&dryRun=All'
  {"kind":"Status","apiVersion":"v1","metadata":{},"status":"Success","details":{"name":"my-secret","kind":"Secret"},"code":200}
  

  詳しくは KEP-3926: Handling undecryptable resources を確認してください。

• 安全でない破損オブジェクトの削除に dry-run サポートを追加し、管理者が削除操作を実際に実行する前に安全にテストできます。 (#134037)

• ⭐ StorageVersionMigration の conditions に進捗報告を追加し、マイグレーションで処理されたオブジェクト数を確認できます。 (#138875)

  📝 StorageVersionMigration の進捗状況が status.conditions から読めるようになりました。詳細はKEP-4192: Move Storage Version Migrator in-tree を参照してください。

HPA

• HPAConfigurableTolerance FeatureGate を GA に昇格しました。 (#140107)

  📝 HPA のスケール判定の許容幅をワークロードごとに調整できる機能が GA しました。v1.35 からベータで、デフォルト有効でした。小さなメトリクス変動による頻繁なスケールを抑えたい場合に使えます。

  KEP-4951: Configurable tolerance for Horizontal Pod Autoscalers

• HorizontalPodAutoscaler の conditions に、条件が記録された時点の observedGeneration をオプションで含められるようにしました。 (#138653)

• HorizontalPodAutoscaler リソースにおいて metadata.generation および status.observedGeneration フィールドを生成します。 (#138228)

🐛 Bug or Regression (バグ修正)

CEL と Admission ポリシー

• CRD の metadata.name および metadata.generateName に対する CEL コスト見積もりを修正し、それらのメタデータフィールドに追加のバリデーションが定義されていない限り、デフォルトの最大長 253 文字を正しく考慮します。 (#139573)

  📝 CRD 名の上限は 253 文字ですが、以前は無限長として見積もられていました。

• ⭐ set および map リストに対する CEL の動作を修正しました。等価性比較（==）で重複を含むリストが一致しなくなり、連結（+）で追加された要素に対して set および map のマージセマンティクスが正しく適用されました。 (#140293)

  📝 CELでは、set または map のリストを扱うための以下の演算子があります。これらが、今回の変更で定義どおりの動きをするようになりました。

  • ==: 要素の順序を無視して比較する (集合として比較)
  • +: set リストは和集合になる。map リストはキーが同じ要素を右側の値で上書きし、新しいキーの要素は末尾に追加する

  たとえばspec.tags: ["a", "b", "c"] という set リストがあった時、各 CEL 式を評価すると次のようになります。

  CEL 式	変更前	変更後
  self.tags == ['c', 'b', 'a']	true	true (順序は無視)
  self.tags == ['a', 'a', 'b']	true	false

  == の修正: 変更前は「要素数が同じ」かつ「右辺の各要素が左辺に含まれる」だけで一致と判定していました。今回右辺が左辺のすべての要素を含んでいるかを確認するようになりました。

  + の修正: 戻り値自体は正しい動きをしていましたが、左辺のリスト(self.tags)の内部キャッシュまで書き換えていました。そのため、変数で同じリストを使い回すと、後続の演算結果が変わっていました。

• quantity.Add がレシーバーを変更（mutate）してしまう CEL のバグを修正しました。 (#140556)

• audit アクションを持つ複数の ValidatingAdmissionPolicy バインディングに一致するリクエストにおいて、最初のバリデーション失敗のみが audit アノテーションに記録されていた kube-apiserver のバグを修正しました。すべての audit 失敗が単一のアノテーションに出力されます。 (#140001)

• 3つのキーを持つ型付きマップリストに対して CEL 式を評価する際に admission コントローラーがパニックを引き起こす可能性があったバグを修正しました。 (#140386)

• キャッシュミスによりパラメータオブジェクトが別のパス経由でロードされた際に、ValidatingAdmissionPolicy および MutatingAdmissionPolicy の評価においてオブジェクト表現の微妙な違い（特に quantity フィールドや type meta フィールド周辺）が観測される可能性があったバグを修正しました。CEL 式は params に対して決定論的に動作します。 (#140201)

• 名前空間が削除された後も残存している名前空間付きオブジェクトへの更新が許可されるよう、admission の処理を修正しました。 (#140661)

• 不正な形式のオブジェクト削除が admission や適切に形成されたオブジェクトのグレースフルな削除をバイパスできてしまう可能性があったエッジケースを排除しました。 (#137582)

API サーバーとリソース管理

• --endpoint-reconciler-type に master-count または lease を使用する場合に kube-apiserver が --advertise-address の IP を検証するように変更し、指定された IP アドレスが Endpoints API オブジェクトに正常に永続化できることを保証しました。 (#138102)

• ホスト名が 63 バイトを超えているなどの理由で identity Lease を作成できなかった場合に、 kube-apiserver が SIGTERM で無期限にハングする問題を修正しました。 (#140241)

• ⭐ create-via-update および created-via-apply リクエストに対して、create リクエストと同様にメタデータフィールドを作成するように kube-apiserver を修正しました。 UID および resourceVersion の前提条件は引き続き尊重されます。 (#138908)

  📝 SSA など update/apply 経由で作成されたオブジェクトは、以前から create 時と同様にUIDやcreationTimestampはサーバ側で上書きされていましたが、 deletionTimestamp などはクライアントが送った値がそのまま保存されていました。(なので、その場合は作成直後から削除中になる)
  この変更により、(作成経由にかかわらず)それらのフィールドもサーバ側で処理されるようになりました。

StorageVersionMigration

• マイグレーションが保留中の間に CRD が削除された場合など、StorageVersionMigration が RESTMapper に存在しないリソースを対象とした場合に kube-controller-manager でパニックが発生する可能性があった問題を修正しました。 (#140586)

client-go と kubeconfig

• watch 確立時における 410 Gone（リソース期限切れ）エラーを、ERROR レベルではなくデバッグ詳細度（V(4)）でログ出力するように client-go の RetryWatcher を変更しました。 (#138295)

• Windows において .kube/config ディレクトリ外にある認証局（CA）パスが、他の OS の動作と一致せず相対パスに変換されていた処理を修正しました。 (#135735)

• kubeconfig ファイルを移行する際（例: ~/.kube/.kubeconfig から ~/.kube/config へ）、元のファイルのパーミッションを保持するように client-go を更新しました。以前は移行先ファイルがより緩いパーミッションで作成され、同一システム上の他のユーザーにクレデンシャルが露出するリスクがありました。 (#138142)

• ⭐ client-go: イベントハンドラーを閉じる前に、実行中のイベントハンドラーの完了を待機するサポートを追加しました。 (#139755)

• client-go: v0.36 で cache.Store インターフェースに追加されたメソッドに合わせて、 FakeCustomStore に Bookmark および LastStoreSyncResourceVersion メソッドを追加し、再びインターフェースを満たすようにしました。 (#140966)

🔬 Others (その他修正)

• ある型に対して宣言的バリデーション関数が登録されているかどうかを報告する HasValidationFunc メソッドを runtime.Scheme に追加しました。 (#140120)
• etcd 内の MutatingAdmissionPolicy および MutatingAdmissionPolicyBinding のストレージを admissionregistration.k8s.io/v1 バージョンに変更します。 (#137375)
• カスタムリソースに対する Server-Side Apply リクエストが、apply パスが完全に同期される前に更新された CustomResourceDefinition を観測してしまい、一貫性のない dry-run 動作を引き起こす可能性があった競合状態を修正しました。 (#140232)
• k8s.io/apiserver/pkg/server/options.EtcdOptions の no-op となっていた DefaultWatchCacheSize フィールドを削除しました。 (#134151)
• Service へプロキシする際に、 kube-apiserver の service/proxy サブリソースが Endpoints ではなく EndpointSlices を使用させます。この変更は、Service に対して手動で Endpoints を作成し、EndpointSlice のミラーリングを無効にしているクラスタにのみ影響します。 (#134860)
• kube-controller-manager の --concurrent-service-syncs フラグ（v1.31 以降 no-op）を削除しました。 (#138002)
• client-go の aggregated discovery 時に v2beta1 にフォールバックせず、v2 をリクエストさせます。 (#138271)
• client-go のリーダー選出 resourcelock パッケージにおいて、 MultiLock、 UnknownLeader、 ConcatRawRecord を非推奨にしました。 (#138070)
• v1.15 で非推奨となっていた kube-apiserver の --enable-logs-handler フラグの非推奨マークを解除しました。デフォルトでは引き続き無効です。 (#138915)
• kubeadm: サポート対象のコントロールプレーンバージョン v1.34, v1.35, v1.36 に対し、サポートする etcd バージョンを v3.6.11 に更新しました。 (#138746)