From bc5d9958be426eb2ae7cb3e6048c86a668165ec0 Mon Sep 17 00:00:00 2001 From: lgunreddi Date: Wed, 29 Jul 2026 11:54:55 -0400 Subject: [PATCH 01/12] Update docs.json --- docs.json | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs.json b/docs.json index e0a2e7388..3d01e0d13 100644 --- a/docs.json +++ b/docs.json @@ -231,6 +231,8 @@ "storage/network-volumes", "storage/high-performance-storage", "storage/s3-api" + "storage/globalstore", + "storage/globalstore-quickstart" ] }, { From b4fd1437bfc779e89ce9ef790baff5d5efecc586 Mon Sep 17 00:00:00 2001 From: lgunreddi Date: Wed, 29 Jul 2026 14:02:20 -0400 Subject: [PATCH 02/12] Create globalstore-quickstart.mdx --- storage/storage/globalstore-quickstart.mdx | 148 +++++++++++++++++++++ 1 file changed, 148 insertions(+) create mode 100644 storage/storage/globalstore-quickstart.mdx diff --git a/storage/storage/globalstore-quickstart.mdx b/storage/storage/globalstore-quickstart.mdx new file mode 100644 index 000000000..38fa76ff3 --- /dev/null +++ b/storage/storage/globalstore-quickstart.mdx @@ -0,0 +1,148 @@ +--- +title: "GlobalStore quickstart" +sidebarTitle: "GlobalStore quickstart" +description: "Register an ObjectStore and mount it into a Pod using the Runpod GraphQL API." +tag: "NEW" +--- +This quickstart walks you through registering an ObjectStore that references your S3-compatible bucket, then mounting a prefix of it into a Pod. + +This quickstart uses the Runpod GraphQL API to register an ObjectStore and mount it into a Pod. See [GlobalStore](/storage/globalstore) for the concepts behind ObjectStores and ObjectMounts. New to the Runpod GraphQL API? See the [GraphQL API overview](/sdks/graphql/configurations). + +## Requirements +- Access to the GlobalStore early access feature. Access is gated, so if GlobalStore isn't enabled for your account, contact Runpod to request it. +- A Runpod API key ([API keys](/get-started/api-keys)). +- An existing S3-compatible bucket on Tigris or Cloudflare R2, along with its endpoint URL, bucket name, access key, and secret. +## Register an ObjectStore + + +Call the `createObjectStore` mutation with your bucket details. Pass the eligible regions in which the ObjectStore can be used. + + +```bash +curl --request POST \ + --header 'content-type: application/json' \ + --url 'https://api.runpod.io/graphql?api_key=${YOUR_API_KEY}' \ + --data '{"query": "mutation { createObjectStore( input: { name: \"my-object-store\", endpointUrl: \"https://fly.storage.tigris.dev\", bucketName: \"my-bucket\", accessKey: \"YOUR_ACCESS_KEY\", secretKey: \"YOUR_SECRET_KEY\", eligibleRegions: [\"US-CA-2\"] } ) { id name } }"}' +``` + + +```graphql +mutation { + createObjectStore( + input: { + name: "my-object-store" + endpointUrl: "https://fly.storage.tigris.dev" + bucketName: "my-bucket" + accessKey: "YOUR_ACCESS_KEY" + secretKey: "YOUR_SECRET_KEY" + eligibleRegions: ["US-CA-2"] + } + ) { + id + name + } +} +``` + + +```json +{ + "data": { + "createObjectStore": { + "id": "obj_abc123", + "name": "my-object-store" + } + } +} +``` + + + + +The returned `id` is the `objectStoreId` you'll use when mounting the ObjectStore into a Pod. The secret you passed in `secretKey` is write-only and is never returned by the API, so store it securely on your side if you need it again. + + +## Mount an ObjectStore into a Pod +You attach ObjectMounts when you create a Pod by passing an `objectMounts` array to the Pod-create input. Each entry is shaped `{ objectStoreId, prefix, readOnly, mountPath }`. +The example below shows `objectMounts` as an addition to the standard `podFindAndDeployOnDemand` input. For the full Pod-create flow, see [Manage Pods](/sdks/graphql/manage-pods). +```graphql +mutation { + podFindAndDeployOnDemand( + input: { + cloudType: ALL + gpuCount: 1 + volumeInGb: 40 + containerDiskInGb: 40 + gpuTypeId: "NVIDIA RTX A6000" + name: "GlobalStore Pod" + imageName: "runpod/pytorch" + objectMounts: [ + { + objectStoreId: "YOUR_OBJECT_STORE_ID" + prefix: "models/" + readOnly: true + mountPath: "/mnt/models" + } + ] + } + ) { + id + imageName + } +} +``` +Keep these rules in mind: +- Each `mountPath` must be unique within a Pod. +- The referenced ObjectStore must belong to your account or organization. +- Mounts are typically read-only. + +Today you attach ObjectMounts through the GraphQL API, as shown above. + +## Check mount status +After the Pod starts, each ObjectMount moves through a short lifecycle: +- `pending`: the mount is queued and hasn't started yet. +- `mounting`: the mount is being established. +- `ready`: the prefix is mounted and available to your application. +- `failed`: the mount couldn't be established. See [Troubleshoot failed mounts](#troubleshoot-failed-mounts). +## Troubleshoot failed mounts +When a mount reports `failed`, it includes a failure reason: +| Failure reason | What it means | +|----------------|---------------| +| `credentials` | The access key or secret was rejected. Resupply valid credentials with `updateObjectStore`. | +| `bucket_access` | The bucket or endpoint couldn't be reached, or permissions are insufficient. Verify the endpoint URL, bucket name, and that the credentials grant access. | +| `prefix_empty` | A read-only mount points at a prefix that contains no objects. Confirm objects exist under the prefix, or set `readOnly: false` if the prefix is intentionally empty. | +| `fuse_crash` | The mount process failed. Retry, and contact support if it persists. | +## Manage ObjectStores +Use `updateObjectStore` to change an ObjectStore's `name` or rotate its credentials. To rotate credentials, supply a new `accessKey` and `secretKey`; the secret stays write-only and is never returned. +```graphql +mutation { + updateObjectStore( + input: { + id: "YOUR_OBJECT_STORE_ID" + name: "my-renamed-store" + accessKey: "NEW_ACCESS_KEY" + secretKey: "NEW_SECRET_KEY" + } + ) { + id + name + } +} +``` +Use `deleteObjectStore` to remove an ObjectStore you no longer need. +```graphql +mutation { + deleteObjectStore(input: { id: "YOUR_OBJECT_STORE_ID" }) { + id + } +} +``` +## Next steps + + + Review the concepts behind ObjectStores and ObjectMounts. + + + Learn about Runpod's regional, high-performance storage. + + From 111a14d0e4d6ea6bd603c5da917436c3acbbe08f Mon Sep 17 00:00:00 2001 From: lgunreddi Date: Wed, 29 Jul 2026 14:13:27 -0400 Subject: [PATCH 03/12] Create globalstore-quickstart.mdx --- storage/globalstore-quickstart.mdx | 148 +++++++++++++++++++++++++++++ 1 file changed, 148 insertions(+) create mode 100644 storage/globalstore-quickstart.mdx diff --git a/storage/globalstore-quickstart.mdx b/storage/globalstore-quickstart.mdx new file mode 100644 index 000000000..38fa76ff3 --- /dev/null +++ b/storage/globalstore-quickstart.mdx @@ -0,0 +1,148 @@ +--- +title: "GlobalStore quickstart" +sidebarTitle: "GlobalStore quickstart" +description: "Register an ObjectStore and mount it into a Pod using the Runpod GraphQL API." +tag: "NEW" +--- +This quickstart walks you through registering an ObjectStore that references your S3-compatible bucket, then mounting a prefix of it into a Pod. + +This quickstart uses the Runpod GraphQL API to register an ObjectStore and mount it into a Pod. See [GlobalStore](/storage/globalstore) for the concepts behind ObjectStores and ObjectMounts. New to the Runpod GraphQL API? See the [GraphQL API overview](/sdks/graphql/configurations). + +## Requirements +- Access to the GlobalStore early access feature. Access is gated, so if GlobalStore isn't enabled for your account, contact Runpod to request it. +- A Runpod API key ([API keys](/get-started/api-keys)). +- An existing S3-compatible bucket on Tigris or Cloudflare R2, along with its endpoint URL, bucket name, access key, and secret. +## Register an ObjectStore + + +Call the `createObjectStore` mutation with your bucket details. Pass the eligible regions in which the ObjectStore can be used. + + +```bash +curl --request POST \ + --header 'content-type: application/json' \ + --url 'https://api.runpod.io/graphql?api_key=${YOUR_API_KEY}' \ + --data '{"query": "mutation { createObjectStore( input: { name: \"my-object-store\", endpointUrl: \"https://fly.storage.tigris.dev\", bucketName: \"my-bucket\", accessKey: \"YOUR_ACCESS_KEY\", secretKey: \"YOUR_SECRET_KEY\", eligibleRegions: [\"US-CA-2\"] } ) { id name } }"}' +``` + + +```graphql +mutation { + createObjectStore( + input: { + name: "my-object-store" + endpointUrl: "https://fly.storage.tigris.dev" + bucketName: "my-bucket" + accessKey: "YOUR_ACCESS_KEY" + secretKey: "YOUR_SECRET_KEY" + eligibleRegions: ["US-CA-2"] + } + ) { + id + name + } +} +``` + + +```json +{ + "data": { + "createObjectStore": { + "id": "obj_abc123", + "name": "my-object-store" + } + } +} +``` + + + + +The returned `id` is the `objectStoreId` you'll use when mounting the ObjectStore into a Pod. The secret you passed in `secretKey` is write-only and is never returned by the API, so store it securely on your side if you need it again. + + +## Mount an ObjectStore into a Pod +You attach ObjectMounts when you create a Pod by passing an `objectMounts` array to the Pod-create input. Each entry is shaped `{ objectStoreId, prefix, readOnly, mountPath }`. +The example below shows `objectMounts` as an addition to the standard `podFindAndDeployOnDemand` input. For the full Pod-create flow, see [Manage Pods](/sdks/graphql/manage-pods). +```graphql +mutation { + podFindAndDeployOnDemand( + input: { + cloudType: ALL + gpuCount: 1 + volumeInGb: 40 + containerDiskInGb: 40 + gpuTypeId: "NVIDIA RTX A6000" + name: "GlobalStore Pod" + imageName: "runpod/pytorch" + objectMounts: [ + { + objectStoreId: "YOUR_OBJECT_STORE_ID" + prefix: "models/" + readOnly: true + mountPath: "/mnt/models" + } + ] + } + ) { + id + imageName + } +} +``` +Keep these rules in mind: +- Each `mountPath` must be unique within a Pod. +- The referenced ObjectStore must belong to your account or organization. +- Mounts are typically read-only. + +Today you attach ObjectMounts through the GraphQL API, as shown above. + +## Check mount status +After the Pod starts, each ObjectMount moves through a short lifecycle: +- `pending`: the mount is queued and hasn't started yet. +- `mounting`: the mount is being established. +- `ready`: the prefix is mounted and available to your application. +- `failed`: the mount couldn't be established. See [Troubleshoot failed mounts](#troubleshoot-failed-mounts). +## Troubleshoot failed mounts +When a mount reports `failed`, it includes a failure reason: +| Failure reason | What it means | +|----------------|---------------| +| `credentials` | The access key or secret was rejected. Resupply valid credentials with `updateObjectStore`. | +| `bucket_access` | The bucket or endpoint couldn't be reached, or permissions are insufficient. Verify the endpoint URL, bucket name, and that the credentials grant access. | +| `prefix_empty` | A read-only mount points at a prefix that contains no objects. Confirm objects exist under the prefix, or set `readOnly: false` if the prefix is intentionally empty. | +| `fuse_crash` | The mount process failed. Retry, and contact support if it persists. | +## Manage ObjectStores +Use `updateObjectStore` to change an ObjectStore's `name` or rotate its credentials. To rotate credentials, supply a new `accessKey` and `secretKey`; the secret stays write-only and is never returned. +```graphql +mutation { + updateObjectStore( + input: { + id: "YOUR_OBJECT_STORE_ID" + name: "my-renamed-store" + accessKey: "NEW_ACCESS_KEY" + secretKey: "NEW_SECRET_KEY" + } + ) { + id + name + } +} +``` +Use `deleteObjectStore` to remove an ObjectStore you no longer need. +```graphql +mutation { + deleteObjectStore(input: { id: "YOUR_OBJECT_STORE_ID" }) { + id + } +} +``` +## Next steps + + + Review the concepts behind ObjectStores and ObjectMounts. + + + Learn about Runpod's regional, high-performance storage. + + From fbcfd72e78c7a08d6f72aaf0fcbed95b45af526d Mon Sep 17 00:00:00 2001 From: lgunreddi Date: Wed, 29 Jul 2026 14:14:28 -0400 Subject: [PATCH 04/12] Delete storage/storage/globalstore-quickstart.mdx --- storage/storage/globalstore-quickstart.mdx | 148 --------------------- 1 file changed, 148 deletions(-) delete mode 100644 storage/storage/globalstore-quickstart.mdx diff --git a/storage/storage/globalstore-quickstart.mdx b/storage/storage/globalstore-quickstart.mdx deleted file mode 100644 index 38fa76ff3..000000000 --- a/storage/storage/globalstore-quickstart.mdx +++ /dev/null @@ -1,148 +0,0 @@ ---- -title: "GlobalStore quickstart" -sidebarTitle: "GlobalStore quickstart" -description: "Register an ObjectStore and mount it into a Pod using the Runpod GraphQL API." -tag: "NEW" ---- -This quickstart walks you through registering an ObjectStore that references your S3-compatible bucket, then mounting a prefix of it into a Pod. - -This quickstart uses the Runpod GraphQL API to register an ObjectStore and mount it into a Pod. See [GlobalStore](/storage/globalstore) for the concepts behind ObjectStores and ObjectMounts. New to the Runpod GraphQL API? See the [GraphQL API overview](/sdks/graphql/configurations). - -## Requirements -- Access to the GlobalStore early access feature. Access is gated, so if GlobalStore isn't enabled for your account, contact Runpod to request it. -- A Runpod API key ([API keys](/get-started/api-keys)). -- An existing S3-compatible bucket on Tigris or Cloudflare R2, along with its endpoint URL, bucket name, access key, and secret. -## Register an ObjectStore - - -Call the `createObjectStore` mutation with your bucket details. Pass the eligible regions in which the ObjectStore can be used. - - -```bash -curl --request POST \ - --header 'content-type: application/json' \ - --url 'https://api.runpod.io/graphql?api_key=${YOUR_API_KEY}' \ - --data '{"query": "mutation { createObjectStore( input: { name: \"my-object-store\", endpointUrl: \"https://fly.storage.tigris.dev\", bucketName: \"my-bucket\", accessKey: \"YOUR_ACCESS_KEY\", secretKey: \"YOUR_SECRET_KEY\", eligibleRegions: [\"US-CA-2\"] } ) { id name } }"}' -``` - - -```graphql -mutation { - createObjectStore( - input: { - name: "my-object-store" - endpointUrl: "https://fly.storage.tigris.dev" - bucketName: "my-bucket" - accessKey: "YOUR_ACCESS_KEY" - secretKey: "YOUR_SECRET_KEY" - eligibleRegions: ["US-CA-2"] - } - ) { - id - name - } -} -``` - - -```json -{ - "data": { - "createObjectStore": { - "id": "obj_abc123", - "name": "my-object-store" - } - } -} -``` - - - - -The returned `id` is the `objectStoreId` you'll use when mounting the ObjectStore into a Pod. The secret you passed in `secretKey` is write-only and is never returned by the API, so store it securely on your side if you need it again. - - -## Mount an ObjectStore into a Pod -You attach ObjectMounts when you create a Pod by passing an `objectMounts` array to the Pod-create input. Each entry is shaped `{ objectStoreId, prefix, readOnly, mountPath }`. -The example below shows `objectMounts` as an addition to the standard `podFindAndDeployOnDemand` input. For the full Pod-create flow, see [Manage Pods](/sdks/graphql/manage-pods). -```graphql -mutation { - podFindAndDeployOnDemand( - input: { - cloudType: ALL - gpuCount: 1 - volumeInGb: 40 - containerDiskInGb: 40 - gpuTypeId: "NVIDIA RTX A6000" - name: "GlobalStore Pod" - imageName: "runpod/pytorch" - objectMounts: [ - { - objectStoreId: "YOUR_OBJECT_STORE_ID" - prefix: "models/" - readOnly: true - mountPath: "/mnt/models" - } - ] - } - ) { - id - imageName - } -} -``` -Keep these rules in mind: -- Each `mountPath` must be unique within a Pod. -- The referenced ObjectStore must belong to your account or organization. -- Mounts are typically read-only. - -Today you attach ObjectMounts through the GraphQL API, as shown above. - -## Check mount status -After the Pod starts, each ObjectMount moves through a short lifecycle: -- `pending`: the mount is queued and hasn't started yet. -- `mounting`: the mount is being established. -- `ready`: the prefix is mounted and available to your application. -- `failed`: the mount couldn't be established. See [Troubleshoot failed mounts](#troubleshoot-failed-mounts). -## Troubleshoot failed mounts -When a mount reports `failed`, it includes a failure reason: -| Failure reason | What it means | -|----------------|---------------| -| `credentials` | The access key or secret was rejected. Resupply valid credentials with `updateObjectStore`. | -| `bucket_access` | The bucket or endpoint couldn't be reached, or permissions are insufficient. Verify the endpoint URL, bucket name, and that the credentials grant access. | -| `prefix_empty` | A read-only mount points at a prefix that contains no objects. Confirm objects exist under the prefix, or set `readOnly: false` if the prefix is intentionally empty. | -| `fuse_crash` | The mount process failed. Retry, and contact support if it persists. | -## Manage ObjectStores -Use `updateObjectStore` to change an ObjectStore's `name` or rotate its credentials. To rotate credentials, supply a new `accessKey` and `secretKey`; the secret stays write-only and is never returned. -```graphql -mutation { - updateObjectStore( - input: { - id: "YOUR_OBJECT_STORE_ID" - name: "my-renamed-store" - accessKey: "NEW_ACCESS_KEY" - secretKey: "NEW_SECRET_KEY" - } - ) { - id - name - } -} -``` -Use `deleteObjectStore` to remove an ObjectStore you no longer need. -```graphql -mutation { - deleteObjectStore(input: { id: "YOUR_OBJECT_STORE_ID" }) { - id - } -} -``` -## Next steps - - - Review the concepts behind ObjectStores and ObjectMounts. - - - Learn about Runpod's regional, high-performance storage. - - From 012395ac38040fb441d6b275c43ece0a2fd431b4 Mon Sep 17 00:00:00 2001 From: lgunreddi Date: Wed, 29 Jul 2026 14:15:58 -0400 Subject: [PATCH 05/12] Create globalstore.mdx --- storage/globalstore.mdx | 75 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 storage/globalstore.mdx diff --git a/storage/globalstore.mdx b/storage/globalstore.mdx new file mode 100644 index 000000000..a43aed867 --- /dev/null +++ b/storage/globalstore.mdx @@ -0,0 +1,75 @@ +--- +title: "GlobalStore" +sidebarTitle: "GlobalStore" +description: "Mount a bring-your-own S3-compatible bucket into Pods for read-heavy, region-portable object storage." +tag: "NEW" +--- + +GlobalStore lets you register a bring-your-own S3-compatible bucket as an **ObjectStore** and mount one or more prefixes of it (**ObjectMounts**) into your Pods at container start. It is object-backed, read-heavy, and region-portable, so you can make the same objects available to Pods across regions without copying data into each one. + + +GlobalStore is an early-access feature and may change while it's in active development. Today it's configured through the Runpod GraphQL API. See [Early access](/get-started/early-access) to learn more. + + +## How GlobalStore works + +An ObjectStore is a registered reference to your external S3-compatible bucket. It records the endpoint URL, bucket name, credentials, and the regions in which the bucket is eligible to be used. + +An ObjectMount attaches a prefix of that bucket (a grouping of object keys, similar to a folder path) into a Pod at a chosen mount path. The mount is established when the container starts, so the objects under that prefix are available to your application as soon as the Pod is running. + +GlobalStore is distinct from the [S3-compatible API](/storage/s3-api), which exposes your Runpod network volumes over an S3 endpoint. GlobalStore instead mounts your own external S3-compatible bucket into Pods. + +## When to use GlobalStore + +Today, you attach ObjectMounts to Pods; Serverless worker support isn't available. + +GlobalStore is built for read-heavy workloads that read the same objects repeatedly or across regions, such as: + +- Serving models. +- Reading inference artifacts. +- Distributing model weights, LoRAs, or configuration read-only across regions. + +## When not to use GlobalStore + + +GlobalStore is not a replacement for [network volumes](/storage/network-volumes), Runpod's regional, high-performance block and file storage. For latency-sensitive or write-heavy workloads, use a network volume or [high-performance storage](/storage/high-performance-storage) instead. + + +GlobalStore does not support the following workloads: + +- High-throughput training. +- POSIX filesystem semantics. +- Active-active concurrent writes. + +Object storage doesn't behave like a POSIX filesystem, so applications that expect local-filesystem behavior aren't a good fit for GlobalStore. + +## Supported providers + +GlobalStore is tested with Tigris and Cloudflare R2. Other S3-compatible providers are untested and not supported. + +## Regional availability + +When you register an ObjectStore, you declare the regions in which it is eligible to be used. GlobalStore is available only in supported regions, and availability expands over time. To confirm whether GlobalStore is available in the regions you need, check the eligible regions when you register an ObjectStore, or contact [Runpod support](https://www.runpod.io/contact). + +## Read and write behavior + +Mounts are typically read-only, which matches GlobalStore's read-heavy design. + +The prefix a mount points at is subject to a simple rule: a read-only mount that points at an empty prefix fails, because there are no objects to read. An empty prefix with read-write access is allowed, and files are created under that prefix on write. + +## Credentials and security + +Your bucket credentials are encrypted at rest. The secret is write-only: the API never returns it after you submit it. Credentials are injected into the mount process through its environment and are never written to disk. + +An ObjectStore can only be used by the same account or organization that registered it. + +## Next steps + + + + Register an ObjectStore and mount it into a Pod using the GraphQL API. + + + Learn about Runpod's regional, high-performance storage. + + From b5fbd75cb564c2d498c7425774d73b53a2255932 Mon Sep 17 00:00:00 2001 From: lgunreddi Date: Wed, 29 Jul 2026 14:17:29 -0400 Subject: [PATCH 06/12] Update docs.json --- docs.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs.json b/docs.json index 3d01e0d13..b5a609c78 100644 --- a/docs.json +++ b/docs.json @@ -230,7 +230,7 @@ "pages": [ "storage/network-volumes", "storage/high-performance-storage", - "storage/s3-api" + "storage/s3-api", "storage/globalstore", "storage/globalstore-quickstart" ] From c2b3f4095ef631143f37b8f82e6825e7ca72ce36 Mon Sep 17 00:00:00 2001 From: lgunreddi Date: Mon, 3 Aug 2026 11:03:25 -0400 Subject: [PATCH 07/12] Update globalstore.mdx --- storage/globalstore.mdx | 150 +++++++++++++++++++++++++++++----------- 1 file changed, 108 insertions(+), 42 deletions(-) diff --git a/storage/globalstore.mdx b/storage/globalstore.mdx index a43aed867..e227ca5d9 100644 --- a/storage/globalstore.mdx +++ b/storage/globalstore.mdx @@ -1,75 +1,141 @@ --- title: "GlobalStore" sidebarTitle: "GlobalStore" -description: "Mount a bring-your-own S3-compatible bucket into Pods for read-heavy, region-portable object storage." -tag: "NEW" +description: "Mount your own S3-compatible bucket directly into Runpod pods." --- -GlobalStore lets you register a bring-your-own S3-compatible bucket as an **ObjectStore** and mount one or more prefixes of it (**ObjectMounts**) into your Pods at container start. It is object-backed, read-heavy, and region-portable, so you can make the same objects available to Pods across regions without copying data into each one. - -GlobalStore is an early-access feature and may change while it's in active development. Today it's configured through the Runpod GraphQL API. See [Early access](/get-started/early-access) to learn more. +GlobalStore is currently in early access. [Contact support](https://www.runpod.io/contact) to enable it for your account. -## How GlobalStore works +GlobalStore lets you attach your own S3-compatible object storage bucket to Runpod pods. Files in your bucket are accessible inside the container as a mounted directory, without needing to bake them into a Docker image or copy them at startup. + +GlobalStore is designed for **read-heavy, object-backed workloads** — primarily model serving and inference. It is not a replacement for [Network Volumes](/storage/network-volumes) or high-performance distributed file storage. + +--- + +## How it works -An ObjectStore is a registered reference to your external S3-compatible bucket. It records the endpoint URL, bucket name, credentials, and the regions in which the bucket is eligible to be used. +GlobalStore uses two resources that work together: + +**ObjectStore** is a registered S3-compatible bucket. You provide Runpod with your bucket credentials once, and Runpod stores them securely. Your credentials are never logged or returned on user-facing API channels. + +**ObjectMount** is a configuration that attaches an ObjectStore to a specific pod at a specific path. When you create a pod with an ObjectMount, Runpod mounts the bucket (or a prefix within it) at the path you specify. Files appear in the container as a local directory. + +A single pod can have multiple ObjectMounts, as long as each mount uses a unique path. + +--- -An ObjectMount attaches a prefix of that bucket (a grouping of object keys, similar to a folder path) into a Pod at a chosen mount path. The mount is established when the container starts, so the objects under that prefix are available to your application as soon as the Pod is running. +## Quickstart -GlobalStore is distinct from the [S3-compatible API](/storage/s3-api), which exposes your Runpod network volumes over an S3 endpoint. GlobalStore instead mounts your own external S3-compatible bucket into Pods. +### Step 1: Register an ObjectStore -## When to use GlobalStore +You will need the following from your S3-compatible storage provider: -Today, you attach ObjectMounts to Pods; Serverless worker support isn't available. +- **Endpoint URL** — the provider's S3-compatible API endpoint +- **Bucket name** — the bucket to mount +- **Access key** and **secret key** — credentials with read (and optionally write) access to the bucket -GlobalStore is built for read-heavy workloads that read the same objects repeatedly or across regions, such as: +{/* [CONFIRM: Console path for registering an ObjectStore. Is it Storage > GlobalStore > Add ObjectStore, or a different location?] */} -- Serving models. -- Reading inference artifacts. -- Distributing model weights, LoRAs, or configuration read-only across regions. +To register an ObjectStore in the Runpod console: -## When not to use GlobalStore +1. Navigate to **Storage** in the left sidebar. +2. Select **GlobalStore** and click **Add ObjectStore**. +3. Enter a name for the ObjectStore, then fill in your endpoint URL, bucket name, access key, and secret key. +4. Click **Save**. Runpod validates your credentials and stores the ObjectStore. - -GlobalStore is not a replacement for [network volumes](/storage/network-volumes), Runpod's regional, high-performance block and file storage. For latency-sensitive or write-heavy workloads, use a network volume or [high-performance storage](/storage/high-performance-storage) instead. - +Note the **ObjectStore ID** — you will need it when creating a pod. -GlobalStore does not support the following workloads: +### Step 2: Create a pod with an ObjectMount -- High-throughput training. -- POSIX filesystem semantics. -- Active-active concurrent writes. +When creating a pod, add one or more ObjectMounts to specify which bucket to mount and where to mount it inside the container. -Object storage doesn't behave like a POSIX filesystem, so applications that expect local-filesystem behavior aren't a good fit for GlobalStore. +{/* [CONFIRM: UI flow for attaching an ObjectMount during pod creation. Does it appear as an "Add ObjectMount" section in the pod creation form?] */} + +1. Open the [Pods page](https://console.runpod.io/pods) and click **+ Deploy**. +2. Configure your pod (GPU, image, disk). +3. In the **Storage** section, click **Add ObjectMount**. +4. Select your ObjectStore, enter a mount path (for example, `/mnt/models`), and optionally provide a prefix to mount only a subdirectory of the bucket. +5. Toggle **Read-only** if the pod should not write to the bucket. +6. Deploy the pod. + +### Step 3: Access your files + +Once the pod is running, your bucket contents are available at the mount path you configured. Mount status transitions from `pending` to `mounting` to `ready` — wait until the status is `ready` before your workload tries to read files. + +```python +import os + +# If mounted at /mnt/models +model_path = "/mnt/models/your-model.safetensors" +print(os.path.exists(model_path)) # True once mount is ready +``` + +--- ## Supported providers -GlobalStore is tested with Tigris and Cloudflare R2. Other S3-compatible providers are untested and not supported. +GlobalStore works with **Tigris** and **Cloudflare R2**. These providers are tested and supported. + +Other S3-compatible providers may work but are not tested and are not officially supported. If you use an unsupported provider and encounter issues, Runpod cannot guarantee compatibility. + +### Tigris -## Regional availability +[Tigris](https://www.tigrisdata.com/) is a globally distributed S3-compatible object store. It is the recommended provider for GlobalStore workloads because of its low-latency access patterns and compatibility with Runpod's infrastructure. -When you register an ObjectStore, you declare the regions in which it is eligible to be used. GlobalStore is available only in supported regions, and availability expands over time. To confirm whether GlobalStore is available in the regions you need, check the eligible regions when you register an ObjectStore, or contact [Runpod support](https://www.runpod.io/contact). +To get your Tigris credentials: -## Read and write behavior +1. Create a bucket in the [Tigris console](https://console.tigrisdata.com/). +2. Generate an access key with read (or read/write) permissions scoped to that bucket. +3. Use `https://fly.storage.tigris.dev` as your endpoint URL. -Mounts are typically read-only, which matches GlobalStore's read-heavy design. +### Cloudflare R2 -The prefix a mount points at is subject to a simple rule: a read-only mount that points at an empty prefix fails, because there are no objects to read. An empty prefix with read-write access is allowed, and files are created under that prefix on write. +[Cloudflare R2](https://www.cloudflare.com/developer-platform/products/r2/) is an S3-compatible object store with no egress fees. It is supported for GlobalStore workloads. -## Credentials and security +To get your R2 credentials: + +1. Create a bucket in the [Cloudflare dashboard](https://dash.cloudflare.com/). +2. Navigate to **R2 > Manage API tokens** and generate a token with **Object Read** (or **Object Read & Write**) permissions for the bucket. +3. Use your account's S3 API endpoint as the endpoint URL: `https://.r2.cloudflarestorage.com` + +--- + +## Recommended workloads + +GlobalStore is well-suited for workloads that primarily read large files from object storage and do not require POSIX file system semantics or high-throughput concurrent writes. + +**Model serving and inference** — load model weights, tokenizer files, and configuration from a central bucket at pod startup. This avoids baking large files into your Docker image and lets you update model files without rebuilding the image. + +**Inference artifact reads** — serve LoRA adapters, prompt templates, embedding indices, or other read-heavy assets that are shared across multiple pods. + +**Configuration and script distribution** — mount read-only configuration files, shell scripts, or small datasets that need to be consistent across a fleet of pods. + +--- + +## Limitations + +GlobalStore is an object-backed mount, not a POSIX file system. It is not a replacement for [Network Volumes](/storage/network-volumes) or high-performance distributed file storage (such as VAST or MFS). Before using GlobalStore, review the following limitations. + +**Not suitable for high-throughput training writes.** Writing large volumes of data (checkpoints, logs, activations) to an object-backed mount during training is not supported. Use a Network Volume for training workloads that write frequently. + +**No POSIX semantics.** GlobalStore does not support file locking, atomic rename, hard links, or other POSIX operations. Applications that depend on POSIX behavior may fail or produce unexpected results. + +**No active-active writes.** Multiple pods writing to the same bucket prefix concurrently can cause data corruption or overwrite conflicts. If you need shared mutable storage across pods, use a Network Volume. + +**Object storage consistency model.** Reads reflect the state of the bucket at mount time. If you update files in the bucket after the pod starts, those updates may not be immediately visible inside the container. + +**Mount readiness.** The mount transitions through `pending → mounting → ready` states at pod startup. Do not attempt to read files until the mount status is `ready`. + +--- -Your bucket credentials are encrypted at rest. The secret is write-only: the API never returns it after you submit it. Credentials are injected into the mount process through its environment and are never written to disk. +## Security -An ObjectStore can only be used by the same account or organization that registered it. +Your ObjectStore credentials (access key and secret key) are stored encrypted and are only transmitted to the machine running your pod via a secure host-only channel. Credentials are never returned on user-facing API responses and are never logged. -## Next steps +Runpod recommends scoping your credentials to the minimum required permissions: - - - Register an ObjectStore and mount it into a Pod using the GraphQL API. - - - Learn about Runpod's regional, high-performance storage. - - +- Use **read-only** credentials whenever the pod does not need to write to the bucket. +- Scope credentials to a single bucket rather than your entire storage account. +- Rotate credentials periodically and update your ObjectStore configuration accordingly. From 1f0e3779b4a5d5d06de1b25fbf46ac9c2c26cced Mon Sep 17 00:00:00 2001 From: lgunreddi Date: Mon, 3 Aug 2026 11:04:14 -0400 Subject: [PATCH 08/12] Delete storage/globalstore-quickstart.mdx --- storage/globalstore-quickstart.mdx | 148 ----------------------------- 1 file changed, 148 deletions(-) delete mode 100644 storage/globalstore-quickstart.mdx diff --git a/storage/globalstore-quickstart.mdx b/storage/globalstore-quickstart.mdx deleted file mode 100644 index 38fa76ff3..000000000 --- a/storage/globalstore-quickstart.mdx +++ /dev/null @@ -1,148 +0,0 @@ ---- -title: "GlobalStore quickstart" -sidebarTitle: "GlobalStore quickstart" -description: "Register an ObjectStore and mount it into a Pod using the Runpod GraphQL API." -tag: "NEW" ---- -This quickstart walks you through registering an ObjectStore that references your S3-compatible bucket, then mounting a prefix of it into a Pod. - -This quickstart uses the Runpod GraphQL API to register an ObjectStore and mount it into a Pod. See [GlobalStore](/storage/globalstore) for the concepts behind ObjectStores and ObjectMounts. New to the Runpod GraphQL API? See the [GraphQL API overview](/sdks/graphql/configurations). - -## Requirements -- Access to the GlobalStore early access feature. Access is gated, so if GlobalStore isn't enabled for your account, contact Runpod to request it. -- A Runpod API key ([API keys](/get-started/api-keys)). -- An existing S3-compatible bucket on Tigris or Cloudflare R2, along with its endpoint URL, bucket name, access key, and secret. -## Register an ObjectStore - - -Call the `createObjectStore` mutation with your bucket details. Pass the eligible regions in which the ObjectStore can be used. - - -```bash -curl --request POST \ - --header 'content-type: application/json' \ - --url 'https://api.runpod.io/graphql?api_key=${YOUR_API_KEY}' \ - --data '{"query": "mutation { createObjectStore( input: { name: \"my-object-store\", endpointUrl: \"https://fly.storage.tigris.dev\", bucketName: \"my-bucket\", accessKey: \"YOUR_ACCESS_KEY\", secretKey: \"YOUR_SECRET_KEY\", eligibleRegions: [\"US-CA-2\"] } ) { id name } }"}' -``` - - -```graphql -mutation { - createObjectStore( - input: { - name: "my-object-store" - endpointUrl: "https://fly.storage.tigris.dev" - bucketName: "my-bucket" - accessKey: "YOUR_ACCESS_KEY" - secretKey: "YOUR_SECRET_KEY" - eligibleRegions: ["US-CA-2"] - } - ) { - id - name - } -} -``` - - -```json -{ - "data": { - "createObjectStore": { - "id": "obj_abc123", - "name": "my-object-store" - } - } -} -``` - - - - -The returned `id` is the `objectStoreId` you'll use when mounting the ObjectStore into a Pod. The secret you passed in `secretKey` is write-only and is never returned by the API, so store it securely on your side if you need it again. - - -## Mount an ObjectStore into a Pod -You attach ObjectMounts when you create a Pod by passing an `objectMounts` array to the Pod-create input. Each entry is shaped `{ objectStoreId, prefix, readOnly, mountPath }`. -The example below shows `objectMounts` as an addition to the standard `podFindAndDeployOnDemand` input. For the full Pod-create flow, see [Manage Pods](/sdks/graphql/manage-pods). -```graphql -mutation { - podFindAndDeployOnDemand( - input: { - cloudType: ALL - gpuCount: 1 - volumeInGb: 40 - containerDiskInGb: 40 - gpuTypeId: "NVIDIA RTX A6000" - name: "GlobalStore Pod" - imageName: "runpod/pytorch" - objectMounts: [ - { - objectStoreId: "YOUR_OBJECT_STORE_ID" - prefix: "models/" - readOnly: true - mountPath: "/mnt/models" - } - ] - } - ) { - id - imageName - } -} -``` -Keep these rules in mind: -- Each `mountPath` must be unique within a Pod. -- The referenced ObjectStore must belong to your account or organization. -- Mounts are typically read-only. - -Today you attach ObjectMounts through the GraphQL API, as shown above. - -## Check mount status -After the Pod starts, each ObjectMount moves through a short lifecycle: -- `pending`: the mount is queued and hasn't started yet. -- `mounting`: the mount is being established. -- `ready`: the prefix is mounted and available to your application. -- `failed`: the mount couldn't be established. See [Troubleshoot failed mounts](#troubleshoot-failed-mounts). -## Troubleshoot failed mounts -When a mount reports `failed`, it includes a failure reason: -| Failure reason | What it means | -|----------------|---------------| -| `credentials` | The access key or secret was rejected. Resupply valid credentials with `updateObjectStore`. | -| `bucket_access` | The bucket or endpoint couldn't be reached, or permissions are insufficient. Verify the endpoint URL, bucket name, and that the credentials grant access. | -| `prefix_empty` | A read-only mount points at a prefix that contains no objects. Confirm objects exist under the prefix, or set `readOnly: false` if the prefix is intentionally empty. | -| `fuse_crash` | The mount process failed. Retry, and contact support if it persists. | -## Manage ObjectStores -Use `updateObjectStore` to change an ObjectStore's `name` or rotate its credentials. To rotate credentials, supply a new `accessKey` and `secretKey`; the secret stays write-only and is never returned. -```graphql -mutation { - updateObjectStore( - input: { - id: "YOUR_OBJECT_STORE_ID" - name: "my-renamed-store" - accessKey: "NEW_ACCESS_KEY" - secretKey: "NEW_SECRET_KEY" - } - ) { - id - name - } -} -``` -Use `deleteObjectStore` to remove an ObjectStore you no longer need. -```graphql -mutation { - deleteObjectStore(input: { id: "YOUR_OBJECT_STORE_ID" }) { - id - } -} -``` -## Next steps - - - Review the concepts behind ObjectStores and ObjectMounts. - - - Learn about Runpod's regional, high-performance storage. - - From e77a17a04a74fb1cf6b968ef7b17f8b178987ba3 Mon Sep 17 00:00:00 2001 From: lgunreddi Date: Mon, 3 Aug 2026 11:05:32 -0400 Subject: [PATCH 09/12] Update docs.json --- docs.json | 1 - 1 file changed, 1 deletion(-) diff --git a/docs.json b/docs.json index b5a609c78..522ac6a7a 100644 --- a/docs.json +++ b/docs.json @@ -232,7 +232,6 @@ "storage/high-performance-storage", "storage/s3-api", "storage/globalstore", - "storage/globalstore-quickstart" ] }, { From b9b611168ecfa09f6801b622b71bc641c2f1a930 Mon Sep 17 00:00:00 2001 From: lgunreddi Date: Mon, 3 Aug 2026 11:23:02 -0400 Subject: [PATCH 10/12] Update docs.json --- docs.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs.json b/docs.json index 83598c405..c8181cb18 100644 --- a/docs.json +++ b/docs.json @@ -231,7 +231,7 @@ "storage/network-volumes", "storage/high-performance-storage", "storage/s3-api", - "storage/globalstore", + "storage/globalstore" ] }, { From 3a6aac1b3320ca43534718366a67f27580bc638f Mon Sep 17 00:00:00 2001 From: lgunreddi Date: Mon, 3 Aug 2026 14:56:05 -0400 Subject: [PATCH 11/12] Update globalstore.mdx --- storage/globalstore.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/storage/globalstore.mdx b/storage/globalstore.mdx index e227ca5d9..8f92bc7a6 100644 --- a/storage/globalstore.mdx +++ b/storage/globalstore.mdx @@ -2,6 +2,7 @@ title: "GlobalStore" sidebarTitle: "GlobalStore" description: "Mount your own S3-compatible bucket directly into Runpod pods." +tag: "Beta" --- From 820c56859a5fc84bf0e1435ea4756ccf0fef62c2 Mon Sep 17 00:00:00 2001 From: lgunreddi Date: Mon, 3 Aug 2026 14:58:32 -0400 Subject: [PATCH 12/12] Update globalstore.mdx --- storage/globalstore.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/storage/globalstore.mdx b/storage/globalstore.mdx index 8f92bc7a6..c236567e9 100644 --- a/storage/globalstore.mdx +++ b/storage/globalstore.mdx @@ -2,7 +2,7 @@ title: "GlobalStore" sidebarTitle: "GlobalStore" description: "Mount your own S3-compatible bucket directly into Runpod pods." -tag: "Beta" +tag: "BETA" ---