> ## Documentation Index
> Fetch the complete documentation index at: https://runpod-b18f5ded-lg-global-store-477.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Note>
  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).
</Note>

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

<Steps>
  <Step title="Create the ObjectStore">
    Call the `createObjectStore` mutation with your bucket details. Pass the eligible regions in which the ObjectStore can be used.

    <Tabs>
      <Tab title="cURL">
        ```bash theme={null}
        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 } }"}'
        ```
      </Tab>

      <Tab title="GraphQL">
        ```graphql theme={null}
        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
          }
        }
        ```
      </Tab>

      <Tab title="Output">
        ```json theme={null}
        {
          "data": {
            "createObjectStore": {
              "id": "obj_abc123",
              "name": "my-object-store"
            }
          }
        }
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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 theme={null}
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.

<Note>
  Today you attach ObjectMounts through the GraphQL API, as shown above.
</Note>

## 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 theme={null}
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 theme={null}
mutation {
  deleteObjectStore(input: { id: "YOUR_OBJECT_STORE_ID" }) {
    id
  }
}
```

## Next steps

<CardGroup cols={2}>
  <Card title="GlobalStore" href="/storage/globalstore" icon="cloud" horizontal>
    Review the concepts behind ObjectStores and ObjectMounts.
  </Card>

  <Card title="Network volumes" href="/storage/network-volumes" icon="hard-drive" horizontal>
    Learn about Runpod's regional, high-performance storage.
  </Card>
</CardGroup>