Custom Cache Invalidation

Custom cache invalidation feature is available for customers on Enterprise / Custom Plans.

This article applies to customers whose CDNs are other than Akamai and Fastly. For Akamai and Fastly CDNs, the process is different. Please open a request with us at support.cloudinary.com

Cloudinary provides an end-to-end media management solution from media upload, their management and delivery via multiple CDNs. While customers get the most out of Cloudinary when using the service end to end, there are cases when customers would want to use their own CDN in front using Cloudinary as an origin.

Cloudinary already supports origin based setup but have now added support to enable cache invalidation on customer CDNs. This means that anytime you add/replace/delete assets from Media Library or perform those functions using API (by passing invalidate=true parameter), Cloudinary can trigger a webhook passing all the asset paths that need to be invalidated on your CDN.

Here's a quick overview -

1. The overall flow would be -
   
   Note: The flow shown above is in AWS but any other systems could be used.
   
   
2. Custom invalidation setup can be done per sub-account.
   
   
3. For each account that needs to have custom invalidation, you will need to provide -
   i) DNS (which will point to Cloudinary origin)
   ii) endpoint that will accept HTTP POST payload like below -
   

   {
     "cnames": [
       “assets.example.com”
     ],
     "paths": [
       "/image/upload/sample.jpg",
       "/image/upload/dog.png"
     ],
     "surrogate_keys": [
       "4461069347633694027258798",
       "355435432223423424288"
     ]
   }

   
   The 'paths' attribute contains the list of urls that need to be invalidated on your CDN.
   
   
4. Once the endpoint receives an invalidation message, it can trigger invalidation request(s) on your CDN.
   Here's a sample app to trigger invalidations on Cloudfront. This app is set up to run as AWS Lambda function to trigger invalidation.
   Note: this app can be hosted in any other environment other than a Lambda function as well.

   const AWS = require('aws-sdk')
   const cloudfront = new AWS.CloudFront()
    
   // Cloudfront distribution id
   const DISTRIBUTION_ID = process.env.distribution_id
   
   exports.handler = async (event, context, callback) => {
      makeInvalidationRequest(event)
          .then(() => {
              callback(null, 200)
          })
          .catch(error => {
              callback(Error(error))
          })
   }
   
   function makeInvalidationRequest(invalidationData) {
      const params = {
          DistributionId: DISTRIBUTION_ID,
          /* required */
          InvalidationBatch: {
              /* required */
              CallerReference: '' + Date.now(),
              /* required */
              Paths: {
                  /* required */
                  Quantity: invalidationData.paths.length,
                  /* required */
                  Items: invalidationData.paths
              }
          }
      }
      return cloudfront.createInvalidation(params).promise()
   }

Few things to note for the attached reference app - 

1. You will need to configure your Cloudfront distribution id on the Lambda environment variable with key as 'distribution_id'
   
2. It would be a good idea to add queue support to handle bursts of cache invalidation requests (for example when bulk invalidation gets done). Cloudfront allows invalidation of up to 3000 objects per request (https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Invalidation.html). So processing invalidation through a queue would help if invalidation is needed for more than 3000.
3. This app does not handle errors and notifications. Those will need to be added as needed.
   
   

Please reach out to support@cloudinary.com to configure for your cache invalidation and any further questions.