| 1 |
/* |
| 2 |
Copyright 2025 The Kubernetes Authors. |
| 3 |
|
| 4 |
Licensed under the Apache License, Version 2.0 (the "License"); |
| 5 |
you may not use this file except in compliance with the License. |
| 6 |
You may obtain a copy of the License at |
| 7 |
|
| 8 |
http://www.apache.org/licenses/LICENSE-2.0 |
| 9 |
|
| 10 |
Unless required by applicable law or agreed to in writing, software |
| 11 |
distributed under the License is distributed on an "AS IS" BASIS, |
| 12 |
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 13 |
See the License for the specific language governing permissions and |
| 14 |
limitations under the License. |
| 15 |
*/ |
| 16 |
|
| 17 |
package rest |
| 18 |
|
| 19 |
import ( |
| 20 |
"context" |
| 21 |
"fmt" |
| 22 |
"strings" |
| 23 |
|
| 24 |
"k8s.io/apimachinery/pkg/runtime" |
| 25 |
"k8s.io/apimachinery/pkg/runtime/schema" |
| 26 |
"k8s.io/apimachinery/pkg/util/sets" |
| 27 |
"k8s.io/apimachinery/pkg/util/validation/field" |
| 28 |
genericapirequest "k8s.io/apiserver/pkg/endpoints/request" |
| 29 |
validationmetrics "k8s.io/apiserver/pkg/validation" |
| 30 |
"k8s.io/klog/v2" |
| 31 |
) |
| 32 |
|
| 33 |
// ValidateDeclaratively validates obj against declarative validation tags |
| 34 |
// defined in its Go type. It uses the API version extracted from ctx and the |
| 35 |
// provided scheme for validation. |
| 36 |
// |
| 37 |
// The ctx MUST contain requestInfo, which determines the target API for |
| 38 |
// validation. The obj is converted to the API version using the provided scheme |
| 39 |
// before validation occurs. The scheme MUST have the declarative validation |
| 40 |
// registered for the requested resource/subresource. |
| 41 |
// |
| 42 |
// option should contain any validation options that the declarative validation |
| 43 |
// tags expect. |
| 44 |
// |
| 45 |
// Returns a field.ErrorList containing any validation errors. An internal error |
| 46 |
// is included if requestInfo is missing from the context or if version |
| 47 |
// conversion fails. |
| 48 |
func ValidateDeclaratively(ctx context.Context, options sets.Set[string], scheme *runtime.Scheme, obj runtime.Object) field.ErrorList { |
| 49 |
if requestInfo, found := genericapirequest.RequestInfoFrom(ctx); found { |
| 50 |
groupVersion := schema.GroupVersion{Group: requestInfo.APIGroup, Version: requestInfo.APIVersion} |
| 51 |
versionedObj, err := scheme.ConvertToVersion(obj, groupVersion) |
| 52 |
if err != nil { |
| 53 |
return field.ErrorList{field.InternalError(nil, fmt.Errorf("unexpected error converting to versioned type: %w", err))} |
| 54 |
} |
| 55 |
subresources, err := parseSubresourcePath(requestInfo.Subresource) |
| 56 |
if err != nil { |
| 57 |
return field.ErrorList{field.InternalError(nil, fmt.Errorf("unexpected error parsing subresource path: %w", err))} |
| 58 |
} |
| 59 |
return scheme.Validate(ctx, options, versionedObj, subresources...) |
| 60 |
} else { |
| 61 |
return field.ErrorList{field.InternalError(nil, fmt.Errorf("could not find requestInfo in context"))} |
| 62 |
} |
| 63 |
} |
| 64 |
|
| 65 |
// ValidateUpdateDeclaratively validates obj and oldObj against declarative |
| 66 |
// validation tags defined in its Go type. It uses the API version extracted from |
| 67 |
// ctx and the provided scheme for validation. |
| 68 |
// |
| 69 |
// The ctx MUST contain requestInfo, which determines the target API for |
| 70 |
// validation. The obj is converted to the API version using the provided scheme |
| 71 |
// before validation occurs. The scheme MUST have the declarative validation |
| 72 |
// registered for the requested resource/subresource. |
| 73 |
// |
| 74 |
// option should contain any validation options that the declarative validation |
| 75 |
// tags expect. |
| 76 |
// |
| 77 |
// Returns a field.ErrorList containing any validation errors. An internal error |
| 78 |
// is included if requestInfo is missing from the context or if version |
| 79 |
// conversion fails. |
| 80 |
func ValidateUpdateDeclaratively(ctx context.Context, options sets.Set[string], scheme *runtime.Scheme, obj, oldObj runtime.Object) field.ErrorList { |
| 81 |
if requestInfo, found := genericapirequest.RequestInfoFrom(ctx); found { |
| 82 |
groupVersion := schema.GroupVersion{Group: requestInfo.APIGroup, Version: requestInfo.APIVersion} |
| 83 |
versionedObj, err := scheme.ConvertToVersion(obj, groupVersion) |
| 84 |
if err != nil { |
| 85 |
return field.ErrorList{field.InternalError(nil, fmt.Errorf("unexpected error converting to versioned type: %w", err))} |
| 86 |
} |
| 87 |
versionedOldObj, err := scheme.ConvertToVersion(oldObj, groupVersion) |
| 88 |
if err != nil { |
| 89 |
return field.ErrorList{field.InternalError(nil, fmt.Errorf("unexpected error converting to versioned type: %w", err))} |
| 90 |
} |
| 91 |
subresources, err := parseSubresourcePath(requestInfo.Subresource) |
| 92 |
if err != nil { |
| 93 |
return field.ErrorList{field.InternalError(nil, fmt.Errorf("unexpected error parsing subresource path: %w", err))} |
| 94 |
} |
| 95 |
return scheme.ValidateUpdate(ctx, options, versionedObj, versionedOldObj, subresources...) |
| 96 |
} else { |
| 97 |
return field.ErrorList{field.InternalError(nil, fmt.Errorf("could not find requestInfo in context"))} |
| 98 |
} |
| 99 |
} |
| 100 |
|
| 101 |
func parseSubresourcePath(subresourcePath string) ([]string, error) { |
| 102 |
if len(subresourcePath) == 0 { |
| 103 |
return nil, nil |
| 104 |
} |
| 105 |
parts := strings.Split(subresourcePath, "/") |
| 106 |
for _, part := range parts { |
| 107 |
if len(part) == 0 { |
| 108 |
return nil, fmt.Errorf("invalid subresource path: %s", subresourcePath) |
| 109 |
} |
| 110 |
} |
| 111 |
return parts, nil |
| 112 |
} |
| 113 |
|
| 114 |
// CompareDeclarativeErrorsAndEmitMismatches checks for mismatches between imperative and declarative validation |
| 115 |
// and logs + emits metrics when inconsistencies are found |
| 116 |
func CompareDeclarativeErrorsAndEmitMismatches(ctx context.Context, imperativeErrs, declarativeErrs field.ErrorList, takeover bool) { |
| 117 |
logger := klog.FromContext(ctx) |
| 118 |
mismatchDetails := gatherDeclarativeValidationMismatches(imperativeErrs, declarativeErrs, takeover) |
| 119 |
for _, detail := range mismatchDetails { |
| 120 |
// Log information about the mismatch using contextual logger |
| 121 |
logger.Error(nil, detail) |
| 122 |
|
| 123 |
// Increment the metric for the mismatch |
| 124 |
validationmetrics.Metrics.IncDeclarativeValidationMismatchMetric() |
| 125 |
} |
| 126 |
} |
| 127 |
|
| 128 |
// gatherDeclarativeValidationMismatches compares imperative and declarative validation errors |
| 129 |
// and returns detailed information about any mismatches found. Errors are compared via type, field, and origin |
| 130 |
func gatherDeclarativeValidationMismatches(imperativeErrs, declarativeErrs field.ErrorList, takeover bool) []string { |
| 131 |
var mismatchDetails []string |
| 132 |
// short circuit here to minimize allocs for usual case of 0 validation errors |
| 133 |
if len(imperativeErrs) == 0 && len(declarativeErrs) == 0 { |
| 134 |
return mismatchDetails |
| 135 |
} |
| 136 |
// recommendation based on takeover status |
| 137 |
recommendation := "This difference should not affect system operation since hand written validation is authoritative." |
| 138 |
if takeover { |
| 139 |
recommendation = "Consider disabling the DeclarativeValidationTakeover feature gate to keep data persisted in etcd consistent with prior versions of Kubernetes." |
| 140 |
} |
| 141 |
fuzzyMatcher := field.ErrorMatcher{}.ByType().ByField().ByOrigin().RequireOriginWhenInvalid() |
| 142 |
exactMatcher := field.ErrorMatcher{}.Exactly() |
| 143 |
|
| 144 |
// Dedupe imperative errors of exact error matches as they are |
| 145 |
// not intended and come from (buggy) duplicate validation calls |
| 146 |
// This is necessary as without deduping we could get unmatched |
| 147 |
// imperative errors for cases that are correct (matching) |
| 148 |
dedupedImperativeErrs := field.ErrorList{} |
| 149 |
for _, err := range imperativeErrs { |
| 150 |
found := false |
| 151 |
for _, existingErr := range dedupedImperativeErrs { |
| 152 |
if exactMatcher.Matches(existingErr, err) { |
| 153 |
found = true |
| 154 |
break |
| 155 |
} |
| 156 |
} |
| 157 |
if !found { |
| 158 |
dedupedImperativeErrs = append(dedupedImperativeErrs, err) |
| 159 |
} |
| 160 |
} |
| 161 |
imperativeErrs = dedupedImperativeErrs |
| 162 |
|
| 163 |
// Create a copy of declarative errors to track remaining ones |
| 164 |
remaining := make(field.ErrorList, len(declarativeErrs)) |
| 165 |
copy(remaining, declarativeErrs) |
| 166 |
|
| 167 |
// Match each "covered" imperative error to declarative errors. |
| 168 |
// We use a fuzzy matching approach to find corresponding declarative errors |
| 169 |
// for each imperative error marked as CoveredByDeclarative. |
| 170 |
// As matches are found, they're removed from the 'remaining' list. |
| 171 |
// They are removed from `remaining` with a "1:many" mapping: for a given |
| 172 |
// imperative error we mark as matched all matching declarative errors |
| 173 |
// This allows us to: |
| 174 |
// 1. Detect imperative errors that should have matching declarative errors but don't |
| 175 |
// 2. Identify extra declarative errors with no imperative counterpart |
| 176 |
// Both cases indicate issues with the declarative validation implementation. |
| 177 |
for _, iErr := range imperativeErrs { |
| 178 |
if !iErr.CoveredByDeclarative { |
| 179 |
continue |
| 180 |
} |
| 181 |
|
| 182 |
tmp := make(field.ErrorList, 0, len(remaining)) |
| 183 |
matchCount := 0 |
| 184 |
|
| 185 |
for _, dErr := range remaining { |
| 186 |
if fuzzyMatcher.Matches(iErr, dErr) { |
| 187 |
matchCount++ |
| 188 |
} else { |
| 189 |
tmp = append(tmp, dErr) |
| 190 |
} |
| 191 |
} |
| 192 |
|
| 193 |
if matchCount == 0 { |
| 194 |
mismatchDetails = append(mismatchDetails, |
| 195 |
fmt.Sprintf( |
| 196 |
"Unexpected difference between hand written validation and declarative validation error results, unmatched error(s) found %s. "+ |
| 197 |
"This indicates an issue with declarative validation. %s", |
| 198 |
fuzzyMatcher.Render(iErr), |
| 199 |
recommendation, |
| 200 |
), |
| 201 |
) |
| 202 |
} |
| 203 |
|
| 204 |
remaining = tmp |
| 205 |
} |
| 206 |
|
| 207 |
// Any remaining unmatched declarative errors are considered "extra" |
| 208 |
for _, dErr := range remaining { |
| 209 |
mismatchDetails = append(mismatchDetails, |
| 210 |
fmt.Sprintf( |
| 211 |
"Unexpected difference between hand written validation and declarative validation error results, extra error(s) found %s. "+ |
| 212 |
"This indicates an issue with declarative validation. %s", |
| 213 |
fuzzyMatcher.Render(dErr), |
| 214 |
recommendation, |
| 215 |
), |
| 216 |
) |
| 217 |
} |
| 218 |
|
| 219 |
return mismatchDetails |
| 220 |
} |
| 221 |
|
| 222 |
// createDeclarativeValidationPanicHandler returns a function with panic recovery logic |
| 223 |
// that will increment the panic metric and either log or append errors based on the takeover parameter. |
| 224 |
func createDeclarativeValidationPanicHandler(ctx context.Context, errs *field.ErrorList, takeover bool) func() { |
| 225 |
logger := klog.FromContext(ctx) |
| 226 |
return func() { |
| 227 |
if r := recover(); r != nil { |
| 228 |
// Increment the panic metric counter |
| 229 |
validationmetrics.Metrics.IncDeclarativeValidationPanicMetric() |
| 230 |
|
| 231 |
const errorFmt = "panic during declarative validation: %v" |
| 232 |
if takeover { |
| 233 |
// If takeover is enabled, output as a validation error as authoritative validator panicked and validation should error |
| 234 |
*errs = append(*errs, field.InternalError(nil, fmt.Errorf(errorFmt, r))) |
| 235 |
} else { |
| 236 |
// if takeover not enabled, log the panic as an error message |
| 237 |
logger.Error(nil, fmt.Sprintf(errorFmt, r)) |
| 238 |
} |
| 239 |
} |
| 240 |
} |
| 241 |
} |
| 242 |
|
| 243 |
// panicSafeValidateFunc wraps a validation function with panic recovery logic. |
| 244 |
// It takes a validation function with the ValidateDeclaratively signature |
| 245 |
// and returns a function with the same signature. |
| 246 |
// The returned function will execute the wrapped function and handle any panics by |
| 247 |
// incrementing the panic metric, and logging an error message |
| 248 |
// if takeover=false, and adding a validation error if takeover=true. |
| 249 |
func panicSafeValidateFunc( |
| 250 |
validateFunc func(ctx context.Context, options sets.Set[string], scheme *runtime.Scheme, obj runtime.Object) field.ErrorList, |
| 251 |
takeover bool, |
| 252 |
) func(ctx context.Context, options sets.Set[string], scheme *runtime.Scheme, obj runtime.Object) field.ErrorList { |
| 253 |
return func(ctx context.Context, options sets.Set[string], scheme *runtime.Scheme, obj runtime.Object) (errs field.ErrorList) { |
| 254 |
defer createDeclarativeValidationPanicHandler(ctx, &errs, takeover)() |
| 255 |
|
| 256 |
return validateFunc(ctx, options, scheme, obj) |
| 257 |
} |
| 258 |
} |
| 259 |
|
| 260 |
// panicSafeValidateUpdateFunc wraps an update validation function with panic recovery logic. |
| 261 |
// It takes a validation function with the ValidateUpdateDeclaratively signature |
| 262 |
// and returns a function with the same signature. |
| 263 |
// The returned function will execute the wrapped function and handle any panics by |
| 264 |
// incrementing the panic metric, and logging an error message |
| 265 |
// if takeover=false, and adding a validation error if takeover=true. |
| 266 |
func panicSafeValidateUpdateFunc( |
| 267 |
validateUpdateFunc func(ctx context.Context, options sets.Set[string], scheme *runtime.Scheme, obj, oldObj runtime.Object) field.ErrorList, |
| 268 |
takeover bool, |
| 269 |
) func(ctx context.Context, options sets.Set[string], scheme *runtime.Scheme, obj, oldObj runtime.Object) field.ErrorList { |
| 270 |
return func(ctx context.Context, options sets.Set[string], scheme *runtime.Scheme, obj, oldObj runtime.Object) (errs field.ErrorList) { |
| 271 |
defer createDeclarativeValidationPanicHandler(ctx, &errs, takeover)() |
| 272 |
|
| 273 |
return validateUpdateFunc(ctx, options, scheme, obj, oldObj) |
| 274 |
} |
| 275 |
} |
| 276 |
|
| 277 |
// ValidateDeclarativelyWithRecovery validates obj against declarative validation tags |
| 278 |
// with panic recovery logic. It uses the API version extracted from ctx and the |
| 279 |
// provided scheme for validation. |
| 280 |
// |
| 281 |
// The ctx MUST contain requestInfo, which determines the target API for |
| 282 |
// validation. The obj is converted to the API version using the provided scheme |
| 283 |
// before validation occurs. The scheme MUST have the declarative validation |
| 284 |
// registered for the requested resource/subresource. |
| 285 |
// |
| 286 |
// option should contain any validation options that the declarative validation |
| 287 |
// tags expect. |
| 288 |
// |
| 289 |
// takeover determines if panic recovery should return validation errors (true) or |
| 290 |
// just log warnings (false). |
| 291 |
// |
| 292 |
// Returns a field.ErrorList containing any validation errors. An internal error |
| 293 |
// is included if requestInfo is missing from the context, if version |
| 294 |
// conversion fails, or if a panic occurs during validation when |
| 295 |
// takeover is true. |
| 296 |
func ValidateDeclarativelyWithRecovery(ctx context.Context, options sets.Set[string], scheme *runtime.Scheme, obj runtime.Object, takeover bool) field.ErrorList { |
| 297 |
return panicSafeValidateFunc(ValidateDeclaratively, takeover)(ctx, options, scheme, obj) |
| 298 |
} |
| 299 |
|
| 300 |
// ValidateUpdateDeclarativelyWithRecovery validates obj and oldObj against declarative |
| 301 |
// validation tags with panic recovery logic. It uses the API version extracted from |
| 302 |
// ctx and the provided scheme for validation. |
| 303 |
// |
| 304 |
// The ctx MUST contain requestInfo, which determines the target API for |
| 305 |
// validation. The obj is converted to the API version using the provided scheme |
| 306 |
// before validation occurs. The scheme MUST have the declarative validation |
| 307 |
// registered for the requested resource/subresource. |
| 308 |
// |
| 309 |
// option should contain any validation options that the declarative validation |
| 310 |
// tags expect. |
| 311 |
// |
| 312 |
// takeover determines if panic recovery should return validation errors (true) or |
| 313 |
// just log warnings (false). |
| 314 |
// |
| 315 |
// Returns a field.ErrorList containing any validation errors. An internal error |
| 316 |
// is included if requestInfo is missing from the context, if version |
| 317 |
// conversion fails, or if a panic occurs during validation when |
| 318 |
// takeover is true. |
| 319 |
func ValidateUpdateDeclarativelyWithRecovery(ctx context.Context, options sets.Set[string], scheme *runtime.Scheme, obj, oldObj runtime.Object, takeover bool) field.ErrorList { |
| 320 |
return panicSafeValidateUpdateFunc(ValidateUpdateDeclaratively, takeover)(ctx, options, scheme, obj, oldObj) |
| 321 |
} |