Update doc comments and change name of feature gate

pkg/apis/apps/types.go

@@ -146,10 +146,14 @@ type StatefulSetPersistentVolumeClaimRetentionPolicy struct {
 // StatefulSetOrdinals describes the policy used for replica ordinal assignment
 // in this StatefulSet.
 type StatefulSetOrdinals struct {
-	// Start is the number representing the first index that is used to represent
+	// start is the number representing the first replica's index. It may be used
-	// replica ordinals. Defaults to 0.
+	// to number replicas from an alternate index (eg: 1-indexed) over the default
-	// If set, replica ordinals will be numbered in the range:
+	// 0-indexed names, or to orchestrate progressive movement of replicas from
-	// [.spec.ordinals.start, .spec.ordinals.start + .spec.replicas).
+	// one StatefulSet to another.
+	// If set, replica indices will be in the range:
+	//   [.spec.ordinals.start, .spec.ordinals.start + .spec.replicas).
+	// If unset, defaults to 0. Replica indices will be in the range:
+	//   [0, .spec.replicas).
 	// +optional
 	Start int32
 }
@@ -227,11 +231,13 @@ type StatefulSetSpec struct {
 	// +optional
 	PersistentVolumeClaimRetentionPolicy *StatefulSetPersistentVolumeClaimRetentionPolicy
 
-	// Ordinals controls how the stateful set creates pod and persistent volume
+	// ordinals controls the numbering of replica indices in a StatefulSet. A
-	// claim names.
+	// StatefulSet will create pods with the format <statefulsetname>-<podindex>.
-	// The default behavior assigns a number starting with zero and incremented by
+	// For example, a pod in a StatefulSet named "web" with index number "3" would
-	// one for each additional replica requested. This requires the
+	// be named "web-3". The default ordinals behavior assigns a "0" index to the
-	// StatefulSetSlice feature gate to be enabled, which is alpha.
+	// first replica and increments the index by one for each additional replica
+	// requested. Using the ordinals field requires the StatefulSetStartOrdinal
+	// feature gate to be enabled, which is alpha.
 	// +optional
 	Ordinals *StatefulSetOrdinals
 }

pkg/apis/apps/validation/validation.go

@@ -130,7 +130,7 @@ func ValidateStatefulSetSpec(spec *apps.StatefulSetSpec, fldPath *field.Path, op
 
 	allErrs = append(allErrs, apivalidation.ValidateNonnegativeField(int64(spec.Replicas), fldPath.Child("replicas"))...)
 	allErrs = append(allErrs, apivalidation.ValidateNonnegativeField(int64(spec.MinReadySeconds), fldPath.Child("minReadySeconds"))...)
-	if utilfeature.DefaultFeatureGate.Enabled(features.StatefulSetSlice) {
+	if utilfeature.DefaultFeatureGate.Enabled(features.StatefulSetStartOrdinal) {
 		if spec.Ordinals != nil {
 			replicaStartOrdinal := spec.Ordinals.Start
 			allErrs = append(allErrs, apivalidation.ValidateNonnegativeField(int64(replicaStartOrdinal), fldPath.Child("ordinals.start"))...)
@@ -185,13 +185,13 @@ func ValidateStatefulSetUpdate(statefulSet, oldStatefulSet *apps.StatefulSet, op
 	newStatefulSetClone.Spec.Template = oldStatefulSet.Spec.Template               // +k8s:verify-mutation:reason=clone
 	newStatefulSetClone.Spec.UpdateStrategy = oldStatefulSet.Spec.UpdateStrategy   // +k8s:verify-mutation:reason=clone
 	newStatefulSetClone.Spec.MinReadySeconds = oldStatefulSet.Spec.MinReadySeconds // +k8s:verify-mutation:reason=clone
-	if utilfeature.DefaultFeatureGate.Enabled(features.StatefulSetSlice) {
+	if utilfeature.DefaultFeatureGate.Enabled(features.StatefulSetStartOrdinal) {
 		newStatefulSetClone.Spec.Ordinals = oldStatefulSet.Spec.Ordinals // +k8s:verify-mutation:reason=clone
 	}
 
 	newStatefulSetClone.Spec.PersistentVolumeClaimRetentionPolicy = oldStatefulSet.Spec.PersistentVolumeClaimRetentionPolicy // +k8s:verify-mutation:reason=clone
 	if !apiequality.Semantic.DeepEqual(newStatefulSetClone.Spec, oldStatefulSet.Spec) {
-		if utilfeature.DefaultFeatureGate.Enabled(features.StatefulSetSlice) {
+		if utilfeature.DefaultFeatureGate.Enabled(features.StatefulSetStartOrdinal) {
 			allErrs = append(allErrs, field.Forbidden(field.NewPath("spec"), "updates to statefulset spec for fields other than 'replicas', 'ordinals', 'template', 'updateStrategy', 'persistentVolumeClaimRetentionPolicy' and 'minReadySeconds' are forbidden"))
 		} else {
 			allErrs = append(allErrs, field.Forbidden(field.NewPath("spec"), "updates to statefulset spec for fields other than 'replicas', 'template', 'updateStrategy', 'persistentVolumeClaimRetentionPolicy' and 'minReadySeconds' are forbidden"))

pkg/apis/apps/validation/validation_test.go

@@ -86,7 +86,7 @@ func TestValidateStatefulSet(t *testing.T) {
 
 	const enableStatefulSetAutoDeletePVC = "[enable StatefulSetAutoDeletePVC]"
 
-	const enableStatefulSetSlice = "[enable StatefulSetSlice]"
+	const enableStatefulSetStartOrdinal = "[enable StatefulSetStartOrdinal]"
 
 	type testCase struct {
 		name string
@@ -196,7 +196,7 @@ func TestValidateStatefulSet(t *testing.T) {
 			},
 		},
 		{
-			name: "ordinals.start positive value " + enableStatefulSetSlice,
+			name: "ordinals.start positive value " + enableStatefulSetStartOrdinal,
 			set: apps.StatefulSet{
 				ObjectMeta: metav1.ObjectMeta{Name: "abc-123", Namespace: metav1.NamespaceDefault},
 				Spec: apps.StatefulSetSpec{
@@ -652,7 +652,7 @@ func TestValidateStatefulSet(t *testing.T) {
 			},
 		},
 		{
-			name: "invalid ordinals.start " + enableStatefulSetSlice,
+			name: "invalid ordinals.start " + enableStatefulSetStartOrdinal,
 			set: apps.StatefulSet{
 				ObjectMeta: metav1.ObjectMeta{Name: "abc-123", Namespace: metav1.NamespaceDefault},
 				Spec: apps.StatefulSetSpec{
@@ -684,8 +684,8 @@ func TestValidateStatefulSet(t *testing.T) {
 			if strings.Contains(name, enableStatefulSetAutoDeletePVC) {
 				defer featuregatetesting.SetFeatureGateDuringTest(t, utilfeature.DefaultFeatureGate, features.StatefulSetAutoDeletePVC, true)()
 			}
-			if strings.Contains(name, enableStatefulSetSlice) {
+			if strings.Contains(name, enableStatefulSetStartOrdinal) {
-				defer featuregatetesting.SetFeatureGateDuringTest(t, utilfeature.DefaultFeatureGate, features.StatefulSetSlice, true)()
+				defer featuregatetesting.SetFeatureGateDuringTest(t, utilfeature.DefaultFeatureGate, features.StatefulSetStartOrdinal, true)()
 			}
 
 			errs := ValidateStatefulSet(&testCase.set, pod.GetValidationOptionsFromPodTemplate(&testCase.set.Spec.Template, nil))

pkg/controller/statefulset/stateful_set_control_test.go

@@ -564,7 +564,7 @@ func emptyInvaraints(set *apps.StatefulSet, om *fakeObjectManager) error {
 }
 
 func TestStatefulSetControlWithStartOrdinal(t *testing.T) {
-	defer featuregatetesting.SetFeatureGateDuringTest(t, utilfeature.DefaultFeatureGate, features.StatefulSetSlice, true)()
+	defer featuregatetesting.SetFeatureGateDuringTest(t, utilfeature.DefaultFeatureGate, features.StatefulSetStartOrdinal, true)()
 
 	simpleSetFn := func() *apps.StatefulSet {
 		statefulSet := newStatefulSet(3)

pkg/controller/statefulset/stateful_set_utils.go

@@ -90,7 +90,7 @@ func getOrdinal(pod *v1.Pod) int {
 // getStartOrdinal gets the first possible ordinal (inclusive).
 // Returns spec.ordinals.start if spec.ordinals is set, otherwise returns 0.
 func getStartOrdinal(set *apps.StatefulSet) int {
-	if utilfeature.DefaultFeatureGate.Enabled(features.StatefulSetSlice) {
+	if utilfeature.DefaultFeatureGate.Enabled(features.StatefulSetStartOrdinal) {
 		if set.Spec.Ordinals != nil {
 			return int(set.Spec.Ordinals.Start)
 		}

pkg/features/kube_features.go

@@ -770,7 +770,7 @@ const (
 	// alpha: v1.26
 	//
 	// Enables a StatefulSet to start from an arbitrary non zero ordinal
-	StatefulSetSlice featuregate.Feature = "StatefulSetSlice"
+	StatefulSetStartOrdinal featuregate.Feature = "StatefulSetStartOrdinal"
 
 	// owner: @robscott
 	// kep: https://kep.k8s.io/2433
@@ -1081,7 +1081,7 @@ var defaultKubernetesFeatureGates = map[featuregate.Feature]featuregate.FeatureS
 
 	StatefulSetMinReadySeconds: {Default: true, PreRelease: featuregate.GA, LockToDefault: true}, // remove in 1.27
 
-	StatefulSetSlice: {Default: false, PreRelease: featuregate.Alpha},
+	StatefulSetStartOrdinal: {Default: false, PreRelease: featuregate.Alpha},
 
 	TopologyAwareHints: {Default: true, PreRelease: featuregate.Beta},
 

pkg/generated/openapi/zz_generated.openapi.go

@@ -4869,7 +4869,7 @@ func schema_k8sio_api_apps_v1_StatefulSetOrdinals(ref common.ReferenceCallback)
 				Properties: map[string]spec.Schema{
 					"start": {
 						SchemaProps: spec.SchemaProps{
-							Description: "Start is the number representing the first index that is used to represent replica ordinals. Defaults to 0. If set, replica ordinals will be numbered [.spec.ordinals.start, .spec.ordinals.start - .spec.replicas).",
+							Description: "start is the number representing the first replica's index. It may be used to number replicas from an alternate index (eg: 1-indexed) over the default 0-indexed names, or to orchestrate progressive movement of replicas from one StatefulSet to another. If set, replica indices will be in the range:\n  [.spec.ordinals.start, .spec.ordinals.start + .spec.replicas).\nIf unset, defaults to 0. Replica indices will be in the range:\n  [0, .spec.replicas).",
 							Default:     0,
 							Type:        []string{"integer"},
 							Format:      "int32",
@@ -4993,7 +4993,7 @@ func schema_k8sio_api_apps_v1_StatefulSetSpec(ref common.ReferenceCallback) comm
 					},
 					"ordinals": {
 						SchemaProps: spec.SchemaProps{
-							Description: "Ordinals controls how the stateful set creates pod and persistent volume claim names. The default behavior assigns a number starting with zero and incremented by one for each additional replica requested. This requires the StatefulSetSlice feature gate to be enabled, which is alpha.",
+							Description: "ordinals controls the numbering of replica indices in a StatefulSet. A StatefulSet will create pods with the format <statefulsetname>-<podindex>. For example, a pod in a StatefulSet named \"web\" with index number \"3\" would be named \"web-3\". The default ordinals behavior assigns a \"0\" index to the first replica and increments the index by one for each additional replica requested. Using the ordinals field requires the StatefulSetStartOrdinal feature gate to be enabled, which is alpha.",
 							Ref:         ref("k8s.io/api/apps/v1.StatefulSetOrdinals"),
 						},
 					},
@@ -6004,7 +6004,7 @@ func schema_k8sio_api_apps_v1beta1_StatefulSetOrdinals(ref common.ReferenceCallb
 				Properties: map[string]spec.Schema{
 					"start": {
 						SchemaProps: spec.SchemaProps{
-							Description: "Start is the number representing the first index that is used to represent replica ordinals. Defaults to 0. If set, replica ordinals will be numbered [.spec.ordinals.start, .spec.ordinals.start - .spec.replicas).",
+							Description: "start is the number representing the first replica's index. It may be used to number replicas from an alternate index (eg: 1-indexed) over the default 0-indexed names, or to orchestrate progressive movement of replicas from one StatefulSet to another. If set, replica indices will be in the range:\n  [.spec.ordinals.start, .spec.ordinals.start + .spec.replicas).\nIf unset, defaults to 0. Replica indices will be in the range:\n  [0, .spec.replicas).",
 							Default:     0,
 							Type:        []string{"integer"},
 							Format:      "int32",
@@ -6128,7 +6128,7 @@ func schema_k8sio_api_apps_v1beta1_StatefulSetSpec(ref common.ReferenceCallback)
 					},
 					"ordinals": {
 						SchemaProps: spec.SchemaProps{
-							Description: "Ordinals controls how the stateful set creates pod and persistent volume claim names. The default behavior assigns a number starting with zero and incremented by one for each additional replica requested. This requires the StatefulSetSlice feature gate to be enabled, which is alpha.",
+							Description: "ordinals controls the numbering of replica indices in a StatefulSet. A StatefulSet will create pods with the format <statefulsetname>-<podindex>. For example, a pod in a StatefulSet named \"web\" with index number \"3\" would be named \"web-3\". The default ordinals behavior assigns a \"0\" index to the first replica and increments the index by one for each additional replica requested. Using the ordinals field requires the StatefulSetStartOrdinal feature gate to be enabled, which is alpha.",
 							Ref:         ref("k8s.io/api/apps/v1beta1.StatefulSetOrdinals"),
 						},
 					},
@@ -7688,7 +7688,7 @@ func schema_k8sio_api_apps_v1beta2_StatefulSetOrdinals(ref common.ReferenceCallb
 				Properties: map[string]spec.Schema{
 					"start": {
 						SchemaProps: spec.SchemaProps{
-							Description: "Start is the number representing the first index that is used to represent replica ordinals. Defaults to 0. If set, replica ordinals will be numbered [.spec.ordinals.start, .spec.ordinals.start - .spec.replicas).",
+							Description: "start is the number representing the first replica's index. It may be used to number replicas from an alternate index (eg: 1-indexed) over the default 0-indexed names, or to orchestrate progressive movement of replicas from one StatefulSet to another. If set, replica indices will be in the range:\n  [.spec.ordinals.start, .spec.ordinals.start + .spec.replicas).\nIf unset, defaults to 0. Replica indices will be in the range:\n  [0, .spec.replicas).",
 							Default:     0,
 							Type:        []string{"integer"},
 							Format:      "int32",
@@ -7812,7 +7812,7 @@ func schema_k8sio_api_apps_v1beta2_StatefulSetSpec(ref common.ReferenceCallback)
 					},
 					"ordinals": {
 						SchemaProps: spec.SchemaProps{
-							Description: "Ordinals controls how the stateful set creates pod and persistent volume claim names. The default behavior assigns a number starting with zero and incremented by one for each additional replica requested. This requires the StatefulSetSlice feature gate to be enabled, which is alpha.",
+							Description: "ordinals controls the numbering of replica indices in a StatefulSet. A StatefulSet will create pods with the format <statefulsetname>-<podindex>. For example, a pod in a StatefulSet named \"web\" with index number \"3\" would be named \"web-3\". The default ordinals behavior assigns a \"0\" index to the first replica and increments the index by one for each additional replica requested. Using the ordinals field requires the StatefulSetStartOrdinal feature gate to be enabled, which is alpha.",
 							Ref:         ref("k8s.io/api/apps/v1beta2.StatefulSetOrdinals"),
 						},
 					},

pkg/registry/apps/statefulset/strategy.go

@@ -128,9 +128,11 @@ func dropStatefulSetDisabledFields(newSS *apps.StatefulSet, oldSS *apps.Stateful
 			newSS.Spec.UpdateStrategy.RollingUpdate.MaxUnavailable = nil
 		}
 	}
-	if !utilfeature.DefaultFeatureGate.Enabled(features.StatefulSetSlice) {
+	if !utilfeature.DefaultFeatureGate.Enabled(features.StatefulSetStartOrdinal) {
-		// Reset Spec.Ordinals to the default value (nil).
+		if oldSS == nil || oldSS.Spec.Ordinals == nil {
-		newSS.Spec.Ordinals = nil
+			// Reset Spec.Ordinals to the default value (nil).
+			newSS.Spec.Ordinals = nil
+		}
 	}
 }
 

pkg/registry/apps/statefulset/strategy_test.go

@@ -328,14 +328,29 @@ func getMaxUnavailable(maxUnavailable int) *int {
 	return &maxUnavailable
 }
 
+func createOrdinalsWithStart(start int) *apps.StatefulSetOrdinals {
+	return &apps.StatefulSetOrdinals{
+		Start: int32(start),
+	}
+}
+
+func makeStatefulSetWithStatefulSetOrdinals(ordinals *apps.StatefulSetOrdinals) *apps.StatefulSet {
+	return &apps.StatefulSet{
+		Spec: apps.StatefulSetSpec{
+			Ordinals: ordinals,
+		},
+	}
+}
+
 // TestDropStatefulSetDisabledFields tests if the drop functionality is working fine or not
 func TestDropStatefulSetDisabledFields(t *testing.T) {
 	testCases := []struct {
-		name                 string
+		name                          string
-		enableMaxUnavailable bool
+		enableMaxUnavailable          bool
-		ss                   *apps.StatefulSet
+		enableStatefulSetStartOrdinal bool
-		oldSS                *apps.StatefulSet
+		ss                            *apps.StatefulSet
-		expectedSS           *apps.StatefulSet
+		oldSS                         *apps.StatefulSet
+		expectedSS                    *apps.StatefulSet
 	}{
 		{
 			name:       "set minReadySeconds, no update",
@@ -388,11 +403,39 @@ func TestDropStatefulSetDisabledFields(t *testing.T) {
 			ss:                   makeStatefulSetWithMaxUnavailable(getMaxUnavailable(1)),
 			oldSS:                makeStatefulSetWithMaxUnavailable(getMaxUnavailable(3)),
 			expectedSS:           makeStatefulSetWithMaxUnavailable(getMaxUnavailable(1)),
+		}, {
+			name:                          "StatefulSetStartOrdinal disabled, ordinals in use in new only",
+			enableStatefulSetStartOrdinal: false,
+			ss:                            makeStatefulSetWithStatefulSetOrdinals(createOrdinalsWithStart(2)),
+			oldSS:                         nil,
+			expectedSS:                    makeStatefulSetWithStatefulSetOrdinals(nil),
+		},
+		{
+			name:                          "StatefulSetStartOrdinal disabled, ordinals in use in both old and new",
+			enableStatefulSetStartOrdinal: false,
+			ss:                            makeStatefulSetWithStatefulSetOrdinals(createOrdinalsWithStart(2)),
+			oldSS:                         makeStatefulSetWithStatefulSetOrdinals(createOrdinalsWithStart(1)),
+			expectedSS:                    makeStatefulSetWithStatefulSetOrdinals(createOrdinalsWithStart(2)),
+		},
+		{
+			name:                          "StatefulSetStartOrdinal enabled, ordinals in use in new only",
+			enableStatefulSetStartOrdinal: true,
+			ss:                            makeStatefulSetWithStatefulSetOrdinals(createOrdinalsWithStart(2)),
+			oldSS:                         nil,
+			expectedSS:                    makeStatefulSetWithStatefulSetOrdinals(createOrdinalsWithStart(2)),
+		},
+		{
+			name:                          "StatefulSetStartOrdinal enabled, ordinals in use in both old and new",
+			enableStatefulSetStartOrdinal: true,
+			ss:                            makeStatefulSetWithStatefulSetOrdinals(createOrdinalsWithStart(2)),
+			oldSS:                         makeStatefulSetWithStatefulSetOrdinals(createOrdinalsWithStart(1)),
+			expectedSS:                    makeStatefulSetWithStatefulSetOrdinals(createOrdinalsWithStart(2)),
 		},
 	}
 	for _, tc := range testCases {
 		t.Run(tc.name, func(t *testing.T) {
 			defer featuregatetesting.SetFeatureGateDuringTest(t, utilfeature.DefaultFeatureGate, features.MaxUnavailableStatefulSet, tc.enableMaxUnavailable)()
+			defer featuregatetesting.SetFeatureGateDuringTest(t, utilfeature.DefaultFeatureGate, features.StatefulSetStartOrdinal, tc.enableStatefulSetStartOrdinal)()
 			old := tc.oldSS.DeepCopy()
 
 			dropStatefulSetDisabledFields(tc.ss, tc.oldSS)

staging/src/k8s.io/api/apps/v1/generated.proto

@@ -625,10 +625,14 @@ message StatefulSetList {
 // StatefulSetOrdinals describes the policy used for replica ordinal assignment
 // in this StatefulSet.
 message StatefulSetOrdinals {
-  // Start is the number representing the first index that is used to represent
+  // start is the number representing the first replica's index. It may be used
-  // replica ordinals. Defaults to 0.
+  // to number replicas from an alternate index (eg: 1-indexed) over the default
-  // If set, replica ordinals will be numbered
+  // 0-indexed names, or to orchestrate progressive movement of replicas from
-  // [.spec.ordinals.start, .spec.ordinals.start - .spec.replicas).
+  // one StatefulSet to another.
+  // If set, replica indices will be in the range:
+  //   [.spec.ordinals.start, .spec.ordinals.start + .spec.replicas).
+  // If unset, defaults to 0. Replica indices will be in the range:
+  //   [0, .spec.replicas).
   // +optional
   optional int32 start = 1;
 }
@@ -725,11 +729,13 @@ message StatefulSetSpec {
   // which is alpha.  +optional
   optional StatefulSetPersistentVolumeClaimRetentionPolicy persistentVolumeClaimRetentionPolicy = 10;
 
-  // Ordinals controls how the stateful set creates pod and persistent volume
+  // ordinals controls the numbering of replica indices in a StatefulSet. A
-  // claim names.
+  // StatefulSet will create pods with the format <statefulsetname>-<podindex>.
-  // The default behavior assigns a number starting with zero and incremented by
+  // For example, a pod in a StatefulSet named "web" with index number "3" would
-  // one for each additional replica requested. This requires the
+  // be named "web-3". The default ordinals behavior assigns a "0" index to the
-  // StatefulSetSlice feature gate to be enabled, which is alpha.
+  // first replica and increments the index by one for each additional replica
+  // requested. Using the ordinals field requires the StatefulSetStartOrdinal
+  // feature gate to be enabled, which is alpha.
   // +optional
   optional StatefulSetOrdinals ordinals = 11;
 }

staging/src/k8s.io/api/apps/v1/types.go

@@ -166,10 +166,14 @@ type StatefulSetPersistentVolumeClaimRetentionPolicy struct {
 // StatefulSetOrdinals describes the policy used for replica ordinal assignment
 // in this StatefulSet.
 type StatefulSetOrdinals struct {
-	// Start is the number representing the first index that is used to represent
+	// start is the number representing the first replica's index. It may be used
-	// replica ordinals. Defaults to 0.
+	// to number replicas from an alternate index (eg: 1-indexed) over the default
-	// If set, replica ordinals will be numbered in the range:
+	// 0-indexed names, or to orchestrate progressive movement of replicas from
-	// [.spec.ordinals.start, .spec.ordinals.start + .spec.replicas).
+	// one StatefulSet to another.
+	// If set, replica indices will be in the range:
+	//   [.spec.ordinals.start, .spec.ordinals.start + .spec.replicas).
+	// If unset, defaults to 0. Replica indices will be in the range:
+	//   [0, .spec.replicas).
 	// +optional
 	Start int32 `json:"start" protobuf:"varint,1,opt,name=start"`
 }
@@ -249,11 +253,13 @@ type StatefulSetSpec struct {
 	// which is alpha.  +optional
 	PersistentVolumeClaimRetentionPolicy *StatefulSetPersistentVolumeClaimRetentionPolicy `json:"persistentVolumeClaimRetentionPolicy,omitempty" protobuf:"bytes,10,opt,name=persistentVolumeClaimRetentionPolicy"`
 
-	// Ordinals controls how the stateful set creates pod and persistent volume
+	// ordinals controls the numbering of replica indices in a StatefulSet. A
-	// claim names.
+	// StatefulSet will create pods with the format <statefulsetname>-<podindex>.
-	// The default behavior assigns a number starting with zero and incremented by
+	// For example, a pod in a StatefulSet named "web" with index number "3" would
-	// one for each additional replica requested. This requires the
+	// be named "web-3". The default ordinals behavior assigns a "0" index to the
-	// StatefulSetSlice feature gate to be enabled, which is alpha.
+	// first replica and increments the index by one for each additional replica
+	// requested. Using the ordinals field requires the StatefulSetStartOrdinal
+	// feature gate to be enabled, which is alpha.
 	// +optional
 	Ordinals *StatefulSetOrdinals `json:"ordinals,omitempty" protobuf:"bytes,11,opt,name=ordinals"`
 }

staging/src/k8s.io/api/apps/v1/types_swagger_doc_generated.go

@@ -326,7 +326,7 @@ func (StatefulSetList) SwaggerDoc() map[string]string {
 
 var map_StatefulSetOrdinals = map[string]string{
 	"":      "StatefulSetOrdinals describes the policy used for replica ordinal assignment in this StatefulSet.",
-	"start": "Start is the number representing the first index that is used to represent replica ordinals. Defaults to 0. If set, replica ordinals will be numbered [.spec.ordinals.start, .spec.ordinals.start - .spec.replicas).",
+	"start": "start is the number representing the first replica's index. It may be used to number replicas from an alternate index (eg: 1-indexed) over the default 0-indexed names, or to orchestrate progressive movement of replicas from one StatefulSet to another. If set, replica indices will be in the range:\n  [.spec.ordinals.start, .spec.ordinals.start + .spec.replicas).\nIf unset, defaults to 0. Replica indices will be in the range:\n  [0, .spec.replicas).",
 }
 
 func (StatefulSetOrdinals) SwaggerDoc() map[string]string {
@@ -355,7 +355,7 @@ var map_StatefulSetSpec = map[string]string{
 	"revisionHistoryLimit":                 "revisionHistoryLimit is the maximum number of revisions that will be maintained in the StatefulSet's revision history. The revision history consists of all revisions not represented by a currently applied StatefulSetSpec version. The default value is 10.",
 	"minReadySeconds":                      "Minimum number of seconds for which a newly created pod should be ready without any of its container crashing for it to be considered available. Defaults to 0 (pod will be considered available as soon as it is ready)",
 	"persistentVolumeClaimRetentionPolicy": "persistentVolumeClaimRetentionPolicy describes the lifecycle of persistent volume claims created from volumeClaimTemplates. By default, all persistent volume claims are created as needed and retained until manually deleted. This policy allows the lifecycle to be altered, for example by deleting persistent volume claims when their stateful set is deleted, or when their pod is scaled down. This requires the StatefulSetAutoDeletePVC feature gate to be enabled, which is alpha.  +optional",
-	"ordinals":                             "Ordinals controls how the stateful set creates pod and persistent volume claim names. The default behavior assigns a number starting with zero and incremented by one for each additional replica requested. This requires the StatefulSetSlice feature gate to be enabled, which is alpha.",
+	"ordinals":                             "ordinals controls the numbering of replica indices in a StatefulSet. A StatefulSet will create pods with the format <statefulsetname>-<podindex>. For example, a pod in a StatefulSet named \"web\" with index number \"3\" would be named \"web-3\". The default ordinals behavior assigns a \"0\" index to the first replica and increments the index by one for each additional replica requested. Using the ordinals field requires the StatefulSetStartOrdinal feature gate to be enabled, which is alpha.",
 }
 
 func (StatefulSetSpec) SwaggerDoc() map[string]string {

staging/src/k8s.io/api/apps/v1beta1/generated.proto

@@ -383,10 +383,14 @@ message StatefulSetList {
 // StatefulSetOrdinals describes the policy used for replica ordinal assignment
 // in this StatefulSet.
 message StatefulSetOrdinals {
-  // Start is the number representing the first index that is used to represent
+  // start is the number representing the first replica's index. It may be used
-  // replica ordinals. Defaults to 0.
+  // to number replicas from an alternate index (eg: 1-indexed) over the default
-  // If set, replica ordinals will be numbered
+  // 0-indexed names, or to orchestrate progressive movement of replicas from
-  // [.spec.ordinals.start, .spec.ordinals.start - .spec.replicas).
+  // one StatefulSet to another.
+  // If set, replica indices will be in the range:
+  //   [.spec.ordinals.start, .spec.ordinals.start + .spec.replicas).
+  // If unset, defaults to 0. Replica indices will be in the range:
+  //   [0, .spec.replicas).
   // +optional
   optional int32 start = 1;
 }
@@ -481,11 +485,13 @@ message StatefulSetSpec {
   // +optional
   optional StatefulSetPersistentVolumeClaimRetentionPolicy persistentVolumeClaimRetentionPolicy = 10;
 
-  // Ordinals controls how the stateful set creates pod and persistent volume
+  // ordinals controls the numbering of replica indices in a StatefulSet. A
-  // claim names.
+  // StatefulSet will create pods with the format <statefulsetname>-<podindex>.
-  // The default behavior assigns a number starting with zero and incremented by
+  // For example, a pod in a StatefulSet named "web" with index number "3" would
-  // one for each additional replica requested. This requires the
+  // be named "web-3". The default ordinals behavior assigns a "0" index to the
-  // StatefulSetSlice feature gate to be enabled, which is alpha.
+  // first replica and increments the index by one for each additional replica
+  // requested. Using the ordinals field requires the StatefulSetStartOrdinal
+  // feature gate to be enabled, which is alpha.
   // +optional
   optional StatefulSetOrdinals ordinals = 11;
 }

staging/src/k8s.io/api/apps/v1beta1/types.go

@@ -207,10 +207,14 @@ type StatefulSetPersistentVolumeClaimRetentionPolicy struct {
 // StatefulSetOrdinals describes the policy used for replica ordinal assignment
 // in this StatefulSet.
 type StatefulSetOrdinals struct {
-	// Start is the number representing the first index that is used to represent
+	// start is the number representing the first replica's index. It may be used
-	// replica ordinals. Defaults to 0.
+	// to number replicas from an alternate index (eg: 1-indexed) over the default
-	// If set, replica ordinals will be numbered in the range:
+	// 0-indexed names, or to orchestrate progressive movement of replicas from
-	// [.spec.ordinals.start, .spec.ordinals.start + .spec.replicas).
+	// one StatefulSet to another.
+	// If set, replica indices will be in the range:
+	//   [.spec.ordinals.start, .spec.ordinals.start + .spec.replicas).
+	// If unset, defaults to 0. Replica indices will be in the range:
+	//   [0, .spec.replicas).
 	// +optional
 	Start int32 `json:"start" protobuf:"varint,1,opt,name=start"`
 }
@@ -288,11 +292,13 @@ type StatefulSetSpec struct {
 	// +optional
 	PersistentVolumeClaimRetentionPolicy *StatefulSetPersistentVolumeClaimRetentionPolicy `json:"persistentVolumeClaimRetentionPolicy,omitempty" protobuf:"bytes,10,opt,name=persistentVolumeClaimRetentionPolicy"`
 
-	// Ordinals controls how the stateful set creates pod and persistent volume
+	// ordinals controls the numbering of replica indices in a StatefulSet. A
-	// claim names.
+	// StatefulSet will create pods with the format <statefulsetname>-<podindex>.
-	// The default behavior assigns a number starting with zero and incremented by
+	// For example, a pod in a StatefulSet named "web" with index number "3" would
-	// one for each additional replica requested. This requires the
+	// be named "web-3". The default ordinals behavior assigns a "0" index to the
-	// StatefulSetSlice feature gate to be enabled, which is alpha.
+	// first replica and increments the index by one for each additional replica
+	// requested. Using the ordinals field requires the StatefulSetStartOrdinal
+	// feature gate to be enabled, which is alpha.
 	// +optional
 	Ordinals *StatefulSetOrdinals `json:"ordinals,omitempty" protobuf:"bytes,11,opt,name=ordinals"`
 }

staging/src/k8s.io/api/apps/v1beta1/types_swagger_doc_generated.go

@@ -230,7 +230,7 @@ func (StatefulSetList) SwaggerDoc() map[string]string {
 
 var map_StatefulSetOrdinals = map[string]string{
 	"":      "StatefulSetOrdinals describes the policy used for replica ordinal assignment in this StatefulSet.",
-	"start": "Start is the number representing the first index that is used to represent replica ordinals. Defaults to 0. If set, replica ordinals will be numbered [.spec.ordinals.start, .spec.ordinals.start - .spec.replicas).",
+	"start": "start is the number representing the first replica's index. It may be used to number replicas from an alternate index (eg: 1-indexed) over the default 0-indexed names, or to orchestrate progressive movement of replicas from one StatefulSet to another. If set, replica indices will be in the range:\n  [.spec.ordinals.start, .spec.ordinals.start + .spec.replicas).\nIf unset, defaults to 0. Replica indices will be in the range:\n  [0, .spec.replicas).",
 }
 
 func (StatefulSetOrdinals) SwaggerDoc() map[string]string {
@@ -259,7 +259,7 @@ var map_StatefulSetSpec = map[string]string{
 	"revisionHistoryLimit":                 "revisionHistoryLimit is the maximum number of revisions that will be maintained in the StatefulSet's revision history. The revision history consists of all revisions not represented by a currently applied StatefulSetSpec version. The default value is 10.",
 	"minReadySeconds":                      "Minimum number of seconds for which a newly created pod should be ready without any of its container crashing for it to be considered available. Defaults to 0 (pod will be considered available as soon as it is ready)",
 	"persistentVolumeClaimRetentionPolicy": "PersistentVolumeClaimRetentionPolicy describes the policy used for PVCs created from the StatefulSet VolumeClaimTemplates. This requires the StatefulSetAutoDeletePVC feature gate to be enabled, which is alpha.",
-	"ordinals":                             "Ordinals controls how the stateful set creates pod and persistent volume claim names. The default behavior assigns a number starting with zero and incremented by one for each additional replica requested. This requires the StatefulSetSlice feature gate to be enabled, which is alpha.",
+	"ordinals":                             "ordinals controls the numbering of replica indices in a StatefulSet. A StatefulSet will create pods with the format <statefulsetname>-<podindex>. For example, a pod in a StatefulSet named \"web\" with index number \"3\" would be named \"web-3\". The default ordinals behavior assigns a \"0\" index to the first replica and increments the index by one for each additional replica requested. Using the ordinals field requires the StatefulSetStartOrdinal feature gate to be enabled, which is alpha.",
 }
 
 func (StatefulSetSpec) SwaggerDoc() map[string]string {

staging/src/k8s.io/api/apps/v1beta2/generated.proto

@@ -670,10 +670,14 @@ message StatefulSetList {
 // StatefulSetOrdinals describes the policy used for replica ordinal assignment
 // in this StatefulSet.
 message StatefulSetOrdinals {
-  // Start is the number representing the first index that is used to represent
+  // start is the number representing the first replica's index. It may be used
-  // replica ordinals. Defaults to 0.
+  // to number replicas from an alternate index (eg: 1-indexed) over the default
-  // If set, replica ordinals will be numbered
+  // 0-indexed names, or to orchestrate progressive movement of replicas from
-  // [.spec.ordinals.start, .spec.ordinals.start - .spec.replicas).
+  // one StatefulSet to another.
+  // If set, replica indices will be in the range:
+  //   [.spec.ordinals.start, .spec.ordinals.start + .spec.replicas).
+  // If unset, defaults to 0. Replica indices will be in the range:
+  //   [0, .spec.replicas).
   // +optional
   optional int32 start = 1;
 }
@@ -767,11 +771,13 @@ message StatefulSetSpec {
   // +optional
   optional StatefulSetPersistentVolumeClaimRetentionPolicy persistentVolumeClaimRetentionPolicy = 10;
 
-  // Ordinals controls how the stateful set creates pod and persistent volume
+  // ordinals controls the numbering of replica indices in a StatefulSet. A
-  // claim names.
+  // StatefulSet will create pods with the format <statefulsetname>-<podindex>.
-  // The default behavior assigns a number starting with zero and incremented by
+  // For example, a pod in a StatefulSet named "web" with index number "3" would
-  // one for each additional replica requested. This requires the
+  // be named "web-3". The default ordinals behavior assigns a "0" index to the
-  // StatefulSetSlice feature gate to be enabled, which is alpha.
+  // first replica and increments the index by one for each additional replica
+  // requested. Using the ordinals field requires the StatefulSetStartOrdinal
+  // feature gate to be enabled, which is alpha.
   // +optional
   optional StatefulSetOrdinals ordinals = 11;
 }

staging/src/k8s.io/api/apps/v1beta2/types.go

@@ -217,10 +217,14 @@ type StatefulSetPersistentVolumeClaimRetentionPolicy struct {
 // StatefulSetOrdinals describes the policy used for replica ordinal assignment
 // in this StatefulSet.
 type StatefulSetOrdinals struct {
-	// Start is the number representing the first index that is used to represent
+	// start is the number representing the first replica's index. It may be used
-	// replica ordinals. Defaults to 0.
+	// to number replicas from an alternate index (eg: 1-indexed) over the default
-	// If set, replica ordinals will be numbered in the range:
+	// 0-indexed names, or to orchestrate progressive movement of replicas from
-	// [.spec.ordinals.start, .spec.ordinals.start + .spec.replicas).
+	// one StatefulSet to another.
+	// If set, replica indices will be in the range:
+	//   [.spec.ordinals.start, .spec.ordinals.start + .spec.replicas).
+	// If unset, defaults to 0. Replica indices will be in the range:
+	//   [0, .spec.replicas).
 	// +optional
 	Start int32 `json:"start" protobuf:"varint,1,opt,name=start"`
 }
@@ -297,11 +301,13 @@ type StatefulSetSpec struct {
 	// +optional
 	PersistentVolumeClaimRetentionPolicy *StatefulSetPersistentVolumeClaimRetentionPolicy `json:"persistentVolumeClaimRetentionPolicy,omitempty" protobuf:"bytes,10,opt,name=persistentVolumeClaimRetentionPolicy"`
 
-	// Ordinals controls how the stateful set creates pod and persistent volume
+	// ordinals controls the numbering of replica indices in a StatefulSet. A
-	// claim names.
+	// StatefulSet will create pods with the format <statefulsetname>-<podindex>.
-	// The default behavior assigns a number starting with zero and incremented by
+	// For example, a pod in a StatefulSet named "web" with index number "3" would
-	// one for each additional replica requested. This requires the
+	// be named "web-3". The default ordinals behavior assigns a "0" index to the
-	// StatefulSetSlice feature gate to be enabled, which is alpha.
+	// first replica and increments the index by one for each additional replica
+	// requested. Using the ordinals field requires the StatefulSetStartOrdinal
+	// feature gate to be enabled, which is alpha.
 	// +optional
 	Ordinals *StatefulSetOrdinals `json:"ordinals,omitempty" protobuf:"bytes,11,opt,name=ordinals"`
 }

staging/src/k8s.io/api/apps/v1beta2/types_swagger_doc_generated.go

@@ -354,7 +354,7 @@ func (StatefulSetList) SwaggerDoc() map[string]string {
 
 var map_StatefulSetOrdinals = map[string]string{
 	"":      "StatefulSetOrdinals describes the policy used for replica ordinal assignment in this StatefulSet.",
-	"start": "Start is the number representing the first index that is used to represent replica ordinals. Defaults to 0. If set, replica ordinals will be numbered [.spec.ordinals.start, .spec.ordinals.start - .spec.replicas).",
+	"start": "start is the number representing the first replica's index. It may be used to number replicas from an alternate index (eg: 1-indexed) over the default 0-indexed names, or to orchestrate progressive movement of replicas from one StatefulSet to another. If set, replica indices will be in the range:\n  [.spec.ordinals.start, .spec.ordinals.start + .spec.replicas).\nIf unset, defaults to 0. Replica indices will be in the range:\n  [0, .spec.replicas).",
 }
 
 func (StatefulSetOrdinals) SwaggerDoc() map[string]string {
@@ -383,7 +383,7 @@ var map_StatefulSetSpec = map[string]string{
 	"revisionHistoryLimit":                 "revisionHistoryLimit is the maximum number of revisions that will be maintained in the StatefulSet's revision history. The revision history consists of all revisions not represented by a currently applied StatefulSetSpec version. The default value is 10.",
 	"minReadySeconds":                      "Minimum number of seconds for which a newly created pod should be ready without any of its container crashing for it to be considered available. Defaults to 0 (pod will be considered available as soon as it is ready)",
 	"persistentVolumeClaimRetentionPolicy": "PersistentVolumeClaimRetentionPolicy describes the policy used for PVCs created from the StatefulSet VolumeClaimTemplates. This requires the StatefulSetAutoDeletePVC feature gate to be enabled, which is alpha.",
-	"ordinals":                             "Ordinals controls how the stateful set creates pod and persistent volume claim names. The default behavior assigns a number starting with zero and incremented by one for each additional replica requested. This requires the StatefulSetSlice feature gate to be enabled, which is alpha.",
+	"ordinals":                             "ordinals controls the numbering of replica indices in a StatefulSet. A StatefulSet will create pods with the format <statefulsetname>-<podindex>. For example, a pod in a StatefulSet named \"web\" with index number \"3\" would be named \"web-3\". The default ordinals behavior assigns a \"0\" index to the first replica and increments the index by one for each additional replica requested. Using the ordinals field requires the StatefulSetStartOrdinal feature gate to be enabled, which is alpha.",
 }
 
 func (StatefulSetSpec) SwaggerDoc() map[string]string {