add nginx content cache as cache policy

.github/data/matrix-smoke-oss.json

@@ -39,14 +39,14 @@
       "label": "policies 1/2",
       "image": "alpine",
       "type": "oss",
-      "marker": "'policies and not policies_rl and not policies_ac and not policies_jwt and not policies_mtls'",
+      "marker": "'policies and not policies_rl and not policies_ac and not policies_jwt and not policies_mtls and not policies_cache'",
       "platforms": "linux/arm64, linux/amd64"
     },
     {
       "label": "policies 2/2",
       "image": "alpine",
       "type": "oss",
-      "marker": "'policies_rl or policies_ac or policies_jwt or policies_mtls or otel'",
+      "marker": "'policies_rl or policies_ac or policies_jwt or policies_mtls or policies_cache or otel'",
       "platforms": "linux/arm64, linux/amd64"
     },
     {

.github/data/matrix-smoke-plus.json

@@ -67,7 +67,7 @@
       "label": "policies 1/3",
       "image": "ubi-9-plus",
       "type": "plus",
-      "marker": "'policies and not policies_ac and not policies_jwt and not policies_mtls and not policies_rl'",
+      "marker": "'policies and not policies_ac and not policies_jwt and not policies_mtls and not policies_rl and not policies_cache'",
       "platforms": "linux/arm64, linux/amd64"
     },
     {
@@ -81,7 +81,7 @@
       "label": "policies 3/3",
       "image": "ubi-9-plus",
       "type": "plus",
-      "marker": "policies_rl",
+      "marker": "'policies_rl or policies_cache'",
       "platforms": "linux/arm64, linux/amd64"
     },
     {

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,92 @@ 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 HTTP response codes should be cached.
+                      Accepts either:
+                      - The string "any" to cache all response codes (must be the only element)
+                      - A list of HTTP status codes as integers (100-599)
+                      Examples: ["any"], [200, 301, 404], [200].
+                      Invalid: ["any", 200] (cannot mix "any" with specific codes).
+                    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 even if not specified.
+                      Maximum of 3 items allowed. Examples: ["GET"], ["GET", "HEAD", "POST"].
+                      Invalid methods: PUT, DELETE, PATCH, etc.
+                    items:
+                      type: string
+                    maxItems: 3
+                    type: array
+                    x-kubernetes-validations:
+                    - message: 'allowed methods must be one of: GET, HEAD, POST'
+                      rule: self.all(method, method in ['GET', 'HEAD', 'POST'])
+                  cachePurgeAllow:
+                    description: |-
+                      CachePurgeAllow defines IP addresses or CIDR blocks allowed to purge cache.
+                      This feature is only available in NGINX Plus.
+                      Examples: ["192.168.1.100", "10.0.0.0/8", "::1"].
+                      Invalid in NGINX OSS (will be ignored).
+                    items:
+                      type: string
+                    type: array
+                  cacheZoneName:
+                    description: |-
+                      CacheZoneName defines the name of the cache zone. Must start with a lowercase letter,
+                      followed by alphanumeric characters or underscores, and end with an alphanumeric character.
+                      Single lowercase letters are also allowed. Examples: "cache", "my_cache", "cache1".
+                    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. Must be a number followed by a size unit:
+                      'k' for kilobytes, 'm' for megabytes, or 'g' for gigabytes.
+                      Examples: "10m", "1g", "512k".
+                    pattern: ^[0-9]+[kmg]$
+                    type: string
+                  levels:
+                    description: |-
+                      Levels defines the cache directory hierarchy levels for storing cached files.
+                      Must be in format "X:Y" or "X:Y:Z" where X, Y, Z are either 1 or 2.
+                      This controls the number of subdirectory levels and their name lengths.
+                      Examples: "1:2", "2:2", "1:2:2".
+                      Invalid: "3:1", "1:3", "1:2:3".
+                    pattern: ^[12](?::[12]){0,2}$
+                    type: string
+                  overrideUpstreamCache:
+                    default: false
+                    description: |-
+                      OverrideUpstreamCache controls whether to override upstream cache headers
+                      (using proxy_ignore_headers directive). When true, NGINX will ignore
+                      cache-related headers from upstream servers like Cache-Control, Expires, etc.
+                      Default: false.
+                    type: boolean
+                  time:
+                    description: |-
+                      Time defines the default cache time. Required when allowedCodes is specified.
+                      Must be a number followed by a time unit:
+                      's' for seconds, 'm' for minutes, 'h' for hours, 'd' for days.
+                      Examples: "30s", "5m", "1h", "2d".
+                    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,92 @@ 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 HTTP response codes should be cached.
+                      Accepts either:
+                      - The string "any" to cache all response codes (must be the only element)
+                      - A list of HTTP status codes as integers (100-599)
+                      Examples: ["any"], [200, 301, 404], [200].
+                      Invalid: ["any", 200] (cannot mix "any" with specific codes).
+                    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 even if not specified.
+                      Maximum of 3 items allowed. Examples: ["GET"], ["GET", "HEAD", "POST"].
+                      Invalid methods: PUT, DELETE, PATCH, etc.
+                    items:
+                      type: string
+                    maxItems: 3
+                    type: array
+                    x-kubernetes-validations:
+                    - message: 'allowed methods must be one of: GET, HEAD, POST'
+                      rule: self.all(method, method in ['GET', 'HEAD', 'POST'])
+                  cachePurgeAllow:
+                    description: |-
+                      CachePurgeAllow defines IP addresses or CIDR blocks allowed to purge cache.
+                      This feature is only available in NGINX Plus.
+                      Examples: ["192.168.1.100", "10.0.0.0/8", "::1"].
+                      Invalid in NGINX OSS (will be ignored).
+                    items:
+                      type: string
+                    type: array
+                  cacheZoneName:
+                    description: |-
+                      CacheZoneName defines the name of the cache zone. Must start with a lowercase letter,
+                      followed by alphanumeric characters or underscores, and end with an alphanumeric character.
+                      Single lowercase letters are also allowed. Examples: "cache", "my_cache", "cache1".
+                    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. Must be a number followed by a size unit:
+                      'k' for kilobytes, 'm' for megabytes, or 'g' for gigabytes.
+                      Examples: "10m", "1g", "512k".
+                    pattern: ^[0-9]+[kmg]$
+                    type: string
+                  levels:
+                    description: |-
+                      Levels defines the cache directory hierarchy levels for storing cached files.
+                      Must be in format "X:Y" or "X:Y:Z" where X, Y, Z are either 1 or 2.
+                      This controls the number of subdirectory levels and their name lengths.
+                      Examples: "1:2", "2:2", "1:2:2".
+                      Invalid: "3:1", "1:3", "1:2:3".
+                    pattern: ^[12](?::[12]){0,2}$
+                    type: string
+                  overrideUpstreamCache:
+                    default: false
+                    description: |-
+                      OverrideUpstreamCache controls whether to override upstream cache headers
+                      (using proxy_ignore_headers directive). When true, NGINX will ignore
+                      cache-related headers from upstream servers like Cache-Control, Expires, etc.
+                      Default: false.
+                    type: boolean
+                  time:
+                    description: |-
+                      Time defines the default cache time. Required when allowedCodes is specified.
+                      Must be a number followed by a time unit:
+                      's' for seconds, 'm' for minutes, 'h' for hours, 'd' for days.
+                      Examples: "30s", "5m", "1h", "2d".
+                    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.