Document global placement, GPU preference lists, and global storage

deployments/multi-region-deployment.mdx

@@ -1,9 +1,9 @@
 ---
 title: Multi-Region Deployment
-description: Deploy your apps globally across multiple regions for improved latency and data residency compliance
+description: Deploy an app once and run it across multiple regions, or pin it to a specific region for data residency
 ---
 
-Deploy apps globally across multiple continents to reduce latency through co-location and meet data residency requirements.
+Deploy an app once and run it in multiple regions. The `region` parameter in `cerebrium.toml` controls placement: run globally on whatever capacity is available (recommended), or pin the app to a specific region. The parameter is optional; when omitted, the platform chooses placement automatically based on the app's hardware requirements.
 
 <Warning>
   Multi-region deployment is currently in **beta**. Rapid updates and
@@ -14,97 +14,149 @@ Deploy apps globally across multiple continents to reduce latency through co-loc
 
 ## Why Use Multi-Region Deployment
 
-- **Reduced Latency**: Deploy closer to users for faster response times and better experience with real-time applications like voice agents and LLMs
-- **Data Residency**: Meet data protection requirements by keeping sensitive data within specific geographic regions to comply with regulations like GDPR and CCPA
-- **High Availability**: Ensure fault tolerance and continuous service through geographic redundancy, disaster recovery, and load balancing across multiple regions
+- **More capacity, less queueing**: An app that can run anywhere draws on the GPU capacity of every region. Constraining placement shrinks the pool of available hardware.
+- **High availability**: Traffic shifts away from degraded or busy regions automatically.
+- **Reduced latency**: Requests are routed to healthy capacity, preferring lower-latency regions.
+- **Data residency**: Pin an app to a region to keep sensitive data within a specific geographic region and comply with regulations like GDPR and CCPA.
+- **No duplicate apps**: One app, one endpoint, and one configuration instead of a separate deployment per region.
 
-## Available Regions
+## 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:
 
-### United States
+```toml
+[cerebrium.hardware]
+region = "global"
+compute = "AMPERE_A10"
+cpu = 2
+memory = 8.0
+```
 
-- **us-east-1** (N. Virginia) - Default region
+When Cerebrium brings new capacity online, global apps can run there without a configuration change or redeploy.
 
-### Europe
+<Note>
+  Geography-based placement is coming soon. This constrains an app to a
+  geographic area such as the US or the EU to meet data-residency requirements.
+</Note>
+
+## Pin a Region
+
+Set `region` to a specific region to run the app only there:
+
+```toml
+[cerebrium.hardware]
+region = "us-east-1"
+compute = "AMPERE_A10"
+cpu = 2
+memory = 8.0
+```
+
+Pinning guarantees placement in that region but limits the app to that region's capacity, which increases the likelihood of request queuing when the region is busy.
+
+### Available Regions
+
+#### United States
+
+- **us-east-1** (N. Virginia)
+- **us-central1** (Kansas City)
+
+#### Europe
 
-- **eu-west-2** (United Kingdom)
 - **eu-north-1** (Stockholm)
+- **eu-north1** (Finland)
+
+#### Available on request
 
-### Asia Pacific
+Contact [support](mailto:support@cerebrium.ai) to enable access to these regions:
 
+- **us-west-2** (Oregon)
+- **eu-west-2** (United Kingdom)
+- **eu-central-1** (Frankfurt)
 - **ap-south-1** (Mumbai)
+- **ap-northeast-1** (Tokyo)
+- **sa-east-1** (São Paulo)
+- **ca-central-1** (Montreal)
+- **me-central-1** (Dubai)
 
 <Info>
-  Additional regions are being evaluated and will be added based on user demand
-  and infrastructure availability. Contact
-  [support](mailto:support@cerebrium.ai) if you need deployment in a specific
-  region not currently listed.
+  Some regions run on cloud providers other than AWS: when pinning `us-central1`
+  or `eu-north1`, set `provider = "nebius"`.
 </Info>
 
-## CLI Configuration
+## Hardware Preferences
+
+Placement respects both the region and the hardware requirements of an app. Specify acceptable GPU types in preference order with a `compute` list (see [GPU preference lists](/hardware/using-gpus#gpu-preference-lists)):
+
+```toml
+[cerebrium.hardware]
+region = "global"
+compute = ["HOPPER_H100", "HOPPER_H200", "AMPERE_A100_80GB"]
+```
+
+The set of eligible regions is the intersection of both constraints: any region with several acceptable GPU types is the widest pool; one region with a single GPU type is the narrowest.
 
-Configure the CLI to work with different regions in two ways:
+## Endpoints
 
-Set a default region for all CLI commands:
+Apps keep a single endpoint no matter how many regions they run in:
+
+```text
+https://api.cerebrium.ai/v4/p-xxxxxxxx/{app-name}/{function-name}
+```
+
+Requests enter through the global router and are directed to a region where the app is running. Regioned hostnames continue to work but add a proxy hop. See [REST API](/endpoints/inference-api).
+
+## How Requests Are Routed
+
+- A request enters through the region closest to where it is made, then routes to a region with a warm instance before a cold start is triggered elsewhere.
+- Routing prefers lower-latency regions but does not guarantee the nearest region.
+- There is no session affinity. Consecutive requests can be served from different regions.
+
+## Scaling Across Regions
+
+`min_replicas`, `max_replicas`, and `scaling_buffer` apply to the app as a whole, not per region. The platform distributes instances across eligible regions based on traffic and available capacity.
+
+View where containers are running:
 
 ```bash
-cerebrium region set us-east-1
+cerebrium containers list my-app
 ```
 
-This sets the default region for commands like listing storage volumes, running applications, and other operations.
+The output includes the region of each container.
+
+## Storage
+
+Persistent storage is managed per region: an app has an independent `/persistent-storage` volume in each region it runs in, however placement is configured. Files written 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 per region.
+
+Apps deployed with `region = "global"` also mount `/global-persistent-storage`, a single volume shared across every region the app runs in. Files written there are visible from all regions, and reads are cached per region. Use the global volume for data that must be available everywhere and `/persistent-storage` for region-local data. Manage files on the global volume by passing `--region global` to the file commands. See [Managing Files](/storage/managing-files#global-storage).
 
-Alternatively, specify the region for individual commands using `--region` (or its short form `-r`). This works for all file commands — `cp`, `ls`, `rm`, and `download`:
+Target a region with the file commands using `--region` (or its short form `-r`). This works for all file commands: `cp`, `ls`, `rm`, and `download`.
 
 ```bash
 cerebrium ls --region eu-north-1
 cerebrium cp model.bin -r eu-north-1
-cerebrium rm old_file.txt --region eu-north-1
-cerebrium download results.json -r eu-north-1
+```
+
+Set a default region for CLI commands:
+
+```bash
+cerebrium region set us-east-1
 ```
 
 <Info>
   `--region` applies only to the command it's attached to. The default set by
   `cerebrium region set` is not modified.
 </Info>
 
-## App Deployment
-
-Set the deployment region using the `region` parameter in the `[cerebrium.hardware]` section of `cerebrium.toml`:
-
-```toml
-[cerebrium.hardware]
-region = "us-east-1"
-provider = "aws"
-compute = "AMPERE_A10"
-cpu = 2
-memory = 8.0
-```
-
-## Pricing
-
-Pricing varies by region based on local infrastructure costs and availability:
-
 ## GPU Availability by Region
 
-GPU availability and pricing vary across regions due to infrastructure constraints and local demand:
-
-| GPU Model         | US East | US Central | EU West | EU North | AP South |
-| ----------------- | ------- | ---------- | ------- | -------- | -------- |
-| BLACKWELL_B300    | ✅      | ❌         | ❌      | ❌       | ❌       |
-| BLACKWELL_B200    | ✅      | ✅         | ❌      | ❌       | ❌       |
-| HOPPER_H200       | ✅      | ✅         | ✅      | ✅       | ✅       |
-| HOPPER_H100       | ✅      | ❌         | ✅      | ✅       | ✅       |
-| BLACKWELL_RTX6000 | ❌      | ✅         | ❌      | ❌       | ❌       |
-| AMPERE_A100_80GB  | ✅      | ❌         | ✅      | ✅       | ✅       |
-| AMPERE_A100_40GB  | ✅      | ❌         | ✅      | ✅       | ✅       |
-| ADA_L40           | ✅      | ❌         | ❌      | ✅       | ❌       |
-| ADA_L4            | ✅      | ❌         | ✅      | ✅       | ✅       |
-| AMPERE_A10        | ✅      | ❌         | ✅      | ✅       | ✅       |
-| TURING_T4         | ✅      | ❌         | ✅      | ✅       | ✅       |
-
-### Limitations
-
-- Each region requires a separate deployment. Apps deployed in one region do not automatically replicate to other regions.
-- Each region has its own isolated persistent storage volume. Data stored in `/persistent-storage` in one region is not accessible
-  from other regions.
+GPU availability varies across regions due to infrastructure constraints and local demand. CPU workloads run in every region.
+
+| Region                  | Available GPUs                                                                                                                                   |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| us-east-1               | BLACKWELL_B300, BLACKWELL_B200, HOPPER_H200, HOPPER_H100, AMPERE_A100_80GB, AMPERE_A100_40GB, ADA_L40, ADA_L4, AMPERE_A10, TURING_T4, INF2, TRN1 |
+| us-central1             | BLACKWELL_RTX6000, BLACKWELL_B200, HOPPER_H200                                                                                                   |
+| eu-north1               | HOPPER_H200, HOPPER_H100, ADA_L40                                                                                                                |
+| us-west-2 (on request)  | HOPPER_H200, HOPPER_H100, AMPERE_A100_80GB, AMPERE_A100_40GB, ADA_L40, ADA_L4, AMPERE_A10, INF2, TRN1                                            |
+| eu-west-2 (on request)  | HOPPER_H100, AMPERE_A10, ADA_L4, TURING_T4                                                                                                       |
+| eu-north-1              | HOPPER_H100, ADA_L40, ADA_L4, AMPERE_A10, TURING_T4, INF2, TRN1                                                                                  |
+| ap-south-1 (on request) | ADA_L4, AMPERE_A10, TURING_T4                                                                                                                    |

getting-started/introduction.mdx

@@ -18,7 +18,7 @@ It is a strong fit when an app requires one or more of the following:
 - Launch code in the cloud in seconds
 - Run [CPUs](/hardware/cpu-and-memory) or [GPUs](/hardware/using-gpus) with automatic scaling
 - Serve [REST APIs](/endpoints/inference-api), [streaming endpoints](/endpoints/streaming), [WebSockets](/endpoints/websockets), or any [ASGI-compatible app](/container-images/custom-web-servers)
-- Deploy across [multiple regions](/deployments/multi-region-deployment) for lower latency and residency requirements
+- Deploy once and run across [multiple regions](/deployments/multi-region-deployment) for lower latency and higher availability
 - Tune [concurrency and batching](/scaling/batching-concurrency) for real production traffic
 - Improve startup performance with [cold-start optimization strategies](/performance/faster-cold-starts)
 - Store model weights and files with [persistent storage](/storage/managing-files)

hardware/using-gpus.mdx

@@ -1,5 +1,6 @@
 ---
 title: Using GPUs
+description: Configure GPU type, quantity, and preference-ordered fallback lists for Cerebrium apps
 ---
 
 GPUs accelerate computational workloads through parallel processing. Originally designed for graphics rendering, modern GPUs are essential for AI models, large-scale data processing, and other compute-intensive applications.
@@ -51,5 +52,25 @@ cpu = 8
 memory = 128.0
 ```
 
-GPU availability varies by region and provider. Narrowing the provider and region constraints increases the likelihood of request queuing.
+## GPU Preference Lists
+
+The `compute` parameter also accepts a list of acceptable GPU types in preference order. The platform allocates the most preferred type with available capacity and falls back to the next entry when needed:
+
+```toml
+[cerebrium.hardware]
+compute = ["HOPPER_H100", "HOPPER_H200", "AMPERE_A100_80GB"]
+gpu_count = 1
+cpu = 8
+memory = 128.0
+```
+
+- Up to 5 entries, ordered from most to least preferred
+- All entries must belong to the same hardware family. NVIDIA GPU types cannot be mixed with CPU or AWS accelerators (INF2, TRN1)
+- `cerebrium run` uses only the first entry
+
+Accepting more GPU types widens the pool of capacity an app can run on and reduces the likelihood of request queuing.
+
+## Availability
+
+GPU availability varies by region and provider. Narrowing the provider and region constraints increases the likelihood of request queuing. See [GPU availability by region](/deployments/multi-region-deployment#gpu-availability-by-region).
 For guaranteed burst capacity, contact the [enterprise plan](mailto:sales@cerebrium.ai) team.

other-topics/using-secrets.mdx

@@ -9,6 +9,8 @@ Secrets can be managed at both project and app levels. Project-level secrets are
 
 Each secret is exposed to the app as an environment variable.
 
+Secrets are available in every region an app runs in. Apps deployed to [multiple regions](/deployments/multi-region-deployment) require no per-region secret setup.
+
 Secrets are loaded on container startup. If you update a secret, you must restart your app container for the changes to take effect.
 
 ```python

performance/faster-cold-starts.mdx

@@ -23,6 +23,8 @@ Store model weights on [persistent storage](/storage/managing-files) at `/persis
 
 Cerebrium caches reads from persistent storage within each region. After weights are loaded once, future cold starts can reuse the cached copy and load faster.
 
+For apps running in [multiple regions](/deployments/multi-region-deployment), each region fills its own cache independently. Store weights on the global volume at `/global-persistent-storage` to make them available in every region without a per-region copy.
+
 This is usually the best default for large models. Baking weights into the container increases image size, which means Cerebrium has to pull and restore a larger image before your application can start initialization.
 
 Only include weights in the container image when they are small enough that the image remains lightweight.
@@ -38,7 +40,7 @@ Only include weights in the container image when they are small enough that the
 Move as much initialization work as possible out of the request path and into module scope so it runs once at container start, before the container accepts traffic.
 
 ```python
-# Runs once at container start — not on every request
+# Runs once at container start, not on every request
 model = load_model("/persistent-storage/models/my-model/")
 tokenizer = load_tokenizer("/persistent-storage/models/my-model/")
 

scaling/scaling-apps.mdx

@@ -29,6 +29,8 @@ The `min_replicas` parameter defines how many instances remain active at all tim
 
 The `max_replicas` parameter sets an upper limit on concurrent instances, controlling costs and protecting backend systems. When traffic increases, new instances start automatically up to this configured maximum.
 
+For apps running in multiple regions, `min_replicas` and `max_replicas` apply to the app as a whole rather than per region. The platform distributes instances across eligible regions based on traffic and available capacity. See [Multi-Region Deployment](/deployments/multi-region-deployment).
+
 ### Cooldown Period
 
 The `cooldown` parameter specifies the time window (in seconds) that must pass at reduced concurrency before an instance scales down. This prevents premature scale-down during brief traffic dips that might be followed by more requests. A longer cooldown period helps handle bursty traffic patterns but increases instance running time and cost.
@@ -49,7 +51,7 @@ _3_ requests in flight with no replicas currently available, Cerebrium will scal
 
 ## Processing Multiple Requests
 
-Apps can process multiple requests simultaneously through batching and concurrency. Cerebrium supports frameworks with built-in batching and enables custom implementations through the [custom runtime](container-images/defining-container-images#custom-runtimes) feature. See the [Batching & Concurrency Guide](/scaling/batching-concurrency) for details.
+Apps can process multiple requests simultaneously through batching and concurrency. Cerebrium supports frameworks with built-in batching and enables custom implementations through the [custom runtime](/container-images/defining-container-images#custom-runtimes) feature. See the [Batching & Concurrency Guide](/scaling/batching-concurrency) for details.
 
 ## Instance Management
 
@@ -149,7 +151,7 @@ scaling_target = 100
 scaling_buffer = 3
 ```
 
-With the above config: when no traffic is received, the app runs **1 replica** as a baseline — the buffer scales based on requests.
+With the above config: when no traffic is received, the app runs **1 replica** as a baseline. The buffer scales based on requests.
 With `concurrency_utilization` at `100` and `replica_concurrency=1`, receiving 1 request causes the autoscaler to suggest 1 replica. With `scaling_buffer=3`, the app scales to **(1+3)=4** replicas.
 The buffer adds a static number of replicas on top of the autoscaler's recommendation.
 After the request completes, the `cooldown` period applies and the replica count scales back to the **1 replica** baseline.