Tools¶

Tools define bundles of software binaries and other assets (e.g. container and virtual machine base-images).

Rationale¶

All Applications in UCloud consist of two components: the Tool and the Application The Tool defines the computational environment. This includes software packages and other assets (e.g. configuration). A typical example would be a base-image for a container or a virtual machine. The Application describes how to invoke the Tool. This includes specifying the input parameters and command-line invocation for the Tool.

⚠️ WARNING: The API listed on this page will likely change to conform with our API conventions. Be careful when building integrations. The following changes are expected:

RPC names will change to conform with the conventions
RPC request and response types will change to conform with the conventions
RPCs which return a page will be collapsed into a single browse endpoint
Some property names will change to be consistent with Resources

Table of Contents¶

1. Examples

Description
Retrieve a container based Tool
Retrieve a virtual machine based Tool

2. Remote Procedure Calls

Name	Description
`fetchLogo`	Retrieves a logo associated with a Tool
`findByName`	Finds a Page of Tools which share the same name
`findByNameAndVersion`	Finds a Tool by name and version
`listAll`	Queries the entire catalog of Tools
`clearLogo`	Deletes an existing logo from a Tool
`create`	Creates a new Tool and adds it to the internal catalog
`uploadLogo`	Uploads a logo and associates it with a Tool

3. Data Models

Name	Description
`Tool`	Tools define bundles of software binaries and other assets (e.g. container and virtual machine base-images).
`NormalizedToolDescription`	The specification of a Tool
`FindByNameAndPagination`	Request type to find a Page of resources defined by a name
`FindByNameAndVersion`	A request type to find a resource by name and version
`NameAndVersion`	A type describing a name and version tuple
`SimpleDuration`	No description
`ToolBackend`	No description
`ClearLogoRequest`	No description
`FetchLogoRequest`	No description
`UploadApplicationLogoRequest`	No description

Example: Retrieve a container based Tool¶

Frequency of use	Common
Actors	An authenticated user (`user`)

Communication Flow: Kotlin

/* This example show an example Tool which uses a container backend. This Tool specifies that the 
container image is "acme/batch:1.0.0". The provider decides how to retrieve these images. We 
recommend that you follow the standard defined by Docker. */

ToolStore.findByNameAndVersion.call(
    FindByNameAndVersion(
        name = "acme-batch", 
        version = "1.0.0", 
    ),
    user
).orThrow()

/*
Tool(
    createdAt = 1633329776235, 
    description = NormalizedToolDescription(
        authors = listOf("Acme Inc."), 
        backend = ToolBackend.DOCKER, 
        container = null, 
        defaultNumberOfNodes = 1, 
        defaultTimeAllocation = SimpleDuration(
            hours = 1, 
            minutes = 0, 
            seconds = 0, 
        ), 
        description = "A batch tool", 
        image = "acme/batch:1.0.0", 
        info = NameAndVersion(
            name = "acme-batch", 
            version = "1.0.0", 
        ), 
        license = "None", 
        requiredModules = emptyList(), 
        supportedProviders = null, 
        title = "Acme Batch", 
    ), 
    modifiedAt = 1633329776235, 
    owner = "_ucloud", 
)
*/

Communication Flow: Curl

# ------------------------------------------------------------------------------------------------------
# $host is the UCloud instance to contact. Example: 'http://localhost:8080' or 'https://cloud.sdu.dk'
# $accessToken is a valid access-token issued by UCloud
# ------------------------------------------------------------------------------------------------------

# This example show an example Tool which uses a container backend. This Tool specifies that the 
# container image is "acme/batch:1.0.0". The provider decides how to retrieve these images. We 
# recommend that you follow the standard defined by Docker.

# Authenticated as user
curl -XGET -H "Authorization: Bearer $accessToken" "$host/api/hpc/tools/byNameAndVersion?name=acme-batch&version=1.0.0" 

# {
#     "owner": "_ucloud",
#     "createdAt": 1633329776235,
#     "modifiedAt": 1633329776235,
#     "description": {
#         "info": {
#             "name": "acme-batch",
#             "version": "1.0.0"
#         },
#         "container": null,
#         "defaultNumberOfNodes": 1,
#         "defaultTimeAllocation": {
#             "hours": 1,
#             "minutes": 0,
#             "seconds": 0
#         },
#         "requiredModules": [
#         ],
#         "authors": [
#             "Acme Inc."
#         ],
#         "title": "Acme Batch",
#         "description": "A batch tool",
#         "backend": "DOCKER",
#         "license": "None",
#         "image": "acme/batch:1.0.0",
#         "supportedProviders": null
#     }
# }

Communication Flow: Visual

Example: Retrieve a virtual machine based Tool¶

Frequency of use	Common
Actors	An authenticated user (`user`)

Communication Flow: Kotlin

/* This example show an example Tool which uses a virtual machine backend. The Tool specifies that 
the base image is "acme-operating-system". The provider decides how to retrieve these images. For 
virtual machines, this is likely so dependant on the provider. As a result, we recommend using the 
supportedProviders property.  */

ToolStore.findByNameAndVersion.call(
    FindByNameAndVersion(
        name = "acme-os", 
        version = "1.0.0", 
    ),
    user
).orThrow()

/*
Tool(
    createdAt = 1633329776235, 
    description = NormalizedToolDescription(
        authors = listOf("Acme Inc."), 
        backend = ToolBackend.VIRTUAL_MACHINE, 
        container = null, 
        defaultNumberOfNodes = 1, 
        defaultTimeAllocation = SimpleDuration(
            hours = 1, 
            minutes = 0, 
            seconds = 0, 
        ), 
        description = "A virtual machine tool", 
        image = "acme-operating-system", 
        info = NameAndVersion(
            name = "acme-batch", 
            version = "1.0.0", 
        ), 
        license = "None", 
        requiredModules = emptyList(), 
        supportedProviders = listOf("example"), 
        title = "Acme Operating System", 
    ), 
    modifiedAt = 1633329776235, 
    owner = "_ucloud", 
)
*/

Communication Flow: Curl

# ------------------------------------------------------------------------------------------------------
# $host is the UCloud instance to contact. Example: 'http://localhost:8080' or 'https://cloud.sdu.dk'
# $accessToken is a valid access-token issued by UCloud
# ------------------------------------------------------------------------------------------------------

# This example show an example Tool which uses a virtual machine backend. The Tool specifies that 
# the base image is "acme-operating-system". The provider decides how to retrieve these images. For 
# virtual machines, this is likely so dependant on the provider. As a result, we recommend using the 
# supportedProviders property. 

# Authenticated as user
curl -XGET -H "Authorization: Bearer $accessToken" "$host/api/hpc/tools/byNameAndVersion?name=acme-os&version=1.0.0" 

# {
#     "owner": "_ucloud",
#     "createdAt": 1633329776235,
#     "modifiedAt": 1633329776235,
#     "description": {
#         "info": {
#             "name": "acme-batch",
#             "version": "1.0.0"
#         },
#         "container": null,
#         "defaultNumberOfNodes": 1,
#         "defaultTimeAllocation": {
#             "hours": 1,
#             "minutes": 0,
#             "seconds": 0
#         },
#         "requiredModules": [
#         ],
#         "authors": [
#             "Acme Inc."
#         ],
#         "title": "Acme Operating System",
#         "description": "A virtual machine tool",
#         "backend": "VIRTUAL_MACHINE",
#         "license": "None",
#         "image": "acme-operating-system",
#         "supportedProviders": [
#             "example"
#         ]
#     }
# }

Communication Flow: Visual

Remote Procedure Calls¶

`fetchLogo`¶

Retrieves a logo associated with a Tool

Request	Response	Error
`FetchLogoRequest`	`Unit`	`CommonErrorMessage`

This endpoint might return 404 Not Found if the Tool has no logo

`findByName`¶

Finds a Page of Tools which share the same name

Request	Response	Error
`FindByNameAndPagination`	`Page<Tool>`	`CommonErrorMessage`

`findByNameAndVersion`¶

Finds a Tool by name and version

Request	Response	Error
`FindByNameAndVersion`	`Tool`	`CommonErrorMessage`

`listAll`¶

Queries the entire catalog of Tools

Request	Response	Error
`PaginationRequest`	`Page<Tool>`	`CommonErrorMessage`

This endpoint is not recommended for use and will likely disappear in a future release. The results are returned in no specific order.

`clearLogo`¶

Deletes an existing logo from a Tool

Request	Response	Error
`ClearLogoRequest`	`Unit`	`CommonErrorMessage`

`create`¶

Creates a new Tool and adds it to the internal catalog

Request	Response	Error
`Unit`	`Unit`	`CommonErrorMessage`

`uploadLogo`¶

Uploads a logo and associates it with a Tool

Request	Response	Error
`UploadApplicationLogoRequest`	`Unit`	`CommonErrorMessage`

Data Models¶

`Tool`¶

Tools define bundles of software binaries and other assets (e.g. container and virtual machine base-images).

data class Tool(
    val owner: String,
    val createdAt: Long,
    val modifiedAt: Long,
    val description: NormalizedToolDescription,
)

See Tools for a more complete discussion.

Properties

owner: String The username of the user who created this Tool

createdAt: Long Timestamp describing initial creation

modifiedAt: Long Timestamp describing most recent modification (Deprecated, Tools are immutable)

description: NormalizedToolDescription The specification for this Tool

`NormalizedToolDescription`¶

The specification of a Tool

data class NormalizedToolDescription(
    val info: NameAndVersion,
    val container: String?,
    val defaultNumberOfNodes: Int,
    val defaultTimeAllocation: SimpleDuration,
    val requiredModules: List<String>,
    val authors: List<String>,
    val title: String,
    val description: String,
    val backend: ToolBackend,
    val license: String,
    val image: String?,
    val supportedProviders: List<String>?,
)

Properties

info: NameAndVersion The unique name and version tuple

container: String? Deprecated, use image instead.

defaultNumberOfNodes: Int The default number of nodes

defaultTimeAllocation: SimpleDuration The default time allocation to use, if none is specified.

requiredModules: List<String> A list of required 'modules'

The provider decides how to interpret this value. It is intended to be used with a module system of traditional HPC systems.

authors: List<String> A list of authors

title: String A title for this Tool used for presentation purposes

description: String A description for this Tool used for presentation purposes

backend: ToolBackend The backend to use for this Tool

license: String A license used for this Tool. Used for presentation purposes.

image: String? The 'image' used for this Tool

This value depends on the backend used for the Tool:

DOCKER: The image is a container image. Typically follows the Docker format.
VIRTUAL_MACHINE: The image is a reference to a base-image

It is always up to the Provider how to interpret this value. We recommend using the supportedProviders property to ensure compatibility.

supportedProviders: List<String>? A list of supported Providers

This property determines which Providers are supported by this Tool. The backend will not allow a user to launch an Application which uses this Tool on a provider not listed in this value.

If no providers are supplied, then this Tool will implicitly support all Providers.

`FindByNameAndPagination`¶

Request type to find a Page of resources defined by a name

data class FindByNameAndPagination(
    val appName: String,
    val itemsPerPage: Int?,
    val page: Int?,
)

Properties

appName: String

itemsPerPage: Int?

page: Int?

`FindByNameAndVersion`¶

A request type to find a resource by name and version

data class FindByNameAndVersion(
    val name: String,
    val version: String,
)

Properties

name: String

version: String

`NameAndVersion`¶

A type describing a name and version tuple

data class NameAndVersion(
    val name: String,
    val version: String,
)

Properties

name: String

version: String

`SimpleDuration`¶

data class SimpleDuration(
    val hours: Int,
    val minutes: Int,
    val seconds: Int,
)

Properties

hours: Int

minutes: Int

seconds: Int

`ToolBackend`¶

enum class ToolBackend {
    SINGULARITY,
    DOCKER,
    VIRTUAL_MACHINE,
    NATIVE,
}

Properties

SINGULARITY

DOCKER

VIRTUAL_MACHINE

NATIVE

`ClearLogoRequest`¶

data class ClearLogoRequest(
    val name: String,
)

Properties

name: String

`FetchLogoRequest`¶

data class FetchLogoRequest(
    val name: String,
)

Properties

name: String

`UploadApplicationLogoRequest`¶

data class UploadApplicationLogoRequest(
    val name: String,
)

Properties

name: String

Tools¶

Rationale¶

Table of Contents¶

Example: Retrieve a container based Tool¶

Example: Retrieve a virtual machine based Tool¶

Remote Procedure Calls¶

fetchLogo¶

findByName¶

findByNameAndVersion¶

listAll¶

clearLogo¶

create¶

uploadLogo¶

Data Models¶

Tool¶

NormalizedToolDescription¶

FindByNameAndPagination¶

FindByNameAndVersion¶

NameAndVersion¶

SimpleDuration¶

ToolBackend¶

ClearLogoRequest¶

FetchLogoRequest¶

UploadApplicationLogoRequest¶

`fetchLogo`¶

`findByName`¶

`findByNameAndVersion`¶

`listAll`¶

`clearLogo`¶

`create`¶

`uploadLogo`¶

`Tool`¶

`NormalizedToolDescription`¶

`FindByNameAndPagination`¶

`FindByNameAndVersion`¶

`NameAndVersion`¶

`SimpleDuration`¶

`ToolBackend`¶

`ClearLogoRequest`¶

`FetchLogoRequest`¶

`UploadApplicationLogoRequest`¶