@@ -12,7 +12,7 @@ found at [API Conventions](api-conventions.md).
12
12
- [ Adding a field] ( #adding-a-field )
13
13
- [ Making a singular field plural] ( #making-a-singular-field-plural )
14
14
- [ Single-Dual ambiguity] ( #single-dual-ambiguity )
15
- - [ Multiple API versions] ( multiple-api-versions )
15
+ - [ Multiple API versions] ( # multiple-api-versions)
16
16
- [ Backward compatibility gotchas] ( #backward-compatibility-gotchas )
17
17
- [ Incompatible API changes] ( #incompatible-api-changes )
18
18
- [ Changing versioned APIs] ( #changing-versioned-apis )
@@ -473,7 +473,7 @@ worked before the change.
473
473
removed value as deprecated but allowed). For enumeration-like fields that expect to add
474
474
new values in the future, such as ` reason ` fields, document that expectation clearly
475
475
in the API field description in the first release the field is made available,
476
- and describe how clients should treat an unknown value. Clients should treat such
476
+ and describe how clients should treat an unknown value. Clients should treat such
477
477
sets of values as potentially open-ended.
478
478
479
479
* For [ Unions] ( api-conventions.md#unions ) , sets of fields where at most one should
@@ -558,9 +558,9 @@ For types that need the generated
558
558
[ DeepCopyObject] ( https://github.com/kubernetes/kubernetes/commit/8dd0989b395b29b872e1f5e06934721863e4a210#diff-6318847735efb6fae447e7dbf198c8b2R3767 )
559
559
methods, usually only required by the top-level types like ` Pod ` , add this line
560
560
to the comment
561
- ([ example] ( https://github.com/kubernetes/kubernetes/commit/39d95b9b065fffebe5b6f233d978fe1723722085#diff-ab819c2e7a94a3521aecf6b477f9b2a7R30 ) ):
561
+ ([ example] ( https://github.com/kubernetes/kubernetes/commit/39d95b9b065fffebe5b6f233d978fe1723722085#diff-ab819c2e7a94a3521aecf6b477f9b2a7R30 ) ):
562
562
563
- ``` golang
563
+ ``` golang
564
564
// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
565
565
```
566
566
@@ -693,7 +693,7 @@ The `make generated_files` will also regenerate the `zz_generated.deepcopy.go`,
693
693
If regeneration is somehow not possible due to compile errors, the easiest
694
694
workaround is to remove the files causing errors and rerun the command.
695
695
696
- ## Generate Code
696
+ ## Generate Code
697
697
698
698
Apart from the ` defaulter-gen ` , ` deepcopy-gen ` , ` conversion-gen ` and
699
699
` openapi-gen ` , there are a few other generators:
@@ -999,7 +999,7 @@ cases, objects will be automatically converted to the new version; in other
999
999
cases, a manual upgrade may be necessary; a manual upgrade may require downtime
1000
1000
for anything relying on the new feature, and may require manual conversion of
1001
1001
objects to the new version; when manual conversion is necessary, the project
1002
- will provide documentation on the process
1002
+ will provide documentation on the process
1003
1003
- Cluster Reliability: since the feature has e2e tests, enabling the feature
1004
1004
via a flag should not create new bugs in unrelated features; because the feature
1005
1005
is new, it may have minor bugs
@@ -1092,7 +1092,7 @@ The preferred approach adds an alpha field to the existing object, and ensures i
1092
1092
//
1093
1093
// Add multiple dimensions to frobbers.
1094
1094
Frobber2D utilfeature.Feature = "Frobber2D"
1095
-
1095
+
1096
1096
var defaultKubernetesFeatureGates = map[utilfeature.Feature]utilfeature.FeatureSpec{
1097
1097
...
1098
1098
Frobber2D: {Default: false, PreRelease: utilfeature.Alpha},
@@ -1106,7 +1106,7 @@ The preferred approach adds an alpha field to the existing object, and ensures i
1106
1106
* add the ` // +optional` comment tag
1107
1107
* ensure the field is entirely absent from API responses when empty (optional fields should be pointers, anyway)
1108
1108
* include details about the alpha-level in the field description
1109
-
1109
+
1110
1110
` ` ` go
1111
1111
// API v6.
1112
1112
type Frobber struct {
@@ -1132,16 +1132,16 @@ The recommended place to do this is in the REST storage strategy's PrepareForCre
1132
1132
```go
1133
1133
func (frobberStrategy) PrepareForCreate(ctx genericapirequest.Context, obj runtime.Object) {
1134
1134
frobber := obj.(*api.Frobber)
1135
-
1135
+
1136
1136
if !utilfeature.DefaultFeatureGate.Enabled(features.Frobber2D) {
1137
1137
frobber.Width = nil
1138
1138
}
1139
1139
}
1140
-
1140
+
1141
1141
func (frobberStrategy) PrepareForUpdate(ctx genericapirequest.Context, obj, old runtime.Object) {
1142
1142
newFrobber := obj.(*api.Frobber)
1143
1143
oldFrobber := old.(*api.Frobber)
1144
-
1144
+
1145
1145
if !utilfeature.DefaultFeatureGate.Enabled(features.Frobber2D) && oldFrobber.Width == nil {
1146
1146
newFrobber.Width = nil
1147
1147
}
@@ -1150,8 +1150,8 @@ The recommended place to do this is in the REST storage strategy's PrepareForCre
1150
1150
1151
1151
4. To future-proof your API testing, when testing with feature gate on and off, ensure that the gate is deliberately set as desired. Don' t assume that gate is off or on. As your feature
1152
1152
progresses from ` alpha` to ` beta` and then ` stable` the feature might be turned on or off by default across the entire code base. The below example
1153
- provides some details
1154
-
1153
+ provides some details
1154
+
1155
1155
` ` ` go
1156
1156
func TestAPI(t *testing.T){
1157
1157
testCases:= []struct{
@@ -1164,7 +1164,7 @@ provides some details
1164
1164
// ... test case ..
1165
1165
},
1166
1166
}
1167
-
1167
+
1168
1168
for _, testCase := range testCases{
1169
1169
t.Run("..name...", func(t *testing.T){
1170
1170
// run with gate on
@@ -1177,7 +1177,7 @@ provides some details
1177
1177
// ... test gate-off testing logic logic ...
1178
1178
})
1179
1179
}
1180
- ` ` `
1180
+ ` ` `
1181
1181
1182
1182
5 . In validation, validate the field if present:
1183
1183
@@ -1204,7 +1204,7 @@ In future Kubernetes versions:
1204
1204
Height int32 ` json:" height" protobuf:" varint,1,opt,name=height" `
1205
1205
// param ...
1206
1206
Param string ` json:" param" protobuf:" bytes,2,opt,name=param" `
1207
-
1207
+
1208
1208
// +k8s:deprecated=width,protobuf=3
1209
1209
}
1210
1210
` ` `
@@ -1267,7 +1267,7 @@ and graduating to beta and enabled by default in release 2.
1267
1267
//
1268
1268
// Allow OnTuesday restart policy in frobbers.
1269
1269
FrobberRestartPolicyOnTuesday utilfeature.Feature = " FrobberRestartPolicyOnTuesday"
1270
-
1270
+
1271
1271
var defaultKubernetesFeatureGates = map [utilfeature.Feature ]utilfeature.FeatureSpec {
1272
1272
...
1273
1273
FrobberRestartPolicyOnTuesday : {Default: false , PreRelease: utilfeature.Alpha },
@@ -1277,7 +1277,7 @@ and graduating to beta and enabled by default in release 2.
1277
1277
2 . Update the documentation on the API type :
1278
1278
1279
1279
* include details about the alpha-level in the field description
1280
-
1280
+
1281
1281
` ` ` go
1282
1282
type Frobber struct {
1283
1283
// restartPolicy may be set to "Always" or "Never" (or "OnTuesday" if the alpha "FrobberRestartPolicyOnTuesday" feature is enabled).
@@ -1299,7 +1299,7 @@ The recommended place to do this is in the REST storage strategy's Validate/Vali
1299
1299
frobber := obj.(*api.Frobber)
1300
1300
return validation.ValidateFrobber(frobber, validationOptionsForFrobber(frobber, nil))
1301
1301
}
1302
-
1302
+
1303
1303
func (frobberStrategy) ValidateUpdate(ctx genericapirequest.Context, obj, old runtime.Object) field.ErrorList {
1304
1304
newFrobber := obj.(*api.Frobber)
1305
1305
oldFrobber := old.(*api.Frobber)
@@ -1355,7 +1355,7 @@ The recommended place to do this is in the REST storage strategy's Validate/Vali
1355
1355
//
1356
1356
// Allow OnTuesday restart policy in frobbers.
1357
1357
FrobberRestartPolicyOnTuesday utilfeature.Feature = "FrobberRestartPolicyOnTuesday"
1358
-
1358
+
1359
1359
var defaultKubernetesFeatureGates = map[utilfeature.Feature]utilfeature.FeatureSpec{
1360
1360
...
1361
1361
FrobberRestartPolicyOnTuesday: {Default: true, PreRelease: utilfeature.Beta},
0 commit comments