tools

« Previous section Next section »

UCloud Developer Guide / Orchestration of Resources / Compute / Application Store / Tools

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

2. Remote Procedure Calls

3. Data Models

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

---

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

---

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

---

FindByNameAndVersion

A request type to find a resource by name and version

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

Properties

---

NameAndVersion

A type describing a name and version tuple

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

Properties

---

SimpleDuration

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

Properties

---

ToolBackend

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

Properties

---

ClearLogoRequest

data class ClearLogoRequest(
    val name: String,
)

Properties

---

FetchLogoRequest

data class FetchLogoRequest(
    val name: String,
)

Properties

---

UploadApplicationLogoRequest

data class UploadApplicationLogoRequest(
    val name: String,
)

Properties

---