Document global placement, GPU preference lists, and global storage by kylegani · Pull Request #298 · CerebriumAI/documentation

kylegani · 2026-07-15T16:04:44Z

Summary

Second PR of the intent-based placement docs work (follows #296).

Multi-Region Deployment rewrite (deployments/multi-region-deployment.mdx, same path and nav slot):

region = "global" as the recommended default: platform places the app in any region with capacity matching its hardware requirements; new regions become eligible without a redeploy
Pinning a region, with the capacity/queueing tradeoff stated
Geography-based placement (US/EU) marked as coming soon
Regions confirmed against the live production GPU availability matrix: self-serve us-east-1, us-central1, eu-north-1, eu-north1; the rest on request. eu-north-1 vs eu-north1 disambiguation; provider = "nebius" requirement for non-AWS pins. No Crusoe regions listed.
Routing behavior: warm capacity anywhere before cold start, soft latency preference, no session affinity
Scaling params are app-wide; platform distributes across regions
Storage: regional volumes plus /global-persistent-storage for global apps

Shipped but undocumented config now covered:

compute preference lists (up to 5 types, one hardware family, cerebrium run uses first entry) in using-gpus + TOML reference
provider/region optional with platform-selected defaults; Complete Example uses region = "global"

Storage fixes (verified against latest CLI v2.5.3 / backend / infra tips, plus live CLI tests):

New Global Storage section in managing-files: --region global file commands work end to end, per-region read caches, no dashboard listing/resize for the global volume
Regional isolation claim softened to "not guaranteed to be available in other regions" (volumes are not all physically isolated across regions)
rm directory syntax requires a trailing slash; resize endpoint corrected to the verified PATCH /v2 route with default-<region> volume id and 50GB-1TB bounds; stale 50GB default removed
faster-cold-starts: per-region cache behavior and global-volume guidance for multi-region apps

Also: secrets documented as available in every region an app runs in; introduction reframed to "deploy once and run across multiple regions".

Open items (flagged during review, need product/eng confirmation)

Crusoe us-east-1 remains deployable in the live availability matrix for anyone setting provider = "crusoe", even though docs no longer mention it; align deploy validation if it should be retired
us-west-2, ap-south-1, and the five new AWS regions (Tokyo, Frankfurt, São Paulo, Montreal, Dubai) exist in latest backend code but not in the live prod matrix; docs list them as on-request
BLACKWELL_B300 is listed for us-east-1 but absent from deploy validation (live and latest code)
Backend ExcludedRegions does not gate us-west-2/eu-west-2, which docs list as on-request
Regional volume physical sharing (us-east-1/us-east-2/us-west-2/us-central1 share a volume; eu-north1 shares eu-north-1's): is this the intended contract? Matters for the residency story.
Intended customer-facing default volume size (50GB claim was stale; PVC request is now 1TB; enforced quota configured outside the repos)

🤖 Generated with Claude Code

Rewrite Multi-Region Deployment around intent-based placement: region = "global" (recommended) or pin a region, geography placement marked coming soon, routing behavior (warm capacity first, soft latency preference, no session affinity), app-wide scaling semantics, and the region list and GPU availability table rebuilt from deploy validation (4 self-serve regions, 10 on request). Document shipped-but-undocumented config: - compute accepts a preference-ordered list of up to 5 types (one hardware family; cerebrium run uses the first entry) - provider and region are optional; defaults are platform-selected Storage, verified against latest CLI/backend/infra tips and live CLI: - Global storage: /global-persistent-storage mount, --region global file commands, per-region read caches - Soften regional isolation claim to "not guaranteed available in other regions" (regional volumes are not all physically isolated) - Fix rm directory syntax (trailing slash required), resize endpoint (PATCH /v2, volume id default-<region>), drop stale 50GB default Secrets are documented as available in every region an app runs in. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

mintlify · 2026-07-15T16:06:04Z

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
cerebrium	🟢 Ready	View Preview	Jul 15, 2026, 4:06 PM

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

…ive API Self-serve regions (us-east-1, us-central1, eu-north-1, eu-north1) all confirmed present in the production GPU availability matrix. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

The region list already names eu-north-1 (Stockholm) and eu-north1 (Finland) as separate regions. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

milo157 · 2026-07-16T12:58:52Z

+## Run Globally

-Cerebrium supports deployment across three major continents with the following regions:
+Set `region = "global"` to let the platform place the app in any region with available capacity that matches its hardware requirements:


maybe specify this is the default so doesn't need to explicitly be set

Fixed further up

milo157 · 2026-07-16T12:59:48Z

+memory = 8.0
+```
+
+Pinning guarantees placement but limits the app to that region's capacity, which increases the likelihood of request queuing when the region is busy.


"guarantees placement in that region"

milo157 · 2026-07-16T18:27:01Z

+
+## How Requests Are Routed
+
+- Requests are served from running capacity first: a request routes to a region with a warm instance before a cold start is triggered elsewhere.


maybe mentioned its served by the region closed to where the request is made and then directed to where there is warm capacity

milo157 · 2026-07-17T13:30:45Z

+
+## Storage
+
+Persistent storage is managed per region. Files written to `/persistent-storage` in one region are not guaranteed to be available in other regions, and region-local caches, such as model weights downloaded on first load, fill independently in each region an app runs in.


how is this going to extend when we have juristictions? Like US (us-east, us-west etc)

Another comment on this, I do believe that we'll have a default (e.g us-east-1 is for all us, eu-north-1 is for all eu)

Will cross that bridge when we get there

milo157 · 2026-07-17T13:31:47Z

-  from other regions.
+GPU availability varies across regions due to infrastructure constraints and local demand. CPU workloads run in every region.
+
+| Region                  | Available GPUs                                                                                                                                   |


Whey did we change this? Feel like the view is harder

7 columns are too wide for regions

milo157 · 2026-07-17T13:34:00Z

+Use the global volume for data that must be available everywhere, such as model weights for a global app. Use `/persistent-storage` for region-local data.
+
+<Note>
+  The global volume does not appear in the dashboard Volumes list and cannot be


so it just adapts or has a limit? or do they need to contact us

global volume is 1TB same as others (Which we haven't really had anyone contact us about again)

milo157 · 2026-07-17T13:34:31Z

 ## Increasing Storage Capacity

-The default 50GB persistent volume can be increased up to 1TB through self-service. The first 100GB is free, then $0.05 per GB per month.
+Persistent volumes can be resized up to 1TB through self-service. The first 100GB is free, then $0.05 per GB per month.


take out the price here. tell them to look at pricing page so in furture if we update then we dont have to update docs

- Pinning wording: guarantees placement in that region - Routing: requests enter through the closest region, then route to warm capacity - Storage wording extends to multi-region placement: one independent regional volume per region an app runs in - Replace storage pricing figures with a pricing page link - Note the global volume size (1TB) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

When omitted, the platform chooses placement automatically based on the app's hardware requirements. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

kylegani requested a review from milo157 as a code owner July 15, 2026 16:04

mintlify Bot deployed to staging July 15, 2026 16:06 View deployment

Remove us-east1 as a deployable region; eu-north-1 is self-serve

d572cc0

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

mintlify Bot deployed to staging July 15, 2026 16:11 View deployment

jonoirwinrsa reviewed Jul 15, 2026

View reviewed changes

Comment thread deployments/multi-region-deployment.mdx Outdated

Remove Crusoe region references; confirm deployable regions against l…

07f3d44

…ive API Self-serve regions (us-east-1, us-central1, eu-north-1, eu-north1) all confirmed present in the production GPU availability matrix. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

mintlify Bot deployed to staging July 17, 2026 10:31 View deployment

kylegani and others added 2 commits July 17, 2026 12:32

Drop the dash vs non-dash region callout

9124f5a

The region list already names eu-north-1 (Stockholm) and eu-north1 (Finland) as separate regions. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Prettified Code!

f80398f

mintlify Bot deployed to staging July 17, 2026 10:33 View deployment

mintlify Bot deployed to staging July 17, 2026 10:34 View deployment

milo157 reviewed Jul 17, 2026

View reviewed changes

mintlify Bot deployed to staging July 17, 2026 13:49 View deployment

State that the region parameter is optional

dad32af

When omitted, the platform chooses placement automatically based on the app's hardware requirements. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

mintlify Bot deployed to staging July 17, 2026 13:57 View deployment


		## How Requests Are Routed

		- Requests are served from running capacity first: a request routes to a region with a warm instance before a cold start is triggered elsewhere.


		## Storage

		Persistent storage is managed per region. Files written to `/persistent-storage` in one region are not guaranteed to be available in other regions, and region-local caches, such as model weights downloaded on first load, fill independently in each region an app runs in.

Uh oh!

Conversation

kylegani commented Jul 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Open items (flagged during review, need product/eng confirmation)

Uh oh!

mintlify Bot commented Jul 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

kylegani commented Jul 15, 2026 •

edited

Loading

mintlify Bot commented Jul 15, 2026 •

edited

Loading