Give Feedback

volume

Generated on 10 Jul 2025 from digitalocean.cloud version v1.2.1

Synopsis

Creates or deletes volumes. View the create API documentation at https://docs.digitalocean.com/reference/api/api-reference/#operation/volumes_create. View the delete API documentation at https://docs.digitalocean.com/reference/api/api-reference/#operation/volumes_delete_byName. Optionally, a filesystem_type attribute may be provided in order to automatically format the volume’s filesystem. Pre-formatted volumes are automatically mounted when attached to Ubuntu, Debian, Fedora, Fedora Atomic, and CentOS Droplets created on or after April 26, 2018. Attaching pre-formatted volumes to Droplets without support for auto-mounting is not recommended.

Requirements

pydo >= 0.1.3
azure-core >= 1.26.1

Parameters

Parameter	Choices / Default	Description
`client_override_options` dict		Client override options (developer use). For example, can be used to override the DigitalOcean API endpoint for an internal test suite. If provided, these options will knock out existing options.
`description` str		An optional free-form text field to describe a block storage volume.
`filesystem_label` str		The label applied to the filesystem. Labels for ext4 type filesystems may contain 16 characters while labels for xfs type filesystems are limited to 12 characters. May only be used in conjunction with filesystem_type.
`filesystem_type` str	Choices: `ext4` `xfs`	The name of the filesystem type to be used on the volume. When provided, the volume will automatically be formatted to the specified filesystem type. Currently, the available options are `ext4` and `xfs`. Pre-formatted volumes are automatically mounted when attached to Ubuntu, Debian, Fedora, Fedora Atomic, and CentOS Droplets created on or after April 26, 2018. Attaching pre-formatted volumes to other Droplets is not recommended.
`module_override_options` dict		Module override options (developer use). Can be used to override module options to support experimental or future options. If provided, these options will knock out existing options.
`name` str / required		A human-readable name for the block storage volume. Must be lowercase and be composed only of numbers, letters and “-”, up to a limit of 64 characters. The name must begin with a letter.
`region` str / required		The slug identifier for the region where the resource will initially be available.
`size_gigabytes` int		The size of the block storage volume in GiB `1024^3`.
`snapshot_id` str		The unique identifier for the volume snapshot from which to create the volume.
`state` str	Choices: `present` (default) `absent`	State of the resource, `present` to create, `absent` to destroy.
`tags` list / elements=str		A flat array of tag names as strings to be applied to the resource. Tag names may be for either existing or new tags.
`timeout` int	Default: `300`	Polling timeout in seconds.
`token` str		DigitalOcean API token. There are several environment variables which can be used to provide this value. `DIGITALOCEAN_ACCESS_TOKEN`, `DIGITALOCEAN_TOKEN`, `DO_API_TOKEN`, `DO_API_KEY`, `DO_OAUTH_TOKEN` and `OAUTH_TOKEN`

Examples

- name: Create DigitalOcean volume
  digitalocean.cloud.volume:
    token: "{{ token }}"
    state: present
    name: test-vol-delete-1
    region: nyc3
    size_gigabytes: 1

- name: Delete DigitalOcean volume
  digitalocean.cloud.volume:
    token: "{{ token }}"
    state: absent
    name: test-vol-delete-1
    region: nyc3

Return Values

Key Returned Description

Key	Returned	Description
`error` dict	failure	DigitalOcean API error. Sample: `{ "Message": "Informational error message.", "Reason": "Unauthorized", "Status Code": 401 }`
`msg` str	always	DigitalOcean volume information. Sample: `[ "Created volume test-vol in nyc3", "Deleted volume test-vol in nyc3" ]`
`volume` dict	always	DigitalOcean volume information. Sample: `{ "created_at": "2022-11-24T19:23:01Z", "description": "", "droplet_ids": null, "filesystem_label": "", "filesystem_type": "", "id": "698d7221-6c2d-11ed-93f9-0a58ac14790c", "name": "test-vol", "region": { "available": true, "features": [ "backups", "ipv6", "metadata", "install_agent", "storage", "image_transfer" ], "name": "New York 3", "sizes": [ "s-1vcpu-1gb", "s-1vcpu-1gb-amd", "s-1vcpu-1gb-intel", "..." ], "slug": "nyc3" }, "size_gigabytes": 1, "tags": null }`

error
dict

failure

DigitalOcean API error.
Sample:

{
  "Message": "Informational error message.",
  "Reason": "Unauthorized",
  "Status Code": 401
}

msg
str

always

DigitalOcean volume information.
Sample:

[
  "Created volume test-vol in nyc3",
  "Deleted volume test-vol in nyc3"
]

volume
dict