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
findByName	Finds a Page of Tools which share the same name
findByNameAndVersion	Finds a Tool by name and version
create	Creates a new Tool and adds it to the internal catalog

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
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
FindByNameRequest	Request type to find a Page of resources defined by a name

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

findByName

Finds a Page of Tools which share the same name

Request	Response	Error
FindByNameRequest	Page<Tool>	CommonErrorMessage

findByNameAndVersion

Finds a Tool by name and version

Request	Response	Error
FindByNameAndVersion	Tool	CommonErrorMessage

create

Creates a new Tool and adds it to the internal catalog

Request	Response	Error
Unit	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.

---

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

---

FindByNameRequest

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

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

Properties

appName: String

itemsPerPage: Int?

page: Int?

---