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:

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 a running unikernel
busy	There are maintenance tasks running on the volume
error	The 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:

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

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

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

Batching

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

Request

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

Parameter	Type	Default	Required	Description
uuid | name1	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.

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.

Field	Type	Description
status	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_to1	array of objects	List of instances that this volume is attached to
uuid	UUID	UUID of the instance
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

¹ A volume can currently 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.

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

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

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

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

Parameter	Type	Default	Required	Description
uuid | name1	UUID | Name		✔️	UUID or name of the volume to detach

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

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>

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

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

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.

Request

Endpoints:
GET /v1/volumes/list

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 ${KRAFTCLOUD_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"
      }
    ]
  }
}