Skip to content

KEP-4192: Remove obsolete fields from the API #5597

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open

KEP-4192: Remove obsolete fields from the API #5597

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
3d45e7b
KEP-4192: style change for the API section
stlaz Oct 1, 2025
7ae9f8b
KEP-4192: API changes
stlaz Sep 8, 2025
2010737
KEP-4192: remove protobuf tags from API structs
stlaz Sep 8, 2025
bb4daa3
KEP-4192: update ToC
stlaz Oct 1, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
201 changes: 85 additions & 116 deletions keps/sig-api-machinery/4192-svm-in-tree/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,6 @@
- [Risks and Mitigations](#risks-and-mitigations)
- [Design Details](#design-details)
- [APIs to move](#apis-to-move)
- [We will move following <a href="https://github.com/kubernetes-sigs/kube-storage-version-migrator/blob/60dee538334c2366994c2323c0db5db8ab4d2838/pkg/apis/migration/v1alpha1/types.go">APIs</a> 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)
- [<a href="https://github.com/kubernetes-sigs/kube-storage-version-migrator/tree/60dee538334c2366994c2323c0db5db8ab4d2838/pkg/controller">Controller</a> to move](#controller-to-move)
- [<a href="https://github.com/kubernetes-sigs/kube-storage-version-migrator/tree/60dee538334c2366994c2323c0db5db8ab4d2838/pkg/migrator">Migrator Controller</a>](#migrator-controller)
Expand Down Expand Up @@ -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`.
Expand Down Expand Up @@ -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
Expand Down