Skip to content

Commit 831fe94

Browse files
haywoodshhaywoodsh
committed
extend cache policy for more configurable parameters
Signed-off-by: Haywood Shannon <[email protected]>
1 parent d078f1a commit 831fe94

File tree

15 files changed

+916
-32
lines changed

15 files changed

+916
-32
lines changed

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

Lines changed: 126 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -140,6 +140,24 @@ 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+
maxLength: 1024
154+
type: string
155+
cacheMinUses:
156+
description: CacheMinUses sets the number of requests after which
157+
the response will be cached (proxy_cache_min_uses).
158+
maximum: 2147483647
159+
minimum: 1
160+
type: integer
143161
cachePurgeAllow:
144162
description: |-
145163
CachePurgeAllow defines IP addresses or CIDR blocks allowed to purge cache.
@@ -149,6 +167,20 @@ spec:
149167
items:
150168
type: string
151169
type: array
170+
cacheRevalidate:
171+
default: false
172+
description: |-
173+
CacheRevalidate enables revalidation of expired cache items using conditional requests (proxy_cache_revalidate).
174+
Uses "If-Modified-Since" and "If-None-Match" header fields.
175+
type: boolean
176+
cacheUseStale:
177+
description: |-
178+
CacheUseStale determines in which cases a stale cached response can be used (proxy_cache_use_stale).
179+
Valid parameters: error, timeout, invalid_header, updating, http_500, http_502, http_503, http_504, http_403, http_404, http_429, off.
180+
items:
181+
type: string
182+
maxItems: 11
183+
type: array
152184
cacheZoneName:
153185
description: |-
154186
CacheZoneName defines the name of the cache zone. Must start with a lowercase letter,
@@ -161,7 +193,32 @@ spec:
161193
CacheZoneSize defines the size of the cache zone. Must be a number followed by a size unit:
162194
'k' for kilobytes, 'm' for megabytes, or 'g' for gigabytes.
163195
Examples: "10m", "1g", "512k".
164-
pattern: ^[0-9]+[kmg]$
196+
pattern: ^[0-9]+[kmgKMG]$
197+
type: string
198+
conditions:
199+
description: Conditions defines when responses should not be cached
200+
or taken from cache.
201+
properties:
202+
bypass:
203+
description: |-
204+
Bypass defines conditions under which the response will not be taken from a cache (proxy_cache_bypass).
205+
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.
206+
items:
207+
type: string
208+
type: array
209+
noCache:
210+
description: |-
211+
NoCache defines conditions under which the response will not be saved to a cache (proxy_no_cache).
212+
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.
213+
items:
214+
type: string
215+
type: array
216+
type: object
217+
inactive:
218+
description: |-
219+
Inactive sets the time after which cached data that are not accessed get removed from the cache (inactive parameter).
220+
By default, inactive is set to 10 minutes.
221+
pattern: ^[0-9]+[smhd]$
165222
type: string
166223
levels:
167224
description: |-
@@ -172,6 +229,68 @@ spec:
172229
Invalid: "3:1", "1:3", "1:2:3".
173230
pattern: ^[12](?::[12]){0,2}$
174231
type: string
232+
lock:
233+
description: Lock configures cache locking to prevent multiple
234+
identical requests from populating the same cache element simultaneously.
235+
properties:
236+
age:
237+
description: |-
238+
Age sets the maximum time a cache lock can be held (proxy_cache_lock_age).
239+
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.
240+
pattern: ^[0-9]+[smhd]$
241+
type: string
242+
enable:
243+
default: false
244+
description: |-
245+
Enable sets whether cache locking is enabled (proxy_cache_lock).
246+
When enabled, only one request at a time will be allowed to populate a new cache element according to the proxy_cache_key.
247+
type: boolean
248+
timeout:
249+
description: |-
250+
Timeout sets a timeout for proxy_cache_lock.
251+
When the time expires, the request will be passed to the proxied server, however, the response will not be cached.
252+
pattern: ^[0-9]+[smhd]$
253+
type: string
254+
type: object
255+
x-kubernetes-validations:
256+
- message: timeout or age require enable=true
257+
rule: (!has(self.timeout) && !has(self.age)) || self.enable
258+
manager:
259+
description: Manager configures the cache manager process parameters
260+
(manager_files, manager_sleep, manager_threshold).
261+
properties:
262+
files:
263+
description: |-
264+
Files sets the maximum number of files that will be deleted in one iteration by the cache manager.
265+
During one iteration no more than manager_files items are deleted (by default, 100).
266+
maximum: 2147483647
267+
minimum: 1
268+
type: integer
269+
sleep:
270+
description: |-
271+
Sleep sets the pause between cache manager iterations.
272+
Between iterations, a pause configured by manager_sleep (by default, 50 milliseconds) is made.
273+
pattern: ^[0-9]+[mu]?s$
274+
type: string
275+
threshold:
276+
description: |-
277+
Threshold sets the maximum duration of one cache manager iteration.
278+
The duration of one iteration is limited by manager_threshold (by default, 200 milliseconds).
279+
pattern: ^[0-9]+[mu]?s$
280+
type: string
281+
type: object
282+
maxSize:
283+
description: |-
284+
MaxSize sets the maximum cache size (max_size parameter).
285+
When the size is exceeded, the cache manager removes the least recently used data.
286+
pattern: ^[0-9]+[kmgKMG]$
287+
type: string
288+
minFree:
289+
description: |-
290+
MinFree sets the minimum amount of free space required on the file system with cache (min_free parameter).
291+
When there is not enough free space, the cache manager removes the least recently used data.
292+
pattern: ^[0-9]+[kmgKMG]$
293+
type: string
175294
overrideUpstreamCache:
176295
default: false
177296
description: |-
@@ -188,6 +307,12 @@ spec:
188307
Examples: "30s", "5m", "1h", "2d".
189308
pattern: ^[0-9]+[smhd]$
190309
type: string
310+
useTempPath:
311+
default: false
312+
description: |-
313+
UseTempPath controls whether temporary files and the cache are put on different file systems (use_temp_path parameter).
314+
If set to off, temporary files will be put directly in the cache directory.
315+
type: boolean
191316
required:
192317
- cacheZoneName
193318
- cacheZoneSize

‎deploy/crds.yaml‎

Lines changed: 126 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -311,6 +311,24 @@ 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+
maxLength: 1024
325+
type: string
326+
cacheMinUses:
327+
description: CacheMinUses sets the number of requests after which
328+
the response will be cached (proxy_cache_min_uses).
329+
maximum: 2147483647
330+
minimum: 1
331+
type: integer
314332
cachePurgeAllow:
315333
description: |-
316334
CachePurgeAllow defines IP addresses or CIDR blocks allowed to purge cache.
@@ -320,6 +338,20 @@ spec:
320338
items:
321339
type: string
322340
type: array
341+
cacheRevalidate:
342+
default: false
343+
description: |-
344+
CacheRevalidate enables revalidation of expired cache items using conditional requests (proxy_cache_revalidate).
345+
Uses "If-Modified-Since" and "If-None-Match" header fields.
346+
type: boolean
347+
cacheUseStale:
348+
description: |-
349+
CacheUseStale determines in which cases a stale cached response can be used (proxy_cache_use_stale).
350+
Valid parameters: error, timeout, invalid_header, updating, http_500, http_502, http_503, http_504, http_403, http_404, http_429, off.
351+
items:
352+
type: string
353+
maxItems: 11
354+
type: array
323355
cacheZoneName:
324356
description: |-
325357
CacheZoneName defines the name of the cache zone. Must start with a lowercase letter,
@@ -332,7 +364,32 @@ spec:
332364
CacheZoneSize defines the size of the cache zone. Must be a number followed by a size unit:
333365
'k' for kilobytes, 'm' for megabytes, or 'g' for gigabytes.
334366
Examples: "10m", "1g", "512k".
335-
pattern: ^[0-9]+[kmg]$
367+
pattern: ^[0-9]+[kmgKMG]$
368+
type: string
369+
conditions:
370+
description: Conditions defines when responses should not be cached
371+
or taken from cache.
372+
properties:
373+
bypass:
374+
description: |-
375+
Bypass defines conditions under which the response will not be taken from a cache (proxy_cache_bypass).
376+
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.
377+
items:
378+
type: string
379+
type: array
380+
noCache:
381+
description: |-
382+
NoCache defines conditions under which the response will not be saved to a cache (proxy_no_cache).
383+
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.
384+
items:
385+
type: string
386+
type: array
387+
type: object
388+
inactive:
389+
description: |-
390+
Inactive sets the time after which cached data that are not accessed get removed from the cache (inactive parameter).
391+
By default, inactive is set to 10 minutes.
392+
pattern: ^[0-9]+[smhd]$
336393
type: string
337394
levels:
338395
description: |-
@@ -343,6 +400,68 @@ spec:
343400
Invalid: "3:1", "1:3", "1:2:3".
344401
pattern: ^[12](?::[12]){0,2}$
345402
type: string
403+
lock:
404+
description: Lock configures cache locking to prevent multiple
405+
identical requests from populating the same cache element simultaneously.
406+
properties:
407+
age:
408+
description: |-
409+
Age sets the maximum time a cache lock can be held (proxy_cache_lock_age).
410+
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.
411+
pattern: ^[0-9]+[smhd]$
412+
type: string
413+
enable:
414+
default: false
415+
description: |-
416+
Enable sets whether cache locking is enabled (proxy_cache_lock).
417+
When enabled, only one request at a time will be allowed to populate a new cache element according to the proxy_cache_key.
418+
type: boolean
419+
timeout:
420+
description: |-
421+
Timeout sets a timeout for proxy_cache_lock.
422+
When the time expires, the request will be passed to the proxied server, however, the response will not be cached.
423+
pattern: ^[0-9]+[smhd]$
424+
type: string
425+
type: object
426+
x-kubernetes-validations:
427+
- message: timeout or age require enable=true
428+
rule: (!has(self.timeout) && !has(self.age)) || self.enable
429+
manager:
430+
description: Manager configures the cache manager process parameters
431+
(manager_files, manager_sleep, manager_threshold).
432+
properties:
433+
files:
434+
description: |-
435+
Files sets the maximum number of files that will be deleted in one iteration by the cache manager.
436+
During one iteration no more than manager_files items are deleted (by default, 100).
437+
maximum: 2147483647
438+
minimum: 1
439+
type: integer
440+
sleep:
441+
description: |-
442+
Sleep sets the pause between cache manager iterations.
443+
Between iterations, a pause configured by manager_sleep (by default, 50 milliseconds) is made.
444+
pattern: ^[0-9]+[mu]?s$
445+
type: string
446+
threshold:
447+
description: |-
448+
Threshold sets the maximum duration of one cache manager iteration.
449+
The duration of one iteration is limited by manager_threshold (by default, 200 milliseconds).
450+
pattern: ^[0-9]+[mu]?s$
451+
type: string
452+
type: object
453+
maxSize:
454+
description: |-
455+
MaxSize sets the maximum cache size (max_size parameter).
456+
When the size is exceeded, the cache manager removes the least recently used data.
457+
pattern: ^[0-9]+[kmgKMG]$
458+
type: string
459+
minFree:
460+
description: |-
461+
MinFree sets the minimum amount of free space required on the file system with cache (min_free parameter).
462+
When there is not enough free space, the cache manager removes the least recently used data.
463+
pattern: ^[0-9]+[kmgKMG]$
464+
type: string
346465
overrideUpstreamCache:
347466
default: false
348467
description: |-
@@ -359,6 +478,12 @@ spec:
359478
Examples: "30s", "5m", "1h", "2d".
360479
pattern: ^[0-9]+[smhd]$
361480
type: string
481+
useTempPath:
482+
default: false
483+
description: |-
484+
UseTempPath controls whether temporary files and the cache are put on different file systems (use_temp_path parameter).
485+
If set to off, temporary files will be put directly in the cache directory.
486+
type: boolean
362487
required:
363488
- cacheZoneName
364489
- cacheZoneSize

0 commit comments

Comments
 (0)