Skip to content

Volumes

This document describes the KraftCloud Volumes REST 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 unikernel. 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 a running unikernel
busyThere are maintenance tasks running on the volume
errorThe volume is in an error state that needs inspection by a KraftCloud engineer

These are reported as volume state by the endpoints.

API Endpoints

The KraftCloud Volumes REST 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

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 ${KRAFTCLOUD_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 volume.

Request

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

ParameterTypeDefaultRequiredDescription
uuid | name1UUID | Name✔️UUID or name of the volume to get the status for

1 Not allowed in local scope. You need to specify either uuid or name.

Example of getting the status of a specific volume
curl -X GET \
-H "Authorization: Bearer ${KRAFTCLOUD_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
stateStateCurrent state of the volume
uuidUUIDUUID of the volume
nameNameName of the volume
size_mbintSize of the volume in megabytes
attached_to1array of UUIDsList of instances that this volume is attached to
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 A volume can be attached to a single instance only

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

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.
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 ${KRAFTCLOUD_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 an Instance

Detaches a volume from an instance. The instance from which to detach must in stopped state. 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

ParameterTypeDefaultRequiredDescription
uuid | name1UUID | Name✔️UUID or name of the volume to detach

1 Not allowed in local scope. You need to specify either uuid or name.

Example of detaching a specific volume
curl -X PUT \
-H "Authorization: Bearer ${KRAFTCLOUD_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>

ParameterTypeDefaultRequiredDescription
uuid | name1UUID | Name✔️UUID or name of the volume to delete

1 Not allowed in local scope. You need to specify either uuid or name.

Example of deleting a specific volume
curl -X DELETE \
-H "Authorization: Bearer ${KRAFTCLOUD_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

ParameterTypeDefaultRequiredDescription
persistentboolDesired persistence value for filtering
stateStateState for filtering
Example of listing all existing volumes
curl -X GET \
-H "Authorization: Bearer ${KRAFTCLOUD_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"
}
]
}
}