k8s.io/apiserver@v0.31.1/pkg/admission/plugin/cel/interface.go (about)

     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  }
    67  
    68  // FilterCompiler contains a function to assist with converting types and values to/from CEL-typed values.
    69  type FilterCompiler interface {
    70  	// Compile is used for the cel expression compilation
    71  	Compile(expressions []ExpressionAccessor, optionalDecls OptionalVariableDeclarations, envType environment.Type) Filter
    72  }
    73  
    74  // OptionalVariableBindings provides expression bindings for optional CEL variables.
    75  type OptionalVariableBindings struct {
    76  	// VersionedParams provides the "params" variable binding. This variable binding may
    77  	// be set to nil even when OptionalVariableDeclarations.HashParams is set to true.
    78  	VersionedParams runtime.Object
    79  	// Authorizer provides the authorizer used for the "authorizer" and
    80  	// "authorizer.requestResource" variable bindings. If the expression was compiled with
    81  	// OptionalVariableDeclarations.HasAuthorizer set to true this must be non-nil.
    82  	Authorizer authorizer.Authorizer
    83  }
    84  
    85  // Filter contains a function to evaluate compiled CEL-typed values
    86  // It expects the inbound object to already have been converted to the version expected
    87  // by the underlying CEL code (which is indicated by the match criteria of a policy definition).
    88  // versionedParams may be nil.
    89  type Filter interface {
    90  	// ForInput converts compiled CEL-typed values into evaluated CEL-typed value.
    91  	// runtimeCELCostBudget was added for testing purpose only. Callers should always use const RuntimeCELCostBudget from k8s.io/apiserver/pkg/apis/cel/config.go as input.
    92  	// If cost budget is calculated, the filter should return the remaining budget.
    93  	ForInput(ctx context.Context, versionedAttr *admission.VersionedAttributes, request *v1.AdmissionRequest, optionalVars OptionalVariableBindings, namespace *corev1.Namespace, runtimeCELCostBudget int64) ([]EvaluationResult, int64, error)
    94  
    95  	// CompilationErrors returns a list of errors from the compilation of the evaluator
    96  	CompilationErrors() []error
    97  }