Debian Codegraph @

pkg/cel/environment/base.go

raw
1 /*
2 Copyright 2023 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 environment
18
19 import (
20 "fmt"
21 "strconv"
22 "sync"
23 "sync/atomic"
24
25 "github.com/google/cel-go/cel"
26 "github.com/google/cel-go/checker"
27 "github.com/google/cel-go/ext"
28 "github.com/google/cel-go/interpreter"
29 "golang.org/x/sync/singleflight"
30
31 "k8s.io/apimachinery/pkg/util/version"
32 celconfig "k8s.io/apiserver/pkg/apis/cel"
33 "k8s.io/apiserver/pkg/cel/library"
34 genericfeatures "k8s.io/apiserver/pkg/features"
35 "k8s.io/apiserver/pkg/util/compatibility"
36 utilfeature "k8s.io/apiserver/pkg/util/feature"
37 basecompatibility "k8s.io/component-base/compatibility"
38 )
39
40 // DefaultCompatibilityVersion returns a default compatibility version for use with EnvSet
41 // that guarantees compatibility with CEL features/libraries/parameters understood by
42 // the api server min compatibility version
43 //
44 // This default will be set to no more than the current Kubernetes major.minor version.
45 //
46 // Note that a default version number less than n-1 the current Kubernetes major.minor version
47 // indicates a wider range of version compatibility than strictly required for rollback.
48 // A wide range of compatibility is desirable because it means that CEL expressions are portable
49 // across a wider range of Kubernetes versions.
50 // A default version number equal to the current Kubernetes major.minor version
51 // indicates fast forward CEL features that can be used when rollback is no longer needed.
52 func DefaultCompatibilityVersion() *version.Version {
53 effectiveVer := compatibility.DefaultComponentGlobalsRegistry.EffectiveVersionFor(basecompatibility.DefaultKubeComponent)
54 if effectiveVer == nil {
55 effectiveVer = compatibility.DefaultBuildEffectiveVersion()
56 }
57 return effectiveVer.MinCompatibilityVersion()
58 }
59
60 var baseOpts = append(baseOptsWithoutStrictCost, StrictCostOpt)
61
62 var baseOptsWithoutStrictCost = []VersionedOptions{
63 {
64 // CEL epoch was actually 1.23, but we artificially set it to 1.0 because these
65 // options should always be present.
66 IntroducedVersion: version.MajorMinor(1, 0),
67 EnvOptions: []cel.EnvOption{
68 cel.HomogeneousAggregateLiterals(),
69 // Validate function declarations once during base env initialization,
70 // so they don't need to be evaluated each time a CEL rule is compiled.
71 // This is a relatively expensive operation.
72 cel.EagerlyValidateDeclarations(true),
73 cel.DefaultUTCTimeZone(true),
74
75 UnversionedLib(library.URLs),
76 UnversionedLib(library.Regex),
77 UnversionedLib(library.Lists),
78
79 // cel-go v0.17.7 change the cost of has() from 0 to 1, but also provided the CostEstimatorOptions option to preserve the old behavior, so we enabled it at the same time we bumped our cel version to v0.17.7.
80 // Since it is a regression fix, we apply it uniformly to all code use v0.17.7.
81 cel.CostEstimatorOptions(checker.PresenceTestHasCost(false)),
82 },
83 ProgramOptions: []cel.ProgramOption{
84 cel.EvalOptions(cel.OptOptimize, cel.OptTrackCost),
85 cel.CostLimit(celconfig.PerCallLimit),
86
87 // cel-go v0.17.7 change the cost of has() from 0 to 1, but also provided the CostEstimatorOptions option to preserve the old behavior, so we enabled it at the same time we bumped our cel version to v0.17.7.
88 // Since it is a regression fix, we apply it uniformly to all code use v0.17.7.
89 cel.CostTrackerOptions(interpreter.PresenceTestHasCost(false)),
90 },
91 },
92 {
93 IntroducedVersion: version.MajorMinor(1, 27),
94 EnvOptions: []cel.EnvOption{
95 UnversionedLib(library.Authz),
96 },
97 },
98 {
99 IntroducedVersion: version.MajorMinor(1, 28),
100 EnvOptions: []cel.EnvOption{
101 cel.CrossTypeNumericComparisons(true),
102 cel.OptionalTypes(),
103 UnversionedLib(library.Quantity),
104 },
105 },
106 // add the new validator in 1.29
107 {
108 IntroducedVersion: version.MajorMinor(1, 29),
109 EnvOptions: []cel.EnvOption{
110 cel.ASTValidators(
111 cel.ValidateDurationLiterals(),
112 cel.ValidateTimestampLiterals(),
113 cel.ValidateRegexLiterals(),
114 cel.ValidateHomogeneousAggregateLiterals(),
115 ),
116 },
117 },
118 // String library
119 {
120 IntroducedVersion: version.MajorMinor(1, 0),
121 RemovedVersion: version.MajorMinor(1, 29),
122 EnvOptions: []cel.EnvOption{
123 ext.Strings(ext.StringsVersion(0)),
124 },
125 },
126 {
127 IntroducedVersion: version.MajorMinor(1, 29),
128 EnvOptions: []cel.EnvOption{
129 ext.Strings(ext.StringsVersion(2)),
130 },
131 },
132 // Set library
133 {
134 IntroducedVersion: version.MajorMinor(1, 29),
135 EnvOptions: []cel.EnvOption{
136 ext.Sets(),
137 },
138 },
139 {
140 IntroducedVersion: version.MajorMinor(1, 30),
141 EnvOptions: []cel.EnvOption{
142 UnversionedLib(library.IP),
143 UnversionedLib(library.CIDR),
144 },
145 },
146 // Format Library
147 {
148 IntroducedVersion: version.MajorMinor(1, 31),
149 EnvOptions: []cel.EnvOption{
150 UnversionedLib(library.Format),
151 },
152 },
153 // Authz selectors
154 {
155 IntroducedVersion: version.MajorMinor(1, 31),
156 FeatureEnabled: func() bool {
157 enabled := utilfeature.DefaultFeatureGate.Enabled(genericfeatures.AuthorizeWithSelectors)
158 authzSelectorsLibraryInit.Do(func() {
159 // Record the first time feature enablement was checked for this library.
160 // This is checked from integration tests to ensure no cached cel envs
161 // are constructed before feature enablement is effectively set.
162 authzSelectorsLibraryEnabled.Store(enabled)
163 // Uncomment to debug where the first initialization is coming from if needed.
164 // debug.PrintStack()
165 })
166 return enabled
167 },
168 EnvOptions: []cel.EnvOption{
169 UnversionedLib(library.AuthzSelectors),
170 },
171 },
172 // Two variable comprehensions
173 {
174 IntroducedVersion: version.MajorMinor(1, 32),
175 EnvOptions: []cel.EnvOption{
176 ext.TwoVarComprehensions(),
177 },
178 },
179 // Semver
180 {
181 IntroducedVersion: version.MajorMinor(1, 33),
182 EnvOptions: []cel.EnvOption{
183 library.SemverLib(library.SemverVersion(1)),
184 },
185 },
186 }
187
188 var (
189 authzSelectorsLibraryInit sync.Once
190 authzSelectorsLibraryEnabled atomic.Value
191 )
192
193 // AuthzSelectorsLibraryEnabled returns whether the AuthzSelectors library was enabled when it was constructed.
194 // If it has not been contructed yet, this returns `false, false`.
195 // This is solely for the benefit of the integration tests making sure feature gates get correctly parsed before AuthzSelector ever has to check for enablement.
196 func AuthzSelectorsLibraryEnabled() (enabled, constructed bool) {
197 enabled, constructed = authzSelectorsLibraryEnabled.Load().(bool)
198 return
199 }
200
201 var StrictCostOpt = VersionedOptions{
202 // This is to configure the cost calculation for extended libraries
203 IntroducedVersion: version.MajorMinor(1, 0),
204 ProgramOptions: []cel.ProgramOption{
205 cel.CostTracking(&library.CostEstimator{}),
206 },
207 }
208
209 // cacheBaseEnvs controls whether calls to MustBaseEnvSet are cached.
210 // Defaults to true, may be disabled by calling DisableBaseEnvSetCachingForTests.
211 var cacheBaseEnvs = true
212
213 // DisableBaseEnvSetCachingForTests clears and disables base env caching.
214 // This is only intended for unit tests exercising MustBaseEnvSet directly with different enablement options.
215 // It does not clear other initialization paths that may cache results of calling MustBaseEnvSet.
216 func DisableBaseEnvSetCachingForTests() {
217 cacheBaseEnvs = false
218 baseEnvs.Clear()
219 baseEnvsWithOption.Clear()
220 }
221
222 // MustBaseEnvSet returns the common CEL base environments for Kubernetes for Version, or panics
223 // if the version is nil, or does not have major and minor components.
224 //
225 // The returned environment contains function libraries, language settings, optimizations and
226 // runtime cost limits appropriate CEL as it is used in Kubernetes.
227 //
228 // The returned environment contains no CEL variable definitions or custom type declarations and
229 // should be extended to construct environments with the appropriate variable definitions,
230 // type declarations and any other needed configuration.
231 // strictCost is used to determine whether to enforce strict cost calculation for CEL expressions.
232 func MustBaseEnvSet(ver *version.Version, strictCost bool) *EnvSet {
233 if ver == nil {
234 panic("version must be non-nil")
235 }
236 if len(ver.Components()) < 2 {
237 panic(fmt.Sprintf("version must contain an major and minor component, but got: %s", ver.String()))
238 }
239 key := strconv.FormatUint(uint64(ver.Major()), 10) + "." + strconv.FormatUint(uint64(ver.Minor()), 10)
240 var entry interface{}
241 if strictCost {
242 if entry, ok := baseEnvs.Load(key); ok {
243 return entry.(*EnvSet)
244 }
245 entry, _, _ = baseEnvsSingleflight.Do(key, func() (interface{}, error) {
246 entry := mustNewEnvSet(ver, baseOpts)
247 if cacheBaseEnvs {
248 baseEnvs.Store(key, entry)
249 }
250 return entry, nil
251 })
252 } else {
253 if entry, ok := baseEnvsWithOption.Load(key); ok {
254 return entry.(*EnvSet)
255 }
256 entry, _, _ = baseEnvsWithOptionSingleflight.Do(key, func() (interface{}, error) {
257 entry := mustNewEnvSet(ver, baseOptsWithoutStrictCost)
258 if cacheBaseEnvs {
259 baseEnvsWithOption.Store(key, entry)
260 }
261 return entry, nil
262 })
263 }
264
265 return entry.(*EnvSet)
266 }
267
268 var (
269 baseEnvs = sync.Map{}
270 baseEnvsWithOption = sync.Map{}
271 baseEnvsSingleflight = &singleflight.Group{}
272 baseEnvsWithOptionSingleflight = &singleflight.Group{}
273 )
274
275 // UnversionedLib wraps library initialization calls like ext.Sets() or library.IP()
276 // to force compilation errors if the call evolves to include a varadic variable option.
277 //
278 // This provides automatic detection of a problem that is hard to catch in review--
279 // If a CEL library used in Kubernetes is unversioned and then become versioned, and we
280 // fail to set a desired version, the libraries defaults to the latest version, changing
281 // CEL environment without controlled rollout, bypassing the entire purpose of the base
282 // environment.
283 //
284 // If usages of this function fail to compile: add version=1 argument to all call sites
285 // that fail compilation while removing the UnversionedLib wrapper. Next, review
286 // the changes in the library present in higher versions and, if needed, use VersionedOptions to
287 // the base environment to roll out to a newer version safely.
288 func UnversionedLib(initializer func() cel.EnvOption) cel.EnvOption {
289 return initializer()
290 }