Example: Creating a simple batch Job

Frequency of useCommon
TriggerUser initiated
Pre-conditions
  • User has been granted credits for using the selected machine
Post-conditions
  • A Job is started in the user's workspace
Actors
  • An authenticated user (user)
Communication Flow: Kotlin
/* The user finds an interesting application from the catalog */


/* The user selects the first application ('batch' in version '1.0.0') */


/* The user requests additional information about the application */

val application = AppStore.findByNameAndVersion.call(
    FindByNameAndVersionRequest(
        appName = "a-batch-application", 
        appVersion = "1.0.0", 
    ),
    user
).orThrow()

/*
application = 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 = "batch", 
        ), VariableInvocationParameter(
            isPrefixVariablePartOfArg = false, 
            isSuffixVariablePartOfArg = false, 
            prefixGlobal = "", 
            prefixVariable = "", 
            suffixGlobal = "", 
            suffixVariable = "", 
            variableNames = listOf("var"), 
        )), 
        licenseServers = emptyList(), 
        modules = null, 
        outputFileGlobs = listOf("*"), 
        parameters = listOf(ApplicationParameter.Text(
            defaultValue = null, 
            description = "An example input variable", 
            name = "var", 
            optional = false, 
            title = "", 
        )), 
        shouldAllowAdditionalMounts = false, 
        shouldAllowAdditionalPeers = true, 
        ssh = null, 
        tool = ToolReference(
            name = "batch-tool", 
            tool = Tool(
                createdAt = 1632979836013, 
                description = NormalizedToolDescription(
                    authors = listOf("UCloud"), 
                    backend = ToolBackend.DOCKER, 
                    container = null, 
                    defaultNumberOfNodes = 1, 
                    defaultTimeAllocation = SimpleDuration(
                        hours = 1, 
                        minutes = 0, 
                        seconds = 0, 
                    ), 
                    description = "Batch tool", 
                    image = "dreg.cloud.sdu.dk/batch/batch:1.0.0", 
                    info = NameAndVersion(
                        name = "batch-tool", 
                        version = "1.0.0", 
                    ), 
                    license = "None", 
                    requiredModules = emptyList(), 
                    supportedProviders = null, 
                    title = "Batch tool", 
                ), 
                modifiedAt = 1632979836013, 
                owner = "user", 
            ), 
            version = "1.0.0", 
        ), 
        vnc = null, 
        web = null, 
    ), 
    metadata = ApplicationMetadata(
        authors = listOf("UCloud"), 
        createdAt = 1717663228434, 
        description = "This is a batch application", 
        flavorName = null, 
        group = null, 
        isPublic = true, 
        name = "a-batch-application", 
        public = true, 
        title = "A Batch Application", 
        version = "1.0.0", 
        website = null, 
    ), 
    tags = listOf("very-scientific"), 
)
*/

/* The user looks for a suitable machine */

val machineTypes = Products.browse.call(
    ProductsBrowseRequest(
        consistency = null, 
        filterArea = ProductType.COMPUTE, 
        filterCategory = null, 
        filterName = null, 
        filterProvider = null, 
        filterVersion = null, 
        includeBalance = null, 
        includeMaxBalance = null, 
        itemsPerPage = 50, 
        itemsToSkip = null, 
        next = null, 
        showAllVersions = null, 
    ),
    user
).orThrow()

/*
machineTypes = PageV2(
    items = listOf(Product.Compute(
        allowAllocationRequestsFrom = AllocationRequestsGroup.ALL, 
        category = ProductCategoryId(
            id = "example-compute", 
            name = "example-compute", 
            provider = "example", 
        ), 
        chargeType = ChargeType.ABSOLUTE, 
        cpu = 10, 
        cpuModel = null, 
        description = "An example compute product", 
        freeToUse = false, 
        gpu = 0, 
        gpuModel = null, 
        hiddenInGrantApplications = false, 
        memoryInGigs = 20, 
        memoryModel = null, 
        name = "example-compute", 
        pricePerUnit = 1000000, 
        priority = 0, 
        productType = ProductType.COMPUTE, 
        unitOfPrice = ProductPriceUnit.CREDITS_PER_MINUTE, 
        version = 1, 
        balance = null, 
        id = "example-compute", 
        maxUsableBalance = null, 
    )), 
    itemsPerPage = 50, 
    next = null, 
)
*/

/* The user starts the Job with input based on previous requests */

Jobs.create.call(
    bulkRequestOf(JobSpecification(
        allowDuplicateJob = false, 
        application = NameAndVersion(
            name = "a-batch-application", 
            version = "1.0.0", 
        ), 
        name = null, 
        openedFile = null, 
        parameters = mapOf("var" to AppParameterValue.Text(
            value = "Example", 
        )), 
        product = ProductReference(
            category = "example-compute", 
            id = "example-compute", 
            provider = "example", 
        ), 
        replicas = 1, 
        resources = null, 
        restartOnExit = null, 
        sshEnabled = null, 
        timeAllocation = null, 
    )),
    user
).orThrow()

/*
BulkResponse(
    responses = listOf(FindByStringId(
        id = "48920", 
    )), 
)
*/
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
# ------------------------------------------------------------------------------------------------------

# The user finds an interesting application from the catalog

# The user selects the first application ('batch' in version '1.0.0')

# The user requests additional information about the application

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

# application = 
# {
#     "metadata": {
#         "name": "a-batch-application",
#         "version": "1.0.0",
#         "authors": [
#             "UCloud"
#         ],
#         "title": "A Batch Application",
#         "description": "This is a batch application",
#         "website": null,
#         "public": true,
#         "flavorName": null,
#         "group": null,
#         "createdAt": 1717663228434
#     },
#     "invocation": {
#         "tool": {
#             "name": "batch-tool",
#             "version": "1.0.0",
#             "tool": {
#                 "owner": "user",
#                 "createdAt": 1632979836013,
#                 "modifiedAt": 1632979836013,
#                 "description": {
#                     "info": {
#                         "name": "batch-tool",
#                         "version": "1.0.0"
#                     },
#                     "container": null,
#                     "defaultNumberOfNodes": 1,
#                     "defaultTimeAllocation": {
#                         "hours": 1,
#                         "minutes": 0,
#                         "seconds": 0
#                     },
#                     "requiredModules": [
#                     ],
#                     "authors": [
#                         "UCloud"
#                     ],
#                     "title": "Batch tool",
#                     "description": "Batch tool",
#                     "backend": "DOCKER",
#                     "license": "None",
#                     "image": "dreg.cloud.sdu.dk/batch/batch:1.0.0",
#                     "supportedProviders": null
#                 }
#             }
#         },
#         "invocation": [
#             {
#                 "type": "word",
#                 "word": "batch"
#             },
#             {
#                 "type": "var",
#                 "variableNames": [
#                     "var"
#                 ],
#                 "prefixGlobal": "",
#                 "suffixGlobal": "",
#                 "prefixVariable": "",
#                 "suffixVariable": "",
#                 "isPrefixVariablePartOfArg": false,
#                 "isSuffixVariablePartOfArg": false
#             }
#         ],
#         "parameters": [
#             {
#                 "type": "text",
#                 "name": "var",
#                 "optional": false,
#                 "defaultValue": null,
#                 "title": "",
#                 "description": "An example input variable"
#             }
#         ],
#         "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": [
#         "very-scientific"
#     ]
# }

# The user looks for a suitable machine

curl -XGET -H "Authorization: Bearer $accessToken" "$host/api/products/browse?itemsPerPage=50&filterArea=COMPUTE" 

# machineTypes = 
# {
#     "itemsPerPage": 50,
#     "items": [
#         {
#             "type": "compute",
#             "balance": null,
#             "maxUsableBalance": null,
#             "name": "example-compute",
#             "pricePerUnit": 1000000,
#             "category": {
#                 "name": "example-compute",
#                 "provider": "example"
#             },
#             "description": "An example compute product",
#             "priority": 0,
#             "cpu": 10,
#             "memoryInGigs": 20,
#             "gpu": 0,
#             "cpuModel": null,
#             "memoryModel": null,
#             "gpuModel": null,
#             "version": 1,
#             "freeToUse": false,
#             "allowAllocationRequestsFrom": "ALL",
#             "unitOfPrice": "CREDITS_PER_MINUTE",
#             "chargeType": "ABSOLUTE",
#             "hiddenInGrantApplications": false,
#             "productType": "COMPUTE"
#         }
#     ],
#     "next": null
# }

# The user starts the Job with input based on previous requests

curl -XPOST -H "Authorization: Bearer $accessToken" -H "Content-Type: content-type: application/json; charset=utf-8" "$host/api/jobs" -d '{
    "items": [
        {
            "application": {
                "name": "a-batch-application",
                "version": "1.0.0"
            },
            "product": {
                "id": "example-compute",
                "category": "example-compute",
                "provider": "example"
            },
            "name": null,
            "replicas": 1,
            "allowDuplicateJob": false,
            "parameters": {
                "var": {
                    "type": "text",
                    "value": "Example"
                }
            },
            "resources": null,
            "timeAllocation": null,
            "openedFile": null,
            "restartOnExit": null,
            "sshEnabled": null
        }
    ]
}'


# {
#     "responses": [
#         {
#             "id": "48920"
#         }
#     ]
# }
Communication Flow: Visual