# Create and attach a volume

Create a block storage volume in a zone, attach it to an instance there, detach it, and delete it.

A volume lives in one zone and attaches to one instance in that zone at a time. It is encrypted
unless you turn that off (see [Encrypted volumes](encrypted-volumes.md)). Replace the ids with your
own.

**Important:**
A volume is billed as volume storage for its full size while it is **Creating**, **Available** or
**In use**, attached or not, until you delete it. A volume in **Error** is not billed.

## Prerequisites

- Permission for `ec2:CreateVolume`, `ec2:AttachVolume`, `ec2:DetachVolume` and
  `ec2:DeleteVolume`, as the step needs. Choosing your own KMS key needs `kms:Encrypt` on it.
- In the console, also `ec2:DescribeVolumes` to open **Volumes** (without it the page says "Access
  denied").
- Room in the **Volumes** (`ec2.volumes`) and **Volume storage** (`ec2.volume-storage`, GiB)
  quotas, both per region. A full quota is refused with `409` "Quota exceeded: …".

## Create a volume

**Console**
1. Open **Compute**, then **Volumes**, and choose **Create volume**.
2. For **Name**, enter data.
3. For **Size (GiB)**, enter a size from 10 to 10 000.
4. For **Region**, choose the region.
5. (Optional) For **Availability zone**, choose the zone. The region's first zone is preselected.
6. Keep **Encrypt the volume** selected, or clear it for a plain volume.
7. (Optional) For **Encryption key**, choose one of your KMS keys instead of **Platform-managed key
   (default)**.
8. Choose **Create volume**.

**CLI**
```sh
dcloud ec2 volumes create --name data --size-gib 50 --region-id de1 --availability-zone-id de1a
```

**API**
```http
POST /ec2/api/volumes
{ "name": "data", "sizeGib": 50, "regionId": "de1", "availabilityZoneId": "de1a" }
```

**Terraform**
```hcl
resource "dcloud_volume" "data" {
  name                 = "data"
  size_gib             = 50
  availability_zone_id = "de1a"
}
```

Without a zone, the volume is in `de1a`. A request without your organization's required tag keys is
refused with `400` "Missing required tags: …"; a KMS key on an unencrypted volume with `400` "A KMS
key only applies to an encrypted volume". The answer is `201` with the volume (`vol-…`), `creating`
until the provider has made it, then `available`. If the provider refuses, the request answers
`502` and the volume is left in `error`.

## Attach it

**Console**
1. On **Volumes**, open the volume's actions menu and choose **Attach to instance**. The volume
   must be **Available**.
2. Choose the instance. Only instances in the volume's region are listed.
3. Choose **Attach**.

**CLI**
```sh
dcloud ec2 volumes attach vol-1a2b3c4d --instance-id i-3f9a2c07
```

**API**
```http
POST /ec2/api/volumes/vol-1a2b3c4d/attach
{ "instanceId": "i-3f9a2c07" }
```

**Terraform**
```hcl
resource "dcloud_volume_attachment" "data" {
  volume_id   = dcloud_volume.data.id
  instance_id = dcloud_instance.web.id
}
```

The volume becomes **In use**. Its side panel shows the **Device on the instance**: a plain volume
appears as `/dev/disk/by-id/scsi-0HC_Volume_<number>`, an encrypted one, once the instance has
opened it, as `/dev/mapper/ews-vol-<number>` (the same number). Format it once and mount it on the
machine (for an encrypted volume, use the `/dev/mapper/…` path):

```sh
sudo mkfs.ext4 /dev/disk/by-id/scsi-0HC_Volume_12345678
sudo mkdir -p /data && sudo mount /dev/disk/by-id/scsi-0HC_Volume_12345678 /data
```

An attach is refused with `409` when:

- the instance is in another zone ("… is in … and … is in …. A volume attaches only to an instance
  in its own availability zone; …") or another region ("A volume can only be attached in its own
  region");
- the volume is already attached ("Already attached to …; detach it first");
- the volume never reached the provider or is in `error` ("The volume was never created at the
  provider");
- the instance has no machine yet, or is terminated ("The instance has no machine to attach to");
- the volume is encrypted and the instance was launched without the volume helper ("… was launched
  without the volume helper, so it cannot open an encrypted volume. …"; see
  [Encrypted volumes](encrypted-volumes.md));
- a snapshot of the volume is in progress ("Snapshot … of this volume is in progress; try again when
  it is done") or it is being restored ("This volume is being restored from …; wait until it is
  available");
- the volume is a Kubernetes cluster's PersistentVolume ("This volume is PersistentVolume … of the
  Kubernetes cluster …. Manage it through its PersistentVolumeClaim instead.").

## Detach it

**Console**
1. Unmount the filesystem on the machine (for an encrypted volume, then run
   `sudo cryptsetup close ews-vol-<number>`).
2. On **Volumes**, open the volume's actions menu and choose **Detach**.
3. In the confirmation dialog, choose **Detach**.

**CLI**
```sh
dcloud ec2 volumes detach vol-1a2b3c4d
```

**API**
```http
POST /ec2/api/volumes/vol-1a2b3c4d/detach
```

**Terraform**
Remove the `dcloud_volume_attachment` resource and run `terraform apply`.

The data stays; the volume is **Available** again. A volume that is not attached is refused with
`409` "The volume is not attached"; a snapshot or restore in progress is refused as for an attach.

## Delete it

**Console**
1. On **Volumes**, open the volume's actions menu and choose **Delete**. An attached volume must
   be detached first.
2. In the confirmation dialog, enter the volume name.
3. Choose **Delete volume**.

**CLI**
```sh
dcloud ec2 volumes delete vol-1a2b3c4d
```

**API**
```http
DELETE /ec2/api/volumes/vol-1a2b3c4d
```

**Terraform**
Remove the `dcloud_volume` resource and run `terraform apply`.

The volume and its data are deleted, and billing for it stops; its snapshots stay. For an encrypted
volume, its key is destroyed too. The delete is refused with `409` while the volume is attached
("Attached to …; detach it first") or a snapshot or restore of it is in progress.

## Result

The volume's row, name and state (**Creating**, **Restoring n %**, **Available**, **In use**,
**Error**) are the same on **Volumes**, on the instance's **Storage** card and in
`GET /ec2/api/volumes`. **Volumes** also lists the data volumes of managed databases; they belong
to their service and carry no actions there.

## Related

- [Grow a volume](grow-a-volume.md)
- [Snapshot a volume](snapshot-a-volume.md)
- `ec2.volumes.create` · `dcloud ec2 volumes attach` · `dcloud_volume` · `dcloud_volume_attachment`
