API reference

This page focuses on the high-level APIs used by UCX applications:

• ucloud.dk/shared/pkg/ucx/ucxsvc (recommended helpers)
• ucloud.dk/shared/pkg/ucx/ucxapi (typed RPC calls)

ucxsvc high-level helpers

ucxsvc wraps common stack workflows and resource orchestration.

Stack lifecycle

Error handling for stack helpers is controlled by the stack state itself. When a stack operation fails, ucxsvc marks stack.Ok = false and sends a user-facing failure message. After this, stack helper calls become safe no-ops, so it is generally safe to keep calling the helper functions in sequence.

If you prefer explicit early exit, check stack.Ok and return immediately:

if !stack.Ok {
    return
}

Resources created as part of a stack are automatically cleaned up if StackConfirmAndOpen(stack) is not called within two minutes of stack creation. As a result, stack flows must end by calling StackConfirmAndOpen(stack). Note that StackConfirmAndOpen(stack) will itself only confirm the stack creation if the internal Ok property is true and it is thus safe to call it without checking the Ok property prior to calling it.

Each stack also has a state directory created automatically by StackCreate(...). StackWriteFile(...) and StackWriteFileEx(...) write files into this directory and are ideal for small initialization scripts and configuration files.

The mount location is controlled by stack.MountPath and can be changed before creating jobs/VMs. By default, stack.MountPath is /etc/ucloud-stack.

Unless explicitly disabled (SkipStackState in VirtualMachineSpec), the state directory is mounted read+write on all jobs/VMs created through stack helpers.

File ownership and permissions in the state directory default to ucloud:ucloud with directory mode 0770. StackWriteFile(...) writes files with default mode 0660 and StackWriteFileEx(...) allows overriding file mode.

StackWriteFile(...) is limited to 64 KiB per file. For more advanced setup logic, prefer init scripts plus custom application/VM images.

Example:

stack, ok := ucxsvc.StackCreate(app, app.JobName, "Kubernetes")
if !ok {
    return
}

ucxsvc.StackWriteFile(stack, "join-token.txt", util.SecureToken())

// Optional: override default mount path before creating jobs/VMs.
stack.MountPath = "/mnt/ucloud-stack"

initLabels := ucxsvc.StackWriteInitScript(stack, `
    cat /mnt/ucloud-stack/join-token.txt > /var/lib/ucloud/join-token.txt
`)

// Create a VirtualMachineCreate and passing the labels from initLabels.
// NOTE: Only one init script per job is possible. Init scripts are currently 
// only supported by virtual machines.

ucxsvc.StackConfirmAndOpen(stack)

Reconstructing stack context in job-connected UCX

If your job session includes stack labels, reconstruct the stack directly from SysHello job context:

type app struct {
    // ...
    Stack *ucxsvc.Stack `ucx:"-"`
}

func (app *app) OnSysHello(payload string) {
    var req orcapi.AppUcxConnectJobProviderRequest
    if err := json.Unmarshal([]byte(payload), &req); err != nil {
        return
    }

    stack, ok := ucxsvc.StackFromJob(app, req.Job)
    if ok {
        app.Stack = stack
    }
}

StackFromJob(...) resolves mount path from job file attachments when available and falls back to /etc/ucloud-stack.

Resource attachments

Jobs and virtual machines

VirtualMachineSpec fields:

• Product and Image select machine+app image.
• Hostname, Attachments, Labels configure VM launch.
• DiskSize (gigabytes) defaults to 50 if omitted.
• SkipStackState controls automatic stack state mount attachment.

UI feedback helpers

ucxapi typed RPC calls

ucxapi exposes typed ucx.Rpc[Req, Resp] calls. Standard usage:

session := *app.Session()
products, err := ucxapi.JobsRetrieveProducts.Invoke(session, util.Empty{})
if err != nil {
    ucxsvc.UiSendFailure(app, "Could not retrieve products")
    return
}

Stack RPCs

Job RPCs

Networking RPCs

Storage and license RPCs

UI RPCs

RouterPushPage has the same effect as clicking ucx.Link(...). It is implemented by the stack page frontend and only available in job-connected UCX sessions.

Notes on choosing API level

• Use ucxsvc first for stack-oriented flows.
• Use direct ucxapi calls when you need full control or unsupported operations.
• Keep user-visible errors explicit (UiSendFailure) when RPC/resource operations fail.