From 139985422a9b71db1ec301bfb3fadd14cddb4c08 Mon Sep 17 00:00:00 2001 From: "promptless[bot]" Date: Tue, 28 Jul 2026 18:37:41 +0000 Subject: [PATCH] Add GlobalStore documentation (overview + quickstart) Document Runpod GlobalStore: register a bring-your-own S3-compatible bucket as an ObjectStore and mount prefixes (ObjectMounts) into Pods. Covers positioning (object-backed, read-heavy; not a network-volume replacement), supported providers (Tigris, Cloudflare R2), recommended and unsupported workloads, and a GraphQL API quickstart. Addresses Linear DOCS-477. --- docs.json | 4 +- storage/globalstore-quickstart.mdx | 178 +++++++++++++++++++++++++++++ storage/globalstore.mdx | 75 ++++++++++++ 3 files changed, 256 insertions(+), 1 deletion(-) create mode 100644 storage/globalstore-quickstart.mdx create mode 100644 storage/globalstore.mdx diff --git a/docs.json b/docs.json index e0a2e7388..b5a609c78 100644 --- a/docs.json +++ b/docs.json @@ -230,7 +230,9 @@ "pages": [ "storage/network-volumes", "storage/high-performance-storage", - "storage/s3-api" + "storage/s3-api", + "storage/globalstore", + "storage/globalstore-quickstart" ] }, { diff --git a/storage/globalstore-quickstart.mdx b/storage/globalstore-quickstart.mdx new file mode 100644 index 000000000..e45cc159c --- /dev/null +++ b/storage/globalstore-quickstart.mdx @@ -0,0 +1,178 @@ +--- +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. + + 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. + +