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

はじめに

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

今回はAPI Machineryとしての大きな変更はありませんでしたが小ネタが色々あります。個人的な気になり変更は EnvFiles, APFのListのコスト見積もり方法の変更、zero値のcreationTimestampのomit, Long Name Deploymentのbug あたりです。

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

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

🗑️ Deprecation (非推奨になったAPI)

• Apimachinery: MessageCountMap と CreateAggregateFromMessageCountMap が非推奨になりました。 (#132376)
• kubeconfig の preferences フィールドを kuberc へ移行するため非推奨になりました。 (#131741)

🌏 API Changes (API周りの変更)

• apply configuration 型で実装される runtime.ApplyConfiguration インターフェイスを追加しました。 (#132194)

  📝 applyconfigを使うオブジェクトと判定するために、生成 IsApplyConfiguration() 関数を持つ runtime.ApplyConfiguration インターフェースが追加されました。このインタフェースは、 applyconfiguration-gen の生成時と各コントローラがSSAを使う際に利用している unstructured.Unstructured にも実装されています。

• Pod のInplace Vertical Scaling完了を知らせる詳細イベントを追加し、クラスタ運用とデバッグを改善しました。 (#130387)

  📝 inplace scaling完了時に、 ResizeCompleted Eventが記録されるようになりました。EventのMessageには完了後のresourceサイズなども含まれます。

• コンテナ再起動を細かく制御できる container-level restart rules (Alpha、 ContainerRestartRules FeatureGate) を追加しました。 (#132642)

  📝 前回Alphaで導入された ContainerRestartRules がBetaになりました。これを利用すると、initContainerとメインコンテナで異なる再起動ポリシを設定できます。他のユースケースとしては、AIワークロードの失敗時に再スケジュールさせずにin-placeに再起動したいということが書かれています。最近、Googleの人々がこの機能やJobSetなどでin-place restartまわりを整備しようとしていて、そこらへんで困っているケースがあるのかなと気になりです。しかし、ライフサイクルがだいぶ複雑化してきて、何かあったときデバッグ大変そうだなという気持ちもあります。詳しくは、Alpha機能の公式ブログで解説されています。

• コンテナに新しい FileKeyRef フィールドを追加し、ファイルから環境変数を読み込めるようにしました。 EnvFiles FeatureGateを導入しました。 (#132626)

  📝 FeatureGateに EnvFiles がAlphaで追加されました。これはその名の通りコンテナ内のファイルから環境変数を読み込めるようにする機能です。"initContainerで生成した環境変数をメインコンテナで読みたい" ということが稀によくありますが、そんなときにメインコンテナへ手を入れずに完結するので便利そうです。

• 割り当て済みデバイス間で指定属性の一意性を強制する制約タイプを追加しました。 (#132522)

• ResouceSlice.Basic と ResourceClaim.Status.AllocatedDeviceStatus に新しい任意 API を追加しました。 (#130160)

• JWT 認証で AuthenticationConfiguration.jwt 配列の issuer.egressSelectorType に controlplane と cluster の egress selector を指定できるようになりました。デフォルト値は今まで通り未選択です。 StructuredAuthenticationConfigurationEgressSelector (Beta/デフォルト有効) が必要です。 (#132768)

• PodSpec の hostnameOverride フィールドで RFC1123 DNS サブドメインを任意指定できるようになりました。制御用に HostnameOverride FeatureGateを追加しました。 (#132558)

  📝 Alpha機能として HostnameOverride が追加されました。ユースケースとしてはKerberosのように認証時にhostnameを利用するサービスなどに利用するための機能で、pod内のhostnameだけを書き換えますが、k8sのDNSレコードには影響をあたえません。既存の hostname, subdomain, setHostnameAsFQDN との関係はKEPの表にまとまっています。

• Dynamic Resource Allocation のコア機能を GA (安定版) に昇格しました。安定版は structured parameters 方式です。 (#132706)

• kube-apiserver で PodCertificateRequest と PodCertificate の projected volume をサポートしました ( PodCertificateRequest FeatureGate)。 (#128010)

• DRA バックエンドの拡張リソースではクラスタ管理者が DeviceClass に extendedResourceName を指定でき、アプリ側は Pod の requests で引き続き拡張リソースによって一致する DRA デバイスを要求できます。 NodeResourcesFit のスコアリングは DRA バック拡張リソースでは動作しません。 (#130653)

• CRD スキーマで k8s-short-name と k8s-long-name の OpenAPI format をサポートしました。 (#132504)

• admissionregistration.k8s.io/v1beta1/MutatingAdmissionPolicy API タイプを導入しました。利用には MutatingAdmissionPolicy FeatureGateを有効化 (デフォルト無効) し kube-apiserver に --runtime-config=admissionregistration.k8s.io/v1beta1=true を指定します。1.34 では保存バージョンは alpha のままなので Beta を有効化する場合は etcd 内の alpha データに依存しないようストレージマイグレーションが必要です。 (#132821)

• kube-apiserver: --authorization-config ファイルで認可 Webhook 判定のキャッシュを無効化できるようになりました。 cacheAuthorizedRequests と cacheUnauthorizedRequests を false に設定できます。詳細はドキュメントを参照してください。 (#129237)

• kube-apiserver: StructuredAuthenticationConfiguration FeatureGateを GA に昇格しました。 (#131916)

• kube-apiserver: --authentication-config で受理する AuthenticationConfiguration タイプを apiserver.config.k8s.io/v1 に昇格しました。 (#131752)

• VolumeAttributesClass / VolumeAttributesClassList API を storage.k8s.io/v1 に昇格しました。 (#131549)

• APIServerTracing FeatureGateを GA に昇格しました。 --tracing-config-file は apiserver.config.k8s.io/v1 の TracingConfiguration を受理します (v1beta1 から変更なし)。 (#132340)

• AuthorizeWithSelectors と AuthorizeNodeWithSelectors FeatureGateをGAし、つねに有効化しました。 (#132656)

• k8s.io/cri-api から非推奨 gogo protocol 定義を削除し google.golang.org/protobuf へ移行しました。 (#128653)

• Boolean ポインタ補助関数を k8s.io/utils/ptr 実装に置換しました。 (#132794)

• apiextensions-apiserver apiextensions で非推奨 k8s.io/utils/pointer を k8s.io/utils/ptr に置換しました。 (#132723)

• apiserver (1/2) で非推奨 k8s.io/utils/pointer を k8s.io/utils/ptr に置換しました。 (#132751)

• component-base で非推奨 k8s.io/utils/pointer を k8s.io/utils/ptr に置換しました。 (#132754)

• kube-aggregator apiregistration で非推奨 k8s.io/utils/pointer を k8s.io/utils/ptr に置換しました。 (#132701)

• 無効フィールドのバリデーションエラーから冗長なフィールド名を除去し簡素化しました。 (#132513)

• 必須フィールドのバリデーションエラーから冗長メッセージを除去し簡素化しました。 (#132472)

• validation-gen コードジェネレータが validation ratcheting をサポートするコードを生成するようになりました。 (#132236)

  📝 validation-genはKEP-5073のいままで手書きでがんばっていたk8sリソースのvalidationを、tagをつかって宣言的に定義してvalidation-genで自動生成させようというものです。今回はこのvalidation-genのコードにvalidation ratchetingのための検証前オブジェクト比較がはいりました。validation ratchetingはリソースのPATCH/UPDATE時に、変更していないフィールドのバリデーションエラーを無視するための機能です。ユーザ影響を気にしてCRDのバリデーションを変更できない…という悩みを解決してくれます。この機能自体は、前回のv1.33でGAしています。

• etcd バージョンを v3.6.0 に更新しました。 (#131501)

• metadata.creationTimestamp のゼロ値を出力から省略し JSON/YAML/CBOR で明示的な null をシリアライズしないよう変更しました。 (#130989)

  📝 CreationTimestampはpointerではないので、tagにomitemptyがついていたものの0はomitされていませんでした。これどうにかしようと2018年からissueはたっていたのですが、pointerに型をかえるのも影響おおきいのでpriority的ににそのままになってました。Go 1.24で omitzero を omitemptyとともに指定すると0のときomitされるという変更が入ったので、 omitzero を追加することで解決しました。podをwrapしているjobsetでこのcreationTimestamp起因のログがよごれる問題があったので解決してめでたい。

• MultiCIDRServiceAllocator と DisableAllocatorDualWrite をデフォルト有効化しました。 (#131318)

✨ Features (機能追加)

• SizeBasedListCostEstimate FeatureGateを追加し、apiserver が LIST リクエストのコスト算出用にオブジェクトサイズ推定を可能にしました。 (#132355)

  📝 k8s docのfeature gateのページにはまだ記載がありませんが、 SizeBasedListCostEstimate はv1.34でBeta (デフォルト有効) で追加されました。この変更はAPFでListリクストのコスト計算にアイテム数をつかっていると、大きなリクエストの際にオブジェクトサイズによって実際のメモリ使用量に大きな乖離があり、OOMがふせげないという問題を解決するために導入されました。この機能では、オブジェクトの平均サイズをetcd cacheから算出し、オブジェクトではなくデータ量(100KB単位)でシート数を計算するようになったようです。これにあわせて、ListリクエストのMaxシート数が100に変更されています。また、APFについては去年のkubernetes meetup tokyo #63で解説しています。

• coordinated leader electionのためのフラグを kube-apiserver に追加しました。 (#132433)

• 構造化認証設定でエスケープが必要な名前を含む CEL 式をサポートしました。名前に特殊文字がある場合は [...] でアクセスすることを推奨します。 has が使えない場面では ? オプショナルを利用できます (例: claims[?"kubernetes.io"], user.extra[?"domain.io/foo"])。 (#131574)

• 新しい kubectl 出力フォーマット kyaml を追加しました。KYAML は YAML の厳密なサブセットで任意の YAML プロセッサが受理可能です。JSON と YAML の中間的で明示的な表記により誤りを減少させます。 (#132942)

• DetectCacheInconsistency FeatureGateを追加し、API Server が定期的に cache と etcd の整合性を検証し、不一致を apiserver_storage_consistency_checks_total で報告し該当スナップショットをパージするようにしました。 (#132884)

• (デフォルト有効) SizeBasedListCostEstimate により LIST リクエストの APF 座席割当方式を変更しました。100KB ごとに 1 seat を割り当てます。 (#132932)

  📝 #1323555の関連PRです。

• kube-apiserver に有用なエンドポイントを追加しました。 (#132581)

  📝 changelogのメッセージがザックリですが、 利用可能なエンドポイント一覧を返す /statusz を kube-apiserver に追加したという変更です。

• 認識できないフォーマットを含む CustomResourceDefinitions の扱いを変更しました。未知のフォーマットを書くと警告を出すようになります。(ひきつづき受け付けられます) (#133136)

• watch キャッシュで etcd 圧縮イベントに基づくコンパクトスナップショットを有効化しました。 (#132876)

• ListFromCacheSnapshot を Beta に昇格しました。 (#132901)

  📝 前回の1.33にAlphaで追加された機能が、Beta (デフォルト有効)になりました。この機能は、APIサーバのキャッシュ機能を拡張して、全てのListリクエストをetcdにバイパスすることなくキャッシュから提供できるようにするものです。

• ResilientWatchCacheInitialization を GA に昇格しました。 (#131979)

  📝 1.31でAlphaをスキップしてベータ(デフォルト有効)で導入された機能がGAになりました。この機能は、未初期化時にリクエストをハングさせたり、全てetcdに移譲するのではなく、負荷が高くなりすぎないリクエストだけetcdに流し、のこりは429エラーを返す機能です。

• StreamingCollectionEncodingToJSON と StreamingCollectionEncodingToProtobuf を GA に昇格しました。 (#132648)

  📝 前回の1.33でアルファをスキップしてBeta (デフォルト有効) で導入された機能がGAしました。これは、メモリ消費を抑えるため、APIサーバのレスポンスエンコーディングを改善する機能です。

• 認証設定ファイルで匿名認証用エンドポイントの設定機能を安定版に昇格しました。 (#131654)

• ConsistentListFromCache を GA に昇格しました。 (#132645)

  📝 1.28でAlpha, 1.31でBeta (デフォルト有効) になっていた機能がGAしました。これは、resourceVersionが指定されていないList/Getの読み取り一貫性をetcdのquoram readと同等であることを保証する機能です。

• kube-apiserver で WatchList FeatureGateを Beta にし、KCM で WatchListClient を有効化しました。 (#132704)

  📝 1.27でAlpha -> 1.32でBeta (デフォルト有効) -> 上のStreaming FGが代替として 1.33で非推奨になりましたが、再びBeta (デフォルト有効) に戻りました。

• LIST リクエストの APF 最大 seat を 100 に増加しました。 (#133034)

  📝 上の#132355のListリクエストのコスト算出精度があがったことに伴う変更です。バケット数が増え、最大シート数が100になりました。小規模サーバには影響がなく、大規模なAPIサーバにおいてメモリ使用量の削減が検証されています。

• kube-apiserver: --etcd-servers-overrides で指定した各 etcd override セットに etcd-override-<index> / etcd-override-readiness-<index> ヘルスチェックを追加しました (既存の ?exclude=etcd 等で除外可能)。 (#129438)

• kube-apiserver: サービスアカウントトークンの外部署名と公開鍵取得を可能にする ExternalServiceAccountTokenSigner を Beta に昇格しました。FeatureGate有効化と --service-account-signing-endpoint 指定 (ファイル上の Unix ソケットパス、または @ で abstract namespace) が必要です。 (#131300)

• LeaseLock がホルダー切替時に上書きされるカスタムラベルを持てるようになりました。 (#131632)

• CertificateSigningRequest のバリデーションを宣言的バリデーションへ移行しました。 DeclarativeValidation 有効で差異報告し、 DeclarativeValidationTakeover 有効で主エラー源になります。 (#132361)

• Ordered Namespace Deletion テストを Conformance に昇格しました。 (#132219)

• OrderedNamespaceDeletion を GA に昇格しました。 (#131514)

• デフォルト APF から "endpoint-controller" と "workload-leader-election" FlowSchema を削除しました。ワークロードのリーダー選出ロックタイプを configmapsleases/endpointsleases から leases への移行が必要です。 (#131215)

• CertificateSigningRequest /status /approval サブリソースのバリデーションを宣言的バリデーションへ移行しました。 (#133068)

• kube-controller-manager のEventをコンテキスト付きロギングに対応しました。 (#128351)

• 集約 API サーバープロキシが、Endpoints ではなく Service に紐づく EndpointSlices を利用するよう変更しました。手動でエンドポイントを管理している場合は EndpointSlice を作成 (必要なら Endpoints と併用) してください。 (#129837)

🐛 Bug or Regression (バグ修正)

• SharedInformers でトランスフォーマが提供され WatchList 有効時、保存前にオブジェクトを変換するように保証しました。 (#131799)

• StorageClassList クエリで ResourceVersion が大きすぎる場合に穏当なエラーメッセージを返すよう修正しました。 (#132374)

• CEL の common.UnstructuredToVal でフィールドが存在し値が null の場合に同一オブジェクト比較 == が false になるバグを修正しました (Kubernetes API への影響なし)。 (#131559)

• 長すぎる Deployment 名で ReplicaSet 作成に失敗するバグを修正しました。 (#132560)

  📝 まだそんなバグ残っていたんだ...みたいなバグでちょっとおもしろいですね。制限内で長いDeployment名でリソースを作成すると、Deployment Controllerは名前をtruncateしないので、ReplicaSet用のsuffix付与によって文字数制限を超え、ReplicaSetの作成に失敗するというものです。

• watch クライアントで watch 未停止時に発生し得るデッドロックを修正しました。 (#131266)

• 1.33 で導入された、一部ページネーション付き LIST がキャッシュではなく etcd にフォールバックする回帰バグを修正しました。 (#132244)

• 終了中の CustomResourceDefinition でも Server-Side Apply で CR を作成できていた問題を修正しました。 (#132467)

• kubelet トークンキャッシュが同名 ServiceAccount 再作成時に古いトークンを返す問題を修正しました (キャッシュが UID 認識に)。 TokenRequestServiceAccountUIDValidation (Beta/デフォルト有効) で TokenRequest の UID と SA UID の一致を保証します。 (#132803)

• 最大長制限付き x-int-or-string CRD スキーマのランタイムコスト推定を修正しました。 (#132837)

• kube-apiserver: 外部 SA トークン署名有効時の OIDC discovery ドキュメント公開を修正しました。 (#131493)

• node-expand-not-required 注釈付き PVC のサイズ拡張を停止しました。 (#131907)

• ガーベジコレクションコントローラが orphan 削除時に ownerReferences 変更と競合しないよう修正しました。 (#132632)

• kubectl create|delete|get|replace --raw コマンドが kubeconfig の server root path を尊重するよう修正しました。 (#131165)

🔬 Others (その他修正)

• json.Marshaler / json.Unmarshaler / encoding.TextMarshaler / encoding.TextUnmarshaler を実装する型の CBOR へのエンコード/デコードをトランスコードでサポートしました。 (#132935)

• cel-go 依存を v0.25.0 へ更新しました (差分: https://github.com/google/cel-go/compare/v0.23.2...v0.25.0)。 (#131444)

  📝 フィールドのquoteと、リストの先頭/末尾のアイテムを取得する関数が追加されました。

• Hack/update-codegen.sh が goimports と protoc を自動確保するよう変更しました。 (#131459)

• SeparateTaintEvictionController FeatureGateを GA に昇格しました (常時有効)。 (#122634)

• k8s.io/kms/apis から非推奨 gogo protocol 定義を削除し google.golang.org/protobuf へ移行しました。 (#132833)

• REST クライアントから API streaming サポートを削除しました。 (#132285)

• typed client の List() から API streaming サポートを削除しました。 (#132257)

• dynamic client の List() から API streaming サポートを削除しました。 (#132229)

• metadata client の List() から API streaming サポートを削除しました。 (#132149)

• watch ストリームの合成 "Bookmark" イベントから kubernetes.io/initial-events-list-blueprint アノテーションを削除しました。 (#132326)

• etcd バージョンを v3.6.1 に更新しました。 (#132284)

• etcd クライアントライブラリを v3.6.4 に更新しました。 (#133226)