Debian Codegraph @

pkg/admission/plugin/policy/generic/policy_dispatcher.go

raw
1 /*
2 Copyright 2024 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 generic
18
19 import (
20 "context"
21 "errors"
22 "fmt"
23 "time"
24
25 "k8s.io/api/admissionregistration/v1"
26 apierrors "k8s.io/apimachinery/pkg/api/errors"
27 "k8s.io/apimachinery/pkg/api/meta"
28 metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
29 "k8s.io/apimachinery/pkg/runtime"
30 "k8s.io/apimachinery/pkg/runtime/schema"
31 utilruntime "k8s.io/apimachinery/pkg/util/runtime"
32 "k8s.io/apiserver/pkg/admission"
33 "k8s.io/apiserver/pkg/admission/plugin/policy/matching"
34 webhookgeneric "k8s.io/apiserver/pkg/admission/plugin/webhook/generic"
35 "k8s.io/client-go/informers"
36 "k8s.io/client-go/tools/cache"
37 )
38
39 // PolicyInvocation is a single policy-binding-param tuple from a Policy Hook
40 // in the context of a specific request. The params have already been resolved
41 // and any error in configuration or setting up the invocation is stored in
42 // the Error field.
43 type PolicyInvocation[P runtime.Object, B runtime.Object, E Evaluator] struct {
44 // Relevant policy for this hook.
45 // This field is always populated
46 Policy P
47
48 // Matched Kind for the request given the policy's matchconstraints
49 // May be empty if there was an error matching the resource
50 Kind schema.GroupVersionKind
51
52 // Matched Resource for the request given the policy's matchconstraints
53 // May be empty if there was an error matching the resource
54 Resource schema.GroupVersionResource
55
56 // Relevant binding for this hook.
57 // May be empty if there was an error with the policy's configuration itself
58 Binding B
59
60 // Compiled policy evaluator
61 Evaluator E
62
63 // Params fetched by the binding to use to evaluate the policy
64 Param runtime.Object
65 }
66
67 // dispatcherDelegate is called during a request with a pre-filtered list
68 // of (Policy, Binding, Param) tuples that are active and match the request.
69 // The dispatcher delegate is responsible for updating the object on the
70 // admission attributes in the case of mutation, or returning a status error in
71 // the case of validation.
72 //
73 // The delegate provides the "validation" or "mutation" aspect of dispatcher functionality
74 // (in contrast to generic.PolicyDispatcher which only selects active policies and params)
75 type dispatcherDelegate[P, B runtime.Object, E Evaluator] func(ctx context.Context, a admission.Attributes, o admission.ObjectInterfaces, versionedAttributes webhookgeneric.VersionedAttributeAccessor, invocations []PolicyInvocation[P, B, E]) ([]PolicyError, *apierrors.StatusError)
76
77 type policyDispatcher[P runtime.Object, B runtime.Object, E Evaluator] struct {
78 newPolicyAccessor func(P) PolicyAccessor
79 newBindingAccessor func(B) BindingAccessor
80 matcher PolicyMatcher
81 delegate dispatcherDelegate[P, B, E]
82 }
83
84 func NewPolicyDispatcher[P runtime.Object, B runtime.Object, E Evaluator](
85 newPolicyAccessor func(P) PolicyAccessor,
86 newBindingAccessor func(B) BindingAccessor,
87 matcher *matching.Matcher,
88 delegate dispatcherDelegate[P, B, E],
89 ) Dispatcher[PolicyHook[P, B, E]] {
90 return &policyDispatcher[P, B, E]{
91 newPolicyAccessor: newPolicyAccessor,
92 newBindingAccessor: newBindingAccessor,
93 matcher: NewPolicyMatcher(matcher),
94 delegate: delegate,
95 }
96 }
97
98 // Dispatch implements generic.Dispatcher. It loops through all active hooks
99 // (policy x binding pairs) and selects those which are active for the current
100 // request. It then resolves all params and creates an Invocation for each
101 // matching policy-binding-param tuple. The delegate is then called with the
102 // list of tuples.
103 func (d *policyDispatcher[P, B, E]) Start(ctx context.Context) error {
104 return nil
105 }
106
107 // Note: MatchConditions expressions are not evaluated here. The dispatcher delegate
108 // is expected to ignore the result of any policies whose match conditions dont pass.
109 // This may be possible to refactor so matchconditions are checked here instead.
110 func (d *policyDispatcher[P, B, E]) Dispatch(ctx context.Context, a admission.Attributes, o admission.ObjectInterfaces, hooks []PolicyHook[P, B, E]) error {
111 var relevantHooks []PolicyInvocation[P, B, E]
112 // Construct all the versions we need to call our webhooks
113 versionedAttrAccessor := &versionedAttributeAccessor{
114 versionedAttrs: map[schema.GroupVersionKind]*admission.VersionedAttributes{},
115 attr: a,
116 objectInterfaces: o,
117 }
118
119 var policyErrors []PolicyError
120 addConfigError := func(err error, definition PolicyAccessor, binding BindingAccessor) {
121 var message error
122 if binding == nil {
123 message = fmt.Errorf("failed to configure policy: %w", err)
124 } else {
125 message = fmt.Errorf("failed to configure binding: %w", err)
126 }
127
128 policyErrors = append(policyErrors, PolicyError{
129 Policy: definition,
130 Binding: binding,
131 Message: message,
132 })
133 }
134
135 for _, hook := range hooks {
136 policyAccessor := d.newPolicyAccessor(hook.Policy)
137 matches, matchGVR, matchGVK, err := d.matcher.DefinitionMatches(a, o, policyAccessor)
138 if err != nil {
139 // There was an error evaluating if this policy matches anything.
140 addConfigError(err, policyAccessor, nil)
141 continue
142 } else if !matches {
143 continue
144 } else if hook.ConfigurationError != nil {
145 addConfigError(hook.ConfigurationError, policyAccessor, nil)
146 continue
147 }
148
149 for _, binding := range hook.Bindings {
150 bindingAccessor := d.newBindingAccessor(binding)
151 matches, err = d.matcher.BindingMatches(a, o, bindingAccessor)
152 if err != nil {
153 // There was an error evaluating if this binding matches anything.
154 addConfigError(err, policyAccessor, bindingAccessor)
155 continue
156 } else if !matches {
157 continue
158 }
159
160 // here the binding matches.
161 // VersionedAttr result will be cached and reused later during parallel
162 // hook calls.
163 if _, err = versionedAttrAccessor.VersionedAttribute(matchGVK); err != nil {
164 // VersionedAttr result will be cached and reused later during parallel
165 // hook calls.
166 addConfigError(err, policyAccessor, nil)
167 continue
168 }
169
170 // Collect params for this binding
171 params, err := CollectParams(
172 policyAccessor.GetParamKind(),
173 hook.ParamInformer,
174 hook.ParamScope,
175 bindingAccessor.GetParamRef(),
176 a.GetNamespace(),
177 )
178 if err != nil {
179 // There was an error collecting params for this binding.
180 addConfigError(err, policyAccessor, bindingAccessor)
181 continue
182 }
183
184 // If params is empty and there was no error, that means that
185 // ParamNotFoundAction is ignore, so it shouldnt be added to list
186 for _, param := range params {
187 relevantHooks = append(relevantHooks, PolicyInvocation[P, B, E]{
188 Policy: hook.Policy,
189 Binding: binding,
190 Kind: matchGVK,
191 Resource: matchGVR,
192 Param: param,
193 Evaluator: hook.Evaluator,
194 })
195 }
196 }
197 }
198
199 if len(relevantHooks) > 0 {
200 extraPolicyErrors, statusError := d.delegate(ctx, a, o, versionedAttrAccessor, relevantHooks)
201 if statusError != nil {
202 return statusError
203 }
204 policyErrors = append(policyErrors, extraPolicyErrors...)
205 }
206
207 var filteredErrors []PolicyError
208 for _, e := range policyErrors {
209 // we always default the FailurePolicy if it is unset and validate it in API level
210 var policy v1.FailurePolicyType
211 if fp := e.Policy.GetFailurePolicy(); fp == nil {
212 policy = v1.Fail
213 } else {
214 policy = *fp
215 }
216
217 switch policy {
218 case v1.Ignore:
219 // TODO: add metrics for ignored error here
220 continue
221 case v1.Fail:
222 filteredErrors = append(filteredErrors, e)
223 default:
224 filteredErrors = append(filteredErrors, e)
225 }
226 }
227
228 if len(filteredErrors) > 0 {
229
230 forbiddenErr := admission.NewForbidden(a, fmt.Errorf("admission request denied by policy"))
231
232 // The forbiddenErr is always a StatusError.
233 var err *apierrors.StatusError
234 if !errors.As(forbiddenErr, &err) {
235 // Should never happen.
236 return apierrors.NewInternalError(fmt.Errorf("failed to create status error"))
237 }
238 err.ErrStatus.Message = ""
239
240 for _, policyError := range filteredErrors {
241 message := policyError.Error()
242
243 // If this is the first denied decision, use its message and reason
244 // for the status error message.
245 if err.ErrStatus.Message == "" {
246 err.ErrStatus.Message = message
247 if policyError.Reason != "" {
248 err.ErrStatus.Reason = policyError.Reason
249 }
250 }
251
252 // Add the denied decision's message to the status error's details
253 err.ErrStatus.Details.Causes = append(
254 err.ErrStatus.Details.Causes,
255 metav1.StatusCause{Message: message})
256 }
257
258 return err
259 }
260
261 return nil
262 }
263
264 // Returns params to use to evaluate a policy-binding with given param
265 // configuration. If the policy-binding has no param configuration, it
266 // returns a single-element list with a nil param.
267 func CollectParams(
268 paramKind *v1.ParamKind,
269 paramInformer informers.GenericInformer,
270 paramScope meta.RESTScope,
271 paramRef *v1.ParamRef,
272 namespace string,
273 ) ([]runtime.Object, error) {
274 // If definition has paramKind, paramRef is required in binding.
275 // If definition has no paramKind, paramRef set in binding will be ignored.
276 var params []runtime.Object
277 var paramStore cache.GenericNamespaceLister
278
279 // Make sure the param kind is ready to use
280 if paramKind != nil && paramRef != nil {
281 if paramInformer == nil {
282 return nil, fmt.Errorf("paramKind kind `%v` not known",
283 paramKind.String())
284 }
285
286 // Set up cluster-scoped, or namespaced access to the params
287 // "default" if not provided, and paramKind is namespaced
288 paramStore = paramInformer.Lister()
289 if paramScope.Name() == meta.RESTScopeNameNamespace {
290 paramsNamespace := namespace
291 if len(paramRef.Namespace) > 0 {
292 paramsNamespace = paramRef.Namespace
293 } else if len(paramsNamespace) == 0 {
294 // You must supply namespace if your matcher can possibly
295 // match a cluster-scoped resource
296 return nil, fmt.Errorf("cannot use namespaced paramRef in policy binding that matches cluster-scoped resources")
297 }
298
299 paramStore = paramInformer.Lister().ByNamespace(paramsNamespace)
300 }
301
302 // If the param informer for this admission policy has not yet
303 // had time to perform an initial listing, don't attempt to use
304 // it.
305 timeoutCtx, cancel := context.WithTimeout(context.Background(), 1*time.Second)
306 defer cancel()
307
308 if !cache.WaitForCacheSync(timeoutCtx.Done(), paramInformer.Informer().HasSynced) {
309 return nil, fmt.Errorf("paramKind kind `%v` not yet synced to use for admission",
310 paramKind.String())
311 }
312 }
313
314 // Find params to use with policy
315 switch {
316 case paramKind == nil:
317 // ParamKind is unset. Ignore any globalParamRef or namespaceParamRef
318 // setting.
319 return []runtime.Object{nil}, nil
320 case paramRef == nil:
321 // Policy ParamKind is set, but binding does not use it.
322 // Validate with nil params
323 return []runtime.Object{nil}, nil
324 case len(paramRef.Namespace) > 0 && paramScope.Name() == meta.RESTScopeRoot.Name():
325 // Not allowed to set namespace for cluster-scoped param
326 return nil, fmt.Errorf("paramRef.namespace must not be provided for a cluster-scoped `paramKind`")
327
328 case len(paramRef.Name) > 0:
329 if paramRef.Selector != nil {
330 // This should be validated, but just in case.
331 return nil, fmt.Errorf("paramRef.name and paramRef.selector are mutually exclusive")
332 }
333
334 switch param, err := paramStore.Get(paramRef.Name); {
335 case err == nil:
336 params = []runtime.Object{param}
337 case apierrors.IsNotFound(err):
338 // Param not yet available. User may need to wait a bit
339 // before being able to use it for validation.
340 //
341 // Set params to nil to prepare for not found action
342 params = nil
343 case apierrors.IsInvalid(err):
344 // Param mis-configured
345 // require to set namespace for namespaced resource
346 // and unset namespace for cluster scoped resource
347 return nil, err
348 default:
349 // Internal error
350 utilruntime.HandleError(err)
351 return nil, err
352 }
353 case paramRef.Selector != nil:
354 // Select everything by default if empty name and selector
355 selector, err := metav1.LabelSelectorAsSelector(paramRef.Selector)
356 if err != nil {
357 // Cannot parse label selector: configuration error
358 return nil, err
359
360 }
361
362 paramList, err := paramStore.List(selector)
363 if err != nil {
364 // There was a bad internal error
365 utilruntime.HandleError(err)
366 return nil, err
367 }
368
369 // Successfully grabbed params
370 params = paramList
371 default:
372 // Should be unreachable due to validation
373 return nil, fmt.Errorf("one of name or selector must be provided")
374 }
375
376 // Apply fail action for params not found case
377 if len(params) == 0 && paramRef.ParameterNotFoundAction != nil && *paramRef.ParameterNotFoundAction == v1.DenyAction {
378 return nil, errors.New("no params found for policy binding with `Deny` parameterNotFoundAction")
379 }
380
381 return params, nil
382 }
383
384 var _ webhookgeneric.VersionedAttributeAccessor = &versionedAttributeAccessor{}
385
386 type versionedAttributeAccessor struct {
387 versionedAttrs map[schema.GroupVersionKind]*admission.VersionedAttributes
388 attr admission.Attributes
389 objectInterfaces admission.ObjectInterfaces
390 }
391
392 func (v *versionedAttributeAccessor) VersionedAttribute(gvk schema.GroupVersionKind) (*admission.VersionedAttributes, error) {
393 if val, ok := v.versionedAttrs[gvk]; ok {
394 return val, nil
395 }
396 versionedAttr, err := admission.NewVersionedAttributes(v.attr, gvk, v.objectInterfaces)
397 if err != nil {
398 return nil, err
399 }
400 v.versionedAttrs[gvk] = versionedAttr
401 return versionedAttr, nil
402 }
403
404 type PolicyError struct {
405 Policy PolicyAccessor
406 Binding BindingAccessor
407 Message error
408 Reason metav1.StatusReason
409 }
410
411 func (c PolicyError) Error() string {
412 if c.Binding != nil {
413 return fmt.Sprintf("policy '%s' with binding '%s' denied request: %s", c.Policy.GetName(), c.Binding.GetName(), c.Message.Error())
414 }
415
416 return fmt.Sprintf("policy %q denied request: %s", c.Policy.GetName(), c.Message.Error())
417 }