> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tensorpool.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Storage

> Persistent storage for TensorPool clusters

Storage volumes are high-performance shared volumes designed for distributed training on multi-node clusters.

* **High aggregate performance**: Up to 300 GB/s aggregate read throughput, 150 GB/s aggregate write throughput, 1.5M read IOPS, 750k write IOPS
* **POSIX compliant**: Full filesystem semantics
* **Fixed volume size**: Volume size must be defined at creation and can be increased at any time. See [pricing](/resources/pricing#storage-volumes) for details.
* **Ideal for**: datasets for distributed training, storing model checkpoints

**Expected single client performance:**

| Metric            | Performance |
| ----------------- | ----------- |
| Read Throughput   | 11,000 MB/s |
| Write Throughput  | 5,000 MB/s  |
| Read IOPS         | 10,000      |
| Write IOPS        | 4,500       |
| Avg Read Latency  | 2ms         |
| Avg Write Latency | 6ms         |
| p99 Read Latency  | 8ms         |
| p99 Write Latency | 20ms        |

<Note>
  Shared storage volumes can only be attached to multi-node GPU clusters and CPU instances. For more flexible storage, use [TensorPool Object Storage](/features/object-storage) (S3-compatible).
</Note>

***

## Quick Start

```bash theme={null}
# 1. Create a 1TB storage volume
tp storage create 1000 --name dataset

# 2. Attach the volume to a cluster
tp cluster attach <cluster_id> <storage_id>

# 3. SSH into your cluster and access the data
tp ssh <instance_id>
cd /mnt/<storage_id>

# 4. When done, detach the volume
tp cluster detach <cluster_id> <storage_id>

# 5. Destroy the volume when no longer needed
tp storage destroy <storage_id>
```

## Core Commands

* `tp storage create <size_gb>` - Create a new storage volume
* `tp storage list` - View all your storage volumes
* `tp cluster attach <cluster_id> <storage_id>` - Attach storage to a cluster
* `tp cluster detach <cluster_id> <storage_id>` - Detach storage from a cluster
* `tp storage destroy <storage_id>` - Delete a storage volume

## Creating Storage Volumes

Create storage volumes by specifying a size in GB:

```bash theme={null}
# Create a 500GB storage volume with a custom name
tp storage create 500 --name training-data

# Create a 1TB volume with deletion protection
tp storage create 1000 --name important-data --deletion-protection
```

## Attaching and Detaching

Attach storage volumes to a cluster:

```bash theme={null}
tp cluster attach <cluster_id> <storage_id>
```

Detach when you're done:

```bash theme={null}
tp cluster detach <cluster_id> <storage_id>
```

## Storage Locations

When you attach a storage volume to your cluster, it will be mounted on each instance at:

```
/mnt/<storage_id>
```

***

## Storage Statuses

Storage volumes progress through various statuses throughout their lifecycle:

```mermaid theme={null}
stateDiagram-v2
    [*] --> PENDING: Storage requested
    PENDING --> PROVISIONING: Resources allocated
    PROVISIONING --> READY: Provisioning complete
    READY --> ATTACHING: Attach requested
    ATTACHING --> READY: Attach complete
    READY --> DETACHING: Detach requested
    DETACHING --> READY: Detach complete
    READY --> DESTROYING: User destroys storage
    DESTROYING --> DESTROYED: Cleanup complete
    PENDING --> FAILED: No capacity
    PROVISIONING --> FAILED: Provisioning error
    ATTACHING --> FAILED: Attach error
    DETACHING --> FAILED: Detach error
    DESTROYED --> [*]
    FAILED --> [*]
```

| Status           | Description                                                                       |
| ---------------- | --------------------------------------------------------------------------------- |
| **PENDING**      | Storage creation request has been submitted and is being queued for provisioning. |
| **PROVISIONING** | Storage has been allocated and is being provisioned.                              |
| **READY**        | Storage is ready for use.                                                         |
| **ATTACHING**    | Storage is being attached to a cluster.                                           |
| **DETACHING**    | Storage is being detached from a cluster.                                         |
| **DESTROYING**   | Storage deletion in progress, resources are being deallocated.                    |
| **DESTROYED**    | Storage has been successfully deleted.                                            |
| **FAILED**       | System-level problem (e.g., no capacity, hardware failure, etc.).                 |

## Best Practices

* **Data persistence**: Use storage volumes for important data that needs to persist across cluster lifecycles
* **Shared data**: Attach the same storage volume to multiple clusters to share data
* **Object storage for archives**: For cost-effective persistent storage without size limits, see [Object Storage](/features/object-storage)

## Next Steps

* Review [best practices](/guides/best-practices) for storage workflows
* See the [CLI reference](/cli/storage-commands) for detailed command options