Debian Codegraph @

pkg/admission/plugin/cel/interface.go

raw
1 /*
2 Copyright 2022 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 cel
18
19 import (
20 "context"
21 "time"
22
23 "github.com/google/cel-go/cel"
24 "github.com/google/cel-go/common/types/ref"
25
26 v1 "k8s.io/api/admission/v1"
27 corev1 "k8s.io/api/core/v1"
28 "k8s.io/apimachinery/pkg/runtime"
29 "k8s.io/apiserver/pkg/admission"
30 "k8s.io/apiserver/pkg/authorization/authorizer"
31 "k8s.io/apiserver/pkg/cel/environment"
32 )
33
34 type ExpressionAccessor interface {
35 GetExpression() string
36 ReturnTypes() []*cel.Type
37 }
38
39 // NamedExpressionAccessor extends NamedExpressionAccessor with a name.
40 type NamedExpressionAccessor interface {
41 ExpressionAccessor
42
43 GetName() string // follows the naming convention of ExpressionAccessor
44 }
45
46 // EvaluationResult contains the minimal required fields and metadata of a cel evaluation
47 type EvaluationResult struct {
48 EvalResult ref.Val
49 ExpressionAccessor ExpressionAccessor
50 Elapsed time.Duration
51 Error error
52 }
53
54 // OptionalVariableDeclarations declares which optional CEL variables
55 // are declared for an expression.
56 type OptionalVariableDeclarations struct {
57 // HasParams specifies if the "params" variable is declared.
58 // The "params" variable may still be bound to "null" when declared.
59 HasParams bool
60 // HasAuthorizer specifies if the "authorizer" and "authorizer.requestResource"
61 // variables are declared. When declared, the authorizer variables are
62 // expected to be non-null.
63 HasAuthorizer bool
64 // StrictCost specifies if the CEL cost limitation is strict for extended libraries as well as native libraries.
65 StrictCost bool
66 // HasPatchTypes specifies if JSONPatch, Object, Object.metadata and similar types are available in CEL. These can be used
67 // to initialize the typed objects in CEL required to create patches.
68 HasPatchTypes bool
69 }
70
71 // ConditionCompiler contains a function to assist with converting types and values to/from CEL-typed values.
72 type ConditionCompiler interface {
73 // CompileCondition is used for the cel expression compilation
74 CompileCondition(expressions []ExpressionAccessor, optionalDecls OptionalVariableDeclarations, envType environment.Type) ConditionEvaluator
75 }
76
77 // OptionalVariableBindings provides expression bindings for optional CEL variables.
78 type OptionalVariableBindings struct {
79 // VersionedParams provides the "params" variable binding. This variable binding may
80 // be set to nil even when OptionalVariableDeclarations.HashParams is set to true.
81 VersionedParams runtime.Object
82 // Authorizer provides the authorizer used for the "authorizer" and
83 // "authorizer.requestResource" variable bindings. If the expression was compiled with
84 // OptionalVariableDeclarations.HasAuthorizer set to true this must be non-nil.
85 Authorizer authorizer.Authorizer
86 }
87
88 // ConditionEvaluator contains the result of compiling a CEL expression
89 // that evaluates to a condition. This is used both for validation and pre-conditions.
90 // It expects the inbound object to already have been converted to the version expected
91 // by the underlying CEL code (which is indicated by the match criteria of a policy definition).
92 // versionedParams may be nil.
93 type ConditionEvaluator interface {
94 // ForInput converts compiled CEL-typed values into evaluated CEL-typed value.
95 // runtimeCELCostBudget was added for testing purpose only. Callers should always use const RuntimeCELCostBudget from k8s.io/apiserver/pkg/apis/cel/config.go as input.
96 // If cost budget is calculated, the condition should return the remaining budget.
97 ForInput(ctx context.Context, versionedAttr *admission.VersionedAttributes, request *v1.AdmissionRequest, optionalVars OptionalVariableBindings, namespace *corev1.Namespace, runtimeCELCostBudget int64) ([]EvaluationResult, int64, error)
98
99 // CompilationErrors returns a list of errors from the compilation of the mutatingEvaluator
100 CompilationErrors() []error
101 }
102
103 // MutatingCompiler contains a function to assist with converting types and values to/from CEL-typed values.
104 type MutatingCompiler interface {
105 // CompileMutatingEvaluator is used for the cel expression compilation
106 CompileMutatingEvaluator(expression ExpressionAccessor, optionalDecls OptionalVariableDeclarations, envType environment.Type) MutatingEvaluator
107 }
108
109 // MutatingEvaluator contains the result of compiling a CEL expression
110 // that evaluates to a mutation.
111 // It expects the inbound object to already have been converted to the version expected
112 // by the underlying CEL code (which is indicated by the match criteria of a policy definition).
113 // versionedParams may be nil.
114 type MutatingEvaluator interface {
115 // ForInput converts compiled CEL-typed values into a CEL-typed value representing a mutation.
116 // runtimeCELCostBudget was added for testing purpose only. Callers should always use const RuntimeCELCostBudget from k8s.io/apiserver/pkg/apis/cel/config.go as input.
117 // If cost budget is calculated, the condition should return the remaining budget.
118 ForInput(ctx context.Context, versionedAttr *admission.VersionedAttributes, request *v1.AdmissionRequest, optionalVars OptionalVariableBindings, namespace *corev1.Namespace, runtimeCELCostBudget int64) (EvaluationResult, int64, error)
119
120 // CompilationErrors returns a list of errors from the compilation of the mutatingEvaluator
121 CompilationErrors() []error
122 }