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..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) @@ -121,118 +120,89 @@ 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"` + // Specification of the migration. + // +optional + Spec StorageVersionMigrationSpec `json:"spec,omitempty"` + // Status of the migration. + // +optional + Status StorageVersionMigrationStatus `json:"status,omitempty"` +} + +// 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"` +} + +// The names of the group, the version, and the resource. +type GroupVersionResource struct { + // The name of the group. + Group string `json:"group,omitempty"` + // The name of the version. + Version string `json:"version,omitempty"` + // The name of the resource. + Resource string `json:"resource,omitempty"` +} + +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" +) + +// 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 []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. + ResourceVersion string `json:"resourceVersion,omitempty"` +} + +// +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"` + // 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"` +} +``` #### 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`. @@ -387,9 +357,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