はじめに

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

今回も色々ありますが、API Machineryらしい変更でいうと恒例になってきたCELの拡張や、新しくアルファで追加されたCoordinatedLeaderElectionがあります。また、List APIの改善も進んでおり、ConsistentListFromCacheはベータに昇格、WatchListはベータに昇格したもののリバートされたので引き続きアルファです。(次のリリースv1.32は12/11予定です。)

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

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

Deprecation (非推奨になったAPI)

staging から k8s.io/legacy-cloud-providers を削除しました。（#124767）

API Changes (API周りの変更)

NodeRuntimeHandlerFeatures に UserNamespaces フィールドを追加しました。（#126034）
⭐ Coordinated Leader Election を CoordinatedLeaderElection FatureGate (Alpha) に追加しました。この機能を有効にすると、コントロールプレーンは LeaseCandidate オブジェクト（coordination.k8s.io/v1alpha1 API グループ）を使用してLeader Electionに参加し、kube-apiserver が特定の戦略に従って最適なインスタンスを選択できるようになります。（#124012）

📝 この機能は、k8sクラスタのアップグレード/ロールバック時の安定性向上を目的にした機能です。Cluster APIなど、node-by-nodeでクラスタアップグレードするのが一般的です。しかし、HA構成の場合、現在のLeaseを使ったリーダ選出(先勝ち式)を使っている kube-controller-manager(KCM) と kube-schedulerは "全てのAPIサーバのアップグレードが完了するまで、KCMとスケジューラは古いバージョンを使わなければならない" という version skew policy を満せないケースがあります。

apiVersion: coordination.k8s.io/v1alpha1
kind: LeaseCandidate
metadata:
 creationTimestamp: "2024-09-03T01:32:35Z"
 name: kind-control-plane_352dae03-4446-43d0-898c-28d4bf769255
 namespace: kube-system
 resourceVersion: "296"
 uid: 410ba746-b565-432f-acff-8147d7f8ab31
spec:
 binaryVersion: 1.31.0
 emulationVersion: 1.31.0
 leaseName: kube-scheduler
 preferredStrategies:
 - OldestEmulationVersion
 renewTime: "2024-09-03T01:32:35.412451Z"

今回導入された CoordinatedLeaderElection では、指定した戦略に基づいてリーダが選出できます。今回追加されたのは、 OldestEmulationVersion という戦略のみで、LeaseCandidateリソースのバイナリバージョンやCreationTimestampから一番古いバージョンだと推測される候補をリーダとして選出します。CoordinatedLeaderElection FatureGateを有効にすると KCMとスケジューラがこの戦略をつかったリーダ選出を実施します。詳しくは KEP-4355 を参照してください。

Nodes に .status.features.supplementalGroupsPolicy フィールドを追加しました。このフィールドは、CRI 実装（KEP-3619）に機能が実装されている場合に true になります。（#125470）
各コンテナのステータスに allocatedResourcesStatus を追加し、デバイスプラグインによって公開されたデバイスの正常性ステータスを示すようにしました。（#126243）
⭐ CEL 拡張ライブラリの厳密なコスト計算を強制するために、 StrictCostEnforcementForVAP と StrictCostEnforcementForWebhooks のFatureGateを追加しました。このFatureGateは有効化が推奨されています。（#124675）

📝 Common Expression Language (CEL) では、APIサーバへの過度な負荷を防ぐためにCEL式の評価コストが高すぎる場合はエラーを返すようになっています。

ValidatingAdmissionPolicy ...: operation cancelled: actual cost limit exceeded

しかし、既存のCEL式のコスト計算では拡張ライブラリの評価が抜けていたため、正しいコストが計算できていませんでした。ValidatingAdmissionPolicyとAdmissionWebhookMatchConditionsは前回のv1.30でGAになっているので、新しいFeatureGateを追加する形でバグ修正が入っています。
FeatureGateの StrictCostEnforcementForVAP と StrictCostEnforcementForWebhooks を有効にすると、拡張ライブラリを使っている場合でも正しいコストが計算されます。(FeatureGate一覧ページには9/2時点で未掲載ですが利用できます。) また、この変更はv1.30にもcherry-pickされています。

Component-base/logs: Go >= 1.21 でコンパイルされた場合、component-base は klog を初期化する際に自動的に slog デフォルトロガーを設定するようになりました。（#120696）
API サーバが Ingress オブジェクトの .spec.defaultBackend を処理する方法が変更されました。ServerSide Applyでは、 .spec.defaultBackend がアトミックな構造体として扱われるようになりました。これにより、その構造体に値を設定するフィールドオーナーは、相互排他的なすべてのフィールドを所有します。ほとんどのユーザにとってこの変更の影響はありませんが、デフォルトのバックエンドポートを番号から名前に（またはその逆に）変更したいコントローラーは変更が容易になります。（#126207）
無効な、または証明書を含まない空ではない caBundle フィールドを持つ CustomResourceDefinition オブジェクトは、有効な caBundle が提供されるまで、ディスカバリーやエンドポイントに表示されません。CustomResourceDefinition の更新では、 caBundle フィールドを有効から無効に移行できなくなりました。これは既存の CustomResourceDefinition の提供が中断されるためです。（#124061）
Dynamic Resource Allocation (DRA): 各 namespace および特定のクラスを介して要求されたデバイス数に基づいて、ResourceClaim オブジェクトの数を v1.ResourceQuota メカニズムによって制限できる機能を追加しました。（#120611）
Dynamic Resource Allocation (DRA): pod.spec.recourceClaims 配列では、 source の間接参照が不要になりました。例えば、 source: resourceClaimTemplateName: my-template の代わりに、 resourceClaimTemplateName: my-template と記述できます。（#125116）
Dynamic Resource Allocation (DRA) の resource.k8s.io API グループバージョンを更新しました。主なユーザ向けインタフェースは引き続き ResourceClaim ですが、新バージョンの v1alpha3 には大幅な変更があります。以前のバージョンとは互換性がありません。（#125488）

📝 DRAのAPIバージョンがv1alpha3になりました。内部的にも様々な変更がありますが、APIリソースの構成も変わっています。また、kubeletのDRA gRPC APIはv1alpha4になりました。

> kubectl api-resources|grep resource.k8s.io # v1.30
podschedulingcontexts   resource.k8s.io/v1alpha2 true  PodSchedulingContext
resourceclaimparameters resource.k8s.io/v1alpha2 true  ResourceClaimParameters
resourceclaims          resource.k8s.io/v1alpha2 true  ResourceClaim
resourceclaimtemplates  resource.k8s.io/v1alpha2 true  ResourceClaimTemplate
resourceclasses         resource.k8s.io/v1alpha2 false ResourceClass
resourceclassparameters resource.k8s.io/v1alpha2 true  ResourceClassParameters
resourceslices          resource.k8s.io/v1alpha2 false ResourceSlice
---
> kubectl api-resources|grep resource.k8s.io # v1.31
deviceclasses          resource.k8s.io/v1alpha3 false DeviceClass
podschedulingcontexts  resource.k8s.io/v1alpha3 true  PodSchedulingContext
resourceclaims         resource.k8s.io/v1alpha3 true  ResourceClaim
resourceclaimtemplates resource.k8s.io/v1alpha3 true  ResourceClaimTemplate
resourceslices         resource.k8s.io/v1alpha3 false ResourceSlice

DRAについては @toVersus さんの [Kubernetes 1.30] Dynamic Resource Allocation の再構築がとても詳しいです。

ValidatingAdmissionPolicies の空のコレクションに items フィールドが含まれていない APIサーバのバグを修正しました。（#124568）
コントローラの参照を取得する際のディープコピー問題を修正しました。（#124116）
code-generator client-gen を api/v1 のようなパッケージ構造で動作するように修正しました。（#125162）
kube-schedulerログの "v1 Binding is deprecated in v1.6+" という誤った警告を修正しました。（#125540）
Job の managedBy フィールドのコメントを修正しました。（#124793）
PodAffinity/PodAntiAffinity の MatchLabelKeys/MismatchLabelKeys 機能がベータに昇格しました。（#123638）
JobPodFailurePolicy がGAに昇格し、デフォルトにロックされました。（#125442）
Job successPolicy フィールドがベータになりました。新しい reason ラベル "SuccessPolicy" および "CompletionsReached" は、 "jobs_finished_total" metricに追加されています。また、 JobSuccessPolicy FatureGateを有効にすると、Job Pod (.status.succeeded) が希望する完了数 (.spec.completions) に達したときに、Job に "SuccessCriteriaMet" と "Complete" の "CompletionsReached" の理由が付与されます。（#126067）
DisableNodeKubeProxyVersion FatureGateがベータに昇格しました。デフォルトで kubelet は Node の .status.kubeProxyVersion フィールドを設定しなくなります。（#123845）
新しい kubelet フラグ --fail-cgroupv1 (Bool値) を導入しました。（#126031）
K8s.io/apimachinery/pkg/util/runtime: PanicHandlers や ErrorHandlers で発生したパニックやエラーが発生したコンテキストを処理する新しい関数がサポートされました。コンテキストの設定が必要になります。また、ログ出力は非構造化から構造化になりました。（#121970）
KEP-1880: Multiple Service CIDRは、デフォルトでdual-write戦略を利用します。これは、異なるアロケーターを使用している kube-apiserver を実行する際に重複する IP がサービスに割り当てられる可能性があるためです。この動作は、FatureGateのDisableAllocatorDualWriteでオプトアウトできます。（#122047）
Kube-apiserver: ControllerRevision オブジェクトは、 data フィールドに有効な JSON データを含んでいることを検証するようになりました。（#125549）
Kube-controller-manager: horizontal-pod-autoscaler-upscale-delay と horizontal-pod-autoscaler-downscale-delay フラグが削除されました（v1.12 以降、非推奨かつ非機能）。（#124948）
PersistentVolumeLastPhaseTransitionTime がStableに昇格し、デフォルト有効になりました。（#124969）
StatefulSetStartOrdinal がStableに昇格しました。これにより、kube-apiserver および kube-controller-manager の --feature-gates=StatefulSetStartOrdinal=true フラグが不要になります。また、https://kubernetes.io/docs/reference/using-api/deprecation-policy/#deprecation のポリシーに従って削除予定です。（#125374）
VolumeAttributesClass FatureGateがベータ版に昇格しました（デフォルト無効）。この機能を使用するには、FatureGateと storage.k8s.io/v1beta1 API グループの有効化が必要です。（#126145）
kube-controller-manager から –volume-host-cidr-denylist および –volume-host-allow-local-loopback の非推奨のフラグを削除しました。（#124017）
CustomResourceValidationExpressions FatureGateを削除しました。（#126136）
Pod API が Alpha として追加されました。OCI ArtifactをSourceしにしたボリュームをサポートします。この機能は ImageVolume FatureGateで制御できます。（#125660）
Fine-grained Supplemental Groups Policyサポートしました（KEP-3619）。これにより、コンテナのプライマリ UID に対して、コンテナイメージで定義さしたグループ（/etc/groups）を含めるかを選択できます。（#117842）
⭐ 使いやすさと開発者体験を向上させるために、CRD Validation Rulesでは、CELの予約語を使ったフィールド名であっても直接参照できるようになりました。互換性の懸念から、この機能は次のリリースで完全にサポートします。（#126188）

📝 以前は、Validation Ruleでフィールドを参照する際に、フィールド名がCELの予約語と一致している場合には、 __{keyward}__ のようにエスケープする必要がありました。

The CustomResourceDefinition "test" is invalid: spec.validation.openAPIV3Schema.properties[spec].x-kubernetes-validations[0].rule: Invalid value: apiextensions.ValidationRule{Rule:"self.ref.namespace != \"\"", Message:"", MessageExpression:"", Reason:(*apiextensions.FieldValueErrorReason)(nil), FieldPath:"", OptionalOldSelf:(*bool)(nil)}: compilation failed: ERROR: <input>:1:9: undefined field 'namespace'
 | self.ref.namespace != ""
 | ........^

しかし、予約語にはnamespaceなどよく使うキーワードが含まれているのでユーザビリティが損なわれているという問題がありました。この変更によって、フィールド値が予約語都一致する場合でも、エスケープ無しで直接参照できるようになります。(予約語は現在ハードコードされています。)

v1.31では既存のruleに対してのみ適用されており、新規作成時にnamespaceなどの予約語を直接指定するとまだ失敗します。次のv1.32で新規作成時もサポート予定のようです。(ドキュメントもその時追加される予定)

MultiCIDRServiceAllocator がベータに昇格しました(デフォルト無効)。この機能を使用するには、FatureGateおよび networking v1beta1 グループの有効化が必要です。これにより、Service CIDR の範囲を動的に再構成できます。（#125021）
AnonymousAuthConfigurableEndpoints FatureGateが有効になっている場合、ユーザは匿名リクエストが許可されているエンドポイントで AuthenticationConfig ファイルを更新できます。（#124917）

Features (機能追加)

Custom resource フィールドセレクタがベータとして追加されました。デフォルト有効です。詳細は https://github.com/kubernetes/enhancements/issues/4358 を参照。（#124681）
Generic Control Plane セットアップ用に Extra.DisableAvailableConditionController を追加しました。（#125650）
cri-client のstagingリポジトリを追加しました。（#123797）
kubectl の WebSockets 経由の PortForward をオフにするには、環境変数FatureGateの明示的な設定が必要です。 PORT_FORWARD_WEBSOCKETS=false （#125528）
⭐ ConsistentListFromCache フラグがベータに昇格し、デフォルト有効になりました。（#123513）

ConsistentListFromCacheは1.28でAlphaで導入され、(ここ最近関連機能の変更が色々入っていましたが)、今回Betaに昇格しデフォルト有効になりました。この機能は、APIサーバ(&etcd)のパフォーマンス向上を目的として導入されたものです。

k8sのList/Get APIは、resourceVersionが指定されていない場合、etcdのQuorum Readを利用してReadの一貫性を保証しています。しかし、多くの場合、WatchCacheもReadのリクエストを返すのに十分な最新のデータを持っています。このWatchCacheを使って直接レスポンスできるとパフォーマンス向上が期待できるので、WatchCacheのReadもetcdと同等の一貫性を保証するように改善しようというものです。詳しくはKEP-2340を参照してください。

ConsistentListFromCache が有効な場合、非推奨の etcd バージョンを警告するためのチェックを追加しました。（#124612）

📝 etcdのprogress notification機能にバグがあったため、ConsistentListFromCacheが有効な場合、v3.3、v3.4.24、v3.5.7を使っていると警告が出ます。この機能を利用する際には、etcdの v3.4.25+ v3.5.8+ を利用してください。

⭐ CEL式と additionalProperties がCRDスキーマのネストされたquantifiers内で使えるようになりました。（#124381）

📝 CEL式はCRDスキーマのquantifiers(allOf, anyOf, oneOf)で利用できませんでしたが、この修正で使えるようになりました。

⭐ CEL: name formatライブラリを追加しました。（#123572）

📝 CELに、DNS名などのフォーマットに沿っているかなどをチェックするformatライブラリが追加されました。

format.dns1123Subdomain().validate("apiextensions.k8s.io")
format.uri().validate("http://example.com")
format.datetime().validate("2021-01-01T00:00:00Z")

まだ Kubernetes CEL libraries ドキュメントの方は更新されていませんが、そのうち使い方がここにも記載されると思います。

Client-go/reflector: 初期イベントのブックマークイベントが受信されていない場合に警告します。（#124614）
⭐ kube-apiserver の WatchList FatureGateがベータに昇格し、kube-controller-manager（KCM）で WatchListClient が有効になりました。（#125591）

📝 この変更は下のバグ修正の方でリバートされています。WatchListClientのFeatureGateはv1.31ではアルファのままです。

client-go の rest client に WatchList メソッドを追加しました。このメソッドを使用すると、サーバからデータの一貫したスナップショットを取得するストリームを確立できます。このメソッドはgenerated clientが利用します。（#122657）
client-go の List メソッドに新しい機能を導入し、ユーザが API ストリーミングを有効にできるようにしました。この機能を有効にするには、 client-go.WatchListClient FatureGateを設定してください。この機能を利用するには、サーバがストリーミングをサポートしている必要があります。サーバがストリーミングをサポートしていない場合、client-go は通常の LIST メソッドを使用してデータを取得します。（#124509）

📝 前回のv1.30でも見た記憶があるなと思いましたが、#122571の方はFeatureGateの追加だけで、今回のv1.31で実装が入りました。前回、client-goにもFeatureGateが追加されましたが、さっそく使われています。今のところ、この WatchListClient と、同じくv1.30で追加された InformerResourceVersion の2つです。

dynamic クライアントの List メソッドに新しい機能を追加しました。API ストリーミングを有効にできるようになります。この機能を有効にするには、 client-go.WatchListClient FatureGateを設定できます。この機能が正常に機能するには、サーバがストリーミングをサポートしている必要があります。サーバがストリーミングをサポートしていない場合、クライアントは通常の LIST メソッドを使用してデータを取得します。（#125305）
kube-apiserver のメモリ使用量を改善し、自己要求したInformerが必要としない .metadata.managedFields フィールドはdropされるようになりました。（#124667）
Client-side Applyによる作成時に、null 値を「この値に関連付けられたキーを削除する」と定義しました。（#125646）
Kube-apiserver: http/2 を無効にする --disable-http2-serving フラグを追加しました。（#122176）
ValidatingAdmissionPolicy（VAP）と CustomResourceDefinition（CRD）validation rulesのメトリクスがベータに昇格しました。（#126237）
CEL（Common Expression Language）のオプションタイプの名前が optional から optional_type に変更されました。（#124328）

Bug or Regression (バグ修正)

"-kube-test-repo-list" e2e フラグが有効にならないバグを修正しました。（#123587）
リソースが移行中に削除された場合、移行試行が失敗する storage-version-migrator-controller のバグを修正しました。（#126107）
Resync 中の transforming informer のバグによる kube-controller-manager とスケジューラーの競合状態を、変換関数を冪等にすることで修正しました。（#124352）
Server Side Apply がカスタムリソースへの no-op パッチで不要な resourceVersion の更新を引き起こすバグを修正しました。（#125263）
Kube-apiserver: 非推奨の /api/v1/watch/namespaces/$name エンドポイントを介して単一の namespace をWatchする際、Watchが確立された後にWatchイベントが配信されない 1.27+ のリグレッションを修正しました。（#125145）
Kube-apiserver: 無効なスキーマと CEL validation ruleを組み合わせた CustomResourceDefinitions を提供する際のクラッシュを修正しました。（#126167）
Kube-apiserver: –authorization-config ファイルで設定された認可 Webhook のタイムアウトが適切に適用されるようになり、Webhook メトリクスで result=timeout として正確に反映されるようになりました。（#125552）
admission プラグイン PersistentVolumeLabel を削除しました。類似の機能が必要な場合は、https://github.com/kubernetes-sigs/cloud-pv-admission-labeler を使用してください。（#124505）
"Graduates the WatchList feature gate to beta for kube-apiserver and enables WatchListClient for kube-controller-manager (KCM)" をリバートしました。（#126191）
client-gen で生成された "fake" クライアントがエラー時に本物のクライアントと同じセマンティクスを持つようになりました。失敗した Get()、Create() などは、 nil を返さなくなりました（今後は、本物のクライアントと同様にゼロ値のオブジェクトへのポインタを返します）。これにより、一部のダウンストリームユニットテストが result = nil= ではなく err ! nil= をテストしていると壊れる可能性があります。誤ったユニットテストによって隠されていたコードのバグが露見する可能性があります。（#122892）
Job: featureGate が有効かどうかにかかわらず、 SuccessCriteriaMet が successPolicy で Job に追加される可能性があるバグを修正しました。（#125429）

Others (その他修正)

API Priority and Fairness が 1.29 で GA に昇格し、それに伴い対応するFatureGate 'APIPriorityAndFairness' が 1.31 で削除されました。（#125846）
etcd イメージの v3.5.13 をビルドしました。（#124026）
Etcd を v3.5.13 に更新しました。（#124027）
kube-scheduler の "/livez" と "/readz" エンドポイントを公開し、https://kubernetes.io/docs/reference/using-api/health-checks/#api-endpoints-for-health に準拠したヘルスチェックを行えるようにしました。（#118148）
Kube-apiserver: 既に非推奨となっていた --enable-logs-handler フラグとログ提供機能がデフォルトで無効になりました。v1.33 で削除予定です。（#125787）
reflector から ENABLE_CLIENT_GO_WATCH_LIST_ALPHA 環境変数を削除しました。この機能を有効にするには、 KUBE_FEATURE_WatchListClient 環境変数、または対応するコマンドラインオプションを設定してください（これは明示的に機能を公開するバイナリでのみ動作します）。（#122791）