add nginx content cache as cache policy

charts/nginx-ingress/templates/_helpers.tpl

@@ -352,14 +352,24 @@ List of volumes for controller.
 {{- if eq (include "nginx-ingress.readOnlyRootFilesystem" .) "true" }}
 - name: nginx-etc
   emptyDir: {}
+{{- if .Values.controller.cache.enableShared }}
+- name: nginx-cache
+  persistentVolumeClaim:
+    claimName: {{ .Values.controller.cache.sharedPVCName }}
+{{- else }}
 - name: nginx-cache
   emptyDir: {}
+{{- end }}
 - name: nginx-lib
   emptyDir: {}
 - name: nginx-state
   emptyDir: {}
 - name: nginx-log
   emptyDir: {}
+{{- else if .Values.controller.cache.enableShared }}
+- name: nginx-cache
+  persistentVolumeClaim:
+    claimName: {{ .Values.controller.cache.sharedPVCName }}
 {{- end }}
 {{- if .Values.controller.appprotect.v5 }}
 {{ toYaml .Values.controller.appprotect.volumes }}
@@ -419,6 +429,9 @@ volumeMounts:
   name: nginx-state
 - mountPath: /var/log/nginx
   name: nginx-log
+{{- else if .Values.controller.cache.enableShared }}
+- mountPath: /var/cache/nginx
+  name: nginx-cache
 {{- end }}
 {{- if .Values.controller.appprotect.v5 }}
 - name: app-protect-bd-config

charts/nginx-ingress/templates/controller-service.yaml

@@ -65,6 +65,14 @@ spec:
 {{- end }}
   selector:
     {{- include "nginx-ingress.selectorLabels" . | nindent 4 }}
+  {{- if .Values.controller.service.sessionAffinity.enable }}
+  sessionAffinity: {{ .Values.controller.service.sessionAffinity.type }}
+  {{- if eq .Values.controller.service.sessionAffinity.type "ClientIP" }}
+  sessionAffinityConfig:
+    clientIP:
+      timeoutSeconds: {{ .Values.controller.service.sessionAffinity.timeoutSeconds }}
+  {{- end }}
+  {{- end }}
   {{- if .Values.controller.service.externalIPs }}
   externalIPs:
 {{ toYaml .Values.controller.service.externalIPs | indent 4 }}

charts/nginx-ingress/values.schema.json

@@ -1455,6 +1455,50 @@
                 "type": "object",
                 "ref": "https://raw.githubusercontent.com/nginxinc/kubernetes-json-schema/master/v1.33.1/_definitions.json#/definitions/io.k8s.api.core.v1.ServicePort"
               }
+            },
+            "sessionAffinity": {
+              "type": "object",
+              "default": {},
+              "title": "The sessionAffinity Schema",
+              "required": [],
+              "properties": {
+                "enable": {
+                  "type": "boolean",
+                  "default": false,
+                  "title": "Enable session affinity",
+                  "examples": [
+                    false
+                  ]
+                },
+                "type": {
+                  "type": "string",
+                  "default": "ClientIP",
+                  "title": "Session affinity type",
+                  "enum": [
+                    "ClientIP"
+                  ],
+                  "examples": [
+                    "ClientIP"
+                  ]
+                },
+                "timeoutSeconds": {
+                  "type": "integer",
+                  "default": 3600,
+                  "title": "Session affinity timeout in seconds",
+                  "minimum": 1,
+                  "maximum": 86400,
+                  "examples": [
+                    3600
+                  ]
+                }
+              },
+              "examples": [
+                {
+                  "enable": false,
+                  "type": "ClientIP",
+                  "timeoutSeconds": 3600
+                }
+              ]
             }
           },
           "examples": [
@@ -1483,7 +1527,12 @@
                 "targetPort": 443,
                 "name": "https"
               },
-              "customPorts": []
+              "customPorts": [],
+              "sessionAffinity": {
+                "enable": false,
+                "type": "ClientIP",
+                "timeoutSeconds": 3600
+              }
             }
           ]
         },

charts/nginx-ingress/values.yaml

@@ -164,6 +164,16 @@ controller:
   ## Sets the log format of Ingress Controller. Options include: glog, json, text
   logFormat: glog
 
+  ## Cache configuration options
+  cache:
+    ## Enables shared cache across multiple pods using an external persistent volume
+    ## When enabled, the /var/cache/nginx directory will be mounted from a PVC instead of using emptyDir
+    ## User must create and configure a PVC with appropriate access mode
+    enableShared: false
+
+    ## The name of the PersistentVolumeClaim to use for shared cache, should match the name of the PVC created by the user
+    sharedPVCName: "nginx-shared-cache"
+
   ## A list of custom ports to expose on the NGINX Ingress Controller pod. Follows the conventional Kubernetes yaml syntax for container ports.
   customPorts: []
 
@@ -502,6 +512,15 @@ controller:
     ## A list of custom ports to expose through the Ingress Controller service. Follows the conventional Kubernetes yaml syntax for service ports.
     customPorts: []
 
+    ## Session affinity configuration for the Ingress Controller service, ensures requests from the same client IP go to the same pod
+    sessionAffinity:
+      ## Enable session affinity. Valid values: None, ClientIP
+      enable: false
+      ## Session affinity type. Currently only ClientIP is supported.
+      type: ClientIP
+      ## Session affinity timeout in seconds (default: 3600 = 1 hour)
+      timeoutSeconds: 3600
+
   serviceAccount:
     ## The annotations of the service account of the Ingress Controller pods.
     annotations: {}

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

@@ -109,6 +109,67 @@ spec:
                       otherwise the secret will be rejected as invalid.
                     type: string
                 type: object
+              cache:
+                description: The Cache Key defines a cache policy for proxy caching
+                properties:
+                  allowedCodes:
+                    description: AllowedCodes defines which response codes should
+                      be cached. Can be HTTP status codes (100-599) or the string
+                      "any" to cache all responses.
+                    items:
+                      anyOf:
+                      - type: integer
+                      - type: string
+                      x-kubernetes-int-or-string: true
+                    type: array
+                  allowedMethods:
+                    description: AllowedMethods defines which HTTP methods should
+                      be cached. Only GET, HEAD, and POST are supported by NGINX proxy_cache_methods
+                      directive. GET and HEAD are always cached by default.
+                    enum:
+                    - GET
+                    - HEAD
+                    - POST
+                    items:
+                      type: string
+                    type: array
+                  cachePurgeAllow:
+                    description: CachePurgeAllow defines IP addresses allowed to purge
+                      cache (NGINX Plus only).
+                    items:
+                      type: string
+                    type: array
+                  cacheZoneName:
+                    description: CacheZoneName defines the name of the cache zone.
+                    maxLength: 64
+                    pattern: ^[a-z][a-zA-Z0-9_]*[a-zA-Z0-9]$|^[a-z]$
+                    type: string
+                  cacheZoneSize:
+                    description: CacheZoneSize defines the size of the cache zone.
+                    pattern: ^[0-9]+[kmg]$
+                    type: string
+                  levels:
+                    description: Levels defines the cache directory hierarchy levels
+                      for storing cached files (e.g., "1:2", "2:2", "1:2:2").
+                    pattern: ^[12](?::[12]){0,2}$
+                    type: string
+                  overrideUpstreamCache:
+                    default: false
+                    description: OverrideUpstreamCache controls whether to override
+                      upstream cache headers (using proxy_ignore_headers directive).
+                    type: boolean
+                  time:
+                    description: Time defines the default cache time (required when
+                      allowedCodes is specified).
+                    pattern: ^[0-9]+[smhd]$
+                    type: string
+                required:
+                - cacheZoneName
+                - cacheZoneSize
+                type: object
+                x-kubernetes-validations:
+                - message: time is required when allowedCodes is specified
+                  rule: '!has(self.allowedCodes) || (has(self.allowedCodes) && has(self.time))'
               egressMTLS:
                 description: The EgressMTLS policy configures upstreams authentication
                   and certificate verification.

deploy/crds.yaml

@@ -280,6 +280,67 @@ spec:
                       otherwise the secret will be rejected as invalid.
                     type: string
                 type: object
+              cache:
+                description: The Cache Key defines a cache policy for proxy caching
+                properties:
+                  allowedCodes:
+                    description: AllowedCodes defines which response codes should
+                      be cached. Can be HTTP status codes (100-599) or the string
+                      "any" to cache all responses.
+                    items:
+                      anyOf:
+                      - type: integer
+                      - type: string
+                      x-kubernetes-int-or-string: true
+                    type: array
+                  allowedMethods:
+                    description: AllowedMethods defines which HTTP methods should
+                      be cached. Only GET, HEAD, and POST are supported by NGINX proxy_cache_methods
+                      directive. GET and HEAD are always cached by default.
+                    enum:
+                    - GET
+                    - HEAD
+                    - POST
+                    items:
+                      type: string
+                    type: array
+                  cachePurgeAllow:
+                    description: CachePurgeAllow defines IP addresses allowed to purge
+                      cache (NGINX Plus only).
+                    items:
+                      type: string
+                    type: array
+                  cacheZoneName:
+                    description: CacheZoneName defines the name of the cache zone.
+                    maxLength: 64
+                    pattern: ^[a-z][a-zA-Z0-9_]*[a-zA-Z0-9]$|^[a-z]$
+                    type: string
+                  cacheZoneSize:
+                    description: CacheZoneSize defines the size of the cache zone.
+                    pattern: ^[0-9]+[kmg]$
+                    type: string
+                  levels:
+                    description: Levels defines the cache directory hierarchy levels
+                      for storing cached files (e.g., "1:2", "2:2", "1:2:2").
+                    pattern: ^[12](?::[12]){0,2}$
+                    type: string
+                  overrideUpstreamCache:
+                    default: false
+                    description: OverrideUpstreamCache controls whether to override
+                      upstream cache headers (using proxy_ignore_headers directive).
+                    type: boolean
+                  time:
+                    description: Time defines the default cache time (required when
+                      allowedCodes is specified).
+                    pattern: ^[0-9]+[smhd]$
+                    type: string
+                required:
+                - cacheZoneName
+                - cacheZoneSize
+                type: object
+                x-kubernetes-validations:
+                - message: time is required when allowedCodes is specified
+                  rule: '!has(self.allowedCodes) || (has(self.allowedCodes) && has(self.time))'
               egressMTLS:
                 description: The EgressMTLS policy configures upstreams authentication
                   and certificate verification.

docs/crd/k8s.nginx.org_policies.md

@@ -26,6 +26,15 @@ The `.spec` object supports the following fields:
 | `basicAuth` | `object` | The basic auth policy configures NGINX to authenticate client requests using HTTP Basic authentication credentials. |
 | `basicAuth.realm` | `string` | The realm for the basic authentication. |
 | `basicAuth.secret` | `string` | The name of the Kubernetes secret that stores the Htpasswd configuration. It must be in the same namespace as the Policy resource. The secret must be of the type nginx.org/htpasswd, and the config must be stored in the secret under the key htpasswd, otherwise the secret will be rejected as invalid. |
+| `cache` | `object` | The Cache Key defines a cache policy for proxy caching |
+| `cache.allowedCodes` | `array` | AllowedCodes defines which response codes should be cached. Can be HTTP status codes (100-599) or the string "any" to cache all responses. |
+| `cache.allowedMethods` | `array[string]` | AllowedMethods defines which HTTP methods should be cached. Only GET, HEAD, and POST are supported by NGINX proxy_cache_methods directive. GET and HEAD are always cached by default. Allowed values: `"GET"`, `"HEAD"`, `"POST"`. |
+| `cache.cachePurgeAllow` | `array[string]` | CachePurgeAllow defines IP addresses allowed to purge cache (NGINX Plus only). |
+| `cache.cacheZoneName` | `string` | CacheZoneName defines the name of the cache zone. |
+| `cache.cacheZoneSize` | `string` | CacheZoneSize defines the size of the cache zone. |
+| `cache.levels` | `string` | Levels defines the cache directory hierarchy levels for storing cached files (e.g., "1:2", "2:2", "1:2:2"). |
+| `cache.overrideUpstreamCache` | `boolean` | OverrideUpstreamCache controls whether to override upstream cache headers (using proxy_ignore_headers directive). |
+| `cache.time` | `string` | Time defines the default cache time (required when allowedCodes is specified). |
 | `egressMTLS` | `object` | The EgressMTLS policy configures upstreams authentication and certificate verification. |
 | `egressMTLS.ciphers` | `string` | Specifies the enabled ciphers for requests to an upstream HTTPS server. The default is DEFAULT. |
 | `egressMTLS.protocols` | `string` | Specifies the protocols for requests to an upstream HTTPS server. The default is TLSv1 TLSv1.1 TLSv1.2. |

examples/custom-resources/cache-policy/cache.yaml

@@ -0,0 +1,28 @@
+apiVersion: k8s.nginx.org/v1
+kind: Policy
+metadata:
+  name: cache-policy
+spec:
+  cache:
+    cacheZoneName: "mycache" #Required
+    cacheZoneSize: "14m" #Required
+    allowedCodes: ["any"] #Optional ["any"] or ["200", "301", ...]
+    allowedMethods: ["GET", "HEAD", "POST"] #Optional
+    time: "25m" #Optional # e.g. "15m", "1h", "2d". Default is "10m"
+    # cachePurgeAllow: [""]
+    overrideUpstreamCache: false
+---
+apiVersion: k8s.nginx.org/v1
+kind: Policy
+metadata:
+  name: cache-policy2
+spec:
+  cache:
+    cacheZoneName: "mycache2" #Required
+    cacheZoneSize: "18m" #Required
+    allowedCodes: ["any"] #Optional
+    allowedMethods: ["GET"] #Optional
+    time: "15m" #Optional
+    # cachePurgeAllow: [""]
+    overrideUpstreamCache: true
+    levels: "1:2" # Optional, e.g. "1:2" or "2:2". This controls the number of subdirectory levels used for cache storage.

examples/custom-resources/cache-policy/cafe-secret.yaml

@@ -0,0 +1 @@
+../../common-secrets/cafe-secret-cafe.example.com.yaml

examples/custom-resources/cache-policy/cafe-virtual-server.yaml

@@ -0,0 +1,32 @@
+apiVersion: k8s.nginx.org/v1
+kind: VirtualServer
+metadata:
+  name: cafe
+spec:
+  server-snippets: |
+    add_header X-Cache-Status $upstream_cache_status;
+  # This header will show the cache status for each request, e.g. X-Cache-Status: MISS or X-Cache-Status: HIT.
+  # The cache status can be "HIT", "MISS", "EXPIRED", etc.
+  # This is useful for debugging and monitoring cache behavior but not required for cache functionality.
+
+  policies:
+  - name: cache-policy
+  host: cafe.example.com
+  tls:
+    secret: cafe-secret
+  upstreams:
+  - name: tea
+    service: tea-svc
+    port: 80
+  - name: coffee
+    service: coffee-svc
+    port: 80
+  routes:
+  - path: /tea
+    action:
+      pass: tea
+    policies:
+    - name: cache-policy2
+  - path: /coffee
+    action:
+      pass: coffee