Zudoku
Unikraft Cloud Platform API

Volumes

Endpoint

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.

List Volumes

GET
https://api.fra.unikraft.cloud
/v1/volumes

Return the current status and the configuration of one or more volumes specified by either UUID(s) or name(s). If no identifier is provided, all volumes are returned.

List Volumes › query Parameters

  • detailsboolean

    Whether to include details about the volume in the response. By default this is set to true, meaning that all information about the volume will be included in the response. If set to false, only the basic information about the volume will be included, such as its name and UUID.

List Volumes › Request Body

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: uuid
type = object · requires: name
Properties for uuid:
  • uuidstring · uuid · required

    Mutually exclusive with name.

    Example: 123e4567-e89b-12d3-a456-426614174000

List Volumes › Responses

default

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object
Properties for message:
  • messagestring

    An optional message providing additional information about the status. This field is useful when the status is not success.

    Example: Failed to perform all operations

Create Volume

POST
https://api.fra.unikraft.cloud
/v1/volumes

Create a volume given the specified configuration parameters. The volume is automatically initialized with an empty file system. After initialization, the volume is 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.

Create Volume › Request Body

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object
Properties for name:
  • namestring

    The name of the volume.

    This is a human-readable name that can be used to identify the volume. The name must be unique within the context of your account. If no name is specified, a random name of the form vol-X is generated for you, where X is a 5 character long random alphanumeric suffix.. The name can also be used to identify the volume in API calls.

    Example: funky-vol-t7qumh5j

Create Volume › Responses

default

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object
Properties for message:
  • messagestring

    An optional message providing additional information about the status. This field is useful when the status is not success.

    Example: Failed to perform all operations

Delete Volumes

DELETE
https://api.fra.unikraft.cloud
/v1/volumes

Delete one or more volumes by their UUID(s) or name(s). If the volumes are still attached to an instance, the operation fails. After this call, the IDs associated with the volumes are no longer valid.

Delete Volumes › Request Body

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: uuid
type = object · requires: name
Properties for uuid:
  • uuidstring · uuid · required

    Mutually exclusive with name.

    Example: 123e4567-e89b-12d3-a456-426614174000

Delete Volumes › Responses

default

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object
Properties for message:
  • messagestring

    An optional message providing additional information about the status. This field is useful when the status is not success.

    Example: Failed to perform all operations

Update Volumes

PATCH
https://api.fra.unikraft.cloud
/v1/volumes

Update one or more volumes specified by either UUID(s) or name(s).

Update Volumes › Request Body

  • propstring · enum · enum · required

    The property to modify.

    Enum values:
    size_mb
    tags
    quota_policy
    delete_lock
    Example: size_mb
  • opstring · enum · enum · required

    The operation to perform.

    Enum values:
    set
    add
    del
    Example: set
  • idstring

    (Optional). A client-provided identifier for tracking this operation in the response.

    Example: op-1
  • uuidstring · uuid

    The UUID of the volume to update. Mutually exclusive with name.

    Example: 123e4567-e89b-12d3-a456-426614174000
  • namestring

    The name of the volume to update. Mutually exclusive with UUID.

    Example: funky-town-g756b5d
  • value

    The value for the update operation. The type depends on the property and operation:

    • For "size_mb": unsigned integer
    • For "quota_policy": 1 - static reservation, 2 - dynamic reservation
    • For "tags": array of Strings
    • For "delete_lock": boolean

Update Volumes › Responses

default

  • statusstring · enum · enum

    The status of the response.

    Enum values:
    success
    error
  • messagestring

    An optional message providing additional information about the status. This field is useful when the status is not success.

    Example: Failed to perform all operations
  • dataobject

    The response data for this request.

  • errorsobject[]

    A list of errors which may have occurred during the request.

  • op_time_usinteger · uint64

    The operation time in microseconds. This is the time it took to process the request and generate the response.

    Example: 76

Attach Volumes

PUT
https://api.fra.unikraft.cloud
/v1/volumes/attach

Attach one or more volumes specified by ID(s) (name or UUID) to instances so that the volumes are mounted when the instances start. The volumes need to be in available state and the instances must be in stopped state.

Attach Volumes › Request Body

  • attach_toobject · required

    UUID or name of the instance to attach the volume to.

  • atstring · regex · pattern: ^/(?!.*\.\./|.*\.$|.… · required

    Path of the mountpoint.

    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: /mnt/my-volume
  • uuidstring · uuid

    The UUID of the volume to attach. Mutually exclusive with name. Exactly one of uuid or name must be provided.

    Example: c1d2e3f4-5678-90ab-cdef-1234567890ab
  • namestring

    The name of the volume to attach. Mutually exclusive with UUID. Exactly one of uuid or name must be provided.

    Example: funky-vol-g7gum5cj
  • readonlyboolean

    Whether the volume should be mounted read-only.

    Example: false

Attach Volumes › Responses

default

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object
Properties for message:
  • messagestring

    An optional message providing additional information about the status. This field is useful when the status is not success.

    Example: Failed to perform all operations

Detach Volumes

PUT
https://api.fra.unikraft.cloud
/v1/volumes/detach

Detach volumes specified by ID(s) (name or UUID) 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 volumes 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).

Detach Volumes › Request Body

  • uuidstring · uuid

    The UUID of the volume to detach. Mutually exclusive with name. Exactly one of uuid or name must be provided.

    Example: c1d2e3f4-5678-90ab-cdef-1234567890ab
  • namestring

    The name of the volume to detach. Mutually exclusive with UUID. Exactly one of uuid or name must be provided.

    Example: funky-town-g7gum5cj
  • fromobject

    UUID or name of the instance to detach the volume from.

Detach Volumes › Responses

default

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object
Properties for message:
  • messagestring

    An optional message providing additional information about the status. This field is useful when the status is not success.

    Example: Failed to perform all operations

Get Volume by UUID

GET
https://api.fra.unikraft.cloud
/v1/volumes/{uuid}

Return the current status and the configuration of a particular volume by its UUID.

Get Volume by UUID › path Parameters

  • uuidstring · uuid · required

    The UUID of the volume to retrieve.

    Example: c1d2e3f4-5678-90ab-cdef-1234567890ab

Get Volume by UUID › query Parameters

  • detailsboolean

    Whether to include details about the volume in the response. By default this is set to true, meaning that all information about the volume will be included in the response. If set to false, only the basic information about the volume will be included, such as its name and UUID.

Get Volume by UUID › Responses

default

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object
Properties for message:
  • messagestring

    An optional message providing additional information about the status. This field is useful when the status is not success.

    Example: Failed to perform all operations

Delete Volume by UUID

DELETE
https://api.fra.unikraft.cloud
/v1/volumes/{uuid}

Delete the specified volume by its UUID. If the volume is still attached to an instance, the operation fails. After this call, the IDs associated with the volume are no longer valid.

Delete Volume by UUID › path Parameters

  • uuidstring · uuid · required

    The UUID of the volume to delete.

    Example: c1d2e3f4-5678-90ab-cdef-1234567890ab

Delete Volume by UUID › Responses

default

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object
Properties for message:
  • messagestring

    An optional message providing additional information about the status. This field is useful when the status is not success.

    Example: Failed to perform all operations

Update Volume by UUID

PATCH
https://api.fra.unikraft.cloud
/v1/volumes/{uuid}

Update the specified volume by its UUID.

Update Volume by UUID › path Parameters

  • uuidstring · uuid · required

    The UUID of the service group to update.

    Example: 123e4567-e89b-12d3-a456-426614174000

Update Volume by UUID › Request Body

  • propstring · enum · enum · required

    The property to modify.

    Enum values:
    size_mb
    tags
    quota_policy
    delete_lock
    Example: size_mb
  • opstring · enum · enum · required

    The operation to perform.

    Enum values:
    set
    add
    del
    Example: set
  • idstring

    (Optional). A client-provided identifier for tracking this operation in the response.

    Example: op-1
  • value

    The value for the update operation. The type depends on the property and operation:

    • For "size_mb": unsigned integer
    • For "quota_policy": "static" or "dynamic"
    • For "tags": array of Strings
    • For "delete_lock": boolean

Update Volume by UUID › Responses

default

  • statusstring · enum · enum

    The status of the response.

    Enum values:
    success
    error
  • messagestring

    An optional message providing additional information about the status. This field is useful when the status is not success.

    Example: Failed to perform all operations
  • dataobject

    The response data for this request.

  • errorsobject[]

    A list of errors which may have occurred during the request.

  • op_time_usinteger · uint64

    The operation time in microseconds. This is the time it took to process the request and generate the response.

    Example: 76

Attach Volume by UUID

PUT
https://api.fra.unikraft.cloud
/v1/volumes/{uuid}/attach

Attach a volume by UUID 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 be in stopped state.

Attach Volume by UUID › path Parameters

  • uuidstring · uuid · required

    The UUID of the volume to attach.

    Example: c1d2e3f4-5678-90ab-cdef-1234567890ab

Attach Volume by UUID › Request Body

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object
Properties for readonly:
  • readonlyboolean

    Whether the volume should be mounted read-only.

    Example: false

Attach Volume by UUID › Responses

default

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object
Properties for message:
  • messagestring

    An optional message providing additional information about the status. This field is useful when the status is not success.

    Example: Failed to perform all operations

Detach Volume by UUID

PUT
https://api.fra.unikraft.cloud
/v1/volumes/{uuid}/detach

Detaches a volume by UUID 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).

Detach Volume by UUID › path Parameters

  • uuidstring · uuid · required

    The UUID of the volume to detach.

    Example: c1d2e3f4-5678-90ab-cdef-1234567890ab

Detach Volume by UUID › Request Body

  • fromobject

    UUID or name of the instance to detach the volume from.

Detach Volume by UUID › Responses

default

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object
Properties for message:
  • messagestring

    An optional message providing additional information about the status. This field is useful when the status is not success.

    Example: Failed to perform all operations
Users