Skip to content

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:

StateDescription
uninitializedThe volume is scheduled to be created
initializingThe volume is currently created and formatted
availableThe volume is healthy and available to be attached to an instance
idleThe volume is healthy and attached to an instance. It is possible to detach it in this state
mountedThe volume is currently mounted in an instance
busyThere are maintenance tasks running on the volume
errorThe 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:

MethodEndpointPurpose and Description
POST/v1/volumesCreates one or more volumes
GET/v1/volumesReturns the current state and configuration of volumes
DELETE/v1/volumesDeletes the specified volumes
PUT/v1/volumes/attachAttaches the volumes to instances
PUT/v1/volumes/detachDetaches volumes from instances
GET/v1/volumes/listLists 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.

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.

Request

Endpoints:
POST /v1/volumes

Body ParameterTypeDefaultRequiredDescription
name1NamerandomName of the volume
size_mbint✔️Size of the volume in megabytes

1If 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.

FieldTypeDescription
statusstringsuccess on success, or error if the request failed
uuidUUIDUUID of the newly created volume
nameNameName of the newly created volume
Status 200 OK
{
"status": "success",
"data": {
"volumes": [
{
"status": "success",
"uuid": "847fe9ef-ccb1-409c-be9c-abdc02498131",
"name": "vol-drq6l"
}
]
}
}

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.

Request

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

Query ParameterTypeDefaultRequiredDescription
detailsbooltrueWhether to provide detailed status and configuration information
name1string | list of stringsNames of volumes to return as comma-separated list
uuid1string | list of stringsUUIDs of volumes to return as comma-separated list
Body ParameterTypeDefaultRequiredDescription
uuid | name1,2UUID | Name✔️UUID or name of the volume to get the status for

1 Not allowed in local scope.
2 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"
Terminal window
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"
}
]'
Terminal window
curl -X GET \
-H "Authorization: Bearer ${UKC_TOKEN}" \
"https://api.fra0.kraft.cloud/v1/volumes?name=my-volume,my-other-volume"
Terminal window
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.

FieldTypeDescription
status1stringsuccess on success, or error if the request failed
stateStateCurrent state of the volume
uuidUUIDUUID of the volume
nameNameName of the volume
size_mbintSize of the volume in megabytes
attached_toarray of objectsList of instances that this volume is attached to
    uuidUUIDUUID of the instance
    nameNameName of the instance
mounted_byarray of objectsList of instances that have this volume mounted
    uuidUUIDUUID of the instance
    nameNameName of the instance
    readonlyboolWhether the volume is mounted read-only or read-write
persistentboolIndicates if the volume will stay alive when the last instance is deleted that this volume is attached to
created_atstringDate and time of creation in ISO8601

1 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.

Request

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

Body ParameterTypeDefaultRequiredDescription
uuid | name1UUID | Name✔️UUID or name of the volume to attach
attach_toobject✔️
    uuid | nameUUID | Name✔️UUID or name of the instance to attach the volume to
at2string✔️Path of the mountpoint
readonlyboolfalseWhether the volume should be mounted read-only

1 Not allowed in local scope. You need to specify either uuid or name within the same body object.
2 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.

FieldTypeDescription
statusstringsuccess on success, or error if the request failed
uuidUUIDUUID of the volume
nameNameName 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).

Request

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

Query ParameterTypeDefaultRequiredDescription
name1,3string | list of stringsNames of volumes to detach as comma-separated list
uuid1,3string | list of stringsUUIDs of volumes to detach as comma-separated list
Body ParameterTypeDefaultRequiredDescription
uuid | name1,2UUID | Name✔️UUID or name of the volume to detach
from3object
    uuid | nameUUID | Name✔️UUID or name of the instance to detach the volume from

1 Not allowed in local scope.
2 You need to specify either uuid or name within the same body object.
3 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.

FieldTypeDescription
statusstringsuccess on success, or error if the request failed
uuidUUIDUUID of the volume
nameNameName 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.

Request

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

Query ParameterTypeDefaultRequiredDescription
name1string | list of stringsNames of volumes to delete as comma-separated list
uuid1string | list of stringsUUIDs of volumes to delete as comma-separated list
Body ParameterTypeDefaultRequiredDescription
uuid | name1,2UUID | Name✔️UUID or name of the volume to delete

1 Not allowed in local scope.
2 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.

FieldTypeDescription
statusstringsuccess on success, or error if the request failed
uuidUUIDUUID of the volume
nameNameName 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.

Request

Endpoints:
GET /v1/volumes/list

Body ParameterTypeDefaultRequiredDescription
persistentboolDesired persistence value for filtering
stateStateState 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.

FieldTypeDescription
uuidUUIDUUID of the volume
nameNameName 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"
}
]
}
}