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.
Note: Volumes are in private preview and are currently only suitable for testing. Please back up any data that you cannot afford to lose when using volumes.
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
Note: Volumes are currently only available in the Washington, D.C. and Frankfurt regions.
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
Note: Currently, once a volume is attached to a Service, it cannot be detached except by deleting the Service. A volume that has been attached to a Service cannot be attached to a new Service, even if the original Service has been deleted.
Due to this limitation, it is important not to delete a Service that a volume is associated with if you intend to access the volume's contents again. Instead, you can pause the Service if you do not currently need it or modify the Service configuration if you need a different Service configuration.
This section is currently for informational purposes only until this limitation is removed.
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>'
Note: Currently, the only way to detach a volume is to delete the associated Service. Updating the Service to remove a volume is currently disabled.
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.
Note: Because to this limitation, it is important to not delete a Service that a volume is associated with if you intend to access the volume's contents again.
Instead, you can pause the Service if you do not currently need it or modify the Service configuration if you need a different Service configuration.
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.