Skip to content

Commit 450d1bc

Browse files
haywoodshhaywoodsh
authored
extend cache policy for more configurable parameters (#8533)
1 parent b8c6d89 commit 450d1bc

File tree

18 files changed

+1628
-53
lines changed

18 files changed

+1628
-53
lines changed

‎config/crd/bases/k8s.nginx.org_policies.yaml‎

Lines changed: 132 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -140,6 +140,29 @@ spec:
140140
x-kubernetes-validations:
141141
- message: 'allowed methods must be one of: GET, HEAD, POST'
142142
rule: self.all(method, method in ['GET', 'HEAD', 'POST'])
143+
cacheBackgroundUpdate:
144+
default: false
145+
description: |-
146+
CacheBackgroundUpdate allows starting a background subrequest to update an expired cache item (proxy_cache_background_update).
147+
A stale cached response is returned to the client while the cache is being updated.
148+
type: boolean
149+
cacheKey:
150+
description: |-
151+
CacheKey defines a key for caching (proxy_cache_key).
152+
By default, close to "$scheme$proxy_host$uri$is_args$args".
153+
Must not contain command execution patterns: $(, `, ;, &&, ||
154+
maxLength: 1024
155+
type: string
156+
x-kubernetes-validations:
157+
- message: 'cache key must not contain command execution patterns:
158+
$(, `, ;, &&, ||'
159+
rule: '!self.contains(''$('') && !self.contains(''`'') && !self.contains('';'')
160+
&& !self.contains(''&&'') && !self.contains(''||'')'
161+
cacheMinUses:
162+
description: CacheMinUses sets the number of requests after which
163+
the response will be cached (proxy_cache_min_uses).
164+
minimum: 1
165+
type: integer
143166
cachePurgeAllow:
144167
description: |-
145168
CachePurgeAllow defines IP addresses or CIDR blocks allowed to purge cache.
@@ -149,6 +172,20 @@ spec:
149172
items:
150173
type: string
151174
type: array
175+
cacheRevalidate:
176+
default: false
177+
description: |-
178+
CacheRevalidate enables revalidation of expired cache items using conditional requests (proxy_cache_revalidate).
179+
Uses "If-Modified-Since" and "If-None-Match" header fields.
180+
type: boolean
181+
cacheUseStale:
182+
description: |-
183+
CacheUseStale determines in which cases a stale cached response can be used (proxy_cache_use_stale).
184+
Valid parameters: error, timeout, invalid_header, updating, http_500, http_502, http_503, http_504, http_403, http_404, http_429, off.
185+
items:
186+
type: string
187+
maxItems: 11
188+
type: array
152189
cacheZoneName:
153190
description: |-
154191
CacheZoneName defines the name of the cache zone. Must start with a lowercase letter,
@@ -159,9 +196,34 @@ spec:
159196
cacheZoneSize:
160197
description: |-
161198
CacheZoneSize defines the size of the cache zone. Must be a number followed by a size unit:
162-
'k' for kilobytes, 'm' for megabytes, or 'g' for gigabytes.
199+
'k' or 'K' for kilobytes, 'm' or 'M' for megabytes, or 'g' or 'G' for gigabytes.
163200
Examples: "10m", "1g", "512k".
164-
pattern: ^[0-9]+[kmg]$
201+
pattern: ^[0-9]+[kmgKMG]$
202+
type: string
203+
conditions:
204+
description: Conditions defines when responses should not be cached
205+
or taken from cache.
206+
properties:
207+
bypass:
208+
description: |-
209+
Bypass defines conditions under which the response will not be taken from a cache (proxy_cache_bypass).
210+
If at least one value of the string parameters is not empty and is not equal to "0" then the response will not be taken from the cache.
211+
items:
212+
type: string
213+
type: array
214+
noCache:
215+
description: |-
216+
NoCache defines conditions under which the response will not be saved to a cache (proxy_no_cache).
217+
If at least one value of the string parameters is not empty and is not equal to "0" then the response will not be saved.
218+
items:
219+
type: string
220+
type: array
221+
type: object
222+
inactive:
223+
description: |-
224+
Inactive sets the time after which cached data that are not accessed get removed from the cache (inactive parameter).
225+
By default, inactive is set to 10 minutes.
226+
pattern: ^[0-9]+[smhd]$
165227
type: string
166228
levels:
167229
description: |-
@@ -172,6 +234,67 @@ spec:
172234
Invalid: "3:1", "1:3", "1:2:3".
173235
pattern: ^[12](?::[12]){0,2}$
174236
type: string
237+
lock:
238+
description: Lock configures cache locking to prevent multiple
239+
identical requests from populating the same cache element simultaneously.
240+
properties:
241+
age:
242+
description: |-
243+
Age sets the maximum time a cache lock can be held (proxy_cache_lock_age).
244+
If the last request passed to the proxied server for populating a new cache element has not completed for the specified time, one more request may be passed.
245+
pattern: ^[0-9]+[smhd]$
246+
type: string
247+
enable:
248+
default: false
249+
description: |-
250+
Enable sets whether cache locking is enabled (proxy_cache_lock).
251+
When enabled, only one request at a time will be allowed to populate a new cache element according to the proxy_cache_key.
252+
type: boolean
253+
timeout:
254+
description: |-
255+
Timeout sets a timeout for proxy_cache_lock.
256+
When the time expires, the request will be passed to the proxied server, however, the response will not be cached.
257+
pattern: ^[0-9]+[smhd]$
258+
type: string
259+
type: object
260+
x-kubernetes-validations:
261+
- message: timeout or age require enable=true
262+
rule: (!has(self.timeout) && !has(self.age)) || self.enable
263+
manager:
264+
description: Manager configures the cache manager process parameters
265+
(manager_files, manager_sleep, manager_threshold).
266+
properties:
267+
files:
268+
description: |-
269+
Files sets the maximum number of files that will be deleted in one iteration by the cache manager.
270+
During one iteration no more than manager_files items are deleted (by default, 100).
271+
minimum: 1
272+
type: integer
273+
sleep:
274+
description: |-
275+
Sleep sets the pause between cache manager iterations.
276+
Between iterations, a pause configured by manager_sleep (by default, 50 milliseconds) is made.
277+
pattern: ^[0-9]+[mu]?s$
278+
type: string
279+
threshold:
280+
description: |-
281+
Threshold sets the maximum duration of one cache manager iteration.
282+
The duration of one iteration is limited by manager_threshold (by default, 200 milliseconds).
283+
pattern: ^[0-9]+[mu]?s$
284+
type: string
285+
type: object
286+
maxSize:
287+
description: |-
288+
MaxSize sets the maximum cache size (max_size parameter).
289+
When the size is exceeded, the cache manager removes the least recently used data.
290+
pattern: ^[0-9]+[kmgKMG]$
291+
type: string
292+
minFree:
293+
description: |-
294+
MinFree sets the minimum amount of free space required on the file system with cache (min_free parameter).
295+
When there is not enough free space, the cache manager removes the least recently used data.
296+
pattern: ^[0-9]+[kmgKMG]$
297+
type: string
175298
overrideUpstreamCache:
176299
default: false
177300
description: |-
@@ -188,6 +311,13 @@ spec:
188311
Examples: "30s", "5m", "1h", "2d".
189312
pattern: ^[0-9]+[smhd]$
190313
type: string
314+
useTempPath:
315+
default: false
316+
description: |-
317+
UseTempPath controls whether temporary files and the cache are put on different file systems (use_temp_path parameter).
318+
If set to false, temporary files will be put directly in the cache directory (use_temp_path=off).
319+
Default: false (use_temp_path=off, which puts temp files directly in cache directory for better performance).
320+
type: boolean
191321
required:
192322
- cacheZoneName
193323
- cacheZoneSize

‎deploy/crds.yaml‎

Lines changed: 132 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -311,6 +311,29 @@ spec:
311311
x-kubernetes-validations:
312312
- message: 'allowed methods must be one of: GET, HEAD, POST'
313313
rule: self.all(method, method in ['GET', 'HEAD', 'POST'])
314+
cacheBackgroundUpdate:
315+
default: false
316+
description: |-
317+
CacheBackgroundUpdate allows starting a background subrequest to update an expired cache item (proxy_cache_background_update).
318+
A stale cached response is returned to the client while the cache is being updated.
319+
type: boolean
320+
cacheKey:
321+
description: |-
322+
CacheKey defines a key for caching (proxy_cache_key).
323+
By default, close to "$scheme$proxy_host$uri$is_args$args".
324+
Must not contain command execution patterns: $(, `, ;, &&, ||
325+
maxLength: 1024
326+
type: string
327+
x-kubernetes-validations:
328+
- message: 'cache key must not contain command execution patterns:
329+
$(, `, ;, &&, ||'
330+
rule: '!self.contains(''$('') && !self.contains(''`'') && !self.contains('';'')
331+
&& !self.contains(''&&'') && !self.contains(''||'')'
332+
cacheMinUses:
333+
description: CacheMinUses sets the number of requests after which
334+
the response will be cached (proxy_cache_min_uses).
335+
minimum: 1
336+
type: integer
314337
cachePurgeAllow:
315338
description: |-
316339
CachePurgeAllow defines IP addresses or CIDR blocks allowed to purge cache.
@@ -320,6 +343,20 @@ spec:
320343
items:
321344
type: string
322345
type: array
346+
cacheRevalidate:
347+
default: false
348+
description: |-
349+
CacheRevalidate enables revalidation of expired cache items using conditional requests (proxy_cache_revalidate).
350+
Uses "If-Modified-Since" and "If-None-Match" header fields.
351+
type: boolean
352+
cacheUseStale:
353+
description: |-
354+
CacheUseStale determines in which cases a stale cached response can be used (proxy_cache_use_stale).
355+
Valid parameters: error, timeout, invalid_header, updating, http_500, http_502, http_503, http_504, http_403, http_404, http_429, off.
356+
items:
357+
type: string
358+
maxItems: 11
359+
type: array
323360
cacheZoneName:
324361
description: |-
325362
CacheZoneName defines the name of the cache zone. Must start with a lowercase letter,
@@ -330,9 +367,34 @@ spec:
330367
cacheZoneSize:
331368
description: |-
332369
CacheZoneSize defines the size of the cache zone. Must be a number followed by a size unit:
333-
'k' for kilobytes, 'm' for megabytes, or 'g' for gigabytes.
370+
'k' or 'K' for kilobytes, 'm' or 'M' for megabytes, or 'g' or 'G' for gigabytes.
334371
Examples: "10m", "1g", "512k".
335-
pattern: ^[0-9]+[kmg]$
372+
pattern: ^[0-9]+[kmgKMG]$
373+
type: string
374+
conditions:
375+
description: Conditions defines when responses should not be cached
376+
or taken from cache.
377+
properties:
378+
bypass:
379+
description: |-
380+
Bypass defines conditions under which the response will not be taken from a cache (proxy_cache_bypass).
381+
If at least one value of the string parameters is not empty and is not equal to "0" then the response will not be taken from the cache.
382+
items:
383+
type: string
384+
type: array
385+
noCache:
386+
description: |-
387+
NoCache defines conditions under which the response will not be saved to a cache (proxy_no_cache).
388+
If at least one value of the string parameters is not empty and is not equal to "0" then the response will not be saved.
389+
items:
390+
type: string
391+
type: array
392+
type: object
393+
inactive:
394+
description: |-
395+
Inactive sets the time after which cached data that are not accessed get removed from the cache (inactive parameter).
396+
By default, inactive is set to 10 minutes.
397+
pattern: ^[0-9]+[smhd]$
336398
type: string
337399
levels:
338400
description: |-
@@ -343,6 +405,67 @@ spec:
343405
Invalid: "3:1", "1:3", "1:2:3".
344406
pattern: ^[12](?::[12]){0,2}$
345407
type: string
408+
lock:
409+
description: Lock configures cache locking to prevent multiple
410+
identical requests from populating the same cache element simultaneously.
411+
properties:
412+
age:
413+
description: |-
414+
Age sets the maximum time a cache lock can be held (proxy_cache_lock_age).
415+
If the last request passed to the proxied server for populating a new cache element has not completed for the specified time, one more request may be passed.
416+
pattern: ^[0-9]+[smhd]$
417+
type: string
418+
enable:
419+
default: false
420+
description: |-
421+
Enable sets whether cache locking is enabled (proxy_cache_lock).
422+
When enabled, only one request at a time will be allowed to populate a new cache element according to the proxy_cache_key.
423+
type: boolean
424+
timeout:
425+
description: |-
426+
Timeout sets a timeout for proxy_cache_lock.
427+
When the time expires, the request will be passed to the proxied server, however, the response will not be cached.
428+
pattern: ^[0-9]+[smhd]$
429+
type: string
430+
type: object
431+
x-kubernetes-validations:
432+
- message: timeout or age require enable=true
433+
rule: (!has(self.timeout) && !has(self.age)) || self.enable
434+
manager:
435+
description: Manager configures the cache manager process parameters
436+
(manager_files, manager_sleep, manager_threshold).
437+
properties:
438+
files:
439+
description: |-
440+
Files sets the maximum number of files that will be deleted in one iteration by the cache manager.
441+
During one iteration no more than manager_files items are deleted (by default, 100).
442+
minimum: 1
443+
type: integer
444+
sleep:
445+
description: |-
446+
Sleep sets the pause between cache manager iterations.
447+
Between iterations, a pause configured by manager_sleep (by default, 50 milliseconds) is made.
448+
pattern: ^[0-9]+[mu]?s$
449+
type: string
450+
threshold:
451+
description: |-
452+
Threshold sets the maximum duration of one cache manager iteration.
453+
The duration of one iteration is limited by manager_threshold (by default, 200 milliseconds).
454+
pattern: ^[0-9]+[mu]?s$
455+
type: string
456+
type: object
457+
maxSize:
458+
description: |-
459+
MaxSize sets the maximum cache size (max_size parameter).
460+
When the size is exceeded, the cache manager removes the least recently used data.
461+
pattern: ^[0-9]+[kmgKMG]$
462+
type: string
463+
minFree:
464+
description: |-
465+
MinFree sets the minimum amount of free space required on the file system with cache (min_free parameter).
466+
When there is not enough free space, the cache manager removes the least recently used data.
467+
pattern: ^[0-9]+[kmgKMG]$
468+
type: string
346469
overrideUpstreamCache:
347470
default: false
348471
description: |-
@@ -359,6 +482,13 @@ spec:
359482
Examples: "30s", "5m", "1h", "2d".
360483
pattern: ^[0-9]+[smhd]$
361484
type: string
485+
useTempPath:
486+
default: false
487+
description: |-
488+
UseTempPath controls whether temporary files and the cache are put on different file systems (use_temp_path parameter).
489+
If set to false, temporary files will be put directly in the cache directory (use_temp_path=off).
490+
Default: false (use_temp_path=off, which puts temp files directly in cache directory for better performance).
491+
type: boolean
362492
required:
363493
- cacheZoneName
364494
- cacheZoneSize

0 commit comments

Comments
 (0)