# Attach and detach volumes

Attach an available volume to a running or stopped instance, choose its guest device name, and detach it again to use elsewhere.

Attach a volume to give an instance another disk. Detach it to move the disk and its data to another instance. The instance can be running or stopped.

## Before you begin [#before-you-begin]

<BeforeYouBegin>

- An instance in `RUNNING` or `STOPPED`.
- A volume in `AVAILABLE` status, in the same project and availability zone as the instance. See [Create a volume](/docs/storage/volumes/create).
- The `origin` CLI, signed in. See [CLI access](/docs/platform/access/cli).

</BeforeYouBegin>

## Attach a volume [#attach-a-volume]

1. Attach the volume:

   ```sh
   origin compute attach-volume \
     --instance-urn <instance-urn> \
     --volume-urn <volume-urn>
   ```

   To choose the guest device name, add `--device-name`, for example `--device-name vdb`. Names run from `vda` to `vdz`, and `vdc` is reserved by the platform. Omitted, the platform assigns the first free name.

1. Check the attachment in the instance’s `volumeAttachments`:

   ```sh
   origin compute get-instance --instance-urn <instance-urn>
   ```

   - On a stopped instance, the attachment reads `ATTACHED` right away and the disk appears in the guest at the next start.
   - On a running instance, the disk is added live. The attachment reads `ATTACHING`, then `ATTACHED` once the guest sees the device. If the device can’t be added, it reads `FAILED` and the volume is released.

1. Verify inside the guest that the disk is there, under the attachment’s `deviceName`:

   ```sh
   lsblk
   ```

   A new volume has no file system. Create one before you mount it.

## Detach a volume [#detach-a-volume]

1. Unmount the file system inside the guest if the instance is running.
1. Detach the volume:

   ```sh
   origin compute detach-volume \
     --instance-urn <instance-urn> \
     --volume-urn <volume-urn>
   ```

   On a running instance the attachment reads `DETACHING` until the guest releases the device. If the guest doesn’t release it, the attachment returns to `ATTACHED` and the volume stays attached.

1. Verify that the volume reads `AVAILABLE`:

   ```sh
   origin storage get-volume --volume-urn <volume-urn>
   ```

   The attachment stays in the instance’s `volumeAttachments` history as `DETACHED`, with its volume reference cleared.

You can’t detach an instance’s root disk.

## Using the API [#using-the-api]

The `attachVolume` and `detachVolume` mutations return the attachment:

```graphql
mutation {
  compute {
    attachVolume(input: {
      instanceUrn: "<instance-urn>"
      volumeUrn: "<volume-urn>"
      deviceName: "vdb"
    }) {
      urn
      deviceName
      status
    }
  }
}
```

## If this fails [#if-this-fails]

An attach is refused when the instance is neither running nor stopped, when the volume isn’t `AVAILABLE`, or when the device name you asked for is already taken. To find which instance holds a volume that reads `INUSE`, see [Find the instance that holds a volume](/docs/storage/volumes/find-instance).

## Related [#related]

- [`attach-volume` reference](/docs/compute/reference/cli#attach-volume)
- [`detach-volume` reference](/docs/compute/reference/cli#detach-volume)
- [Instance storage](/docs/compute/instance-storage)