Volumes

Koyeb volumes are block storage devices that can be provisioned to provide persistent storage across deployments. Unlike the local ephemeral storage available for Instances, volume storage can be reattached to new deployments, saving important context and configuration that would otherwise be lost.

Volume operations

Volume operations are available using the Koyeb control panel (opens in a new tab), Koyeb CLI, and API. Using these tools, you can create, get, list, update, attach, detach, and delete volumes.

This section will use the Koyeb CLI to talk about the available volume operations.

Create volumes

To create a volume, use the koyeb volume create command.

The command requires you to provide a name for the volume:

koyeb volume create <VOLUME_NAME>

By default, the creation command will create a 7 Gigabyte volume in the was region. To use a different region or size, include the --region and --size flags, respectively:

koyeb volume create <VOLUME_NAME> --region fra --size 7G

Get volume details

To display the details about a specific volume, use the koyeb volume get command. The command takes the volume name or volume ID:

koyeb volume get <VOLUME_NAME>

The output will include the volume's ID, name, region, type, status, size, creation time, and the service it is attached to (if any):

ID      	NAME       	REGION	TYPE     	STATUS  	SIZE  	CREATED AT         	SERVICE
39a447af    my-volume   fra     local-blk   detached    7.00G   28 Jun 24 12:31 UTC

List volumes

To get list of all of your volumes, use the koyeb volume list command. This command takes no special arguments and returns a list of all volumes:

koyeb volume list

The output matches the koyeb volume get output, with one line per volume:

ID      	NAME       	REGION	TYPE     	STATUS  	SIZE  	CREATED AT         	SERVICE
39a447af    my-volume   fra     local-blk   detached     7.00G   28 Jun 24 12:31 UTC
8cd91e34	test-volume	fra   	local-blk	detached	10.00G   01 Jul 24 09:01 UTC

Update volumes

You can update an existing volume to either change its name or increase its size.

To change a volume name, pass in the --name option with the new name you'd like to use:

koyeb volume update <OLD_VOLUME_NAME> --name <NEW_VOLUME_NAME>

To grow the size of your volume, pass in a new volume size with the --size option. The new volume size must be larger than the current volume size:

koyeb volume update <VOLUME_NAME> --size 10G

Attach volumes to a Service

To attach a volume to a Service, pass the --volumes option to any of the commands that create or update Services:

• koyeb app init
• koyeb service create
• koyeb service update

The --volumes option takes the volume name and the path where it should be mounted on the Service's Instance filesystem, separated by a colon (:):

koyeb service update <SERVICE_NAME> --volumes <VOLUME_NAME>:<VOLUME_MOUNT_POINT>

A new deployment for the given Service will be created with the volume attached and mounted at the provided mount point. The volume will always be moved to the latest active deployment of the Service.

Detach volumes from a Service

To detach a volume from a Service, update the Service definition with the koyeb service update command using the --volumes option.

To unmount and detach a volume, use the ! negation syntax with the volume name. This will remove the volume from the Service Instance:

koyeb service update <SERVICE_NAME> --volume '!<VOLUME_NAME>'

Delete volumes

To delete a volume, use the koyeb volume delete command. Pass in the name of the volume:

koyeb volume delete <VOLUME_NAME>

To delete a volume, it must not be attached to a Service. To detach a volume, you can either delete the associated Service or update the service to detach the volume by typing:

koyeb service update mysql --volume '!<VOLUME_NAME>'

Example workflow

To create a volume, use the Koyeb CLI to specify the volume name, region, and size.

This command creates a 10 Gigabyte volume called my-volume in the Frankfurt region:

koyeb volume create my-volume --size 10G --region fra

You can view existing volumes by typing:

koyeb volume list

The list will show the volume ID, name, region, type, status, size, creation date, and the service it is attached to (if attached):

ID              NAME            REGION  TYPE            STATUS          SIZE    CREATED AT              SERVICE
39a447af        my-volume       fra     local-blk       detached        10.00G  28 Jun 24 12:31 UTC

With the volume provisioned, you can attach it to a Koyeb Service using the --volumes option.

For example, this command creates a new Koyeb App and Service called mysql provisioned using the mysql Docker image. It is created in the same region as the volume created earlier and the volume is attached by specifying <VOLUME_NAME>:<MOUNT_POINT>:

koyeb app init mysql --docker mysql --region fra --volumes my-volume:/var/lib/mysql --env MYSQL_ROOT_PASSWORD=${{ secrets.mysql_root_password }} --port 3306:tcp

The --volumes option is also available when using the koyeb create and koyeb update commands.

To unmount and detach a volume, use the ! negation syntax with the volume name. This will remove the volume from the current instance:

koyeb service update mysql --volume '!my-volume'

Once a volume is detached, you can delete the volume by typing:

koyeb volume delete my-volume

Limitations

Koyeb volumes are currently in private preview and have the following limitations.

Regions

Volumes are currently only available in the Washington, D.C. (was) and Frankfurt (fra) regions.

Sizes

At present, volumes must be between 1 and 10 Gigabytes in size.

Scale

Volumes currently only work with Services with a scale of one.

Instance type

Volumes can only be attached to standard and GPU Services. You cannot attach a volume to eco-* or free Instance. Learn more about the different types of Instances available on the Instance reference page.

Service association

At the moment, once a volume is attached to a Service, it cannot be associated with another Service. This limitation exists even if the volume is detached from the initial service.

An attached volume cannot currently be detached except by deleting the associated Service.

Redeployment downtime

The introduction of volumes introduces a stateful component to the deployment workflow. This means that Services that have volumes attached may experience downtime during redeployment while the volume is detached from the previous deployment and attached to the new deployment.