Applications

API: Experimental/Alpha

Applications specify the input parameters and invocation of a software package.

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.

In concrete terms, the “invocation” of an Application covers:


⚠️ 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
Simple batch application
Simple virtual machine
Simple web application
Simple remote desktop application (VNC)
Registering a file handler
An Application with default values
2. Remote Procedure Calls
Name Description
advancedSearch Searches in the Application catalog using more advanced parameters
create Creates a new Application and inserts it into the catalog
fetchLogo Retrieves a logo associated with an Application
findByName Finds Applications given an exact name
findByNameAndVersion Retrieves an Application by name and version
findBySupportedFileExtension Finds a page of Application which can open a specific UFile
findLatestByTool Retrieves the latest version of an Application using a specific tool
hasPermission Check if an entity has permission to use a specific Application
isPublic Checks if an Application is publicly accessible
listAcl Retrieves the permission information associated with an Application
listAll Lists all Applications
retrieveFavorites Retrieves the list of favorite Applications for the curent user
searchApps Searches in the Application catalog using a free-text query
searchTags Browses the Application catalog by tag
clearLogo Removes a logo associated with an Application
createTag Attaches a set of tags to an Application
delete Removes an Application from the catalog
removeTag Removes a set of tags from an Application
setPublic Changes the 'publicly accessible' status of an Application
toggleFavorite Toggles the favorite status of an Application for the current user
updateAcl Updates the permissions associated with an Application
uploadLogo Uploads a logo and associates it with an Application
3. Data Models
Name Description
Application Applications specify the input parameters and invocation of a software package.
ApplicationMetadata Metadata associated with an Application
ApplicationInvocationDescription The specification for how to invoke an Application
ApplicationType The ApplicationType determines how user's interact with an Application
VncDescription Information to the Provider about how to reach the VNC services
WebDescription Information to the Provider about how to reach the web services
ContainerDescription Information to the Provider about how to launch the container
ApplicationParameter An ApplicationParameter describe a single input parameter to an Application.
ApplicationParameter.TextArea An ApplicationParameter describe a single input parameter to an Application.
ApplicationParameter.Bool An input parameter which accepts any boolean value
ApplicationParameter.Enumeration An input parameter which accepts an enum
ApplicationParameter.FloatingPoint An input parameter which accepts any floating point value
ApplicationParameter.Ingress An input parameter which accepts a ingress (public link)
ApplicationParameter.InputDirectory An input parameter which accepts UFiles of type `DIRECTORY`
ApplicationParameter.InputFile An input parameter which accepts UFiles of type `FILE`
ApplicationParameter.Integer An input parameter which accepts any integer value
ApplicationParameter.LicenseServer An input parameter which accepts a license
ApplicationParameter.NetworkIP An input parameter which accepts an IP address
ApplicationParameter.Peer An input parameter which accepts a peering Job
ApplicationParameter.Text An input parameter which accepts text
AppParameterValue An `AppParameterValue` is value which is supplied to a parameter of an `Application`.
AppParameterValue.BlockStorage A reference to block storage (Not yet implemented)
AppParameterValue.Bool A boolean value (true or false)
AppParameterValue.File A reference to a UCloud file
AppParameterValue.FloatingPoint A floating point value
AppParameterValue.Ingress A reference to an HTTP ingress, registered locally at the provider
AppParameterValue.Integer An integral value
AppParameterValue.License A reference to a software license, registered locally at the provider
AppParameterValue.Network A reference to block storage (Not yet implemented)
AppParameterValue.Peer A reference to a separate UCloud `Job`
AppParameterValue.Text A textual value
InvocationParameter InvocationParameters supply values to either the command-line or environment variables.
BooleanFlagParameter Produces a toggleable command-line flag
EnvironmentVariableParameter Produces an environment variable (TODO Documentation)
VariableInvocationParameter An InvocationParameter which produces value(s) from parameters.
WordInvocationParameter A static value for an InvocationParameter
AccessEntity No description
AppParameterValue.TextArea A textual value
ApplicationAccessRight No description
ApplicationParameter.EnumOption No description
ApplicationSummaryWithFavorite Applications specify the input parameters and invocation of a software package.
ApplicationWithExtension Applications specify the input parameters and invocation of a software package.
ApplicationWithFavoriteAndTags Applications specify the input parameters and invocation of a software package.
DetailedAccessEntity No description
DetailedEntityWithPermission No description
FindApplicationAndOptionalDependencies No description
FindBySupportedFileExtension The base type for requesting paginated content.
Project No description
SshDescription Information to the provider about the SSH capabilities of this application
SshDescription.Mode No description
ToolReference A reference to a Tool
ACLEntryRequest No description
AdvancedSearchRequest No description
AppSearchRequest No description
CreateTagsRequest No description
DeleteAppRequest No description
FavoriteRequest No description
FindLatestByToolRequest No description
HasPermissionRequest No description
IsPublicRequest No description
ListAclRequest No description
SetPublicRequest No description
TagSearchRequest No description
UpdateAclRequest No description
IsPublicResponse No description

Example: Simple batch application

Frequency of useCommon
Actors
  • An authenticated user (user)
Communication Flow: Kotlin
/* Applications contain quite a lot of information. The most important pieces of information are
summarized below:

- This Job will run a `BATCH` application
  - See `invocation.applicationType`
  
- The application should launch the `acme/batch:1.0.0` container
  - `invocation.tool.tool.description.backend`
  - `invocation.tool.tool.description.image`
  
- The command-line invocation will look like this: `acme-batch --debug "Hello, World!"`. 
  - The invocation is created from `invocation.invocation`
  - With parameters defined in `invocation.parameters` */

AppStore.findByNameAndVersion.call(
    FindApplicationAndOptionalDependencies(
        appName = "acme-batch", 
        appVersion = "1.0.0", 
    ),
    user
).orThrow()

/*
ApplicationWithFavoriteAndTags(
    favorite = false, 
    invocation = ApplicationInvocationDescription(
        allowAdditionalMounts = null, 
        allowAdditionalPeers = null, 
        allowMultiNode = false, 
        allowPublicIp = false, 
        allowPublicLink = null, 
        applicationType = ApplicationType.BATCH, 
        container = null, 
        environment = null, 
        fileExtensions = emptyList(), 
        invocation = listOf(WordInvocationParameter(
            word = "acme-batch", 
        ), VariableInvocationParameter(
            isPrefixVariablePartOfArg = false, 
            isSuffixVariablePartOfArg = false, 
            prefixGlobal = "--debug ", 
            prefixVariable = "", 
            suffixGlobal = "", 
            suffixVariable = "", 
            variableNames = listOf("debug"), 
        ), VariableInvocationParameter(
            isPrefixVariablePartOfArg = false, 
            isSuffixVariablePartOfArg = false, 
            prefixGlobal = "", 
            prefixVariable = "", 
            suffixGlobal = "", 
            suffixVariable = "", 
            variableNames = listOf("value"), 
        )), 
        licenseServers = emptyList(), 
        outputFileGlobs = listOf("*"), 
        parameters = listOf(ApplicationParameter.Bool(
            defaultValue = null, 
            description = "Should debug be enabled?", 
            falseValue = "false", 
            name = "debug", 
            optional = false, 
            title = "", 
            trueValue = "true", 
        ), ApplicationParameter.Text(
            defaultValue = null, 
            description = "The value for the batch application", 
            name = "value", 
            optional = false, 
            title = "", 
        )), 
        shouldAllowAdditionalMounts = false, 
        shouldAllowAdditionalPeers = true, 
        ssh = null, 
        tool = ToolReference(
            name = "acme-batch", 
            tool = Tool(
                createdAt = 1633329776235, 
                description = NormalizedToolDescription(
                    authors = listOf("UCloud"), 
                    backend = ToolBackend.DOCKER, 
                    container = null, 
                    defaultNumberOfNodes = 1, 
                    defaultTimeAllocation = SimpleDuration(
                        hours = 1, 
                        minutes = 0, 
                        seconds = 0, 
                    ), 
                    description = "An example 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", 
            ), 
            version = "1.0.0", 
        ), 
        vnc = null, 
        web = null, 
    ), 
    metadata = ApplicationMetadata(
        authors = listOf("UCloud"), 
        description = "An example application", 
        isPublic = true, 
        name = "acme-batch", 
        public = true, 
        title = "Acme batch", 
        version = "1.0.0", 
        website = null, 
    ), 
    tags = emptyList(), 
)
*/
Communication Flow: TypeScript
/* Applications contain quite a lot of information. The most important pieces of information are
summarized below:

- This Job will run a `BATCH` application
  - See `invocation.applicationType`
  
- The application should launch the `acme/batch:1.0.0` container
  - `invocation.tool.tool.description.backend`
  - `invocation.tool.tool.description.image`
  
- The command-line invocation will look like this: `acme-batch --debug "Hello, World!"`. 
  - The invocation is created from `invocation.invocation`
  - With parameters defined in `invocation.parameters` */

// Authenticated as user
await callAPI(HpcAppsApi.findByNameAndVersion(
    {
        "appName": "acme-batch",
        "appVersion": "1.0.0"
    }
);

/*
{
    "metadata": {
        "name": "acme-batch",
        "version": "1.0.0",
        "authors": [
            "UCloud"
        ],
        "title": "Acme batch",
        "description": "An example application",
        "website": null,
        "public": true
    },
    "invocation": {
        "tool": {
            "name": "acme-batch",
            "version": "1.0.0",
            "tool": {
                "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": [
                        "UCloud"
                    ],
                    "title": "Acme batch",
                    "description": "An example tool",
                    "backend": "DOCKER",
                    "license": "None",
                    "image": "acme/batch:1.0.0",
                    "supportedProviders": null
                }
            }
        },
        "invocation": [
            {
                "type": "word",
                "word": "acme-batch"
            },
            {
                "type": "var",
                "variableNames": [
                    "debug"
                ],
                "prefixGlobal": "--debug ",
                "suffixGlobal": "",
                "prefixVariable": "",
                "suffixVariable": "",
                "isPrefixVariablePartOfArg": false,
                "isSuffixVariablePartOfArg": false
            },
            {
                "type": "var",
                "variableNames": [
                    "value"
                ],
                "prefixGlobal": "",
                "suffixGlobal": "",
                "prefixVariable": "",
                "suffixVariable": "",
                "isPrefixVariablePartOfArg": false,
                "isSuffixVariablePartOfArg": false
            }
        ],
        "parameters": [
            {
                "type": "boolean",
                "name": "debug",
                "optional": false,
                "defaultValue": null,
                "title": "",
                "description": "Should debug be enabled?",
                "trueValue": "true",
                "falseValue": "false"
            },
            {
                "type": "text",
                "name": "value",
                "optional": false,
                "defaultValue": null,
                "title": "",
                "description": "The value for the batch application"
            }
        ],
        "outputFileGlobs": [
            "*"
        ],
        "applicationType": "BATCH",
        "vnc": null,
        "web": null,
        "ssh": null,
        "container": null,
        "environment": null,
        "allowAdditionalMounts": null,
        "allowAdditionalPeers": null,
        "allowMultiNode": false,
        "allowPublicIp": false,
        "allowPublicLink": null,
        "fileExtensions": [
        ],
        "licenseServers": [
        ]
    },
    "favorite": false,
    "tags": [
    ]
}
*/
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
# ------------------------------------------------------------------------------------------------------

# Applications contain quite a lot of information. The most important pieces of information are
# summarized below:
# 
# - This Job will run a `BATCH` application
#   - See `invocation.applicationType`
#   
# - The application should launch the `acme/batch:1.0.0` container
#   - `invocation.tool.tool.description.backend`
#   - `invocation.tool.tool.description.image`
#   
# - The command-line invocation will look like this: `acme-batch --debug "Hello, World!"`. 
#   - The invocation is created from `invocation.invocation`
#   - With parameters defined in `invocation.parameters`

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

# {
#     "metadata": {
#         "name": "acme-batch",
#         "version": "1.0.0",
#         "authors": [
#             "UCloud"
#         ],
#         "title": "Acme batch",
#         "description": "An example application",
#         "website": null,
#         "public": true
#     },
#     "invocation": {
#         "tool": {
#             "name": "acme-batch",
#             "version": "1.0.0",
#             "tool": {
#                 "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": [
#                         "UCloud"
#                     ],
#                     "title": "Acme batch",
#                     "description": "An example tool",
#                     "backend": "DOCKER",
#                     "license": "None",
#                     "image": "acme/batch:1.0.0",
#                     "supportedProviders": null
#                 }
#             }
#         },
#         "invocation": [
#             {
#                 "type": "word",
#                 "word": "acme-batch"
#             },
#             {
#                 "type": "var",
#                 "variableNames": [
#                     "debug"
#                 ],
#                 "prefixGlobal": "--debug ",
#                 "suffixGlobal": "",
#                 "prefixVariable": "",
#                 "suffixVariable": "",
#                 "isPrefixVariablePartOfArg": false,
#                 "isSuffixVariablePartOfArg": false
#             },
#             {
#                 "type": "var",
#                 "variableNames": [
#                     "value"
#                 ],
#                 "prefixGlobal": "",
#                 "suffixGlobal": "",
#                 "prefixVariable": "",
#                 "suffixVariable": "",
#                 "isPrefixVariablePartOfArg": false,
#                 "isSuffixVariablePartOfArg": false
#             }
#         ],
#         "parameters": [
#             {
#                 "type": "boolean",
#                 "name": "debug",
#                 "optional": false,
#                 "defaultValue": null,
#                 "title": "",
#                 "description": "Should debug be enabled?",
#                 "trueValue": "true",
#                 "falseValue": "false"
#             },
#             {
#                 "type": "text",
#                 "name": "value",
#                 "optional": false,
#                 "defaultValue": null,
#                 "title": "",
#                 "description": "The value for the batch application"
#             }
#         ],
#         "outputFileGlobs": [
#             "*"
#         ],
#         "applicationType": "BATCH",
#         "vnc": null,
#         "web": null,
#         "ssh": null,
#         "container": null,
#         "environment": null,
#         "allowAdditionalMounts": null,
#         "allowAdditionalPeers": null,
#         "allowMultiNode": false,
#         "allowPublicIp": false,
#         "allowPublicLink": null,
#         "fileExtensions": [
#         ],
#         "licenseServers": [
#         ]
#     },
#     "favorite": false,
#     "tags": [
#     ]
# }
Communication Flow: Visual

Example: Simple virtual machine

Frequency of useCommon
Actors
  • An authenticated user (user)
Communication Flow: Kotlin
/* This example shows an Application encoding a virtual machine. It will use the
"acme-operating-system" as its base image, as defined in the Tool.  */

AppStore.findByNameAndVersion.call(
    FindApplicationAndOptionalDependencies(
        appName = "acme-os", 
        appVersion = "1.0.0", 
    ),
    user
).orThrow()

/*
ApplicationWithFavoriteAndTags(
    favorite = false, 
    invocation = ApplicationInvocationDescription(
        allowAdditionalMounts = null, 
        allowAdditionalPeers = null, 
        allowMultiNode = false, 
        allowPublicIp = false, 
        allowPublicLink = null, 
        applicationType = ApplicationType.BATCH, 
        container = null, 
        environment = null, 
        fileExtensions = emptyList(), 
        invocation = emptyList(), 
        licenseServers = emptyList(), 
        outputFileGlobs = listOf("*"), 
        parameters = emptyList(), 
        shouldAllowAdditionalMounts = false, 
        shouldAllowAdditionalPeers = true, 
        ssh = null, 
        tool = ToolReference(
            name = "acme-os", 
            tool = Tool(
                createdAt = 1633329776235, 
                description = NormalizedToolDescription(
                    authors = listOf("UCloud"), 
                    backend = ToolBackend.VIRTUAL_MACHINE, 
                    container = null, 
                    defaultNumberOfNodes = 1, 
                    defaultTimeAllocation = SimpleDuration(
                        hours = 1, 
                        minutes = 0, 
                        seconds = 0, 
                    ), 
                    description = "An example tool", 
                    image = "acme-operating-system", 
                    info = NameAndVersion(
                        name = "acme-os", 
                        version = "1.0.0", 
                    ), 
                    license = "None", 
                    requiredModules = emptyList(), 
                    supportedProviders = null, 
                    title = "Acme os", 
                ), 
                modifiedAt = 1633329776235, 
                owner = "_ucloud", 
            ), 
            version = "1.0.0", 
        ), 
        vnc = null, 
        web = null, 
    ), 
    metadata = ApplicationMetadata(
        authors = listOf("UCloud"), 
        description = "An example application", 
        isPublic = true, 
        name = "acme-os", 
        public = true, 
        title = "Acme os", 
        version = "1.0.0", 
        website = null, 
    ), 
    tags = emptyList(), 
)
*/
Communication Flow: TypeScript
/* This example shows an Application encoding a virtual machine. It will use the
"acme-operating-system" as its base image, as defined in the Tool.  */

// Authenticated as user
await callAPI(HpcAppsApi.findByNameAndVersion(
    {
        "appName": "acme-os",
        "appVersion": "1.0.0"
    }
);

/*
{
    "metadata": {
        "name": "acme-os",
        "version": "1.0.0",
        "authors": [
            "UCloud"
        ],
        "title": "Acme os",
        "description": "An example application",
        "website": null,
        "public": true
    },
    "invocation": {
        "tool": {
            "name": "acme-os",
            "version": "1.0.0",
            "tool": {
                "owner": "_ucloud",
                "createdAt": 1633329776235,
                "modifiedAt": 1633329776235,
                "description": {
                    "info": {
                        "name": "acme-os",
                        "version": "1.0.0"
                    },
                    "container": null,
                    "defaultNumberOfNodes": 1,
                    "defaultTimeAllocation": {
                        "hours": 1,
                        "minutes": 0,
                        "seconds": 0
                    },
                    "requiredModules": [
                    ],
                    "authors": [
                        "UCloud"
                    ],
                    "title": "Acme os",
                    "description": "An example tool",
                    "backend": "VIRTUAL_MACHINE",
                    "license": "None",
                    "image": "acme-operating-system",
                    "supportedProviders": null
                }
            }
        },
        "invocation": [
        ],
        "parameters": [
        ],
        "outputFileGlobs": [
            "*"
        ],
        "applicationType": "BATCH",
        "vnc": null,
        "web": null,
        "ssh": null,
        "container": null,
        "environment": null,
        "allowAdditionalMounts": null,
        "allowAdditionalPeers": null,
        "allowMultiNode": false,
        "allowPublicIp": false,
        "allowPublicLink": null,
        "fileExtensions": [
        ],
        "licenseServers": [
        ]
    },
    "favorite": false,
    "tags": [
    ]
}
*/
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 shows an Application encoding a virtual machine. It will use the
# "acme-operating-system" as its base image, as defined in the Tool. 

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

# {
#     "metadata": {
#         "name": "acme-os",
#         "version": "1.0.0",
#         "authors": [
#             "UCloud"
#         ],
#         "title": "Acme os",
#         "description": "An example application",
#         "website": null,
#         "public": true
#     },
#     "invocation": {
#         "tool": {
#             "name": "acme-os",
#             "version": "1.0.0",
#             "tool": {
#                 "owner": "_ucloud",
#                 "createdAt": 1633329776235,
#                 "modifiedAt": 1633329776235,
#                 "description": {
#                     "info": {
#                         "name": "acme-os",
#                         "version": "1.0.0"
#                     },
#                     "container": null,
#                     "defaultNumberOfNodes": 1,
#                     "defaultTimeAllocation": {
#                         "hours": 1,
#                         "minutes": 0,
#                         "seconds": 0
#                     },
#                     "requiredModules": [
#                     ],
#                     "authors": [
#                         "UCloud"
#                     ],
#                     "title": "Acme os",
#                     "description": "An example tool",
#                     "backend": "VIRTUAL_MACHINE",
#                     "license": "None",
#                     "image": "acme-operating-system",
#                     "supportedProviders": null
#                 }
#             }
#         },
#         "invocation": [
#         ],
#         "parameters": [
#         ],
#         "outputFileGlobs": [
#             "*"
#         ],
#         "applicationType": "BATCH",
#         "vnc": null,
#         "web": null,
#         "ssh": null,
#         "container": null,
#         "environment": null,
#         "allowAdditionalMounts": null,
#         "allowAdditionalPeers": null,
#         "allowMultiNode": false,
#         "allowPublicIp": false,
#         "allowPublicLink": null,
#         "fileExtensions": [
#         ],
#         "licenseServers": [
#         ]
#     },
#     "favorite": false,
#     "tags": [
#     ]
# }
Communication Flow: Visual

Example: Simple web application

Frequency of useCommon
Actors
  • An authenticated user (user)
Communication Flow: Kotlin
/* This example shows an Application with a graphical web interface. The web server, hosting the 
interface, runs on port 8080 as defined in the `invocation.web` section. */

AppStore.findByNameAndVersion.call(
    FindApplicationAndOptionalDependencies(
        appName = "acme-web", 
        appVersion = "1.0.0", 
    ),
    user
).orThrow()

/*
ApplicationWithFavoriteAndTags(
    favorite = false, 
    invocation = ApplicationInvocationDescription(
        allowAdditionalMounts = null, 
        allowAdditionalPeers = null, 
        allowMultiNode = false, 
        allowPublicIp = false, 
        allowPublicLink = null, 
        applicationType = ApplicationType.WEB, 
        container = null, 
        environment = null, 
        fileExtensions = emptyList(), 
        invocation = listOf(WordInvocationParameter(
            word = "web-server", 
        )), 
        licenseServers = emptyList(), 
        outputFileGlobs = listOf("*"), 
        parameters = emptyList(), 
        shouldAllowAdditionalMounts = true, 
        shouldAllowAdditionalPeers = true, 
        ssh = null, 
        tool = ToolReference(
            name = "acme-web", 
            tool = Tool(
                createdAt = 1633329776235, 
                description = NormalizedToolDescription(
                    authors = listOf("UCloud"), 
                    backend = ToolBackend.DOCKER, 
                    container = null, 
                    defaultNumberOfNodes = 1, 
                    defaultTimeAllocation = SimpleDuration(
                        hours = 1, 
                        minutes = 0, 
                        seconds = 0, 
                    ), 
                    description = "An example tool", 
                    image = "acme/web:1.0.0", 
                    info = NameAndVersion(
                        name = "acme-web", 
                        version = "1.0.0", 
                    ), 
                    license = "None", 
                    requiredModules = emptyList(), 
                    supportedProviders = null, 
                    title = "Acme web", 
                ), 
                modifiedAt = 1633329776235, 
                owner = "_ucloud", 
            ), 
            version = "1.0.0", 
        ), 
        vnc = null, 
        web = WebDescription(
            port = 8080, 
        ), 
    ), 
    metadata = ApplicationMetadata(
        authors = listOf("UCloud"), 
        description = "An example application", 
        isPublic = true, 
        name = "acme-web", 
        public = true, 
        title = "Acme web", 
        version = "1.0.0", 
        website = null, 
    ), 
    tags = emptyList(), 
)
*/
Communication Flow: TypeScript
/* This example shows an Application with a graphical web interface. The web server, hosting the 
interface, runs on port 8080 as defined in the `invocation.web` section. */

// Authenticated as user
await callAPI(HpcAppsApi.findByNameAndVersion(
    {
        "appName": "acme-web",
        "appVersion": "1.0.0"
    }
);

/*
{
    "metadata": {
        "name": "acme-web",
        "version": "1.0.0",
        "authors": [
            "UCloud"
        ],
        "title": "Acme web",
        "description": "An example application",
        "website": null,
        "public": true
    },
    "invocation": {
        "tool": {
            "name": "acme-web",
            "version": "1.0.0",
            "tool": {
                "owner": "_ucloud",
                "createdAt": 1633329776235,
                "modifiedAt": 1633329776235,
                "description": {
                    "info": {
                        "name": "acme-web",
                        "version": "1.0.0"
                    },
                    "container": null,
                    "defaultNumberOfNodes": 1,
                    "defaultTimeAllocation": {
                        "hours": 1,
                        "minutes": 0,
                        "seconds": 0
                    },
                    "requiredModules": [
                    ],
                    "authors": [
                        "UCloud"
                    ],
                    "title": "Acme web",
                    "description": "An example tool",
                    "backend": "DOCKER",
                    "license": "None",
                    "image": "acme/web:1.0.0",
                    "supportedProviders": null
                }
            }
        },
        "invocation": [
            {
                "type": "word",
                "word": "web-server"
            }
        ],
        "parameters": [
        ],
        "outputFileGlobs": [
            "*"
        ],
        "applicationType": "WEB",
        "vnc": null,
        "web": {
            "port": 8080
        },
        "ssh": null,
        "container": null,
        "environment": null,
        "allowAdditionalMounts": null,
        "allowAdditionalPeers": null,
        "allowMultiNode": false,
        "allowPublicIp": false,
        "allowPublicLink": null,
        "fileExtensions": [
        ],
        "licenseServers": [
        ]
    },
    "favorite": false,
    "tags": [
    ]
}
*/
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 shows an Application with a graphical web interface. The web server, hosting the 
# interface, runs on port 8080 as defined in the `invocation.web` section.

# Authenticated as user
curl -XGET -H "Authorization: Bearer $accessToken" "$host/api/hpc/apps/byNameAndVersion?appName=acme-web&appVersion=1.0.0" 

# {
#     "metadata": {
#         "name": "acme-web",
#         "version": "1.0.0",
#         "authors": [
#             "UCloud"
#         ],
#         "title": "Acme web",
#         "description": "An example application",
#         "website": null,
#         "public": true
#     },
#     "invocation": {
#         "tool": {
#             "name": "acme-web",
#             "version": "1.0.0",
#             "tool": {
#                 "owner": "_ucloud",
#                 "createdAt": 1633329776235,
#                 "modifiedAt": 1633329776235,
#                 "description": {
#                     "info": {
#                         "name": "acme-web",
#                         "version": "1.0.0"
#                     },
#                     "container": null,
#                     "defaultNumberOfNodes": 1,
#                     "defaultTimeAllocation": {
#                         "hours": 1,
#                         "minutes": 0,
#                         "seconds": 0
#                     },
#                     "requiredModules": [
#                     ],
#                     "authors": [
#                         "UCloud"
#                     ],
#                     "title": "Acme web",
#                     "description": "An example tool",
#                     "backend": "DOCKER",
#                     "license": "None",
#                     "image": "acme/web:1.0.0",
#                     "supportedProviders": null
#                 }
#             }
#         },
#         "invocation": [
#             {
#                 "type": "word",
#                 "word": "web-server"
#             }
#         ],
#         "parameters": [
#         ],
#         "outputFileGlobs": [
#             "*"
#         ],
#         "applicationType": "WEB",
#         "vnc": null,
#         "web": {
#             "port": 8080
#         },
#         "ssh": null,
#         "container": null,
#         "environment": null,
#         "allowAdditionalMounts": null,
#         "allowAdditionalPeers": null,
#         "allowMultiNode": false,
#         "allowPublicIp": false,
#         "allowPublicLink": null,
#         "fileExtensions": [
#         ],
#         "licenseServers": [
#         ]
#     },
#     "favorite": false,
#     "tags": [
#     ]
# }
Communication Flow: Visual

Example: Simple remote desktop application (VNC)

Frequency of useCommon
Actors
  • An authenticated user (user)
Communication Flow: Kotlin
/* This example shows an Application with a graphical web interface. The VNC server, hosting the 
interface, runs on port 5900 as defined in the `invocation.vnc` section. */

AppStore.findByNameAndVersion.call(
    FindApplicationAndOptionalDependencies(
        appName = "acme-remote-desktop", 
        appVersion = "1.0.0", 
    ),
    user
).orThrow()

/*
ApplicationWithFavoriteAndTags(
    favorite = false, 
    invocation = ApplicationInvocationDescription(
        allowAdditionalMounts = null, 
        allowAdditionalPeers = null, 
        allowMultiNode = false, 
        allowPublicIp = false, 
        allowPublicLink = null, 
        applicationType = ApplicationType.VNC, 
        container = null, 
        environment = null, 
        fileExtensions = emptyList(), 
        invocation = listOf(WordInvocationParameter(
            word = "vnc-server", 
        )), 
        licenseServers = emptyList(), 
        outputFileGlobs = listOf("*"), 
        parameters = emptyList(), 
        shouldAllowAdditionalMounts = true, 
        shouldAllowAdditionalPeers = true, 
        ssh = null, 
        tool = ToolReference(
            name = "acme-remote-desktop", 
            tool = Tool(
                createdAt = 1633329776235, 
                description = NormalizedToolDescription(
                    authors = listOf("UCloud"), 
                    backend = ToolBackend.DOCKER, 
                    container = null, 
                    defaultNumberOfNodes = 1, 
                    defaultTimeAllocation = SimpleDuration(
                        hours = 1, 
                        minutes = 0, 
                        seconds = 0, 
                    ), 
                    description = "An example tool", 
                    image = "acme/remote-desktop:1.0.0", 
                    info = NameAndVersion(
                        name = "acme-remote-desktop", 
                        version = "1.0.0", 
                    ), 
                    license = "None", 
                    requiredModules = emptyList(), 
                    supportedProviders = null, 
                    title = "Acme remote desktop", 
                ), 
                modifiedAt = 1633329776235, 
                owner = "_ucloud", 
            ), 
            version = "1.0.0", 
        ), 
        vnc = VncDescription(
            password = null, 
            port = 5900, 
        ), 
        web = null, 
    ), 
    metadata = ApplicationMetadata(
        authors = listOf("UCloud"), 
        description = "An example application", 
        isPublic = true, 
        name = "acme-remote-desktop", 
        public = true, 
        title = "Acme remote desktop", 
        version = "1.0.0", 
        website = null, 
    ), 
    tags = emptyList(), 
)
*/
Communication Flow: TypeScript
/* This example shows an Application with a graphical web interface. The VNC server, hosting the 
interface, runs on port 5900 as defined in the `invocation.vnc` section. */

// Authenticated as user
await callAPI(HpcAppsApi.findByNameAndVersion(
    {
        "appName": "acme-remote-desktop",
        "appVersion": "1.0.0"
    }
);

/*
{
    "metadata": {
        "name": "acme-remote-desktop",
        "version": "1.0.0",
        "authors": [
            "UCloud"
        ],
        "title": "Acme remote desktop",
        "description": "An example application",
        "website": null,
        "public": true
    },
    "invocation": {
        "tool": {
            "name": "acme-remote-desktop",
            "version": "1.0.0",
            "tool": {
                "owner": "_ucloud",
                "createdAt": 1633329776235,
                "modifiedAt": 1633329776235,
                "description": {
                    "info": {
                        "name": "acme-remote-desktop",
                        "version": "1.0.0"
                    },
                    "container": null,
                    "defaultNumberOfNodes": 1,
                    "defaultTimeAllocation": {
                        "hours": 1,
                        "minutes": 0,
                        "seconds": 0
                    },
                    "requiredModules": [
                    ],
                    "authors": [
                        "UCloud"
                    ],
                    "title": "Acme remote desktop",
                    "description": "An example tool",
                    "backend": "DOCKER",
                    "license": "None",
                    "image": "acme/remote-desktop:1.0.0",
                    "supportedProviders": null
                }
            }
        },
        "invocation": [
            {
                "type": "word",
                "word": "vnc-server"
            }
        ],
        "parameters": [
        ],
        "outputFileGlobs": [
            "*"
        ],
        "applicationType": "VNC",
        "vnc": {
            "password": null,
            "port": 5900
        },
        "web": null,
        "ssh": null,
        "container": null,
        "environment": null,
        "allowAdditionalMounts": null,
        "allowAdditionalPeers": null,
        "allowMultiNode": false,
        "allowPublicIp": false,
        "allowPublicLink": null,
        "fileExtensions": [
        ],
        "licenseServers": [
        ]
    },
    "favorite": false,
    "tags": [
    ]
}
*/
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 shows an Application with a graphical web interface. The VNC server, hosting the 
# interface, runs on port 5900 as defined in the `invocation.vnc` section.

# Authenticated as user
curl -XGET -H "Authorization: Bearer $accessToken" "$host/api/hpc/apps/byNameAndVersion?appName=acme-remote-desktop&appVersion=1.0.0" 

# {
#     "metadata": {
#         "name": "acme-remote-desktop",
#         "version": "1.0.0",
#         "authors": [
#             "UCloud"
#         ],
#         "title": "Acme remote desktop",
#         "description": "An example application",
#         "website": null,
#         "public": true
#     },
#     "invocation": {
#         "tool": {
#             "name": "acme-remote-desktop",
#             "version": "1.0.0",
#             "tool": {
#                 "owner": "_ucloud",
#                 "createdAt": 1633329776235,
#                 "modifiedAt": 1633329776235,
#                 "description": {
#                     "info": {
#                         "name": "acme-remote-desktop",
#                         "version": "1.0.0"
#                     },
#                     "container": null,
#                     "defaultNumberOfNodes": 1,
#                     "defaultTimeAllocation": {
#                         "hours": 1,
#                         "minutes": 0,
#                         "seconds": 0
#                     },
#                     "requiredModules": [
#                     ],
#                     "authors": [
#                         "UCloud"
#                     ],
#                     "title": "Acme remote desktop",
#                     "description": "An example tool",
#                     "backend": "DOCKER",
#                     "license": "None",
#                     "image": "acme/remote-desktop:1.0.0",
#                     "supportedProviders": null
#                 }
#             }
#         },
#         "invocation": [
#             {
#                 "type": "word",
#                 "word": "vnc-server"
#             }
#         ],
#         "parameters": [
#         ],
#         "outputFileGlobs": [
#             "*"
#         ],
#         "applicationType": "VNC",
#         "vnc": {
#             "password": null,
#             "port": 5900
#         },
#         "web": null,
#         "ssh": null,
#         "container": null,
#         "environment": null,
#         "allowAdditionalMounts": null,
#         "allowAdditionalPeers": null,
#         "allowMultiNode": false,
#         "allowPublicIp": false,
#         "allowPublicLink": null,
#         "fileExtensions": [
#         ],
#         "licenseServers": [
#         ]
#     },
#     "favorite": false,
#     "tags": [
#     ]
# }
Communication Flow: Visual

Example: Registering a file handler

Frequency of useCommon
Actors
  • An authenticated user (user)
Communication Flow: Kotlin
/* This example shows an Application with a graphical web interface. The web server, hosting the 
interface, runs on port 8080 as defined in the `invocation.web` section. */


/* The Application also registers a file handler of all files with the `*.c` extension. This is used as
a hint for the frontend that files with this extension can be opened with this Application. When
opened like this, the file's parent folder will be mounted as a resource. */

AppStore.findByNameAndVersion.call(
    FindApplicationAndOptionalDependencies(
        appName = "acme-web", 
        appVersion = "1.0.0", 
    ),
    user
).orThrow()

/*
ApplicationWithFavoriteAndTags(
    favorite = false, 
    invocation = ApplicationInvocationDescription(
        allowAdditionalMounts = null, 
        allowAdditionalPeers = null, 
        allowMultiNode = false, 
        allowPublicIp = false, 
        allowPublicLink = null, 
        applicationType = ApplicationType.WEB, 
        container = null, 
        environment = null, 
        fileExtensions = listOf(".c"), 
        invocation = listOf(WordInvocationParameter(
            word = "web-server", 
        )), 
        licenseServers = emptyList(), 
        outputFileGlobs = listOf("*"), 
        parameters = emptyList(), 
        shouldAllowAdditionalMounts = true, 
        shouldAllowAdditionalPeers = true, 
        ssh = null, 
        tool = ToolReference(
            name = "acme-web", 
            tool = Tool(
                createdAt = 1633329776235, 
                description = NormalizedToolDescription(
                    authors = listOf("UCloud"), 
                    backend = ToolBackend.DOCKER, 
                    container = null, 
                    defaultNumberOfNodes = 1, 
                    defaultTimeAllocation = SimpleDuration(
                        hours = 1, 
                        minutes = 0, 
                        seconds = 0, 
                    ), 
                    description = "An example tool", 
                    image = "acme/web:1.0.0", 
                    info = NameAndVersion(
                        name = "acme-web", 
                        version = "1.0.0", 
                    ), 
                    license = "None", 
                    requiredModules = emptyList(), 
                    supportedProviders = null, 
                    title = "Acme web", 
                ), 
                modifiedAt = 1633329776235, 
                owner = "_ucloud", 
            ), 
            version = "1.0.0", 
        ), 
        vnc = null, 
        web = WebDescription(
            port = 8080, 
        ), 
    ), 
    metadata = ApplicationMetadata(
        authors = listOf("UCloud"), 
        description = "An example application", 
        isPublic = true, 
        name = "acme-web", 
        public = true, 
        title = "Acme web", 
        version = "1.0.0", 
        website = null, 
    ), 
    tags = emptyList(), 
)
*/
Communication Flow: TypeScript
/* This example shows an Application with a graphical web interface. The web server, hosting the 
interface, runs on port 8080 as defined in the `invocation.web` section. */


/* The Application also registers a file handler of all files with the `*.c` extension. This is used as
a hint for the frontend that files with this extension can be opened with this Application. When
opened like this, the file's parent folder will be mounted as a resource. */

// Authenticated as user
await callAPI(HpcAppsApi.findByNameAndVersion(
    {
        "appName": "acme-web",
        "appVersion": "1.0.0"
    }
);

/*
{
    "metadata": {
        "name": "acme-web",
        "version": "1.0.0",
        "authors": [
            "UCloud"
        ],
        "title": "Acme web",
        "description": "An example application",
        "website": null,
        "public": true
    },
    "invocation": {
        "tool": {
            "name": "acme-web",
            "version": "1.0.0",
            "tool": {
                "owner": "_ucloud",
                "createdAt": 1633329776235,
                "modifiedAt": 1633329776235,
                "description": {
                    "info": {
                        "name": "acme-web",
                        "version": "1.0.0"
                    },
                    "container": null,
                    "defaultNumberOfNodes": 1,
                    "defaultTimeAllocation": {
                        "hours": 1,
                        "minutes": 0,
                        "seconds": 0
                    },
                    "requiredModules": [
                    ],
                    "authors": [
                        "UCloud"
                    ],
                    "title": "Acme web",
                    "description": "An example tool",
                    "backend": "DOCKER",
                    "license": "None",
                    "image": "acme/web:1.0.0",
                    "supportedProviders": null
                }
            }
        },
        "invocation": [
            {
                "type": "word",
                "word": "web-server"
            }
        ],
        "parameters": [
        ],
        "outputFileGlobs": [
            "*"
        ],
        "applicationType": "WEB",
        "vnc": null,
        "web": {
            "port": 8080
        },
        "ssh": null,
        "container": null,
        "environment": null,
        "allowAdditionalMounts": null,
        "allowAdditionalPeers": null,
        "allowMultiNode": false,
        "allowPublicIp": false,
        "allowPublicLink": null,
        "fileExtensions": [
            ".c"
        ],
        "licenseServers": [
        ]
    },
    "favorite": false,
    "tags": [
    ]
}
*/
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 shows an Application with a graphical web interface. The web server, hosting the 
# interface, runs on port 8080 as defined in the `invocation.web` section.

# The Application also registers a file handler of all files with the `*.c` extension. This is used as
# a hint for the frontend that files with this extension can be opened with this Application. When
# opened like this, the file's parent folder will be mounted as a resource.

# Authenticated as user
curl -XGET -H "Authorization: Bearer $accessToken" "$host/api/hpc/apps/byNameAndVersion?appName=acme-web&appVersion=1.0.0" 

# {
#     "metadata": {
#         "name": "acme-web",
#         "version": "1.0.0",
#         "authors": [
#             "UCloud"
#         ],
#         "title": "Acme web",
#         "description": "An example application",
#         "website": null,
#         "public": true
#     },
#     "invocation": {
#         "tool": {
#             "name": "acme-web",
#             "version": "1.0.0",
#             "tool": {
#                 "owner": "_ucloud",
#                 "createdAt": 1633329776235,
#                 "modifiedAt": 1633329776235,
#                 "description": {
#                     "info": {
#                         "name": "acme-web",
#                         "version": "1.0.0"
#                     },
#                     "container": null,
#                     "defaultNumberOfNodes": 1,
#                     "defaultTimeAllocation": {
#                         "hours": 1,
#                         "minutes": 0,
#                         "seconds": 0
#                     },
#                     "requiredModules": [
#                     ],
#                     "authors": [
#                         "UCloud"
#                     ],
#                     "title": "Acme web",
#                     "description": "An example tool",
#                     "backend": "DOCKER",
#                     "license": "None",
#                     "image": "acme/web:1.0.0",
#                     "supportedProviders": null
#                 }
#             }
#         },
#         "invocation": [
#             {
#                 "type": "word",
#                 "word": "web-server"
#             }
#         ],
#         "parameters": [
#         ],
#         "outputFileGlobs": [
#             "*"
#         ],
#         "applicationType": "WEB",
#         "vnc": null,
#         "web": {
#             "port": 8080
#         },
#         "ssh": null,
#         "container": null,
#         "environment": null,
#         "allowAdditionalMounts": null,
#         "allowAdditionalPeers": null,
#         "allowMultiNode": false,
#         "allowPublicIp": false,
#         "allowPublicLink": null,
#         "fileExtensions": [
#             ".c"
#         ],
#         "licenseServers": [
#         ]
#     },
#     "favorite": false,
#     "tags": [
#     ]
# }
Communication Flow: Visual

Example: An Application with default values

Frequency of useCommon
Actors
  • An authenticated user (user)
Communication Flow: Kotlin
/* This example shows an Application which has a single input parameter. The parameter contains a 
textual value. If the user does not provide a specific value, it will default to 'hello'. UCloud 
passes this value as the first argument on the command-line. */

AppStore.findByNameAndVersion.call(
    FindApplicationAndOptionalDependencies(
        appName = "acme-web", 
        appVersion = "1.0.0", 
    ),
    user
).orThrow()

/*
ApplicationWithFavoriteAndTags(
    favorite = false, 
    invocation = ApplicationInvocationDescription(
        allowAdditionalMounts = null, 
        allowAdditionalPeers = null, 
        allowMultiNode = false, 
        allowPublicIp = false, 
        allowPublicLink = null, 
        applicationType = ApplicationType.WEB, 
        container = null, 
        environment = null, 
        fileExtensions = emptyList(), 
        invocation = listOf(WordInvocationParameter(
            word = "web-server", 
        ), VariableInvocationParameter(
            isPrefixVariablePartOfArg = false, 
            isSuffixVariablePartOfArg = false, 
            prefixGlobal = "", 
            prefixVariable = "", 
            suffixGlobal = "", 
            suffixVariable = "", 
            variableNames = listOf("variable"), 
        )), 
        licenseServers = emptyList(), 
        outputFileGlobs = listOf("*"), 
        parameters = listOf(ApplicationParameter.Text(
            defaultValue = JsonObject(mapOf("type" to JsonLiteral(
                content = "text", 
                isString = true, 
            )),"value" to JsonLiteral(
                content = "hello", 
                isString = true, 
            )),)), 
            description = "A variable passed to the Application (default = 'hello')", 
            name = "variable", 
            optional = true, 
            title = "My Variable", 
        )), 
        shouldAllowAdditionalMounts = true, 
        shouldAllowAdditionalPeers = true, 
        ssh = null, 
        tool = ToolReference(
            name = "acme-web", 
            tool = Tool(
                createdAt = 1633329776235, 
                description = NormalizedToolDescription(
                    authors = listOf("UCloud"), 
                    backend = ToolBackend.DOCKER, 
                    container = null, 
                    defaultNumberOfNodes = 1, 
                    defaultTimeAllocation = SimpleDuration(
                        hours = 1, 
                        minutes = 0, 
                        seconds = 0, 
                    ), 
                    description = "An example tool", 
                    image = "acme/web:1.0.0", 
                    info = NameAndVersion(
                        name = "acme-web", 
                        version = "1.0.0", 
                    ), 
                    license = "None", 
                    requiredModules = emptyList(), 
                    supportedProviders = null, 
                    title = "Acme web", 
                ), 
                modifiedAt = 1633329776235, 
                owner = "_ucloud", 
            ), 
            version = "1.0.0", 
        ), 
        vnc = null, 
        web = WebDescription(
            port = 8080, 
        ), 
    ), 
    metadata = ApplicationMetadata(
        authors = listOf("UCloud"), 
        description = "An example application", 
        isPublic = true, 
        name = "acme-web", 
        public = true, 
        title = "Acme web", 
        version = "1.0.0", 
        website = null, 
    ), 
    tags = emptyList(), 
)
*/
Communication Flow: TypeScript
/* This example shows an Application which has a single input parameter. The parameter contains a 
textual value. If the user does not provide a specific value, it will default to 'hello'. UCloud 
passes this value as the first argument on the command-line. */

// Authenticated as user
await callAPI(HpcAppsApi.findByNameAndVersion(
    {
        "appName": "acme-web",
        "appVersion": "1.0.0"
    }
);

/*
{
    "metadata": {
        "name": "acme-web",
        "version": "1.0.0",
        "authors": [
            "UCloud"
        ],
        "title": "Acme web",
        "description": "An example application",
        "website": null,
        "public": true
    },
    "invocation": {
        "tool": {
            "name": "acme-web",
            "version": "1.0.0",
            "tool": {
                "owner": "_ucloud",
                "createdAt": 1633329776235,
                "modifiedAt": 1633329776235,
                "description": {
                    "info": {
                        "name": "acme-web",
                        "version": "1.0.0"
                    },
                    "container": null,
                    "defaultNumberOfNodes": 1,
                    "defaultTimeAllocation": {
                        "hours": 1,
                        "minutes": 0,
                        "seconds": 0
                    },
                    "requiredModules": [
                    ],
                    "authors": [
                        "UCloud"
                    ],
                    "title": "Acme web",
                    "description": "An example tool",
                    "backend": "DOCKER",
                    "license": "None",
                    "image": "acme/web:1.0.0",
                    "supportedProviders": null
                }
            }
        },
        "invocation": [
            {
                "type": "word",
                "word": "web-server"
            },
            {
                "type": "var",
                "variableNames": [
                    "variable"
                ],
                "prefixGlobal": "",
                "suffixGlobal": "",
                "prefixVariable": "",
                "suffixVariable": "",
                "isPrefixVariablePartOfArg": false,
                "isSuffixVariablePartOfArg": false
            }
        ],
        "parameters": [
            {
                "type": "text",
                "name": "variable",
                "optional": true,
                "defaultValue": {
                    "type": "text",
                    "value": "hello"
                },
                "title": "My Variable",
                "description": "A variable passed to the Application (default = 'hello')"
            }
        ],
        "outputFileGlobs": [
            "*"
        ],
        "applicationType": "WEB",
        "vnc": null,
        "web": {
            "port": 8080
        },
        "ssh": null,
        "container": null,
        "environment": null,
        "allowAdditionalMounts": null,
        "allowAdditionalPeers": null,
        "allowMultiNode": false,
        "allowPublicIp": false,
        "allowPublicLink": null,
        "fileExtensions": [
        ],
        "licenseServers": [
        ]
    },
    "favorite": false,
    "tags": [
    ]
}
*/
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 shows an Application which has a single input parameter. The parameter contains a 
# textual value. If the user does not provide a specific value, it will default to 'hello'. UCloud 
# passes this value as the first argument on the command-line.

# Authenticated as user
curl -XGET -H "Authorization: Bearer $accessToken" "$host/api/hpc/apps/byNameAndVersion?appName=acme-web&appVersion=1.0.0" 

# {
#     "metadata": {
#         "name": "acme-web",
#         "version": "1.0.0",
#         "authors": [
#             "UCloud"
#         ],
#         "title": "Acme web",
#         "description": "An example application",
#         "website": null,
#         "public": true
#     },
#     "invocation": {
#         "tool": {
#             "name": "acme-web",
#             "version": "1.0.0",
#             "tool": {
#                 "owner": "_ucloud",
#                 "createdAt": 1633329776235,
#                 "modifiedAt": 1633329776235,
#                 "description": {
#                     "info": {
#                         "name": "acme-web",
#                         "version": "1.0.0"
#                     },
#                     "container": null,
#                     "defaultNumberOfNodes": 1,
#                     "defaultTimeAllocation": {
#                         "hours": 1,
#                         "minutes": 0,
#                         "seconds": 0
#                     },
#                     "requiredModules": [
#                     ],
#                     "authors": [
#                         "UCloud"
#                     ],
#                     "title": "Acme web",
#                     "description": "An example tool",
#                     "backend": "DOCKER",
#                     "license": "None",
#                     "image": "acme/web:1.0.0",
#                     "supportedProviders": null
#                 }
#             }
#         },
#         "invocation": [
#             {
#                 "type": "word",
#                 "word": "web-server"
#             },
#             {
#                 "type": "var",
#                 "variableNames": [
#                     "variable"
#                 ],
#                 "prefixGlobal": "",
#                 "suffixGlobal": "",
#                 "prefixVariable": "",
#                 "suffixVariable": "",
#                 "isPrefixVariablePartOfArg": false,
#                 "isSuffixVariablePartOfArg": false
#             }
#         ],
#         "parameters": [
#             {
#                 "type": "text",
#                 "name": "variable",
#                 "optional": true,
#                 "defaultValue": {
#                     "type": "text",
#                     "value": "hello"
#                 },
#                 "title": "My Variable",
#                 "description": "A variable passed to the Application (default = 'hello')"
#             }
#         ],
#         "outputFileGlobs": [
#             "*"
#         ],
#         "applicationType": "WEB",
#         "vnc": null,
#         "web": {
#             "port": 8080
#         },
#         "ssh": null,
#         "container": null,
#         "environment": null,
#         "allowAdditionalMounts": null,
#         "allowAdditionalPeers": null,
#         "allowMultiNode": false,
#         "allowPublicIp": false,
#         "allowPublicLink": null,
#         "fileExtensions": [
#         ],
#         "licenseServers": [
#         ]
#     },
#     "favorite": false,
#     "tags": [
#     ]
# }
Communication Flow: Visual

Remote Procedure Calls

advancedSearch

API: Experimental/Alpha Auth: Authenticated

Searches in the Application catalog using more advanced parameters

Request Response Error
AdvancedSearchRequest Page<ApplicationSummaryWithFavorite> CommonErrorMessage

create

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

Creates a new Application and inserts it into the catalog

Request Response Error
Unit Unit CommonErrorMessage

findByName

API: Experimental/Alpha Auth: Authenticated

Finds Applications given an exact name

Request Response Error
FindByNameAndPagination Page<ApplicationSummaryWithFavorite> CommonErrorMessage

findByNameAndVersion

API: Experimental/Alpha Auth: Authenticated

Retrieves an Application by name and version

Request Response Error
FindApplicationAndOptionalDependencies ApplicationWithFavoriteAndTags CommonErrorMessage

findBySupportedFileExtension

API: Experimental/Alpha Auth: Users

Finds a page of Application which can open a specific UFile

Request Response Error
FindBySupportedFileExtension PageV2<ApplicationWithExtension> CommonErrorMessage

findLatestByTool

API: Experimental/Alpha Auth: Authenticated

Retrieves the latest version of an Application using a specific tool

Request Response Error
FindLatestByToolRequest Page<Application> CommonErrorMessage

hasPermission

API: Experimental/Alpha Auth: Authenticated

Check if an entity has permission to use a specific Application

Request Response Error
HasPermissionRequest Boolean CommonErrorMessage

isPublic

API: Experimental/Alpha Auth: Services

Checks if an Application is publicly accessible

Request Response Error
IsPublicRequest IsPublicResponse CommonErrorMessage

listAcl

API: Experimental/Alpha Auth: Services

Retrieves the permission information associated with an Application

Request Response Error
ListAclRequest List<DetailedEntityWithPermission> CommonErrorMessage

listAll

API: Experimental/Alpha Auth: Authenticated

Lists all Applications

Request Response Error
PaginationRequest Page<ApplicationSummaryWithFavorite> CommonErrorMessage

Results are not ordered in any specific fashion

retrieveFavorites

API: Experimental/Alpha Auth: Users

Retrieves the list of favorite Applications for the curent user

Request Response Error
PaginationRequest Page<ApplicationSummaryWithFavorite> CommonErrorMessage

searchApps

API: Experimental/Alpha Auth: Authenticated

Searches in the Application catalog using a free-text query

Request Response Error
AppSearchRequest Page<ApplicationSummaryWithFavorite> CommonErrorMessage

searchTags

API: Experimental/Alpha Auth: Authenticated

Browses the Application catalog by tag

Request Response Error
TagSearchRequest Page<ApplicationSummaryWithFavorite> CommonErrorMessage

createTag

API: Experimental/Alpha Auth: Services

Attaches a set of tags to an Application

Request Response Error
CreateTagsRequest Unit CommonErrorMessage

delete

API: Experimental/Alpha Auth: Admin

Removes an Application from the catalog

Request Response Error
DeleteAppRequest Unit CommonErrorMessage

removeTag

API: Experimental/Alpha Auth: Services

Removes a set of tags from an Application

Request Response Error
CreateTagsRequest Unit CommonErrorMessage

setPublic

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

Changes the ‘publicly accessible’ status of an Application

Request Response Error
SetPublicRequest Unit CommonErrorMessage

toggleFavorite

API: Experimental/Alpha Auth: Users

Toggles the favorite status of an Application for the current user

Request Response Error
FavoriteRequest Unit CommonErrorMessage

updateAcl

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

Updates the permissions associated with an Application

Request Response Error
UpdateAclRequest Unit CommonErrorMessage

Data Models

Application

API: Internal/Beta

Applications specify the input parameters and invocation of a software package.

data class Application(
    val metadata: ApplicationMetadata,
    val invocation: ApplicationInvocationDescription,
)

For more information see the full documentation.

Properties
metadata: ApplicationMetadata
invocation: ApplicationInvocationDescription

ApplicationMetadata

API: Internal/Beta

Metadata associated with an Application

data class ApplicationMetadata(
    val name: String,
    val version: String,
    val authors: List<String>,
    val title: String,
    val description: String,
    val website: String?,
    val public: Boolean,
    val isPublic: Boolean,
)

The metadata describes information mostly useful for presentation purposes. The only exception are name and version which are (also) used as identifiers.

Properties
name: String A stable identifier for this Application's name
version: String A stable identifier for this Application's version
authors: List<String> A list of authors
title: String A (non-stable) title for this Application, used for presentation
description: String A markdown document describing this Application
website: String? An absolute URL which points to further information about the Application
public: Boolean A flag which describes if this Application is publicly accessible
isPublic: Boolean

Deprecated: Yes


ApplicationInvocationDescription

API: Internal/Beta

The specification for how to invoke an Application

data class ApplicationInvocationDescription(
    val tool: ToolReference,
    val invocation: List<InvocationParameter>,
    val parameters: List<ApplicationParameter>,
    val outputFileGlobs: List<String>,
    val applicationType: ApplicationType?,
    val vnc: VncDescription?,
    val web: WebDescription?,
    val ssh: SshDescription?,
    val container: ContainerDescription?,
    val environment: JsonObject?,
    val allowAdditionalMounts: Boolean?,
    val allowAdditionalPeers: Boolean?,
    val allowMultiNode: Boolean?,
    val allowPublicIp: Boolean?,
    val allowPublicLink: Boolean?,
    val fileExtensions: List<String>?,
    val licenseServers: List<String>?,
    val shouldAllowAdditionalMounts: Boolean,
    val shouldAllowAdditionalPeers: Boolean,
)

All Applications require a tool. The Tool specify the concrete computing environment. With the tool we get the required software packages and configuration.

In this environment, we must start some software. Any Job launched with this Application will only run for as long as the software runs. You can specify the command-line invocation through the invocation property. Each element in this list produce zero or more arguments for the actual invocation. These InvocationParameters can reference the input parameters of the Application. In addition, you can set the environment variables through the same mechanism.

All Applications have an ApplicationType associated with them. This type determines how the user interacts with your Application. We support the following types:

  • BATCH: A non-interactive Application which runs without user input

  • VNC: An interactive Application exposing a remote desktop interface

  • WEB: An interactive Application exposing a graphical web interface

The Application must expose information about how to access interactive services. It can do so by setting vnc and web. Providers must use this information when opening an interactive session.

Users can launch a Job with additional resources, such as IP addresses and files. The Application author specifies the supported resources through the allowXXX properties.

Properties
tool: ToolReference A reference to the Tool used by this Application
invocation: List<InvocationParameter> Instructions on how to build the command-line invocation
parameters: List<ApplicationParameter> The input parameters used by this Application
outputFileGlobs: List<String>

Deprecated: Yes

applicationType: ApplicationType? The type of this Application, it determines how users will interact with the Application
vnc: VncDescription? Information about how to reach the VNC service
web: WebDescription? Information about how to reach the web service
ssh: SshDescription? Information about how the SSH capabilities of this application
container: ContainerDescription? Hints to the container system about how the Application should be launched
environment: JsonObject? Additional environment variables to be added in the environment
allowAdditionalMounts: Boolean? Flag to enable/disable support for additional file mounts (default: true for interactive apps)
allowAdditionalPeers: Boolean? Flag to enable/disable support for connecting Jobs together (default: true)
allowMultiNode: Boolean? Flag to enable/disable multiple replicas of this Application (default: false)
allowPublicIp: Boolean? Flag to enable/disable support for public IP (default false)
allowPublicLink: Boolean? Flag to enable/disable support for public link (default: true for web apps)
fileExtensions: List<String>? The file extensions which this Application can handle

This list used as a suffix filter. As a result, this list should typically include the dot.

licenseServers: List<String>? Hint used by the frontend to find appropriate license servers
shouldAllowAdditionalMounts: Boolean
shouldAllowAdditionalPeers: Boolean

ApplicationType

API: Internal/Beta

The ApplicationType determines how user’s interact with an Application

enum class ApplicationType {
    BATCH,
    VNC,
    WEB,
}
  • BATCH: A non-interactive Application which runs without user input

  • VNC: An interactive Application exposing a remote desktop interface

  • WEB: An interactive Application exposing a graphical web interface

Properties
BATCH A non-interactive [`Application`](/docs/reference/dk.sdu.cloud.app.store.api.Application.md) which runs without user input
VNC An interactive [`Application`](/docs/reference/dk.sdu.cloud.app.store.api.Application.md) exposing a remote desktop interface
WEB An interactive [`Application`](/docs/reference/dk.sdu.cloud.app.store.api.Application.md) exposing a graphical web interface

VncDescription

API: Internal/Beta

Information to the Provider about how to reach the VNC services

data class VncDescription(
    val password: String?,
    val port: Int?,
)

Providers must use this information when opening an interactive session.

Properties
password: String?
port: Int?

WebDescription

API: Internal/Beta

Information to the Provider about how to reach the web services

data class WebDescription(
    val port: Int?,
)

Providers must use this information when opening an interactive session.

Properties
port: Int?

ContainerDescription

API: Internal/Beta

Information to the Provider about how to launch the container

data class ContainerDescription(
    val changeWorkingDirectory: Boolean?,
    val runAsRoot: Boolean?,
    val runAsRealUser: Boolean?,
)
Properties
changeWorkingDirectory: Boolean?
runAsRoot: Boolean?
runAsRealUser: Boolean?

ApplicationParameter

API: Internal/Beta

An ApplicationParameter describe a single input parameter to an Application.

sealed class ApplicationParameter {
    abstract val defaultValue: Any?
    abstract val description: String
    abstract val name: String
    abstract val optional: Boolean
    abstract val title: String?

    class Bool : ApplicationParameter()
    class Enumeration : ApplicationParameter()
    class FloatingPoint : ApplicationParameter()
    class Ingress : ApplicationParameter()
    class InputDirectory : ApplicationParameter()
    class InputFile : ApplicationParameter()
    class Integer : ApplicationParameter()
    class LicenseServer : ApplicationParameter()
    class NetworkIP : ApplicationParameter()
    class Peer : ApplicationParameter()
    class Text : ApplicationParameter()
    class TextArea : ApplicationParameter()
}

All ApplicationParameters contain metadata used for the presentation in the frontend. This metadata includes a title and help-text. This allows UCloud to create a rich user-interface with widgets which are easy to use.

When the user requests the creation of a Job, they supply a lot of information. This includes a reference to the Application and a set of AppParameterValues. The user must supply a value for every mandatory ApplicationParameter. Every parameter has a type associated with it. This type controls the set of valid AppParameterValues it can take.

Properties
defaultValue: Any?
description: String
name: String
optional: Boolean
title: String?

ApplicationParameter.TextArea

API: Internal/Beta

An ApplicationParameter describe a single input parameter to an Application.

data class TextArea(
    val name: String?,
    val optional: Boolean?,
    val defaultValue: Any?,
    val title: String?,
    val description: String?,
    val type: String /* "textarea" */,
)

All ApplicationParameters contain metadata used for the presentation in the frontend. This metadata includes a title and help-text. This allows UCloud to create a rich user-interface with widgets which are easy to use.

When the user requests the creation of a Job, they supply a lot of information. This includes a reference to the Application and a set of AppParameterValues. The user must supply a value for every mandatory ApplicationParameter. Every parameter has a type associated with it. This type controls the set of valid AppParameterValues it can take.

Properties
name: String?
optional: Boolean?
defaultValue: Any?
title: String?
description: String?
type: String /* "textarea" */ The type discriminator

API: Stable


ApplicationParameter.Bool

API: Internal/Beta

An input parameter which accepts any boolean value

data class Bool(
    val name: String?,
    val optional: Boolean?,
    val defaultValue: Any?,
    val title: String?,
    val description: String?,
    val trueValue: String?,
    val falseValue: String?,
    val type: String /* "boolean" */,
)

Compatible with: AppParameterValue.Bool

Properties
name: String?
optional: Boolean?
defaultValue: Any?
title: String?
description: String?
trueValue: String?
falseValue: String?
type: String /* "boolean" */ The type discriminator

API: Stable


ApplicationParameter.Enumeration

API: Internal/Beta

An input parameter which accepts an enum

data class Enumeration(
    val name: String?,
    val optional: Boolean?,
    val defaultValue: Any?,
    val title: String?,
    val description: String?,
    val options: List<ApplicationParameter.EnumOption>?,
    val type: String /* "enumeration" */,
)

Compatible with: AppParameterValue.Text (Note: the text should match the value of the selected option)

Properties
name: String?
optional: Boolean?
defaultValue: Any?
title: String?
description: String?
options: List<ApplicationParameter.EnumOption>?
type: String /* "enumeration" */ The type discriminator

API: Stable


ApplicationParameter.FloatingPoint

API: Internal/Beta

An input parameter which accepts any floating point value

data class FloatingPoint(
    val name: String?,
    val optional: Boolean?,
    val defaultValue: Any?,
    val title: String?,
    val description: String?,
    val min: Double?,
    val max: Double?,
    val step: Double?,
    val unitName: String?,
    val type: String /* "floating_point" */,
)

Compatible with: AppParameterValue.FloatingPoint

This parameter can be tweaked using the various options. For example, it is possible to provide a minimum and maximum value.

Properties
name: String?
optional: Boolean?
defaultValue: Any?
title: String?
description: String?
min: Double?
max: Double?
step: Double?
unitName: String?
type: String /* "floating_point" */ The type discriminator

API: Stable


ApplicationParameter.Ingress

API: Internal/Beta

An input parameter which accepts a ingress (public link)

data class Ingress(
    val name: String?,
    val title: String?,
    val description: String?,
    val defaultValue: Any?,
    val optional: Boolean,
    val type: String /* "ingress" */,
)

Compatible with: AppParameterValue.Ingress

Properties
name: String?
title: String?
description: String?
defaultValue: Any?
optional: Boolean
type: String /* "ingress" */ The type discriminator

API: Stable


ApplicationParameter.InputDirectory

API: Internal/Beta

An input parameter which accepts UFiles of type DIRECTORY

data class InputDirectory(
    val name: String?,
    val optional: Boolean?,
    val defaultValue: Any?,
    val title: String?,
    val description: String?,
    val type: String /* "input_directory" */,
)

Compatible with: AppParameterValue.File

Properties
name: String?
optional: Boolean?
defaultValue: Any?
title: String?
description: String?
type: String /* "input_directory" */ The type discriminator

API: Stable


ApplicationParameter.InputFile

API: Internal/Beta

An input parameter which accepts UFiles of type FILE

data class InputFile(
    val name: String?,
    val optional: Boolean?,
    val defaultValue: Any?,
    val title: String?,
    val description: String?,
    val type: String /* "input_file" */,
)

Compatible with: AppParameterValue.File

Properties
name: String?
optional: Boolean?
defaultValue: Any?
title: String?
description: String?
type: String /* "input_file" */ The type discriminator

API: Stable


ApplicationParameter.Integer

API: Internal/Beta

An input parameter which accepts any integer value

data class Integer(
    val name: String?,
    val optional: Boolean?,
    val defaultValue: Any?,
    val title: String?,
    val description: String?,
    val min: Long?,
    val max: Long?,
    val step: Long?,
    val unitName: String?,
    val type: String /* "integer" */,
)

Compatible with: AppParameterValue.Integer

This parameter can be tweaked using the various options. For example, it is possible to provide a minimum and maximum value.

Properties
name: String?
optional: Boolean?
defaultValue: Any?
title: String?
description: String?
min: Long?
max: Long?
step: Long?
unitName: String?
type: String /* "integer" */ The type discriminator

API: Stable


ApplicationParameter.LicenseServer

API: Internal/Beta

An input parameter which accepts a license

data class LicenseServer(
    val name: String?,
    val title: String?,
    val optional: Boolean?,
    val description: String?,
    val tagged: List<String>,
    val defaultValue: Any?,
    val type: String /* "license_server" */,
)

Compatible with: AppParameterValue.License

Properties
name: String?
title: String?
optional: Boolean?
description: String?
tagged: List<String>
defaultValue: Any?
type: String /* "license_server" */ The type discriminator

API: Stable


ApplicationParameter.NetworkIP

API: Internal/Beta

An input parameter which accepts an IP address

data class NetworkIP(
    val name: String?,
    val title: String?,
    val description: String?,
    val defaultValue: Any?,
    val optional: Boolean,
    val type: String /* "network_ip" */,
)

Compatible with: AppParameterValue.Network

Properties
name: String?
title: String?
description: String?
defaultValue: Any?
optional: Boolean
type: String /* "network_ip" */ The type discriminator

API: Stable


ApplicationParameter.Peer

API: Internal/Beta

An input parameter which accepts a peering Job

data class Peer(
    val name: String?,
    val title: String?,
    val description: String,
    val suggestedApplication: String?,
    val defaultValue: Any?,
    val optional: Boolean,
    val type: String /* "peer" */,
)

Compatible with: AppParameterValue.Peer

Properties
name: String?
title: String?
description: String
suggestedApplication: String?
defaultValue: Any?
optional: Boolean
type: String /* "peer" */ The type discriminator

API: Stable


ApplicationParameter.Text

API: Internal/Beta

An input parameter which accepts text

data class Text(
    val name: String?,
    val optional: Boolean?,
    val defaultValue: Any?,
    val title: String?,
    val description: String?,
    val type: String /* "text" */,
)

Compatible with: AppParameterValue.Text

Properties
name: String?
optional: Boolean?
defaultValue: Any?
title: String?
description: String?
type: String /* "text" */ The type discriminator

API: Stable


AppParameterValue

API: Experimental/Alpha

An AppParameterValue is value which is supplied to a parameter of an Application.

sealed class AppParameterValue {
    class BlockStorage : AppParameterValue()
    class Bool : AppParameterValue()
    class File : AppParameterValue()
    class FloatingPoint : AppParameterValue()
    class Ingress : AppParameterValue()
    class Integer : AppParameterValue()
    class License : AppParameterValue()
    class Network : AppParameterValue()
    class Peer : AppParameterValue()
    class Text : AppParameterValue()
    class TextArea : AppParameterValue()
}

Each value type can is type-compatible with one or more ApplicationParameters. The effect of a specific value depends on its use-site, and the type of its associated parameter.

ApplicationParameters have the following usage sites:

  • Invocation: This affects the command line arguments passed to the software.

  • Environment variables: This affects the environment variables passed to the software.

  • Resources: This only affects the resources which are imported into the software environment. Not all values can be used as a resource.


AppParameterValue.BlockStorage

API: Experimental/Alpha

A reference to block storage (Not yet implemented)

data class BlockStorage(
    val id: String,
    val type: String /* "block_storage" */,
)
Properties
id: String
type: String /* "block_storage" */ The type discriminator

API: Stable


AppParameterValue.Bool

API: Experimental/Alpha

A boolean value (true or false)

data class Bool(
    val value: Boolean,
    val type: String /* "boolean" */,
)
  • Compatible with: ApplicationParameter.Bool

  • Mountable as a resource: ❌ No

  • Expands to: trueValue of ApplicationParameter.Bool if value is true otherwise falseValue

  • Side effects: None

Properties
value: Boolean
type: String /* "boolean" */ The type discriminator

API: Stable


AppParameterValue.File

API: Experimental/Alpha

A reference to a UCloud file

data class File(
    val path: String,
    val readOnly: Boolean?,
    val type: String /* "file" */,
)
  • Compatible with: ApplicationParameter.InputFile and ApplicationParameter.InputDirectory

  • Mountable as a resource: ✅ Yes

  • Expands to: The absolute path to the file or directory in the software’s environment

  • Side effects: Includes the file or directory in the Job’s temporary work directory

The path of the file must be absolute and refers to either a UCloud directory or file.

Properties
path: String The absolute path to the file or directory in UCloud
readOnly: Boolean? Indicates if this file or directory should be mounted as read-only

A provider must reject the request if it does not support read-only mounts when readOnly = true.

type: String /* "file" */ The type discriminator

API: Stable


AppParameterValue.FloatingPoint

API: Experimental/Alpha

A floating point value

data class FloatingPoint(
    val value: Double,
    val type: String /* "floating_point" */,
)
  • Compatible with: ApplicationParameter.FloatingPoint

  • Mountable as a resource: ❌ No

  • Expands to: The number

  • Side effects: None

Internally this uses a big decimal type and there are no defined limits.

Properties
value: Double
type: String /* "floating_point" */ The type discriminator

API: Stable


AppParameterValue.Ingress

API: Experimental/Alpha

A reference to an HTTP ingress, registered locally at the provider

data class Ingress(
    val id: String,
    val type: String /* "ingress" */,
)
  • Compatible with: ApplicationParameter.Ingress

  • Mountable as a resource: ✅ Yes

  • Expands to: ${id}

  • Side effects: Configures an HTTP ingress for the application’s interactive web interface. This interface should not perform any validation, that is, the application should be publicly accessible.

Properties
id: String
type: String /* "ingress" */ The type discriminator

API: Stable


AppParameterValue.Integer

API: Experimental/Alpha

An integral value

data class Integer(
    val value: Long,
    val type: String /* "integer" */,
)
  • Compatible with: ApplicationParameter.Integer

  • Mountable as a resource: ❌ No

  • Expands to: The number

  • Side effects: None

Internally this uses a big integer type and there are no defined limits.

Properties
value: Long
type: String /* "integer" */ The type discriminator

API: Stable


AppParameterValue.License

API: Experimental/Alpha

A reference to a software license, registered locally at the provider

data class License(
    val id: String,
    val type: String /* "license_server" */,
)
  • Compatible with: ApplicationParameter.LicenseServer

  • Mountable as a resource: ❌ No

  • Expands to: ${license.address}:${license.port}/${license.key} or ${license.address}:${license.port} if no key is provided

  • Side effects: None

Properties
id: String
type: String /* "license_server" */ The type discriminator

API: Stable


AppParameterValue.Network

API: Experimental/Alpha

A reference to block storage (Not yet implemented)

data class Network(
    val id: String,
    val type: String /* "network" */,
)
Properties
id: String
type: String /* "network" */ The type discriminator

API: Stable


AppParameterValue.Peer

API: Experimental/Alpha

A reference to a separate UCloud Job

data class Peer(
    val hostname: String,
    val jobId: String,
    val type: String /* "peer" */,
)
  • Compatible with: ApplicationParameter.Peer

  • Mountable as a resource: ✅ Yes

  • Expands to: The hostname

  • Side effects: Configures the firewall to allow bidirectional communication between this Job and the peering Job

Properties
hostname: String
jobId: String
type: String /* "peer" */ The type discriminator

API: Stable


AppParameterValue.Text

API: Experimental/Alpha

A textual value

data class Text(
    val value: String,
    val type: String /* "text" */,
)
  • Compatible with: ApplicationParameter.Text and ApplicationParameter.Enumeration

  • Mountable as a resource: ❌ No

  • Expands to: The text, when used in an invocation this will be passed as a single argument.

  • Side effects: None

When this is used with an Enumeration it must match the value of one of the associated options.

Properties
value: String
type: String /* "text" */ The type discriminator

API: Stable


InvocationParameter

API: Internal/Beta

InvocationParameters supply values to either the command-line or environment variables.

sealed class InvocationParameter {
    class BooleanFlagParameter : InvocationParameter()
    class EnvironmentVariableParameter : InvocationParameter()
    class VariableInvocationParameter : InvocationParameter()
    class WordInvocationParameter : InvocationParameter()
}

Every parameter can run in one of two contexts. They produce a value when combined with a ApplicationParameter
and a AppParameterValue:

  • Command line argument: Produces zero or more arguments for the command-line

  • Environment variable: Produces exactly one value.

For each of the InvocationParameter types, we will describe the value(s) they produce. We will also highlight notable differences between CLI args and environment variables.


BooleanFlagParameter

API: Internal/Beta

Produces a toggleable command-line flag

data class BooleanFlagParameter(
    val variableName: String,
    val flag: String,
    val type: String /* "bool_flag" */,
)

The parameter referenced by variableName must be of type ApplicationParameter.Bool, and the value must be AppParamValue.Bool. This invocation parameter will produce the flag if the variable’s value is true. Otherwise, it will produce no values.

Example: Example (with true value)

VariableInvocationParameter:

{
    "type": "bool_flag",
    "variableName": ["myVariable"],
    "flag": "--example"
}

Values (AppParameterValue):

{
    "myVariable": { "type": "bool", "value": true }
}

Expands to:

"--example"

Example: Example (with false value)

VariableInvocationParameter:

{
    "type": "bool_flag",
    "variableName": ["myVariable"],
    "flag": "--example"
}

Values (AppParameterValue):

{
    "myVariable": { "type": "bool", "value": false }
}

Expands to (nothing):


Example: With spaces

VariableInvocationParameter:

{
    "type": "bool_flag",
    "variableName": ["myVariable"],
    "flag": "--hello world"
}

Values (AppParameterValue):

{
    "myVariable": { "type": "bool", "value": true }
}

Expands to:

"--hello world"
Properties
variableName: String
flag: String
type: String /* "bool_flag" */ The type discriminator

API: Stable


EnvironmentVariableParameter

API: Internal/Beta

Produces an environment variable (TODO Documentation)

data class EnvironmentVariableParameter(
    val variable: String,
    val type: String /* "env" */,
)
Properties
variable: String
type: String /* "env" */ The type discriminator

API: Stable


VariableInvocationParameter

API: Internal/Beta

An InvocationParameter which produces value(s) from parameters.

data class VariableInvocationParameter(
    val variableNames: List<String>,
    val prefixGlobal: String?,
    val suffixGlobal: String?,
    val prefixVariable: String?,
    val suffixVariable: String?,
    val isPrefixVariablePartOfArg: Boolean?,
    val isSuffixVariablePartOfArg: Boolean?,
    val type: String /* "var" */,
)

The parameter receives a list of variableNames. Each must reference an ApplicationParameter. It is valid to reference both optional and mandatory parameters. This invocation will produce zero values if all the parameters have no value. This is regardless of the prefixes and suffixes.

The invocation accepts prefixes and suffixes. These will alter the values produced. The global affixes always produce one value each, if supplied. The variable specific affixes produce their own value if isXVariablePartOfArg.

Example: Simple variable

VariableInvocationParameter:

{
    "variableNames": ["myVariable"]
}

Values (AppParameterValue):

{
    "myVariable": { "type": "text", "value": "Hello, World!" }
}

Expands to:

"Hello, World!"

Example: Global prefix (command line flags)

VariableInvocationParameter:

{
    "variableNames": ["myVariable"],
    "prefixGlobal": "--count"
}

Values (AppParameterValue):

{
    "myVariable": { "type": "integer", "value": 42 }
}

Expands to:

"--count" "42"

Example: Multiple variables

VariableInvocationParameter:

{
    "variableNames": ["myVariable", "mySecondVariable"],
    "prefixGlobal": "--count"
}

Values (AppParameterValue):

{
    "myVariable": { "type": "integer", "value": 42 },
    "mySecondVariable": { "type": "integer", "value": 120 },
}

Expands to:

"--count" "42" "120"

Example: Variable prefixes and suffixes

VariableInvocationParameter:

{
    "variableNames": ["myVariable"],
    "prefixGlobal": "--entries",
    "prefixVariable": "--entry",
    "suffixVariable": "--next",
    "isPrefixVariablePartOfArg": true,
    "isSuffixVariablePartOfArg": false
}

Values (AppParameterValue):

{
    "myVariable": { "type": "integer", "value": 42 },
}

Expands to:

"--entries" "--entry42" "--next"

Example: Complete example

VariableInvocationParameter:

{
    "variableNames": ["myVariable", "mySecondVariable"],
    "prefixGlobal": "--entries",
    "prefixVariable": "--entry",
    "suffixVariable": "--next",
    "suffixGlobal": "--endOfEntries",
    "isPrefixVariablePartOfArg": false,
    "isSuffixVariablePartOfArg": true
}

Values (AppParameterValue):

{
    "myVariable": { "type": "integer", "value": 42 },
    "mySecondVariable": { "type": "text", "value": "hello" },
}

Expands to:

"--entries" "--entry" "42--next" "--entry" "hello--next" "--endOfEntries"
Properties
variableNames: List<String>
prefixGlobal: String?
suffixGlobal: String?
prefixVariable: String?
suffixVariable: String?
isPrefixVariablePartOfArg: Boolean?
isSuffixVariablePartOfArg: Boolean?
type: String /* "var" */ The type discriminator

API: Stable


WordInvocationParameter

API: Internal/Beta

A static value for an InvocationParameter

data class WordInvocationParameter(
    val word: String,
    val type: String /* "word" */,
)

This value is static and will always produce only a single value. As a result, you do not need to escape any values for this parameter.

Properties
word: String
type: String /* "word" */ The type discriminator

API: Stable


AccessEntity

API: Internal/Beta

data class AccessEntity(
    val user: String?,
    val project: String?,
    val group: String?,
)
Properties
user: String?
project: String?
group: String?

AppParameterValue.TextArea

API: Experimental/Alpha

A textual value

data class TextArea(
    val value: String,
    val type: String /* "textarea" */,
)
  • Compatible with: ApplicationParameter.Text and ApplicationParameter.Enumeration

  • Mountable as a resource: ❌ No

  • Expands to: The text, when used in an invocation this will be passed as a single argument.

  • Side effects: None

When this is used with an Enumeration it must match the value of one of the associated options.

Properties
value: String
type: String /* "textarea" */ The type discriminator

API: Stable


ApplicationAccessRight

API: Internal/Beta

enum class ApplicationAccessRight {
    LAUNCH,
}
Properties
LAUNCH

ApplicationParameter.EnumOption

API: Internal/Beta

data class EnumOption(
    val name: String,
    val value: String,
)
Properties
name: String
value: String

ApplicationSummaryWithFavorite

API: Internal/Beta

Applications specify the input parameters and invocation of a software package.

data class ApplicationSummaryWithFavorite(
    val metadata: ApplicationMetadata,
    val favorite: Boolean,
    val tags: List<String>,
)

For more information see the full documentation.

Properties
metadata: ApplicationMetadata
favorite: Boolean
tags: List<String>

ApplicationWithExtension

API: Internal/Beta

Applications specify the input parameters and invocation of a software package.

data class ApplicationWithExtension(
    val metadata: ApplicationMetadata,
    val extensions: List<String>,
)

For more information see the full documentation.

Properties
metadata: ApplicationMetadata
extensions: List<String>

ApplicationWithFavoriteAndTags

API: Internal/Beta

Applications specify the input parameters and invocation of a software package.

data class ApplicationWithFavoriteAndTags(
    val metadata: ApplicationMetadata,
    val invocation: ApplicationInvocationDescription,
    val favorite: Boolean,
    val tags: List<String>,
)

For more information see the full documentation.

Properties
metadata: ApplicationMetadata
invocation: ApplicationInvocationDescription
favorite: Boolean
tags: List<String>

DetailedAccessEntity

API: Internal/Beta

data class DetailedAccessEntity(
    val user: String?,
    val project: Project?,
    val group: Project?,
)
Properties
user: String?
project: Project?
group: Project?

DetailedEntityWithPermission

API: Internal/Beta

data class DetailedEntityWithPermission(
    val entity: DetailedAccessEntity,
    val permission: ApplicationAccessRight,
)
Properties
entity: DetailedAccessEntity
permission: ApplicationAccessRight

FindApplicationAndOptionalDependencies

API: Internal/Beta

data class FindApplicationAndOptionalDependencies(
    val appName: String,
    val appVersion: String,
)
Properties
appName: String
appVersion: String

FindBySupportedFileExtension

API: Internal/Beta

The base type for requesting paginated content.

data class FindBySupportedFileExtension(
    val files: List<String>,
    val itemsPerPage: Int?,
    val next: String?,
    val consistency: PaginationRequestV2Consistency?,
    val itemsToSkip: Long?,
)

Paginated content can be requested with one of the following consistency guarantees, this greatly changes the semantics of the call:

Consistency Description
PREFER Consistency is preferred but not required. An inconsistent snapshot might be returned.
REQUIRE Consistency is required. A request will fail if consistency is no longer guaranteed.

The consistency refers to if collecting all the results via the pagination API are consistent. We consider the results to be consistent if it contains a complete view at some point in time. In practice this means that the results must contain all the items, in the correct order and without duplicates.

If you use the PREFER consistency then you may receive in-complete results that might appear out-of-order and can contain duplicate items. UCloud will still attempt to serve a snapshot which appears mostly consistent. This is helpful for user-interfaces which do not strictly depend on consistency but would still prefer something which is mostly consistent.

The results might become inconsistent if the client either takes too long, or a service instance goes down while fetching the results. UCloud attempts to keep each next token alive for at least one minute before invalidating it. This does not mean that a client must collect all results within a minute but rather that they must fetch the next page within a minute of the last page. If this is not feasible and consistency is not required then PREFER should be used.


📝 NOTE: Services are allowed to ignore extra criteria of the request if the next token is supplied. This is needed in order to provide a consistent view of the results. Clients should provide the same criterion as they paginate through the results.


Properties
files: List<String>
itemsPerPage: Int? Requested number of items per page. Supported values: 10, 25, 50, 100, 250.
next: String? A token requesting the next page of items
consistency: PaginationRequestV2Consistency? Controls the consistency guarantees provided by the backend
itemsToSkip: Long? Items to skip ahead

Project

API: Internal/Beta

data class Project(
    val id: String,
    val title: String,
)
Properties
id: String
title: String

SshDescription

API: Internal/Beta

Information to the provider about the SSH capabilities of this application

data class SshDescription(
    val mode: SshDescription.Mode?,
)

Providers must use this information, if SSH is supported, to correctly configure applications with the appropriate keys. See /docs/reference/jobs.control.browseSshKeys.md for more information.

Properties
mode: SshDescription.Mode?

SshDescription.Mode

API: Internal/Beta

enum class Mode {
    DISABLED,
    OPTIONAL,
    MANDATORY,
}
Properties
DISABLED
OPTIONAL
MANDATORY

ToolReference

API: Internal/Beta

A reference to a Tool

data class ToolReference(
    val name: String,
    val version: String,
    val tool: Tool?,
)
Properties
name: String
version: String
tool: Tool?

ACLEntryRequest

API: Internal/Beta

data class ACLEntryRequest(
    val entity: AccessEntity,
    val rights: ApplicationAccessRight,
    val revoke: Boolean?,
)
Properties
entity: AccessEntity
rights: ApplicationAccessRight
revoke: Boolean?

AdvancedSearchRequest

API: Internal/Beta

data class AdvancedSearchRequest(
    val query: String?,
    val tags: List<String>?,
    val showAllVersions: Boolean,
    val itemsPerPage: Int?,
    val page: Int?,
)
Properties
query: String?
tags: List<String>?
showAllVersions: Boolean
itemsPerPage: Int?
page: Int?

AppSearchRequest

API: Internal/Beta

data class AppSearchRequest(
    val query: String,
    val itemsPerPage: Int?,
    val page: Int?,
)
Properties
query: String
itemsPerPage: Int?
page: Int?

CreateTagsRequest

API: Internal/Beta

data class CreateTagsRequest(
    val tags: List<String>,
    val applicationName: String,
)
Properties
tags: List<String>
applicationName: String

DeleteAppRequest

API: Internal/Beta

data class DeleteAppRequest(
    val appName: String,
    val appVersion: String,
)
Properties
appName: String
appVersion: String

FavoriteRequest

API: Internal/Beta

data class FavoriteRequest(
    val appName: String,
    val appVersion: String,
)
Properties
appName: String
appVersion: String

FindLatestByToolRequest

API: Internal/Beta

data class FindLatestByToolRequest(
    val tool: String,
    val itemsPerPage: Int?,
    val page: Int?,
)
Properties
tool: String
itemsPerPage: Int?
page: Int?

HasPermissionRequest

API: Internal/Beta

data class HasPermissionRequest(
    val appName: String,
    val appVersion: String,
    val permission: List<ApplicationAccessRight>,
)
Properties
appName: String
appVersion: String
permission: List<ApplicationAccessRight>

IsPublicRequest

API: Internal/Beta

data class IsPublicRequest(
    val applications: List<NameAndVersion>,
)
Properties
applications: List<NameAndVersion>

ListAclRequest

API: Internal/Beta

data class ListAclRequest(
    val appName: String,
)
Properties
appName: String

SetPublicRequest

API: Internal/Beta

data class SetPublicRequest(
    val appName: String,
    val appVersion: String,
    val public: Boolean,
)
Properties
appName: String
appVersion: String
public: Boolean

TagSearchRequest

API: Internal/Beta

data class TagSearchRequest(
    val query: String,
    val excludeTools: String?,
    val itemsPerPage: Int?,
    val page: Int?,
)
Properties
query: String
excludeTools: String?
itemsPerPage: Int?
page: Int?

UpdateAclRequest

API: Internal/Beta

data class UpdateAclRequest(
    val applicationName: String,
    val changes: List<ACLEntryRequest>,
)
Properties
applicationName: String
changes: List<ACLEntryRequest>

IsPublicResponse

API: Internal/Beta

data class IsPublicResponse(
    val public: JsonObject,
)
Properties
public: JsonObject