How to Create and Set Up Volumes for Use with Droplets

Volumes are network-based block devices that provide additional data storage for Droplets. You can move them between Droplets, create disk images of them, and resize them at any time.


To create and use a new volume with a Droplet, you need to create the volume itself, and then format and mount it to prepare it for use. Formatting and mounting is automatic by default for Droplets with supported operating systems, and you can choose to format and mount manually.

Create Volumes Using Automation

How to create a volume using the DigitalOcean CLI

To create a volume via the command-line, follow these steps:

  1. Install doctl, the DigitalOcean command-line tool.

  2. Create a personal access token, and save it for use with doctl.

  3. Use the token to grant doctl access to your DigitalOcean account.

                  doctl auth init
                
  4. Finally, create a volume with doctl compute volume create. The basic usage looks like this, but you'll want to read the usage docs for more details:

                  doctl compute volume create <volume-name> [flags]
                

    The following example creates a 4TiB volume named example-volume in the nyc1 region. The command also applies two tags to the volume

                       doctl compute volume create example-volume --region nyc1 --size 4TiB --tag frontend,backend
                    
How to create a volume using the DigitalOcean API

To create a volume using the DigitalOcean API, follow these steps:

  1. Create a personal access token, and save it for use with the API.

  2. Send a POST request to https://api.digitalocean.com/v2/volumes

    cURL

    To create a volume with cURL, call:

    
                    curl -X POST \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
      -d '{"size_gigabytes":10, "name": "example", "description": "Block store for examples", "region": "nyc1", "filesystem_type": "ext4", "filesystem_label": "example"}' \
      "https://api.digitalocean.com/v2/volumes"

    Go

    Go developers can use Godo, the official DigitalOcean V2 API client for Go. To create a volume with Godo, use the following code:

    
                    import (
        "context"
        "os"
    
        "github.com/digitalocean/godo"
    )
    
    func main() {
        token := os.Getenv("DIGITALOCEAN_TOKEN")
    
        client := godo.NewFromToken(token)
        ctx := context.TODO()
    
        createRequest := &VolumeCreateRequest{
            Region:        "nyc1",
            Name:          "example",
            Description:   "Block store for examples",
            SizeGigaBytes: 10,
        }
    
        volume, _, err := client.Storage.CreateVolume(ctx, createRequest)
    }

    Ruby

    Ruby developers can use DropletKit, the official DigitalOcean V2 API client for Ruby. To create a volume with DropletKit, use the following code:

    
                    require 'droplet_kit'
    token = ENV['DIGITALOCEAN_TOKEN']
    client = DropletKit::Client.new(access_token: token)
    
    volume = DropletKit::Volume.new(
      size_gigabytes: 10,
      name: 'Example',
      description: 'Block store for examples',
      region: 'nyc1'
    )
    client.volumes.create(volume)

    Python

    
                    import os
    from pydo import Client
    
    client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))
    
    req = {
      "size_gigabytes": 10,
      "name": "ext4-example",
      "description": "Block store for examples",
      "region": "nyc1",
      "filesystem_type": "ext4",
      "filesystem_label": "ext4_volume_01"
    }
    
    resp = client.volumes.create(body=req)

Create Volumes Using the Control Panel

To start creating a volume from the control panel, open the Create menu and select Volumes. You can also create and attach a new volume as you create a new Droplet, in the Droplet create page’s Add block storage section.

Create menu

Select Volume Size

In the Select Volume Size section, choose the size of the volume, either by selecting a preset size or entering a size in gigabytes.

The select volume size section of the volume creation window

Some teams may be limited to creating volumes below a certain size. To access larger sizes, you can request an increase in the amount of available storage by contacting support. This option is available on the volumes creation page, by clicking the Request button on top of an unavailable size.

You can increase the size of a volume after you create it.

Select Droplet to Attach To and Name Volume

In the next section, choose the Droplet that you want to attach the volume to and enter a name for the volume. Volumes are located in the same datacenter and project as their associated Droplets.

The select Droplet to attach to and name volume sections of the volume creation window

You can create a volume while creating a new Droplet, in the Add block storage section of the Droplet create page. Volumes you create this way have automatically generated names and are attached to the new Droplet, so the Select Droplet to Attach To and Name Volume sections do not display from the Droplet create page.

Choose Configuration Options

In the Choose Configuration Options section, you choose how you want to format and mount the new volume.

The choose configuration options section of the volume creation window

A newly-created volume has no filesystem, which is what lets a Droplet’s operating system read and write files to it. Formatting a volume creates a filesystem on it (and erases any existing data). You only need to format a volume once, when you first create it. Mounting a formatted volume makes its filesystem accessible to its Droplet. You need to mount the volume every time you attach it to a Droplet.

You can automatically format and mount volumes to Droplets with supported operating systems, and this option is selected by default when it is available. You can always choose to manually format and mount volumes.

Automatically Format & Mount

When you automatically format and mount a volume, you also choose a filesystem. ext4 is the default because of its stability, backwards compatibility, and mature support and tooling. XFS, which specializes in performance for large data files, is also available.

Automatic mounting uses systemd on distributions that support it. The mount unit files are /etc/systemd/system/mnt-volume_*.mount. The udev rules that control the configuration are in /etc/udev/rules.d/99-digitalocean-automount.rules.

On non-systemd distributions, automatic mounting uses fstab, following the same commands and options provided in the control panel’s instructions for manual formatting and mounting.

Volumes are auto-mounted into the /mnt directory with the options defaults,nofail,discard,noatime.

Note
When automatically creating mount points, we replace hyphens with underscores in the volume name. This is because systemd mount unit files use hyphens as separators instead of forward slashes, and for consistency, we match this behavior even on older distributions without systemd.

Manually Format & Mount

If you choose to manually format and mount your volume, you can use the Droplet-specific directions in the volume’s More menu under Config instructions.

Volume more menu

The instructions include three customized commands that you can copy and paste into a terminal from your local machine:

  1. SSH to your Droplet, which includes the SSH command with the Droplet’s IP address filled in. If you disabled root logins, you need to substitute the appropriate user for root.

  2. Format the volume: One time only, which includes the commands to set up a filesystem with the Droplet’s IP address and the SCSI ID of the volume pre-filled. This command specifies ext4 for the filesystem. To use XFS, If you prefer, change mkfs.ext4 to mkfs.xfs.

  3. Mount the volume, which includes the commands to create a mount point, mount the volume, and set the volume to automatically mount when you reboot. The specific SCSI ID of the volume is pre-filled.

Create Volume

After you’ve chosen all necessary settings, click Create Volume to create the volume. Once the volume is formatted and mounted, it is ready to use.

If a Droplet is in a volume-supported datacenter, the Droplet’s Volumes page lets you create and manage its volumes. You can manage all the volumes associated with your account on the Volumes page:

Volumes overview page in the control panel

After creation, you can move volumes between Droplets and increase the size of volumes.

Add, Move, or Delete Files

After mounting the volume, it is accessible on your Droplet at /mnt/your-volume-name. You can use this path to do any file operations you would do with a native volume, including creating, moving, or deleting files.

If you do not change the volume name at creation time, it will be given a default name based on the volume’s datacenter, making the path something like /mnt/volume-nyc3-01. You can run ls /mnt to get a list of attached volumes and their paths.