For AI agents: The documentation index is at https://docs.digitalocean.com/llms.txt. Markdown versions of pages use the same URL with index.html.md in place of the HTML page (for example, append index.html.md to the directory path instead of opening the HTML document).

Usage

client.volume_actions.post_by_id(
    volume_id="7724db7c-e098-11e5-b522-000f53304e51",
    per_page=20,
    page=1,
    body={
        "type": "attach",
        "region": "nyc3",
        "droplet_id": 11612190,
        ...,
    },
)

Description

To initiate an action on a block storage volume by Id, send a POST request to ~/v2/volumes/$VOLUME_ID/actions. The body should contain the appropriate attributes for the respective action.

Attach a Block Storage Volume to a Droplet

Each volume may only be attached to a single Droplet. However, up to fifteen volumes may be attached to a Droplet at a time. Pre-formatted volumes will be automatically mounted to Ubuntu, Debian, Fedora, Fedora Atomic, and CentOS Droplets created on or after April 26, 2018 when attached. On older Droplets, additional configuration is required.

Remove a Block Storage Volume from a Droplet

Resize a Volume

Volumes may only be resized upwards. The maximum size for a volume is 16TiB.

Parameters

volume_id string required

The ID of the block storage volume.

per_page integer optional

Number of items returned per page

Min: 1

Max: 200

Default: 20

page integer optional

Which 'page' of paginated results to return.

Min: 1

Default: 1

type string required

The volume action to initiate.

One of: attach, detach, resize

region string optional

The slug identifier for the region where the resource will initially be available.

One of: ams1, ams2, ams3, blr1, fra1, lon1, nyc1, nyc2, nyc3, sfo1, sfo2, sfo3, sgp1, tor1, syd1

droplet_id integer optional

Example: 11612190

The unique identifier for the Droplet the volume will be attached or detached from.

tags array of strings or null optional

Example: ['base-image', 'prod']

A flat array of tag names as strings to be applied to the resource. Tag names may be for either existing or new tags.

Requires tag:create scope.

size_gigabytes integer optional

The new size of the block storage volume in GiB (1024^3).

Max: 16384

Request Sample

import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

req = {
  "type": "attach",
  "droplet_id": 11612190,
  "region": "nyc1",
  "tags": [
    "aninterestingtag"
  ]
}

resp = client.volume_actions.post_by_id(volume_id="7724db7c", body=req)

Response Example

{
  "action": {
    "id": 72531856,
    "status": "completed",
    "type": "attach_volume",
    "started_at": "2020-11-12T17:51:03Z",
    "completed_at": "2020-11-12T17:51:14Z",
    "resource_type": "volume",
    "region": {
      "name": "New York 1",
      "slug": "nyc1",
      "sizes": [
        "s-1vcpu-1gb",
        "s-1vcpu-2gb",
        "s-1vcpu-3gb",
        "s-2vcpu-2gb",
        "s-3vcpu-1gb",
        "s-2vcpu-4gb",
        "s-4vcpu-8gb",
        "s-6vcpu-16gb",
        "s-8vcpu-32gb",
        "s-12vcpu-48gb",
        "s-16vcpu-64gb",
        "s-20vcpu-96gb",
        "s-24vcpu-128gb",
        "s-32vcpu-192gb"
      ],
      "features": [
        "private_networking",
        "backups",
        "ipv6",
        "metadata"
      ],
      "available": true
    },
    "region_slug": "nyc1"
  }
}

More Information

See /v2/volumes/{volume_id}/actions in the API reference for additional detail on responses, headers, parameters, and more.