Volumes

This document describes the Unikraft Cloud Volumes API (v1) for managing persistent volumes.

InitRds vs. Volumes

Initrd (initial ramdisk) and actual volumes serve different purposes. An initrd is a file system loaded into memory during the boot process of the instance. Any new files created as well as any modifications made to files in the initrd are lost when the instance is stopped. In contrast, a volume is a persistent storage device that keeps data across restarts. In addition, it can be initialized with a set of files with one instance and then be detached and attached to a another one.

Volume States

A volume can be in one of the following states:

State	Description
uninitialized	The volume is scheduled to be created
initializing	The volume is currently created and formatted
available	The volume is healthy and available to be attached to an instance
idle	The volume is healthy and attached to an instance. It is possible to detach it in this state
mounted	The volume is currently mounted in an instance
busy	There are maintenance tasks running on the volume
error	The volume is in an error state that needs inspection by a Unikraft Cloud engineer

These are reported as volume state by the endpoints.

API Endpoints

The Unikraft Cloud Volumes API provides the following endpoints:

Method	Endpoint	Purpose and Description
POST	/v1/volumes	Creates one or more volumes
GET	/v1/volumes	Returns the current state and configuration of volumes
DELETE	/v1/volumes	Deletes the specified volumes
PUT	/v1/volumes/attach	Attaches the volumes to instances
PUT	/v1/volumes/detach	Detaches volumes from instances
GET	/v1/volumes/list	Lists all existing volumes

In the following, the API endpoints are specified relative to this base URL:

https://api.X.kraft.cloud/

With X being the IATA metro code. We use fra0 as an example in the documentation. See the introduciton for more information on how to connect to the API.

Local Scope

Local API endpoints directed at a specific volumes additionally include the UUID of the volume (i.e., GET /v1/volumes/<UUID>)

Creating Volumes

Creates one or more volumes with the given configuration. The volumes are automatically initialized with an empty file system. After initialization the volumes are in the available state and can be attached to an instance with the PUT /v1/volumes/attach endpoint. Note that, the size of a volume cannot be changed after creation.

Batching

You can specify an array of volume descriptions to create multiple volumes with different properties with the same call.

Request

Endpoints:
POST /v1/volumes

Body Parameter	Type	Default	Required	Description
name1	Name	random		Name of the volume
size_mb	int		✔️	Size of the volume in megabytes

¹If no name is specified a random name of the form vol-X is auto-generated, where X is a 5 character long random alphanumeric suffix.

Example of creating a single 100 MB volume

curl -X POST \
     -H "Authorization: Bearer ${UKC_TOKEN}" \
     -H "Content-Type: application/json" \
     "https://api.fra0.kraft.cloud/v1/volumes" \
     -d '{
        "size_mb": 100
      }'

Response

The response is embedded in a JSON object as described in API Responses.

Field	Type	Description
status	string	success on success, or error if the request failed
uuid	UUID	UUID of the newly created volume
name	Name	Name of the newly created volume

Status 200 OK

{
  "status": "success",
  "data": {
    "volumes": [
      {
        "status": "success",
        "uuid": "847fe9ef-ccb1-409c-be9c-abdc02498131",
        "name": "vol-drq6l"
      }
    ]
  }
}

Quota Exceeded Error

If you experience a Quota exceeded error (EDQUOT), check your user account’s quota usage and limits.

Getting the Status of a Volume

Returns the current status and the configuration of a particular volume if a UUID or name is specified. Otherwise, returns the current status and configuration of all volumes.

Batching

In global scope, you can specify an array of status requests to retrieve the status of multiple volumes with the same call.

Listing All Existing Volumes

In global scope, do not provide any IDs via body or query parameters if you want to list all existing volumes.

Request

Endpoints:
GET /v1/volumes
GET /v1/volumes/<UUID>

Query Parameter	Type	Default	Required	Description
details	bool	true		Whether to provide detailed status and configuration information
name1	string | list of strings			Names of volumes to return as comma-separated list
uuid1	string | list of strings			UUIDs of volumes to return as comma-separated list

Body Parameter	Type	Default	Required	Description
uuid | name1,2	UUID | Name		✔️	UUID or name of the volume to get the status for

¹ Not allowed in local scope.
² You need to specify either uuid or name within the same body object.

Example of getting the status of volumes

curl -X GET \
     -H "Authorization: Bearer ${UKC_TOKEN}" \
     "https://api.fra0.kraft.cloud/v1/volumes/847fe9ef-ccb1-409c-be9c-abdc02498131"

curl -X GET \
     -H "Authorization: Bearer ${UKC_TOKEN}" \
     "https://api.fra0.kraft.cloud/v1/volumes" \
     -d '[
      {
        "uuid": "847fe9ef-ccb1-409c-be9c-abdc02498131"
      },
      {
        "name": "my-volume"
      }
     ]'

curl -X GET \
     -H "Authorization: Bearer ${UKC_TOKEN}" \
     "https://api.fra0.kraft.cloud/v1/volumes?name=my-volume,my-other-volume"

curl -X GET \
     -H "Authorization: Bearer ${UKC_TOKEN}" \
     "https://api.fra0.kraft.cloud/v1/volumes?details=false"

Response

The response is embedded in a JSON object as described in API Responses.

Field	Type	Description
status1	string	success on success, or error if the request failed
state	State	Current state of the volume
uuid	UUID	UUID of the volume
name	Name	Name of the volume
size_mb	int	Size of the volume in megabytes
attached_to	array of objects	List of instances that this volume is attached to
uuid	UUID	UUID of the instance
name	Name	Name of the instance
mounted_by	array of objects	List of instances that have this volume mounted
uuid	UUID	UUID of the instance
name	Name	Name of the instance
readonly	bool	Whether the volume is mounted read-only or read-write
persistent	bool	Indicates if the volume will stay alive when the last instance is deleted that this volume is attached to
created_at	string	Date and time of creation in ISO8601

¹ Not when listing all existing volumes.

Status 200 OK

{
  "status": "success",
  "data": {
    "volumes": [
      {
        "status": "success",
        "state": "available",
        "uuid": "847fe9ef-ccb1-409c-be9c-abdc02498131",
        "name": "vol-drq6l",
        "created_at": "2023-08-21T16:38:15Z",
        "size_mb": 100
      }
    ]
  }
}

Attaching a Volume to an Instance

Attaches a volume to an instance so that the volume is mounted when the instance starts. The volume needs to be in available state and the instance must in stopped state. Currently, each instance can have only one volume attached at most.

Batching

You can specify an array of attach descriptions to attach multiple volumes with the same call.

Request

Endpoints:
PUT /v1/volumes/attach
PUT /v1/volumes/<UUID>/attach

Body Parameter	Type	Default	Required	Description
uuid | name1	UUID | Name		✔️	UUID or name of the volume to attach
attach_to	object		✔️
uuid | name	UUID | Name		✔️	UUID or name of the instance to attach the volume to
at2	string		✔️	Path of the mountpoint
readonly	bool	false		Whether the volume should be mounted read-only

¹ Not allowed in local scope. You need to specify either uuid or name within the same body object.
² The path must be absolute, not contain . and .. components, and not contain colons (:). The path must point to an empty directory. If the directory does not exist, it is created.

Example of attaching a volume to an instance and mount it in /mnt/

curl -X PUT \
     -H "Authorization: Bearer ${UKC_TOKEN}" \
     -H "Content-Type: application/json" \
     "https://api.fra0.kraft.cloud/v1/volumes/847fe9ef-ccb1-409c-be9c-abdc02498131/attach" \
     -d "{
        'attach_to': {
          'uuid': '77d0316a-fbbe-488d-8618-5bf7a612477a'
        },
        'at': '/mnt/'
      }"

Response

The response is embedded in a JSON object as described in API Responses.

Field	Type	Description
status	string	success on success, or error if the request failed
uuid	UUID	UUID of the volume
name	Name	Name of the volume

Status 200 OK

{
  "status": "success",
  "data": {
    "volumes": [
      {
        "status": "success",
        "uuid": "847fe9ef-ccb1-409c-be9c-abdc02498131",
        "name": "vol-drq6l"
      }
    ]
  }
}

Detaching a Volume from Instances

Detaches a volume from instances. If no particular instance is specified the volume is detached from all instances. The instances from which to detach must not have the volume mounted. The API returns an error for each instance from which it was unable to detach the volume. If the volume has been created together with an instance, detaching the volume will make it persistent (i.e., it survives the deletion of the instance).

Batching

You can specify an array of detach descriptions to detach multiple volumes with the same call.

Request

Endpoints:
PUT /v1/volumes/detach
PUT /v1/volumes/<UUID>/detach

Query Parameter	Type	Default	Required	Description
name1,3	string | list of strings			Names of volumes to detach as comma-separated list
uuid1,3	string | list of strings			UUIDs of volumes to detach as comma-separated list

Body Parameter	Type	Default	Required	Description
uuid | name1,2	UUID | Name		✔️	UUID or name of the volume to detach
from3	object
uuid | name	UUID | Name		✔️	UUID or name of the instance to detach the volume from

¹ Not allowed in local scope.
² You need to specify either uuid or name within the same body object.
³ If the from field is not specified the volume is detached from all instances. The same applies if the volume is specified via a query parameter.

Example of detaching a specific volume

curl -X PUT \
     -H "Authorization: Bearer ${UKC_TOKEN}" \
     "https://api.fra0.kraft.cloud/v1/volumes/847fe9ef-ccb1-409c-be9c-abdc02498131/detach"

Response

The response is embedded in a JSON object as described in API Responses.

Field	Type	Description
status	string	success on success, or error if the request failed
uuid	UUID	UUID of the volume
name	Name	Name of the volume

Status 200 OK

{
  "status": "success",
  "data": {
    "volumes": [
      {
        "status": "success",
        "uuid": "847fe9ef-ccb1-409c-be9c-abdc02498131",
        "name": "vol-drq6l"
      }
    ]
  }
}

Deleting a Volume

Deletes the specified volume. Fails if the volume is still attached to an instance. After this call the IDs associated with the volume are no longer valid.

Batching

In global scope, you can specify an array of delete requests to delete multiple volumes with the same call.

Request

Endpoints:
DELETE /v1/volumes
DELETE /v1/volumes/<UUID>

Query Parameter	Type	Default	Required	Description
name1	string | list of strings			Names of volumes to delete as comma-separated list
uuid1	string | list of strings			UUIDs of volumes to delete as comma-separated list

Body Parameter	Type	Default	Required	Description
uuid | name1,2	UUID | Name		✔️	UUID or name of the volume to delete

¹ Not allowed in local scope.
² You need to specify either uuid or name within the same body object.

Example of deleting a specific volume

curl -X DELETE \
     -H "Authorization: Bearer ${UKC_TOKEN}" \
     "https://api.fra0.kraft.cloud/v1/volumes/847fe9ef-ccb1-409c-be9c-abdc02498131"

Response

The response is embedded in a JSON object as described in API Responses.

Field	Type	Description
status	string	success on success, or error if the request failed
uuid	UUID	UUID of the volume
name	Name	Name of the volume

Status 200 OK

{
  "status": "success",
  "data": {
    "volumes": [
      {
        "status": "success",
        "uuid": "847fe9ef-ccb1-409c-be9c-abdc02498131",
        "name": "vol-drq6l"
      }
    ]
  }
}

List Existing Volumes

Lists all existing volumes. You can filter by persistence and volume state. The returned volumes fulfill all provided filter criteria. No particular value is assumed if a filter is not part of the request.

Caution

This endpoint has been deprecated and will be removed in future versions. Use GET /v1/volumes instead.

Request

Endpoints:
GET /v1/volumes/list

Body Parameter	Type	Default	Required	Description
persistent	bool			Desired persistence value for filtering
state	State			State for filtering

Example of listing all existing volumes

curl -X GET \
     -H "Authorization: Bearer ${UKC_TOKEN}" \
     "https://api.fra0.kraft.cloud/v1/volumes/list"

Response

The response is embedded in a JSON object as described in API Responses.

Field	Type	Description
uuid	UUID	UUID of the volume
name	Name	Name of the volume

Status 200 OK

{
  "status": "success",
  "data": {
    "volumes": [
      {
        "uuid": "847fe9ef-ccb1-409c-be9c-abdc02498131",
        "name": "vol-drq6l"
      },
      {
        "uuid": "c376880c-84df-4c17-b2b1-df7181f9c26f",
        "name": "vol-gl2z1"
      }
    ]
  }
}