apps

« Previous section Next section »

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

Applications

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:

• Mandatory and optional input parameters. For example: text and numeric values, command-line flags and input files.

• The command-line invocation, using values from the input parameters.

• Resources attached to the compute environment. For example: files, IP addresses and software licenses.

• An application type, defining how the user interacts with it. For example: Batch, web and remote desktop (VNC).

---

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

• RPC names will change to conform with the conventions

• RPC request and response types will change to conform with the conventions

• RPCs which return a page will be collapsed into a single browse endpoint

• Some property names will change to be consistent with Resources

---

Table of Contents

1. Examples

2. Remote Procedure Calls

3. Data Models

Example: Simple batch application

Frequency of use	Common
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(), 
        modules = null, 
        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", 
        flavorName = null, 
        group = ApplicationGroup(
            defaultApplication = null, 
            description = null, 
            id = 0, 
            tags = emptyList(), 
            title = "Test Group", 
        ), 
        isPublic = true, 
        name = "acme-batch", 
        public = true, 
        title = "Acme batch", 
        version = "1.0.0", 
        website = null, 
    ), 
    tags = emptyList(), 
)
*/

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,
#         "flavorName": null,
#         "group": {
#             "id": 0,
#             "title": "Test Group",
#             "description": null,
#             "defaultApplication": null,
#             "tags": [
#             ]
#         }
#     },
#     "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": [
#         ],
#         "modules": null
#     },
#     "favorite": false,
#     "tags": [
#     ]
# }

Communication Flow: Visual

Example: Simple virtual machine

Frequency of use	Common
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(), 
        modules = null, 
        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", 
        flavorName = null, 
        group = ApplicationGroup(
            defaultApplication = null, 
            description = null, 
            id = 0, 
            tags = emptyList(), 
            title = "Test Group", 
        ), 
        isPublic = true, 
        name = "acme-os", 
        public = true, 
        title = "Acme os", 
        version = "1.0.0", 
        website = null, 
    ), 
    tags = emptyList(), 
)
*/

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,
#         "flavorName": null,
#         "group": {
#             "id": 0,
#             "title": "Test Group",
#             "description": null,
#             "defaultApplication": null,
#             "tags": [
#             ]
#         }
#     },
#     "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": [
#         ],
#         "modules": null
#     },
#     "favorite": false,
#     "tags": [
#     ]
# }

Communication Flow: Visual

Example: Simple web application

Frequency of use	Common
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(), 
        modules = null, 
        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", 
        flavorName = null, 
        group = ApplicationGroup(
            defaultApplication = null, 
            description = null, 
            id = 0, 
            tags = emptyList(), 
            title = "Test Group", 
        ), 
        isPublic = true, 
        name = "acme-web", 
        public = true, 
        title = "Acme web", 
        version = "1.0.0", 
        website = null, 
    ), 
    tags = emptyList(), 
)
*/

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,
#         "flavorName": null,
#         "group": {
#             "id": 0,
#             "title": "Test Group",
#             "description": null,
#             "defaultApplication": null,
#             "tags": [
#             ]
#         }
#     },
#     "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": [
#         ],
#         "modules": null
#     },
#     "favorite": false,
#     "tags": [
#     ]
# }

Communication Flow: Visual

Example: Simple remote desktop application (VNC)

Frequency of use	Common
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(), 
        modules = null, 
        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", 
        flavorName = null, 
        group = ApplicationGroup(
            defaultApplication = null, 
            description = null, 
            id = 0, 
            tags = emptyList(), 
            title = "Test Group", 
        ), 
        isPublic = true, 
        name = "acme-remote-desktop", 
        public = true, 
        title = "Acme remote desktop", 
        version = "1.0.0", 
        website = null, 
    ), 
    tags = emptyList(), 
)
*/

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,
#         "flavorName": null,
#         "group": {
#             "id": 0,
#             "title": "Test Group",
#             "description": null,
#             "defaultApplication": null,
#             "tags": [
#             ]
#         }
#     },
#     "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": [
#         ],
#         "modules": null
#     },
#     "favorite": false,
#     "tags": [
#     ]
# }

Communication Flow: Visual

Example: Registering a file handler

Frequency of use	Common
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(), 
        modules = null, 
        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", 
        flavorName = null, 
        group = ApplicationGroup(
            defaultApplication = null, 
            description = null, 
            id = 0, 
            tags = emptyList(), 
            title = "Test Group", 
        ), 
        isPublic = true, 
        name = "acme-web", 
        public = true, 
        title = "Acme web", 
        version = "1.0.0", 
        website = null, 
    ), 
    tags = emptyList(), 
)
*/

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,
#         "flavorName": null,
#         "group": {
#             "id": 0,
#             "title": "Test Group",
#             "description": null,
#             "defaultApplication": null,
#             "tags": [
#             ]
#         }
#     },
#     "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": [
#         ],
#         "modules": null
#     },
#     "favorite": false,
#     "tags": [
#     ]
# }

Communication Flow: Visual

Example: An Application with default values

Frequency of use	Common
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(), 
        modules = null, 
        outputFileGlobs = listOf("*"), 
        parameters = listOf(ApplicationParameter.Text(
            defaultValue = JsonObject(mapOf("type" to JsonLiteral(
                coerceToInlineType = null, 
                content = "text", 
                isString = true, 
            )),"value" to JsonLiteral(
                coerceToInlineType = null, 
                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", 
        flavorName = null, 
        group = ApplicationGroup(
            defaultApplication = null, 
            description = null, 
            id = 0, 
            tags = emptyList(), 
            title = "Test Group", 
        ), 
        isPublic = true, 
        name = "acme-web", 
        public = true, 
        title = "Acme web", 
        version = "1.0.0", 
        website = null, 
    ), 
    tags = emptyList(), 
)
*/

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,
#         "flavorName": null,
#         "group": {
#             "id": 0,
#             "title": "Test Group",
#             "description": null,
#             "defaultApplication": null,
#             "tags": [
#             ]
#         }
#     },
#     "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": [
#         ],
#         "modules": null
#     },
#     "favorite": false,
#     "tags": [
#     ]
# }

Communication Flow: Visual

Remote Procedure Calls

advancedSearch

Searches in the Application catalog using more advanced parameters

Request	Response	Error
AdvancedSearchRequest	Page<ApplicationSummaryWithFavorite>	CommonErrorMessage

create

Creates a new Application and inserts it into the catalog

Request	Response	Error
Unit	Unit	CommonErrorMessage

fetchLogo

Retrieves a logo associated with a group

Request	Response	Error
FetchLogoRequest	Unit	CommonErrorMessage

findByName

Finds Applications given an exact name

Request	Response	Error
FindByNameAndPagination	Page<ApplicationSummaryWithFavorite>	CommonErrorMessage

findByNameAndVersion

Retrieves an Application by name and version, or newest Application if version is not specified

Request	Response	Error
FindApplicationAndOptionalDependencies	ApplicationWithFavoriteAndTags	CommonErrorMessage

findBySupportedFileExtension

Finds a page of Application which can open a specific UFile

Request	Response	Error
FindBySupportedFileExtension	PageV2<ApplicationWithExtension>	CommonErrorMessage

findLatestByTool

Retrieves the latest version of an Application using a specific tool

Request	Response	Error
FindLatestByToolRequest	Page<Application>	CommonErrorMessage

hasPermission

Check if an entity has permission to use a specific Application

Request	Response	Error
HasPermissionRequest	Boolean	CommonErrorMessage

isPublic

Checks if an Application is publicly accessible

Request	Response	Error
IsPublicRequest	IsPublicResponse	CommonErrorMessage

listAcl

Retrieves the permission information associated with an Application

Request	Response	Error
ListAclRequest	List<DetailedEntityWithPermission>	CommonErrorMessage

listAll

Lists all Applications

Request	Response	Error
PaginationRequest	Page<ApplicationSummaryWithFavorite>	CommonErrorMessage

Results are not ordered in any specific fashion

listGroups

Request	Response	Error
Unit	List<ApplicationGroup>	CommonErrorMessage

listTags

List all application tags

Request	Response	Error
Unit	List<String>	CommonErrorMessage

retrieveFavorites

Retrieves the list of favorite Applications for the curent user

Request	Response	Error
PaginationRequest	Page<ApplicationSummaryWithFavorite>	CommonErrorMessage

retrieveGroup

Request	Response	Error
RetrieveGroupRequest	RetrieveGroupResponse	CommonErrorMessage

searchApps

Searches in the Application catalog using a free-text query

Request	Response	Error
AppSearchRequest	Page<ApplicationSummaryWithFavorite>	CommonErrorMessage

searchTags

Browses the Application catalog by tag

Request	Response	Error
TagSearchRequest	Page<ApplicationSummaryWithFavorite>	CommonErrorMessage

store

Returns the application catalog sections

Request	Response	Error
AppStoreSectionsRequest	AppStoreSectionsResponse	CommonErrorMessage

clearGroupLogo

Removes a logo associated with a group

Request	Response	Error
ClearLogoRequest	Unit	CommonErrorMessage

clearLogo

Removes a logo associated with an Application

Request	Response	Error
ClearLogoRequest	Unit	CommonErrorMessage

createGroup

Request	Response	Error
CreateGroupRequest	CreateGroupResponse	CommonErrorMessage

createTag

Attaches a set of tags to an Application

Request	Response	Error
CreateTagsRequest	Unit	CommonErrorMessage

delete

Removes an Application from the catalog

Request	Response	Error
DeleteAppRequest	Unit	CommonErrorMessage

deleteGroup

Request	Response	Error
DeleteGroupRequest	Unit	CommonErrorMessage

devImport

An endpoint for importing applications - Only usable in dev environments

Request	Response	Error
DevImportRequest	Unit	CommonErrorMessage

removeTag

Removes a set of tags from an Application

Request	Response	Error
CreateTagsRequest	Unit	CommonErrorMessage

setGroup

Request	Response	Error
SetGroupRequest	Unit	CommonErrorMessage

setPublic

Changes the 'publicly accessible' status of an Application

Request	Response	Error
SetPublicRequest	Unit	CommonErrorMessage

toggleFavorite

Toggles the favorite status of an Application for the current user

Request	Response	Error
FavoriteRequest	Unit	CommonErrorMessage

updateAcl

Updates the permissions associated with an Application

Request	Response	Error
UpdateAclRequest	Unit	CommonErrorMessage

updateFlavor

Updates the flavor name for a set of applications

Request	Response	Error
UpdateFlavorRequest	Unit	CommonErrorMessage

updateGroup

Request	Response	Error
UpdateGroupRequest	Unit	CommonErrorMessage

updateLanding

Updates the landing page of the application store

Request	Response	Error
Unit	Unit	CommonErrorMessage

updateOverview

Updates the overview page of the application store

Request	Response	Error
Unit	Unit	CommonErrorMessage

uploadGroupLogo

Uploads a logo and associates it with a group

Request	Response	Error
UploadApplicationLogoRequest	Unit	CommonErrorMessage

uploadLogo

Uploads a logo and associates it with an Application

Request	Response	Error
UploadApplicationLogoRequest	Unit	CommonErrorMessage

Data Models

Application

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

---

ApplicationMetadata

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 flavorName: String?,
    val group: ApplicationGroup?,
    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

---

ApplicationInvocationDescription

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 modules: ModulesSection?,
    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

---

ApplicationType

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

---

VncDescription

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

---

WebDescription

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

---

ContainerDescription

Information to the Provider about how to launch the container

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

Properties

---

ApplicationParameter

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

---

ApplicationParameter.TextArea

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

---

ApplicationParameter.Bool

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

---

ApplicationParameter.Enumeration

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

---

ApplicationParameter.FloatingPoint

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

---

ApplicationParameter.Ingress

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

---

ApplicationParameter.InputDirectory

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

---

ApplicationParameter.InputFile

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

---

ApplicationParameter.Integer

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

---

ApplicationParameter.LicenseServer

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

---

ApplicationParameter.NetworkIP

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

---

ApplicationParameter.Peer

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

---

ApplicationParameter.Text

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

---

AppParameterValue

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

A reference to block storage (Not yet implemented)

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

Properties

---

AppParameterValue.Bool

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

---

AppParameterValue.File

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

---

AppParameterValue.FloatingPoint

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

---

AppParameterValue.Ingress

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

---

AppParameterValue.Integer

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

---

AppParameterValue.License

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

---

AppParameterValue.Network

A reference to block storage (Not yet implemented)

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

Properties

---

AppParameterValue.Peer

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

---

AppParameterValue.Text

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

---

InvocationParameter

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

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

---

EnvironmentVariableParameter

Produces an environment variable (TODO Documentation)

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

Properties

---

VariableInvocationParameter

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

---

WordInvocationParameter

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

---

AccessEntity

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

Properties

---

AppParameterValue.TextArea

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

---

AppStorePageType

enum class AppStorePageType {
    LANDING,
    FULL,
}

Properties

---

AppStoreSection

data class AppStoreSection(
    val id: Int,
    val name: String,
    val featured: List<ApplicationGroup>,
    val items: List<ApplicationGroup>,
)

Properties

---

ApplicationAccessRight

enum class ApplicationAccessRight {
    LAUNCH,
}

Properties

---

ApplicationGroup

data class ApplicationGroup(
    val id: Int,
    val title: String,
    val description: String?,
    val defaultApplication: String?,
    val tags: List<String>?,
)

Properties

---

ApplicationParameter.EnumOption

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

Properties

---

ApplicationSummary

data class ApplicationSummary(
    val metadata: ApplicationMetadata,
)

Properties

---

ApplicationSummaryWithFavorite

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

---

ApplicationWithExtension

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

---

ApplicationWithFavoriteAndTags

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

---

DetailedAccessEntity

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

Properties

---

DetailedEntityWithPermission

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

Properties

---

FindApplicationAndOptionalDependencies

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

Properties

---

FindBySupportedFileExtension

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

---

ModulesSection

Section describing the module capabilities of an application

data class ModulesSection(
    val mountPath: String,
    val optional: List<String>,
)

Properties

---

Project

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

Properties

---

SshDescription

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

---

SshDescription.Mode

enum class Mode {
    DISABLED,
    OPTIONAL,
    MANDATORY,
}

Properties

---

ToolReference

A reference to a Tool

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

Properties

---

ACLEntryRequest

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

Properties

---

AdvancedSearchRequest

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

Properties

---

AppSearchRequest

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

Properties

---

AppStoreSectionsRequest

data class AppStoreSectionsRequest(
    val page: AppStorePageType,
)

Properties

---

CreateGroupRequest

data class CreateGroupRequest(
    val title: String,
)

Properties

---

CreateTagsRequest

data class CreateTagsRequest(
    val tags: List<String>,
    val groupId: Int,
)

Properties

---

DeleteAppRequest

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

Properties

---

DeleteGroupRequest

data class DeleteGroupRequest(
    val id: Int,
)

Properties

---

DevImportRequest

data class DevImportRequest(
    val endpoint: String,
    val checksum: String,
)

Properties

---

FavoriteRequest

data class FavoriteRequest(
    val appName: String,
)

Properties

---

FindLatestByToolRequest

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

Properties

---

HasPermissionRequest

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

Properties

---

IsPublicRequest

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

Properties

---

ListAclRequest

data class ListAclRequest(
    val appName: String,
)

Properties

---

RetrieveGroupRequest

data class RetrieveGroupRequest(
    val id: Int?,
    val name: String?,
)

Properties

---

SetGroupRequest

data class SetGroupRequest(
    val groupId: Int?,
    val applicationName: String,
)

Properties

---

SetPublicRequest

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

Properties

---

TagSearchRequest

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

Properties

---

UpdateAclRequest

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

Properties

---

UpdateFlavorRequest

data class UpdateFlavorRequest(
    val applicationName: String,
    val flavorName: String,
)

Properties

---

UpdateGroupRequest

data class UpdateGroupRequest(
    val id: Int,
    val title: String,
    val logo: List<Byte>?,
    val description: String?,
    val defaultApplication: String?,
)

Properties

---

AppStoreSectionsResponse

data class AppStoreSectionsResponse(
    val sections: List<AppStoreSection>,
)

Properties

---

CreateGroupResponse

data class CreateGroupResponse(
    val id: Int,
)

Properties

---

IsPublicResponse

data class IsPublicResponse(
    val public: JsonObject,
)

Properties

---

RetrieveGroupResponse

data class RetrieveGroupResponse(
    val group: ApplicationGroup,
    val applications: List<ApplicationSummary>,
)

Properties

---