How to Enable Caching in NGINX Ingress Controller [Step-by-Step Guide]

Step 1: Nginx Deployment Update

Create a ConfigMap nginx-configmap.yaml as shown below, replace the namespace with the namespace of your NGINX Ingress controller, and rename the keys_zone with your desired name. In this example, it is named test_cache.

kind: ConfigMap
apiVersion: v1
metadata:
  name: nginx-configmap
  namespace: nginx-ingress
data:
  custom-cache.conf: |
    # NGINX proxy cache path
    proxy_cache_path  /tmp/nginx-cache levels=1:2 keys_zone=test_cache:300m max_size=950m  inactive=1d use_temp_path=off;
    proxy_cache_key $scheme$proxy_host$request_uri;
    proxy_cache_lock on;
    proxy_cache_use_stale updating;

kind: ConfigMap
apiVersion: v1
metadata:
  name: nginx-configmap
  namespace: nginx-ingress
data:
  custom-cache.conf: |
    # NGINX proxy cache path
    proxy_cache_path  /tmp/nginx-cache levels=1:2 keys_zone=test_cache:300m max_size=950m  inactive=1d use_temp_path=off;
    proxy_cache_key $scheme$proxy_host$request_uri;
    proxy_cache_lock on;
    proxy_cache_use_stale updating;

Once you have created the ConfigMap nginx-configmap.yaml, apply it by running the following command:

kubectl apply -f nginx-configmap.yaml

kubectl apply -f nginx-configmap.yaml

Now edit the deployment of your NGINX by running the following command:

kubectl edit deployment {nginx-deployment-name} -n {your-nginx-ingress-namespace}

kubectl edit deployment {nginx-deployment-name} -n {your-nginx-ingress-namespace}

Attach this ConfigMap as a volume to the deployment at the following path: /etc/nginx/conf.d/custom-cache.conf.

Volume:

      volumes:
        - name: nginx-config
          configMap:
            name: nginx-configmap

      volumes:
        - name: nginx-config
          configMap:
            name: nginx-configmap

Volume Mount:

          volumeMounts:
            - name: nginx-config
              mountPath: /etc/nginx/conf.d/custom-cache.conf
              subPath: custom-cache.conf

          volumeMounts:
            - name: nginx-config
              mountPath: /etc/nginx/conf.d/custom-cache.conf
              subPath: custom-cache.conf

To load your cache content faster, you can use your RAM as a temporary volume mounted to the pod. To do this, add the following configuration to the NGINX Ingress deployment.

We mount the file at /etc/nginx/conf.d/custom-cache.conf because NGINX’s default config includes /etc/nginx/conf.d/*.conf;, which ensures the file is automatically loaded.

I am mounting my 2GB RAM as a cache volume

      volumes:
        - name: nginx-config
          configMap:
            name: nginx-configmap
        - name: cache
          emptyDir:
            medium: Memory
            sizeLimit: 2Gi

      volumes:
        - name: nginx-config
          configMap:
            name: nginx-configmap
        - name: cache
          emptyDir:
            medium: Memory
            sizeLimit: 2Gi

          volumeMounts:
            - name: nginx-config
              mountPath: /etc/nginx/conf.d/custom-cache.conf
              subPath: custom-cache.conf
            - name: cache
              mountPath: /tmp

          volumeMounts:
            - name: nginx-config
              mountPath: /etc/nginx/conf.d/custom-cache.conf
              subPath: custom-cache.conf
            - name: cache
              mountPath: /tmp

Step 2: Update Ingress file

In your Ingress file, add the annotation below to enable caching for the application and apply.

    nginx.org/location-snippets: |
      proxy_cache test_cache;
      proxy_cache_valid 200 302 10m;
      proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504;
      proxy_cache_methods GET HEAD POST;
      proxy_set_header X-Cache-Status $upstream_cache_status;
      add_header X-Cache-Status $upstream_cache_status;

    nginx.org/location-snippets: |
      proxy_cache test_cache;
      proxy_cache_valid 200 302 10m;
      proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504;
      proxy_cache_methods GET HEAD POST;
      proxy_set_header X-Cache-Status $upstream_cache_status;
      add_header X-Cache-Status $upstream_cache_status;

Step 3: Validate

To validate whether caching is working, you can check in 3 ways:

1. Validate the latency speed.
2. Check whether files are being generated in the /tmp/nginx path.
3. Validate the X-Cache-Status header

Method 1:

After applying the changes, load the page. The first time, you will notice higher latency. When you reload or open the same page in another tab (e.g., Incognito mode), you should see reduced latency.

1st Try:

2nd Try:

Method 2:

Log in to the NGINX Ingress pod by running the following command:

Bash Shell:

kubectl exec -it -n <namespace> <nginx-ingress-pod-name> -- /bin/sh

kubectl exec -it -n <namespace> <nginx-ingress-pod-name> -- /bin/sh

SH shell:

kubectl exec -it -n <namespace> <nginx-ingress-pod-name> -- /bin/bash

kubectl exec -it -n <namespace> <nginx-ingress-pod-name> -- /bin/bash

Now change the directory to /tmp/nginx-cache and list its contents. There you will see the cache files.

cd /tmp/nginx-cache

cd /tmp/nginx-cache

Method 3:

Hit the URL using Postman or any API testing tool, and check the response headers — if caching is used, you’ll see X-Cache-Status: HIT; otherwise, it will show MISS

⚠️ Warning: Do not enable caching for POST requests unless the content is static and does not change. Caching dynamic POST requests can cause inconsistent or incorrect application behavior.