From 3d45e7ba80d4f9c550801c8c5415fa5f95d25d69 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Stanislav=20L=C3=A1zni=C4=8Dka?= Date: Wed, 1 Oct 2025 15:35:18 +0200 Subject: [PATCH 1/4] KEP-4192: style change for the API section MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Stanislav Láznička --- .../4192-svm-in-tree/README.md | 222 +++++++++--------- 1 file changed, 110 insertions(+), 112 deletions(-) diff --git a/keps/sig-api-machinery/4192-svm-in-tree/README.md b/keps/sig-api-machinery/4192-svm-in-tree/README.md index 682fbc4150f..c6216a11959 100644 --- a/keps/sig-api-machinery/4192-svm-in-tree/README.md +++ b/keps/sig-api-machinery/4192-svm-in-tree/README.md @@ -121,118 +121,116 @@ As an end user using encryption at rest, whenever the key change is detected we ## Design Details ### APIs to move -#### We will move following [APIs](https://github.com/kubernetes-sigs/kube-storage-version-migrator/blob/60dee538334c2366994c2323c0db5db8ab4d2838/pkg/apis/migration/v1alpha1/types.go) in-tree: -- `v1alpha1` of `storageversionmigrations.migration.k8s.io` - - ```go - // StorageVersionMigration represents a migration of stored data to the latest - // storage version. - type StorageVersionMigration struct { - metav1.TypeMeta `json:",inline"` - // Standard object metadata. - // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - // +optional - metav1.ObjectMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"` - // Specification of the migration. - // +optional - Spec StorageVersionMigrationSpec `json:"spec,omitempty" protobuf:"bytes,2,opt,name=spec"` - // Status of the migration. - // +optional - Status StorageVersionMigrationStatus `json:"status,omitempty" protobuf:"bytes,3,opt,name=status"` - } - - // Spec of the storage version migration. - type StorageVersionMigrationSpec struct { - // The resource that is being migrated. The migrator sends requests to - // the endpoint serving the resource. - // Immutable. - Resource GroupVersionResource `json:"resource" protobuf:"bytes,1,opt,name=resource"` - // The token used in the list options to get the next chunk of objects - // to migrate. When the .status.conditions indicates the migration is - // "Running", users can use this token to check the progress of the - // migration. - // +optional - ContinueToken string `json:"continueToken,omitempty" protobuf:"bytes,2,opt,name=continueToken"` - // TODO: consider recording the storage version hash when the migration - // is created. It can avoid races. - } - - // The names of the group, the version, and the resource. - type GroupVersionResource struct { - // The name of the group. - Group string `json:"group,omitempty" protobuf:"bytes,1,opt,name=group"` - // The name of the version. - Version string `json:"version,omitempty" protobuf:"bytes,2,opt,name=version"` - // The name of the resource. - Resource string `json:"resource,omitempty" protobuf:"bytes,3,opt,name=resource"` - } - - type MigrationConditionType string - - const ( - // Indicates that the migration is running. - MigrationRunning MigrationConditionType = "Running" - // Indicates that the migration has completed successfully. - MigrationSucceeded MigrationConditionType = "Succeeded" - // Indicates that the migration has failed. - MigrationFailed MigrationConditionType = "Failed" - ) - - // Describes the state of a migration at a certain point. - type MigrationCondition struct { - // Type of the condition. - Type MigrationConditionType `json:"type" protobuf:"bytes,1,opt,name=type,casttype=MigrationConditionType"` - // Status of the condition, one of True, False, Unknown. - Status corev1.ConditionStatus `json:"status" protobuf:"bytes,2,opt,name=status,casttype=k8s.io/api/core/v1.ConditionStatus"` - // The last time this condition was updated. - // +optional - LastUpdateTime metav1.Time `json:"lastUpdateTime,omitempty" protobuf:"bytes,3,opt,name=lastUpdateTime"` - // The reason for the condition's last transition. - // +optional - Reason string `json:"reason,omitempty" protobuf:"bytes,4,opt,name=reason"` - // A human readable message indicating details about the transition. - // +optional - Message string `json:"message,omitempty" protobuf:"bytes,5,opt,name=message"` - } - - // Status of the storage version migration. - type StorageVersionMigrationStatus struct { - // The latest available observations of the migration's current state. - // +patchMergeKey=type - // +patchStrategy=merge - // +listType=map - // +listMapKey=type - // +optional - Conditions []MigrationCondition `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type" protobuf:"bytes,1,rep,name=conditions"` - // ResourceVersion to compare with the GC cache for performing the migration. - // This is the current resource version of given group, version and resource when - // kube-controller-manager first observes this StorageVersionMigration resource. - ResourceVersion string `json:"resourceVersion,omitempty" protobuf:"bytes,2,opt,name=resourceVersion"` - // LastMigratedResourceNameHash is use to pick up migration from where it left off in case of failure. - LastMigratedResourceNameHash string `json:"lastMigratedResourceNameHash,omitempty" protobuf:"bytes,3,opt,name=lastMigratedResourceNameHash"` - } - - // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object - // +k8s:prerelease-lifecycle-gen:introduced=1.30 - - // StorageVersionMigrationList is a collection of storage version migrations. - type StorageVersionMigrationList struct { - metav1.TypeMeta `json:",inline"` - - // Standard list metadata - // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - // +optional - metav1.ListMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"` - // Items is the list of StorageVersionMigration - // +patchMergeKey=type - // +patchStrategy=merge - // +listType=map - // +listMapKey=type - Items []StorageVersionMigration `json:"items" listType:"map" listMapKey:"type" patchStrategy:"merge" patchMergeKey:"type" protobuf:"bytes,2,rep,name=items"` - } - ``` - -- APIs in-tree will be _converted to `built-in types`_ from CRD. +The following API of the `storageversionmigrations.migration.k8s.io` API group is +based on the [original out-of-tree API types](https://github.com/kubernetes-sigs/kube-storage-version-migrator/blob/60dee538334c2366994c2323c0db5db8ab4d2838/pkg/apis/migration/v1alpha1/types.go). + +```go +// StorageVersionMigration represents a migration of stored data to the latest +// storage version. +type StorageVersionMigration struct { + metav1.TypeMeta `json:",inline"` + // Standard object metadata. + // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata + // +optional + metav1.ObjectMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"` + // Specification of the migration. + // +optional + Spec StorageVersionMigrationSpec `json:"spec,omitempty" protobuf:"bytes,2,opt,name=spec"` + // Status of the migration. + // +optional + Status StorageVersionMigrationStatus `json:"status,omitempty" protobuf:"bytes,3,opt,name=status"` +} + +// Spec of the storage version migration. +type StorageVersionMigrationSpec struct { + // The resource that is being migrated. The migrator sends requests to + // the endpoint serving the resource. + // Immutable. + Resource GroupVersionResource `json:"resource" protobuf:"bytes,1,opt,name=resource"` + // The token used in the list options to get the next chunk of objects + // to migrate. When the .status.conditions indicates the migration is + // "Running", users can use this token to check the progress of the + // migration. + // +optional + ContinueToken string `json:"continueToken,omitempty" protobuf:"bytes,2,opt,name=continueToken"` + // TODO: consider recording the storage version hash when the migration + // is created. It can avoid races. +} + +// The names of the group, the version, and the resource. +type GroupVersionResource struct { + // The name of the group. + Group string `json:"group,omitempty" protobuf:"bytes,1,opt,name=group"` + // The name of the version. + Version string `json:"version,omitempty" protobuf:"bytes,2,opt,name=version"` + // The name of the resource. + Resource string `json:"resource,omitempty" protobuf:"bytes,3,opt,name=resource"` +} + +type MigrationConditionType string + +const ( + // Indicates that the migration is running. + MigrationRunning MigrationConditionType = "Running" + // Indicates that the migration has completed successfully. + MigrationSucceeded MigrationConditionType = "Succeeded" + // Indicates that the migration has failed. + MigrationFailed MigrationConditionType = "Failed" +) + +// Describes the state of a migration at a certain point. +type MigrationCondition struct { + // Type of the condition. + Type MigrationConditionType `json:"type" protobuf:"bytes,1,opt,name=type,casttype=MigrationConditionType"` + // Status of the condition, one of True, False, Unknown. + Status corev1.ConditionStatus `json:"status" protobuf:"bytes,2,opt,name=status,casttype=k8s.io/api/core/v1.ConditionStatus"` + // The last time this condition was updated. + // +optional + LastUpdateTime metav1.Time `json:"lastUpdateTime,omitempty" protobuf:"bytes,3,opt,name=lastUpdateTime"` + // The reason for the condition's last transition. + // +optional + Reason string `json:"reason,omitempty" protobuf:"bytes,4,opt,name=reason"` + // A human readable message indicating details about the transition. + // +optional + Message string `json:"message,omitempty" protobuf:"bytes,5,opt,name=message"` +} + +// Status of the storage version migration. +type StorageVersionMigrationStatus struct { + // The latest available observations of the migration's current state. + // +patchMergeKey=type + // +patchStrategy=merge + // +listType=map + // +listMapKey=type + // +optional + Conditions []MigrationCondition `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type" protobuf:"bytes,1,rep,name=conditions"` + // ResourceVersion to compare with the GC cache for performing the migration. + // This is the current resource version of given group, version and resource when +// kube-controller-manager first observes this StorageVersionMigration resource. + ResourceVersion string `json:"resourceVersion,omitempty" protobuf:"bytes,2,opt,name=resourceVersion"` + // LastMigratedResourceNameHash is use to pick up migration from where it left off in case of failure. + LastMigratedResourceNameHash string `json:"lastMigratedResourceNameHash,omitempty" protobuf:"bytes,3,opt,name=lastMigratedResourceNameHash"` +} + +// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object +// +k8s:prerelease-lifecycle-gen:introduced=1.30 + +// StorageVersionMigrationList is a collection of storage version migrations. +type StorageVersionMigrationList struct { + metav1.TypeMeta `json:",inline"` + + // Standard list metadata + // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata + // +optional + metav1.ListMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"` + // Items is the list of StorageVersionMigration + // +patchMergeKey=type + // +patchStrategy=merge + // +listType=map + // +listMapKey=type + Items []StorageVersionMigration `json:"items" listType:"map" listMapKey:"type" patchStrategy:"merge" patchMergeKey:"type" protobuf:"bytes,2,rep,name=items"` +} +``` #### Changes while we move above APIs in-tree: To avoid any conflicts with the Storage Version Migrators running out of tree, we will change the _`group`_ from `migration.k8s.io` to `storagemigration.k8s.io`. From 7ae9f8bd2b89a544826edd1d7485775e48cb4d6b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Stanislav=20L=C3=A1zni=C4=8Dka?= Date: Mon, 8 Sep 2025 15:29:20 +0200 Subject: [PATCH 2/4] KEP-4192: API changes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - move to metav1.Conditions - remove the unused ContinueToken field - rename LastMigratedResourceNameHash to LastMigratedResource Signed-off-by: Stanislav Láznička --- .../4192-svm-in-tree/README.md | 36 +++---------------- 1 file changed, 4 insertions(+), 32 deletions(-) diff --git a/keps/sig-api-machinery/4192-svm-in-tree/README.md b/keps/sig-api-machinery/4192-svm-in-tree/README.md index c6216a11959..68325cb01b1 100644 --- a/keps/sig-api-machinery/4192-svm-in-tree/README.md +++ b/keps/sig-api-machinery/4192-svm-in-tree/README.md @@ -147,14 +147,6 @@ type StorageVersionMigrationSpec struct { // the endpoint serving the resource. // Immutable. Resource GroupVersionResource `json:"resource" protobuf:"bytes,1,opt,name=resource"` - // The token used in the list options to get the next chunk of objects - // to migrate. When the .status.conditions indicates the migration is - // "Running", users can use this token to check the progress of the - // migration. - // +optional - ContinueToken string `json:"continueToken,omitempty" protobuf:"bytes,2,opt,name=continueToken"` - // TODO: consider recording the storage version hash when the migration - // is created. It can avoid races. } // The names of the group, the version, and the resource. @@ -178,23 +170,6 @@ const ( MigrationFailed MigrationConditionType = "Failed" ) -// Describes the state of a migration at a certain point. -type MigrationCondition struct { - // Type of the condition. - Type MigrationConditionType `json:"type" protobuf:"bytes,1,opt,name=type,casttype=MigrationConditionType"` - // Status of the condition, one of True, False, Unknown. - Status corev1.ConditionStatus `json:"status" protobuf:"bytes,2,opt,name=status,casttype=k8s.io/api/core/v1.ConditionStatus"` - // The last time this condition was updated. - // +optional - LastUpdateTime metav1.Time `json:"lastUpdateTime,omitempty" protobuf:"bytes,3,opt,name=lastUpdateTime"` - // The reason for the condition's last transition. - // +optional - Reason string `json:"reason,omitempty" protobuf:"bytes,4,opt,name=reason"` - // A human readable message indicating details about the transition. - // +optional - Message string `json:"message,omitempty" protobuf:"bytes,5,opt,name=message"` -} - // Status of the storage version migration. type StorageVersionMigrationStatus struct { // The latest available observations of the migration's current state. @@ -203,13 +178,11 @@ type StorageVersionMigrationStatus struct { // +listType=map // +listMapKey=type // +optional - Conditions []MigrationCondition `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type" protobuf:"bytes,1,rep,name=conditions"` + Conditions []metav1.Condition `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type"` // ResourceVersion to compare with the GC cache for performing the migration. // This is the current resource version of given group, version and resource when -// kube-controller-manager first observes this StorageVersionMigration resource. + // kube-controller-manager first observes this StorageVersionMigration resource. ResourceVersion string `json:"resourceVersion,omitempty" protobuf:"bytes,2,opt,name=resourceVersion"` - // LastMigratedResourceNameHash is use to pick up migration from where it left off in case of failure. - LastMigratedResourceNameHash string `json:"lastMigratedResourceNameHash,omitempty" protobuf:"bytes,3,opt,name=lastMigratedResourceNameHash"` } // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object @@ -385,9 +358,8 @@ total: #### Beta -- Feature is enabled by default -- All of the above documented tests are complete -- Leader election to make sure new controller can work with both CRD and in-tree APIs. +- Feature is enabled by default. +- All of the above documented tests are complete. - Using Garbage Collection Cache means using RV as an integer to validate the freshness of the cache. Approval from SigArch is required on this RV semantics. ### Upgrade / Downgrade Strategy From 2010737f33842d24f1cd9fcd93e91f6de56dddc3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Stanislav=20L=C3=A1zni=C4=8Dka?= Date: Mon, 8 Sep 2025 15:31:42 +0200 Subject: [PATCH 3/4] KEP-4192: remove protobuf tags from API structs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Stanislav Láznička --- .../4192-svm-in-tree/README.md | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/keps/sig-api-machinery/4192-svm-in-tree/README.md b/keps/sig-api-machinery/4192-svm-in-tree/README.md index 68325cb01b1..7f787cea5d0 100644 --- a/keps/sig-api-machinery/4192-svm-in-tree/README.md +++ b/keps/sig-api-machinery/4192-svm-in-tree/README.md @@ -132,13 +132,13 @@ type StorageVersionMigration struct { // Standard object metadata. // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata // +optional - metav1.ObjectMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"` + metav1.ObjectMeta `json:"metadata,omitempty"` // Specification of the migration. // +optional - Spec StorageVersionMigrationSpec `json:"spec,omitempty" protobuf:"bytes,2,opt,name=spec"` + Spec StorageVersionMigrationSpec `json:"spec,omitempty"` // Status of the migration. // +optional - Status StorageVersionMigrationStatus `json:"status,omitempty" protobuf:"bytes,3,opt,name=status"` + Status StorageVersionMigrationStatus `json:"status,omitempty"` } // Spec of the storage version migration. @@ -146,17 +146,17 @@ type StorageVersionMigrationSpec struct { // The resource that is being migrated. The migrator sends requests to // the endpoint serving the resource. // Immutable. - Resource GroupVersionResource `json:"resource" protobuf:"bytes,1,opt,name=resource"` + Resource GroupVersionResource `json:"resource"` } // The names of the group, the version, and the resource. type GroupVersionResource struct { // The name of the group. - Group string `json:"group,omitempty" protobuf:"bytes,1,opt,name=group"` + Group string `json:"group,omitempty"` // The name of the version. - Version string `json:"version,omitempty" protobuf:"bytes,2,opt,name=version"` + Version string `json:"version,omitempty"` // The name of the resource. - Resource string `json:"resource,omitempty" protobuf:"bytes,3,opt,name=resource"` + Resource string `json:"resource,omitempty"` } type MigrationConditionType string @@ -182,7 +182,7 @@ type StorageVersionMigrationStatus struct { // ResourceVersion to compare with the GC cache for performing the migration. // This is the current resource version of given group, version and resource when // kube-controller-manager first observes this StorageVersionMigration resource. - ResourceVersion string `json:"resourceVersion,omitempty" protobuf:"bytes,2,opt,name=resourceVersion"` + ResourceVersion string `json:"resourceVersion,omitempty"` } // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object @@ -195,13 +195,13 @@ type StorageVersionMigrationList struct { // Standard list metadata // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata // +optional - metav1.ListMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"` + metav1.ListMeta `json:"metadata,omitempty"` // Items is the list of StorageVersionMigration // +patchMergeKey=type // +patchStrategy=merge // +listType=map // +listMapKey=type - Items []StorageVersionMigration `json:"items" listType:"map" listMapKey:"type" patchStrategy:"merge" patchMergeKey:"type" protobuf:"bytes,2,rep,name=items"` + Items []StorageVersionMigration `json:"items" listType:"map" listMapKey:"type" patchStrategy:"merge" patchMergeKey:"type"` } ``` From bb4daa3b647386deaf0da25c0ed1dd0524c2d0d6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Stanislav=20L=C3=A1zni=C4=8Dka?= Date: Wed, 1 Oct 2025 15:49:05 +0200 Subject: [PATCH 4/4] KEP-4192: update ToC MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Stanislav Láznička --- keps/sig-api-machinery/4192-svm-in-tree/README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/keps/sig-api-machinery/4192-svm-in-tree/README.md b/keps/sig-api-machinery/4192-svm-in-tree/README.md index 7f787cea5d0..cc630000c5b 100644 --- a/keps/sig-api-machinery/4192-svm-in-tree/README.md +++ b/keps/sig-api-machinery/4192-svm-in-tree/README.md @@ -15,7 +15,6 @@ - [Risks and Mitigations](#risks-and-mitigations) - [Design Details](#design-details) - [APIs to move](#apis-to-move) - - [We will move following APIs in-tree:](#we-will-move-following-apis-in-tree) - [Changes while we move above APIs in-tree:](#changes-while-we-move-above-apis-in-tree) - [Controller to move](#controller-to-move) - [Migrator Controller](#migrator-controller)