Custom cache invalidation

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

This article applies to customers using CDNs other than Akamai and Fastly. For Akamai and Fastly CDNs, please open a support request with us at support.cloudinary.com

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

Cloudinary already supports origin-based setups but we have now added support to enable cache invalidation on customer CDNs. This means that any time you add/replace/delete assets from the Media Library or perform similar functions using the API (by passing the invalidate parameter and setting it to true, i.e. invalidate: true), 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 is pictured below:
   
   Note: The flow shown above is specific to AWS but any other systems can be used.
   
   
2. Custom invalidation setup can be done for each product environment.
   
   
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 an 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()
   }

Please note note for the above:

1. You will need to configure your Cloudfront distribution id on the Lambda environment variable with the key as 'distribution_id'
   
2. It is advised for you to add queue support to handle bursts of cache invalidation requests (for example, when bulk invalidations are requested). Cloudfront allows invalidation of up to 3000 objects per request (https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Invalidation.html). Processing invalidations through a queue would help if invalidation is needed for more than 3000 objects.
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 your cache invalidation or if you have further questions about this.