How to Manage the Spaces CDN Cache

After you enable the Spaces CDN, the CDN’s edge servers begin caching and serving the contents of the Spaces bucket.

Using presigned URLs does not allow transferred files to be cached when using the Spaces CDN. Attempting to do so may result in double the bandwidth charge without the CDN’s performance benefit.

Each request with a unique URL, including the URL’s query string, is treated as a unique asset and has its own cache. Requests with identical URLs return the same cached value. For example, the caches for the following two URLs are separate because the query strings are different:

nyc3.cdn.digitaloceanspaces.com/examplefile.jpg?query=examplequery
nyc3.cdn.digitaloceanspaces.com/examplefile.jpg?query=differentquery

This URL is based on the datacenter you created your bucket in, followed by digitaloceanspaces.com. For nyc3, for example, use nyc3.digitaloceanspaces.com/....

There are two ways you can control the CDN cache:

• Set the edge cache TTL. The edge cache TTL determines how long the CDN’s edge servers keep a particular copy of your files before getting the current version from the origin.

• Purge the cache. Purging files from the CDN cache makes all edge servers immediately clear their versions of those files and request the current version from buckets.

  You may want to purge files to quickly correct errors, fully remove deleted content, or deploy urgent fixes.

Set the Edge Cache TTL Using the Control Panel

You can set the default edge cache TTL for the entire bucket and customize the TTL for specific files.

Change the Bucket’s Default Edge Cache TTL

The edge cache TTL for Spaces is set to one hour by default. You can change this when you first enable the CDN and modify it at any time after.

To change the bucket’s default edge cache TTL, go to the control panel, in the left menu, click Spaces Object Storage, and then under the Buckets tab, click the bucket you want to change the edge cache TTL for. From the bucket’s overview page, click the Settings tab, under the CDN (content Delivery Network) section, click Edit, and then in the Edge Cache TTL sub-section, click the drop-down menu, and then choose a new time.

A longer TTL improves performance, but you can’t see updated content until the cached version expires. Use longer TTLs for static content or content that rarely changes, and shorter TTLs for dynamic or frequently updated content. You may also want to increase the edge cache TTL if you expect a significant spike in traffic.

After setting the new time for your edge cache TTL, click Save.

Customize the Edge Cache TTL for Specific Files

If you want the edge cache TTL for specific files to differ from the default of the bucket, you can add a custom key-value pair to the file’s metadata.

To customize the edge cache TTL for specific files, go to the control panel, in the left menu, click Spaces Object Storage, and then under the Buckets tab, click the bucket you want to change edge cache TTL for specific files.

From the bucket’s overview page, under the Files tab, either click the file you want to manage edge cache TTL for or on the left, click the checkbox to select multiple files, and then on the right, click …, click Manage Metadata to open the Manage metadata window for the specific file.

In this window, at the bottom, click Add Custom Pairing, and then enter max-age as the Key, which specifies how long, in seconds, the file can be cached by CDN edge servers before it must be revalidated. Then, as the Value, enter the TTL you want in seconds, and then click Save.

Set the Edge Cache TTL Using Automation

The DigitalOcean CLI (doctl) does not support configuring edge cache TTL settings for Spaces buckets. To manage edge cache behavior, use the API.

Set the Edge Cache TTL via the API

You can set the default edge cache TTL for a bucket by updating the bucket’s CDN configuration. The TTL value is specified in seconds and applies to all cached objects unless overridden by a custom rule.

To update the edge cache TTL, send a PUT request to the CDN configuration endpoint for your bucket. Ensure the request is authenticated and sent to the correct region endpoint.

You can also customize the edge cache TTL for specific files by defining cache rules that match object paths or file extensions. These rules allow you to override the default TTL for selected content, such as frequently updated files or long-lived static assets.

To add or update cache rules, include them in the same CDN configuration request when updating the bucket. Rules are evaluated in order and applied to matching objects.

Purge Files From the CDN Cache

You can purge individual files, recursively purge folders, or purge the entire contents of a bucket using the same method. Purging clears the file(s) or directories from all of your edge caches and requests a pristine copy from Spaces.

To purge files from the CDN cache of your bucket, go to the control panel, in the left menu, click Spaces Object Storage, and then under the Buckets tab, click the bucket you want to purge the CDN cache for. From the bucket’s overview page, click the Settings tab, and then under the CDN (content Delivery Network) section, click Edit, and then on the right, click Change, and then Purge CDN Cache to open the Purge CDN Cache window.

To confirm purge, select the directories or the entire bucket to purge the cache for, and then click Purge Cache in Selected Directories.

Purge a Specific File from the CDN Cache

To purge a specific file from the CDN cache, go to the control panel, in the left menu, click Spaces Object Storage, and then under the Buckets tab, click the bucket you want to purge a file from the CDN cache. From the bucket’s overview page, under the Files tab, find the file you want to purge from the CDN cache, on the right, click …, and then click Purge from CDN cache to open the Purge from CDN Cache window.

To confirm the file’s purge, click Purge file from CDN Cache.

Purge Multiple Files from the CDN Cache

To purge multiple files from the CDN cache, go to the control panel, in the left menu, click Spaces Object Storage, and then under the Buckets tab, click the bucket you want to purge files from the CDN cache. From the bucket’s overview page, under the Files tab, on the left, click the checkbox for all the files you want to purge, and then in the top right, click Actions, and then click Purge From CDN Cache to open the Purge from CDN Cache window.

To confirm the files purge, click Purge file from CDN Cache.

Purge Files From the CDN Cache Using Automation

You can purge cached content from the Spaces CDN using either the DigitalOcean CLI (doctl) or the DigitalOcean API. Purging removes cached objects from edge servers so the next request fetches a fresh copy from the origin bucket.

Purge Files via the CLI

You can purge the Spaces CDN cache using doctl. To purge cached files, use doctl compute cdn flush and specify one or more paths (or a wildcard). If you provide only a wildcard (*) or no files, all cached content is purged.

To purge a specific file, provide the file path relative to the bucket. For example, --files /path/to/file.jpg.

To purge multiple files, provide multiple --files values. For example, --files /a.jpg --files /b.css --files /dir/c.js.

To purge all files, use a wildcard or omit the flag. For example, --files "*", or run the command without --files.

Purge Files via the API

To purge cached content from a CDN endpoint, send a DELETE request to the CDN cache endpoint and include a files array in the request body. Each entry can be a single file path or include a wildcard (*) to purge recursively under a prefix. Providing only * purges all cached content.

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{"files": ["assets/img/hero.png","assets/css/*"]}' \
  "https://api.digitalocean.com/v2/cdn/endpoints/19f06b6a-3ace-4315-b086-499a0e521b76/cache"

import (
    "context"
    "os"

    "github.com/digitalocean/godo"
)

func main() {
    token := os.Getenv("DIGITALOCEAN_TOKEN")

    client := godo.NewFromToken(token)
    ctx := context.TODO()

    flushRequest := &godo.CDNFlushCacheRequest{
        Files: []string{"assets/img/hero.png","assets/css/*"},
    }

    _, err := client.CDNs.FlushCache(ctx, "19f06b6a-3ace-4315-b086-499a0e521b76", flushRequest)
}

require 'droplet_kit'
token = ENV['DIGITALOCEAN_TOKEN']
client = DropletKit::Client.new(access_token: token)

client.cdns.flush_cache(
  id: '19f06b6a-3ace-4315-b086-499a0e521b76',
  files: ['assets/img/hero.png','assets/css/*']
)

import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

purge_req = {"files": ["path/to/image.png", "path/to/css/*"]}

purge_resp = client.cdn.purge_cache("19f06b6a", purge_req)

To purge a specific file, include a single path in files. For example, files: ["/path/to/file.jpg"].

To purge multiple files, include multiple paths in files. For example, files: ["/a.jpg", "/b.css", "/dir/c.js"].

To purge all files, use a wildcard as the only entry. For example, files: ["*"]. The API has a purge rate limit. For more information, see our limits page.