Debian Codegraph @

pkg/registry/rest/validate.go

raw
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 }