GlobalStore quickstart

Register an ObjectStore and mount it into a Pod using the Runpod GraphQL API.

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 for the concepts behind ObjectStores and ObjectMounts. New to the Runpod GraphQL API? See the GraphQL API overview.

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).
• An existing S3-compatible bucket on Tigris or Cloudflare R2, along with its endpoint URL, bucket name, access key, and secret.

Register an ObjectStore

1. Create the ObjectStore

   Call the createObjectStore mutation with your bucket details. Pass the eligible regions in which the ObjectStore can be used.

   cURL

   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
     }
   }
   

   Output

   {
     "data": {
       "createObjectStore": {
         "id": "obj_abc123",
         "name": "my-object-store"
       }
     }
   }
   
2. Save the ObjectStore ID

   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.

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

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.

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.

mutation {
  deleteObjectStore(input: { id: "YOUR_OBJECT_STORE_ID" }) {
    id
  }
}

Next steps

GlobalStore

Review the concepts behind ObjectStores and ObjectMounts.

Network volumes

Learn about Runpod’s regional, high-performance storage.