Serve several buckets from one address, step by step
One address of your own, such as cdn.example.com, can serve files from several buckets and one video library, each under its
own folder. You keep the addresses your pages and apps already use, and plycdn decides which bucket answers each one. This
page takes you from the list of routes to a check that every folder is served. The reference is in
API; adding the address itself is in Your own domain.
You need: a custom domain that is active and whose own bucket is private; the buckets (and, if you want one, the video
library) to serve; an admin key to save a table; and one of plycdn's server packages
(ASP.NET Core, Node.js or Python) or the API with your key.
Routes can point at the buckets and video libraries of your organization and of its sub-organizations.
1When to use it
- Your old setup served several folders from one address. For example
cdn.example.com/org-content/videos/…came from one place,cdn.example.com/org-content/documents/…from another andcdn.example.com/assets/…from a third. Give each folder its own bucket here and nothing that links to those addresses has to change. - You want one address for several customers or products, each in its own bucket, without a different hostname for each.
- You are moving from another cloud and your pages still use one gateway address: Moving from another cloud.
2How a route table works
A table is a list of routes. Each route says "paths that start with this folder go to this bucket".
- Prefix. Whole folders ending in
/, such asorg-content/videos/. When more than one route matches, the longest prefix wins, soorg-content/videos/live/can go to a different bucket fromorg-content/videos/. - Remove the prefix (
stripPrefix). Off: the bucket sees the whole path, so/org-content/videos/intro.mp4is the fileorg-content/videos/intro.mp4. On: it sees what follows the prefix, so the same address is the fileintro.mp4. Turn it on when the bucket holds the files without the folder name. - The video library. One route can point at a video library. It has no prefix: it serves your players' addresses (
/v/…and/_s/…) on this address. At most one per address. - The default route. The domain's own bucket answers every address no route matches. Turn it off to answer those addresses with a plain "not found" page instead.
- Up to 50 routes per address. Saving takes effect within about a minute, with no DNS or certificate change, and works on a domain that already serves traffic.
For the example above, the table is:
| Prefix | Bucket | Remove the prefix |
|---|---|---|
org-content/videos/ |
acme-videos |
no (files are stored under that folder) |
org-content/documents/ |
acme-documents |
yes (files are stored without it) |
assets/ |
acme-assets |
no |
| (none) | acme-library (a video library) |
not used |
and acme-main, the domain's own bucket, answers every other path.
3Set it up in the dashboard
- Domains & routing → Routing lists every address you serve, its rules and its targets. Open the address, then its Rules tab. (The Map tab shows where each request goes, in the order the rules are checked. The same rules are on the domain's Routes tab under Custom domains.)
- Choose Add rule, then Send to buckets (the rules above) or Redirect (see Redirect a path). For a bucket, type the prefix, choose the bucket (or the video library) in Target, and tick Remove the prefix if the bucket stores the files without the folder name. A video library needs no prefix.
- Leave Serve the domain's own bucket for every other path on, or turn it off to answer other paths with "not found".
- Choose Save routes. It is live within about a minute. Check it on the Map tab.
A route whose bucket was deleted shows Broken: its prefix falls back to the default route until you change it. Each save is kept as a version in Earlier versions, with Restore beside it.
4Set it up from your code
Reading a domain's routes works with any key. Saving and restoring need an admin key.
GET /api/content/v1/domains/{domainId}/routes
PUT /api/content/v1/domains/{domainId}/routes
POST /api/content/v1/domains/{domainId}/routes/restore {"version": 2}
PUT replaces the whole table. Send the version you last read in If-Match so that two people saving at once cannot
overwrite each other: the second is refused with version_conflict.
ASP.NET Core
var table = await storage.GetDomainRoutesAsync(organizationId, domainId);
var saved = await storage.SetDomainRoutesAsync(organizationId, domainId, new DomainRoutesBody
{
DefaultRoute = true,
Routes = new[]
{
new DomainRoute("org-content/videos/", videosBucketId),
new DomainRoute("org-content/documents/", documentsBucketId, StripPrefix: true),
new DomainRoute("assets/", assetsBucketId),
new DomainRoute(null, libraryId), // the video library
},
}, ifMatch: table.Version);
// Go back to an earlier table:
await storage.RestoreDomainRoutesAsync(organizationId, domainId, version: 2);
Node.js
const table = await storage.getDomainRoutes(organizationId, domainId);
const saved = await storage.setDomainRoutes(organizationId, domainId, {
defaultRoute: true,
routes: [
{ pathPrefix: 'org-content/videos/', bucketId: videosBucketId },
{ pathPrefix: 'org-content/documents/', bucketId: documentsBucketId, stripPrefix: true },
{ pathPrefix: 'assets/', bucketId: assetsBucketId },
{ pathPrefix: null, bucketId: libraryId }, // the video library
],
}, { ifMatch: table.version });
// Go back to an earlier table:
await storage.restoreDomainRoutes(organizationId, domainId, 2);
Python
table = storage.get_domain_routes(organization_id, domain_id)
saved = storage.set_domain_routes(organization_id, domain_id, {
"defaultRoute": True,
"routes": [
{"pathPrefix": "org-content/videos/", "bucketId": videos_bucket_id},
{"pathPrefix": "org-content/documents/", "bucketId": documents_bucket_id, "stripPrefix": True},
{"pathPrefix": "assets/", "bucketId": assets_bucket_id},
{"pathPrefix": None, "bucketId": library_id}, # the video library
],
}, if_match=table["version"])
# Go back to an earlier table:
storage.restore_domain_routes(organization_id, domain_id, 2)
Every answer is the saved table: defaultRoute, routes (each with a status of ok or broken), version, updatedAt and
the last 20 versions. A domain that never had a table answers version 0 with the default route on.
5Sign links on the shared address
A link to a private bucket's file on a shared address is signed over the full path the viewer sees, prefix included. That keeps a link made for one folder from working under another. Links to a public bucket's route need no signature: use the plain address.
Sign on the shared address's hostname. plycdn accepts it for every bucket and video library a route of that address points at:
their signing profile lists the address under routes (one entry per route, with its pathPrefix and stripPrefix), and the
server packages read it from there. What else to give depends on the route:
- The route removes the prefix (the bucket holds
intro.pdf, viewers open/org-content/documents/intro.pdf): give the address's hostname, the route's prefix, and the file's key as stored. - The route keeps the prefix (the bucket holds
org-content/videos/intro.mp4and viewers open the same path): give the hostname and the key as stored, which already starts with the prefix. Do not give the prefix: it would be added twice. - The video library route: sign videos as you do today, with the hostname set to the shared address. The player's
addresses (
/v/…,/_s/…) never carry a prefix.
ASP.NET Core
var link = await signer.SignAsync(organizationId, documentsBucketId, "intro.pdf",
new PlycdnSignOptions { Hostname = "cdn.example.com", PathPrefix = "org-content/documents/", Ttl = TimeSpan.FromMinutes(5) });
// https://cdn.example.com/org-content/documents/intro.pdf?token=…
var kept = await signer.SignAsync(organizationId, videosBucketId, "org-content/videos/intro.mp4",
new PlycdnSignOptions { Hostname = "cdn.example.com" });
Node.js
const link = await signer.sign(organizationId, documentsBucketId, 'intro.pdf',
{ hostname: 'cdn.example.com', pathPrefix: 'org-content/documents/', ttlSeconds: 300 });
// https://cdn.example.com/org-content/documents/intro.pdf?token=…
const kept = await signer.sign(organizationId, videosBucketId, 'org-content/videos/intro.mp4', { hostname: 'cdn.example.com' });
Python
link = signer.sign(organization_id, documents_bucket_id, "intro.pdf",
hostname="cdn.example.com", path_prefix="org-content/documents/", ttl_seconds=300)
# https://cdn.example.com/org-content/documents/intro.pdf?token=…
kept = signer.sign(organization_id, videos_bucket_id, "org-content/videos/intro.mp4", hostname="cdn.example.com")
The API. POST /api/content/v1/sign with {"bucketId": "…", "key": "intro.pdf", "hostname": "cdn.example.com", "pathPrefix": "org-content/documents/"}; leave out pathPrefix for a route that keeps its prefix.
When you save or restore a table, plycdn sends signing_profile.changed (reason domains_changed) for every bucket and library
the change adds or removes, so the server packages pick up the new routes at once. Without the webhook they notice within the
hour, or on the first link for an address they do not know yet.
The browser packages only show addresses they are given, so they need no change: have your server sign the link and pass it to the page.
6Redirect a path
A redirect rule sends viewers who ask for a folder, or for the whole address, to another address. Use it when a folder moved,
when an old address should lead to the new one, or to send everything on old.example.com to your new site.
- Prefix. A folder ending in
/, such asold-docs/, or an empty prefix for the whole address. - Where to (
location). A full address starting withhttps://orhttp://, at most 2,048 characters, with no user name, password or#part. - Permanent redirect (
permanent). On sends 301, which browsers and search engines remember; off sends 302, for a move that may change. For requests other than GET and HEAD (an upload, say) viewers get 308 or 307, which keep the method. - Keep the rest of the path (
keepPath). On adds what follows the prefix to the end oflocation: with prefixold-docs/and locationhttps://www.example.com/docs/,/old-docs/setup/introgoes tohttps://www.example.com/docs/setup/intro. - Keep the query (
keepQuery). On keeps the viewer's?a=1&b=2on the new address.
Redirects are checked before the rules that send to buckets, and the longest matching prefix wins. A redirect on the whole
address (empty prefix) also redirects the video player's addresses (/v/…) and share addresses (/_s/…), so players and share
links on that address stop working: use a folder prefix unless you mean to move everything. A browser's OPTIONS check
before a cross-site request to a redirected path gets the redirect too, not a permission answer.
In the dashboard: Domains & routing → Routing → the address → Rules → Add rule → Redirect. Type the prefix and the address to send viewers to, and turn on Permanent redirect, Keep the rest of the path or Keep the query as you need. Choose Save routes.
ASP.NET Core
var saved = await storage.SetDomainRoutesAsync(organizationId, domainId, new DomainRoutesBody
{
DefaultRoute = true,
Routes = new[]
{
DomainRoute.Redirect("old-docs/", "https://www.example.com/docs/", permanent: true, keepPath: true, keepQuery: true),
new DomainRoute("assets/", assetsBucketId),
},
}, ifMatch: table.Version);
Node.js
await storage.setDomainRoutes(organizationId, domainId, {
defaultRoute: true,
routes: [
{ kind: 'redirect', pathPrefix: 'old-docs/', location: 'https://www.example.com/docs/',
permanent: true, keepPath: true, keepQuery: true },
{ pathPrefix: 'assets/', bucketId: assetsBucketId },
],
}, { ifMatch: table.version });
Python
storage.set_domain_routes(organization_id, domain_id, {
"defaultRoute": True,
"routes": [
{"kind": "redirect", "pathPrefix": "old-docs/", "location": "https://www.example.com/docs/",
"permanent": True, "keepPath": True, "keepQuery": True},
{"pathPrefix": "assets/", "bucketId": assets_bucket_id},
],
}, if_match=table["version"])
The API body for a redirect is {"kind": "redirect", "pathPrefix": "old-docs/", "location": "https://www.example.com/docs/", "permanent": true, "keepPath": true, "keepQuery": true}.
7Share traffic between buckets, with backups
A rule can name 1 to 5 buckets instead of one. Each gets a share of the viewers, a whole number from 1 to 100. Shares are relative: 70 and 30 send 70% and 30% of viewers, and so do 7 and 3. Use it to spread delivery between two storage locations, to move a folder gradually from one bucket to another, or to keep a backup bucket that takes over when the first cannot answer.
- Viewers stay put. A viewer is sent to the same bucket for every file under the rule (every segment of a video, every page of a course), so a page never mixes two buckets. Changing the shares moves only the viewers who must move.
- Backups. When the bucket chosen for a viewer cannot answer, plycdn tries the next one, for GET and HEAD requests and only before any of the file has been sent: at most 3 tries, about 8 seconds each and 25 seconds in all. The file the viewer gets is the same; nothing in the address changes.
- A bucket that cannot serve is skipped. A bucket that is paused or taken down shows Paused and is left out until it
can serve again. A rule with every bucket down answers viewers with plycdn's "temporarily unavailable" page (503, with
Retry-After: 30), never an empty page. - Same visibility. All the buckets of one rule must be public, or all private (
route_targets_invalid). A video library rule has one library only. - Signing. Links to a private rule with several buckets are checked with the first bucket's key and access settings
(allowed sites, countries, rate limit, address binding). In the dashboard the first bucket is marked Signs with. The
server packages do this for you: sign with any of the rule's buckets and the package uses the first one's key, from the
signing profile. With the API,
POST /signfor any bucket of the rule signs with the first one when the buckets are in the same organization; otherwise sign through the first bucket's organization. A link you sign yourself with another bucket's key is refused with 403. If the first bucket is paused, its links still work while the others serve.
In the dashboard: Domains & routing → Routing → the address → Rules → Add rule → Send to buckets. Type the prefix, Add each bucket and give it a Share, with the first bucket the one that signs. Choose Save routes.
ASP.NET Core
await storage.SetDomainRoutesAsync(organizationId, domainId, new DomainRoutesBody
{
DefaultRoute = true,
Routes = new[]
{
DomainRoute.Forward("videos/", new[]
{
new DomainRouteTarget(mumbaiBucketId, 70),
new DomainRouteTarget(backupBucketId, 30),
}),
},
}, ifMatch: table.Version);
Node.js
await storage.setDomainRoutes(organizationId, domainId, {
defaultRoute: true,
routes: [
{ pathPrefix: 'videos/', targets: [
{ bucketId: mumbaiBucketId, share: 70 },
{ bucketId: backupBucketId, share: 30 },
] },
],
}, { ifMatch: table.version });
Python
storage.set_domain_routes(organization_id, domain_id, {
"defaultRoute": True,
"routes": [
{"pathPrefix": "videos/", "targets": [
{"bucketId": mumbai_bucket_id, "share": 70},
{"bucketId": backup_bucket_id, "share": 30},
]},
],
}, if_match=table["version"])
Give a rule bucketId or targets, never both (route_bucket_and_targets). The answer lists each rule with its kind,
and each bucket with its share and a status of ok, paused or broken. A rule you saved with one bucketId is shown as
one bucket with a share of 100 and keeps working as before.
Sign as you do today, with any bucket of the rule:
var link = await signer.SignAsync(organizationId, backupBucketId, "intro.mp4",
new PlycdnSignOptions { Hostname = "cdn.example.com", PathPrefix = "videos/" }); // signed with the first bucket's key
const link = await signer.sign(organizationId, backupBucketId, 'intro.mp4', { hostname: 'cdn.example.com', pathPrefix: 'videos/' });
link = signer.sign(organization_id, backup_bucket_id, "intro.mp4", hostname="cdn.example.com", path_prefix="videos/")
8Check that it works
Read the table again (
GET /domains/{domainId}/routes, or open the domain's page): every route saysok, andversionis the one you saved.Wait about a minute, then open one address under each prefix. For a private bucket use a freshly signed link:
curl -I "https://cdn.example.com/org-content/documents/intro.pdf?token=…"200means that route is serving. A plain404page means no route (and no default route) matched that path.Check that a link made for one folder does not open under another: change
documentstovideosin the signed address. It is refused, because the signature covers the whole path.Delivery → Delivery analytics counts each file against the bucket that served it, so each route's delivery shows on its own bucket.
Account & security → Audit log shows every save as
domain.routes_changed, with the table before and after.A redirect:
curl -I "https://cdn.example.com/old-docs/setup/intro"answers301(or302) with alocation:line that is the address you set. The Map tab shows redirects first, in the order they are checked.Shared traffic: open several files under the rule from different browsers or
curl --interfaceaddresses and compare which bucket answers (the Map tab lists each bucket and its share). Pause one bucket to try a backup: viewers still get their files from the others. Delivery → Delivery analytics shows the traffic per bucket, and the "Shared addresses" dashboard in Logthread (see Logthread) shows redirects, backups used and rules with every bucket down.Before or after you save, try an address without sending any traffic: Domains & routing → Routing → the address → Rules (or Map) → Test an address. Type a path or a full address, a Sample viewer (a viewer's IP address) and the Request (GET, HEAD, POST or PUT). It shows which rule answers and its number in the order rules are checked. For a redirect it shows the address viewers are sent to and the status (301, 302, 307 or 308). For a rule with buckets it shows the bucket that viewer gets (Serving now), the backups in order, the bucket links are checked with (Signs with) and the path the bucket is asked for. When every bucket of the rule is paused, it shows the "temporarily unavailable" page. Otherwise it shows the domain's own bucket, or "not found". On the Rules tab the test includes changes you have not saved yet; on the Map it uses only the rules that are saved, which are what viewers get now.
9Errors and fixes
| Code | What it means | What to do |
|---|---|---|
route_prefix_invalid (422) |
A prefix is not whole folders ending in /, or a bucket route has none |
Use a prefix such as org-content/videos/: no . or .. folder, no //, \, %, ? or # |
route_prefix_reserved (422) |
A bucket route's prefix starts with v/ or _s/, which belong to the video library route |
Choose another folder, such as videos/ |
route_prefix_duplicate (422) |
Two routes share a prefix | Give each route its own prefix (one inside another is fine) |
route_too_many (422) |
More than 50 routes | Remove some, or put several folders in one bucket |
route_video_twice (422) |
More than one video library route | Keep one |
route_target_not_found (404) |
A bucket or library does not exist, or is not yours | Pick it from your buckets and libraries |
route_target_scope (403) |
Your key may not reach that bucket or library | Use a key that covers its organization |
routes_need_private_address (409) |
The domain's own bucket is public, so its domain cannot carry routes | Add the address to a private bucket, then add routes |
route_redirect_invalid (422) |
A redirect has no usable location (not an https:// or http:// address, over 2,048 characters, or with a user name, password or # part), or a prefix that is not whole folders |
Give a full address such as https://www.example.com/docs/, and a prefix ending in / (or empty for the whole address) |
route_redirect_loop (422) |
A redirect sends viewers back to the same address, to a folder that redirects again, or round a circle of redirects | Send it to a different address, or to a folder no redirect matches |
route_targets_invalid (422) |
A rule has no bucket or more than 5, the same bucket twice, a share outside 1 to 100, buckets that are not all public or all private, or a video library with other buckets | Give 1 to 5 different buckets, whole shares from 1 to 100, buckets of one visibility, and one library on its own |
route_bucket_and_targets (422) |
A rule has both bucketId and targets |
Keep one: bucketId for one bucket, targets for several |
version_conflict (409) |
Someone saved a newer table | Read the table again, apply your change, save again |
route_version_not_found (404) |
That version is not among the last 20 | Read versions and restore one of them |
domain_not_active (409) when signing |
No route of that address points at this bucket (or the address is not active yet) | Check the route's bucket, wait a minute after saving, or sign on the bucket's own address |
validation_error (422), field pathPrefix, when signing |
The route removes its prefix and none was given, or it keeps its prefix and one was given | Give the route's prefix for a route that removes it; give only the stored key for one that keeps it |
admin_key_required (403) |
Saving and restoring need an admin key | Use an admin key from Developers → API keys |
domain_not_found (404) |
No such domain here | Check the domain ID and the organization |
10Where to go next
- Add the address itself, and its records: Your own domain.
- Make a bucket's files private and sign links: Delivering files and video.
- Play video on your address: Playing video.