Attach a volume

post

https://api.linode.com/{apiVersion}/volumes/{volumeId}/attach

Attach a Block Storage volume to an existing Linode.

📘

The volume and its target Linode need to exist in the same region. You can run the List volumes and List Linodes operations and review the region for each.

There's a maximum number of volumes that can be attached to a single Linode configuration. This number varies, based on the Linode's plan, with higher plan types supporting more volumes. The maximum follows a formula of the Linode plan's total_ram / 1024, with a minimum of 8 and a total maximum of 64 volumes. Rescue configurations support a maximum of 8.

Permissions and scopes

To call this operation, you need permissions, based on the model you're using:

Identity and access permissions. Your user needs a role with these permissions. Learn more.
- Permissions: attach_volume
OAuth scopes. Your user needs these scopes assigned. Learn more.
- Scopes: volumes:read_write, linodes:read_write

CLI

linode-cli volumes attach 12345 \
  --linode_id 12346 \
  --config_id 23456

Learn more

Path Params

apiVersion

string

enum

required

Enum Call either the v4 URL, or v4beta for operations still in Beta.

Allowed:

volumeId

integer

required

The unique identifier for the target volume. Run the List volumes operation and store the id for the target volume as your volumeId.

Body Params

config_id

integer

The unique identifier assigned to the Linode configuration where you want to include this volume. Run the List configuration profiles operation and store the id for the target configuration.

📘

The configuration needs to belong to the Linode referenced by linode_id.

If you don't include this value, the API uses the last booted configuration.

linode_id

integer

required

The unique identifier assigned to the Linode where you want to attach the volume. Run the List Linodes operation and store the id for the target Linode.

persist_across_boots

boolean

Defaults to true

If set to false, the volume won't be attached to the Linode configuration. In this case, more than eight volumes may be attached to a Linode if a Linode has 16GB of RAM or more. The number of volumes you can attach is equal to the number of GB of RAM that the Linode has, up to a maximum of 64. If you set this to false, you can't include a config_id and only the linode_id should be passed.

📘
To use this object, the target linode_id needs to have a status of running. Run the List Linodes operation to check the status of each Linode.

Responses

Response body

object

created

date-time

Read-only When this volume was created.

encryption

string

enum

Read-only Whether encryption is enabled on this volume.

enabled disabled

filesystem_path

string

Read-only The full file system path for the volume, based on its label. The path is /dev/disk/by-id/scsi-0Linode_Volume_label.

hardware_type

string

enum

Read-only The storage type of this volume. This can be either hdd to emulate a hard disk drive for the volume, or nvme to emulate a non-volatile memory express solid state drive.

hdd nvme

integer

Read-only The unique identifier for the volume.

io_ready

boolean

Read-only Indicates whether the volume is successfully attached to a Linode and ready for read and write operations.

label

string

length between 1 and 32

Filterable The name of the volume. A label can be up to 32 characters long and contain alphanumeric characters, hyphens, and underscores. This value is also used in the volume's filesystem_path.

linode_id

integer | null

The unique identifier of the Linode this volume is attached to, if applicable.

linode_label

string | null

Read-only The name of the Linode this volume is attached to, if applicable.

locks

array of strings

Beta A resource lock applied to the Block Storage volume. You can optionally set up this lock to prevent you from inadvertently deleting the volume. Supported values here include:

cannot_delete. The volume itself can't be deleted. Any sub-resources assigned to it can be freely deleted. You need to unlock the volume by deleting its lock to delete the volume.
cannot_delete_with_subresources. The volume and various sub-resources assigned to it can't be deleted. For example, if a volume has a configuration profile interface assigned to it, this lock prevents you from deleting either of them. You need to unlock the resource (the volume) by deleting its lock. Then you can delete the volume and any of its sub-resources.
Empty. The volume doesn't have a resource lock configured. This is also empty when you clone a volume, because resource lock settings aren't carried to the cloned volume.

📘
This array appears for a volume only if you call this operation using the v4beta path parameter in the URL.

locks

region

string

The unique identifier for the region where the volume lives.

size

integer

≤ 10240

The volume's size, in gigabytes.

status

string

enum

Read-only The current status of the volume. This can be one of:

creating. The API is creating the volume and it's not ready for use.
active. The volume is online and ready for use.
resizing. The volume's capacity is being upgraded.
key_rotating. The volume's encryption keys are being rotated to new values. Requests to resize, delete, or clone a volume fail during encryption key rotation.

creating active resizing key_rotating

200The volume was attached to a Linode.

defaultSee Errors for the range of possible error response codes.