Tools

API: Experimental/Alpha

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 useCommon
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: TypeScript
/* 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
await callAPI(HpcToolsApi.findByNameAndVersion(
    {
        "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: 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 useCommon
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: TypeScript
/* 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
await callAPI(HpcToolsApi.findByNameAndVersion(
    {
        "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: 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

API: Experimental/Alpha Auth: Authenticated

Finds a Page of Tools which share the same name

Request Response Error
FindByNameAndPagination Page<Tool> CommonErrorMessage

findByNameAndVersion

API: Experimental/Alpha Auth: Authenticated

Finds a Tool by name and version

Request Response Error
FindByNameAndVersion Tool CommonErrorMessage

listAll

API: Experimental/Alpha Auth: Authenticated

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.

create

API: Experimental/Alpha Auth: SERVICE, ADMIN, PROVIDER

Creates a new Tool and adds it to the internal catalog

Request Response Error
Unit Unit CommonErrorMessage

Data Models

Tool

API: Internal/Beta

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)

Deprecated: Yes

description: NormalizedToolDescription The specification for this Tool

NormalizedToolDescription

API: Internal/Beta

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.

Deprecated: Yes

defaultNumberOfNodes: Int The default number of nodes

Deprecated: Yes

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

Deprecated: Yes

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

API: Internal/Beta

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

API: Internal/Beta

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

API: Internal/Beta

A type describing a name and version tuple

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

SimpleDuration

API: Internal/Beta

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

ToolBackend

API: Internal/Beta

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

ClearLogoRequest

API: Internal/Beta

data class ClearLogoRequest(
    val name: String,
)
Properties
name: String

FetchLogoRequest

API: Internal/Beta

data class FetchLogoRequest(
    val name: String,
)
Properties
name: String

UploadApplicationLogoRequest

API: Internal/Beta

data class UploadApplicationLogoRequest(
    val name: String,
)
Properties
name: String