products

« Previous section Next section »

UCloud Developer Guide / Accounting and Project Management / Products

Products

Products define the services exposed by a Provider.

Rationale

Providers expose services into UCloud. But, different Providers expose different services. UCloud uses Products to define the services of a Provider. As an example, a Provider might have the following services:

• Storage: Two tiers of storage. Fast storage, for short-lived data. Slower storage, for long-term data storage.

• Compute: Three tiers of compute. Slim nodes for ordinary computations. Fat nodes for memory-hungry applications. GPU powered nodes for artificial intelligence.

For many Providers, the story doesn't stop here. You can often allocate your Jobs on a machine "slice". This can increase overall utilization, as users aren't forced to request full nodes. A Provider might advertise the following slices:

Name	vCPU	RAM (GB)	GPU	Price
example-slim-1	1	4	0	0,100 DKK/hr
example-slim-2	2	8	0	0,200 DKK/hr
example-slim-4	4	16	0	0,400 DKK/hr
example-slim-8	8	32	0	0,800 DKK/hr

Table: A single node-type split up into individual slices.

Concepts

UCloud represent these concepts in the following abstractions:

• ProductType: A classifier for a Product, defines the behavior of a Product.

• ProductCategory: A group of similar Products. In most cases, Products in a category run on identical hardware.

• Product: Defines a concrete service exposed by a Provider

Below, we show an example of how a Provider can organize their services.

Figure: All Products in UCloud are of a specific type, such as: STORAGE and COMPUTE. Providers have zero or more categories of every type, e.g. example-slim. In a given category, the Provider has one or more slices.

Payment Model

UCloud uses a flexible payment model, which allows Providers to use a model which is familiar to them. In short, a Provider must first choose one of the following payment types:

1. Differential models (ChargeType.DIFFERENTIAL_QUOTA)

   1. Quota (ProductPriceUnit.PER_UNIT)

2. Absolute models (ChargeType.ABSOLUTE)

   1. One-time payment (ProductPriceUnit.PER_UNIT and ProductPriceUnit.CREDITS_PER_UNIT)

   2. Periodic payment (ProductPriceUnit.UNITS_PER_X and ProductPriceUnit.CREDITS_PER_X)

---

📝 NOTE: To select a model, you must specify a ChargeType and a ProductPriceUnit. We have shown all valid combinations above.

---

Quotas put a strict limit on the "number of units" in concurrent use. UCloud measures this number in a Product specific way. A unit is pre-defined and stable across the entirety of UCloud. A few quick examples:

• Storage: Measured in GB (10⁹ bytes. 1 byte = 1 octet)

• Compute: Measured in hyper-threaded cores (vCPU)

• Public IPs: Measured in IP addresses

• Public links: Measured in public links

If using an absolute model, then you must choose the unit of allocation:

• You specify allocations in units (UNITS_PER_X). For example: 3000 IP addresses.

• You specify allocations in money (CREDITS_PER_X). For example: 1000 DKK.

---

📝 NOTE: For precision purposes, UCloud specifies all money sums as integers. As a result, 1 UCloud credit is equal to one millionth of a Danish Crown (DKK).

---

When using periodic payments, you must also specify the length of a single period. Providers are not required to report usage once for every period. But the reporting itself must specify usage in number of periods. UCloud supports period lengths of a minute, one hour and one day.

Understanding the price

All Products have a pricePerUnit property:

The pricePerUnit specifies the cost of a single unit in a single period.

Products not paid with credits must have a pricePerUnit of 1. Quotas and one-time payments are always made for a single "period".

This can lead to some surprising results when defining compute products. Let's consider the example from the beginning:

Name	vCPU	RAM (GB)	GPU	Price
example-slim-1	1	4	0	0,100 DKK/hr
example-slim-2	2	8	0	0,200 DKK/hr
example-slim-4	4	16	0	0,400 DKK/hr
example-slim-8	8	32	0	0,800 DKK/hr

Table: Human-readable compute products.

When implementing this in UCloud, a Provider might naively set the following prices:

Name	ChargeType	ProductPriceUnit	Price
example-slim-1	ABSOLUTE	CREDITS_PER_HOUR	100_000
example-slim-2	ABSOLUTE	CREDITS_PER_HOUR	200_000
example-slim-4	ABSOLUTE	CREDITS_PER_HOUR	400_000
example-slim-8	ABSOLUTE	CREDITS_PER_HOUR	800_000

Table: ️⚠️ Incorrect implementation of prices in UCloud ️⚠️

This is wrong. UCloud defines the price as the cost of using a single unit in a single period. The "unit of use" for a compute product is a single vCPU. Thus, a correct Provider implementation would over-report the usage by a factor equal to the number of vCPUs in the machine. Instead, the price must be based on a single vCPU:

Name	ChargeType	ProductPriceUnit	Price
example-slim-1	ABSOLUTE	CREDITS_PER_HOUR	100_000
example-slim-2	ABSOLUTE	CREDITS_PER_HOUR	100_000
example-slim-4	ABSOLUTE	CREDITS_PER_HOUR	100_000
example-slim-8	ABSOLUTE	CREDITS_PER_HOUR	100_000

Table: ✅ Correct implementation of prices in UCloud ✅

Table of Contents

1. Examples

2. Remote Procedure Calls

3. Data Models

Example: Browse all available products

Frequency of use	Common
Actors	An authenticated user (user)

Communication Flow: Kotlin

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

/*
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, 
    ), Product.Storage(
        allowAllocationRequestsFrom = AllocationRequestsGroup.ALL, 
        category = ProductCategoryId(
            id = "example-storage", 
            name = "example-storage", 
            provider = "example", 
        ), 
        chargeType = ChargeType.DIFFERENTIAL_QUOTA, 
        description = "An example storage product (Quota)", 
        freeToUse = false, 
        hiddenInGrantApplications = false, 
        name = "example-storage", 
        pricePerUnit = 1, 
        priority = 0, 
        productType = ProductType.STORAGE, 
        unitOfPrice = ProductPriceUnit.PER_UNIT, 
        version = 1, 
        balance = null, 
        id = "example-storage", 
        maxUsableBalance = null, 
    )), 
    itemsPerPage = 50, 
    next = null, 
)
*/

Communication Flow: Curl

# ------------------------------------------------------------------------------------------------------
# $host is the UCloud instance to contact. Example: 'http://localhost:8080' or 'https://cloud.sdu.dk'
# $accessToken is a valid access-token issued by UCloud
# ------------------------------------------------------------------------------------------------------

# Authenticated as user
curl -XGET -H "Authorization: Bearer $accessToken" "$host/api/products/browse?itemsPerPage=50" 

# {
#     "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"
#         },
#         {
#             "type": "storage",
#             "balance": null,
#             "maxUsableBalance": null,
#             "name": "example-storage",
#             "pricePerUnit": 1,
#             "category": {
#                 "name": "example-storage",
#                 "provider": "example"
#             },
#             "description": "An example storage product (Quota)",
#             "priority": 0,
#             "version": 1,
#             "freeToUse": false,
#             "allowAllocationRequestsFrom": "ALL",
#             "unitOfPrice": "PER_UNIT",
#             "chargeType": "DIFFERENTIAL_QUOTA",
#             "hiddenInGrantApplications": false,
#             "productType": "STORAGE"
#         }
#     ],
#     "next": null
# }

Communication Flow: Visual

Example: Browse products by type

Frequency of use	Common
Actors	An authenticated user (user)

Communication Flow: Kotlin

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()

/*
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, 
)
*/

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
# ------------------------------------------------------------------------------------------------------

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

# {
#     "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
# }

Communication Flow: Visual

Example: Retrieve a single product

Frequency of use	Common
Actors	An authenticated user (user)

Communication Flow: Kotlin

Products.retrieve.call(
    ProductsRetrieveRequest(
        filterArea = null, 
        filterCategory = "example-compute", 
        filterName = "example-compute", 
        filterProvider = "example", 
        filterVersion = null, 
        includeBalance = null, 
        includeMaxBalance = null, 
    ),
    user
).orThrow()

/*
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, 
)
*/

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
# ------------------------------------------------------------------------------------------------------

# Authenticated as user
curl -XGET -H "Authorization: Bearer $accessToken" "$host/api/products/retrieve?filterName=example-compute&filterCategory=example-compute&filterProvider=example" 

# {
#     "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"
# }

Communication Flow: Visual

Remote Procedure Calls

browse

Browse a set of products

Request	Response	Error
ProductsBrowseRequest	PageV2<Product>	CommonErrorMessage

This endpoint uses the normal pagination and filter mechanisms to return a list of Product.

Examples:

Example
Browse in the full product catalog
Browse for a specific type of product (e.g. compute)

retrieve

Retrieve a single product

Request	Response	Error
ProductsRetrieveRequest	Product	CommonErrorMessage

Examples:

Example
Retrieving a single product by ID

create

Creates a new Product in UCloud

Request	Response	Error
BulkRequest<Product>	Unit	CommonErrorMessage

Only providers and UCloud administrators can create a Product. When this endpoint is invoked by a provider, then the provider field of the Product must match the invoking user.

The Product will become ready and visible in UCloud immediately after invoking this call. If no Product has been created in this category before, then this category will be created.

---

📝 NOTE: Most properties of a ProductCategory are immutable and must not be changed. As a result, you cannot create a new Product later with different category properties.

---

If the Product already exists, then a new version of it is created. Version numbers are always sequential and the incoming version number is always ignored by UCloud.

Data Models

ChargeType

enum class ChargeType {
    ABSOLUTE,
    DIFFERENTIAL_QUOTA,
}

Properties

---

Product

Products define the services exposed by a Provider.

sealed class Product {
    abstract val allowAllocationRequestsFrom: AllocationRequestsGroup
    abstract val balance: Long?
    abstract val category: ProductCategoryId
    abstract val chargeType: ChargeType
    abstract val description: String
    abstract val freeToUse: Boolean
    abstract val hiddenInGrantApplications: Boolean
    abstract val id: String
    abstract val maxUsableBalance: Long?
    abstract val name: String
    abstract val pricePerUnit: Long
    abstract val priority: Int
    abstract val productType: ProductType
    abstract val unitOfPrice: ProductPriceUnit
    abstract val version: Int

    class Compute : Product()
    class Ingress : Product()
    class License : Product()
    class NetworkIP : Product()
    class Storage : Product()
}

For more information see this page.

Properties

---

Product.Compute

A compute Product

data class Compute(
    val name: String,
    val pricePerUnit: Long,
    val category: ProductCategoryId,
    val description: String?,
    val priority: Int?,
    val cpu: Int?,
    val memoryInGigs: Int?,
    val gpu: Int?,
    val cpuModel: String?,
    val memoryModel: String?,
    val gpuModel: String?,
    val version: Int?,
    val freeToUse: Boolean?,
    val allowAllocationRequestsFrom: AllocationRequestsGroup?,
    val unitOfPrice: ProductPriceUnit?,
    val chargeType: ChargeType?,
    val hiddenInGrantApplications: Boolean?,
    val productType: ProductType,
    val balance: Long?,
    val id: String,
    val maxUsableBalance: Long?,
    val type: String /* "compute" */,
)

Unit	API
Measured in hyper-threaded cores (vCPU)	Click here

Properties

---

Product.Ingress

An ingress Product

data class Ingress(
    val name: String,
    val pricePerUnit: Long,
    val category: ProductCategoryId,
    val description: String?,
    val priority: Int?,
    val version: Int?,
    val freeToUse: Boolean?,
    val allowAllocationRequestsFrom: AllocationRequestsGroup?,
    val unitOfPrice: ProductPriceUnit?,
    val chargeType: ChargeType?,
    val hiddenInGrantApplications: Boolean?,
    val productType: ProductType,
    val balance: Long?,
    val id: String,
    val maxUsableBalance: Long?,
    val type: String /* "ingress" */,
)

Unit	API
Measured in number of ingresses	Click here

Properties

---

Product.License

A license Product

data class License(
    val name: String,
    val pricePerUnit: Long,
    val category: ProductCategoryId,
    val description: String?,
    val priority: Int?,
    val tags: List<String>?,
    val version: Int?,
    val freeToUse: Boolean?,
    val allowAllocationRequestsFrom: AllocationRequestsGroup?,
    val unitOfPrice: ProductPriceUnit?,
    val chargeType: ChargeType?,
    val hiddenInGrantApplications: Boolean?,
    val productType: ProductType,
    val balance: Long?,
    val id: String,
    val maxUsableBalance: Long?,
    val type: String /* "license" */,
)

Unit	API
Measured in number of licenses	Click here

Properties

---

Product.NetworkIP

An IP address Product

data class NetworkIP(
    val name: String,
    val pricePerUnit: Long,
    val category: ProductCategoryId,
    val description: String?,
    val priority: Int?,
    val version: Int?,
    val freeToUse: Boolean?,
    val allowAllocationRequestsFrom: AllocationRequestsGroup?,
    val unitOfPrice: ProductPriceUnit?,
    val chargeType: ChargeType?,
    val hiddenInGrantApplications: Boolean?,
    val productType: ProductType,
    val balance: Long?,
    val id: String,
    val maxUsableBalance: Long?,
    val type: String /* "network_ip" */,
)

Unit	API
Measured in number of IP addresses	Click here

Properties

---

Product.Storage

A storage Product

data class Storage(
    val name: String,
    val pricePerUnit: Long,
    val category: ProductCategoryId,
    val description: String?,
    val priority: Int?,
    val version: Int?,
    val freeToUse: Boolean?,
    val allowAllocationRequestsFrom: AllocationRequestsGroup?,
    val unitOfPrice: ProductPriceUnit?,
    val chargeType: ChargeType?,
    val hiddenInGrantApplications: Boolean?,
    val productType: ProductType,
    val balance: Long?,
    val id: String,
    val maxUsableBalance: Long?,
    val type: String /* "storage" */,
)

Unit	API
Measured in GB (10⁹ bytes. 1 byte = 1 octet)	Click here

Properties

---

ProductCategoryId

data class ProductCategoryId(
    val name: String,
    val provider: String,
    val id: String,
)

Properties

---

ProductPriceUnit

enum class ProductPriceUnit {
    CREDITS_PER_UNIT,
    PER_UNIT,
    CREDITS_PER_MINUTE,
    CREDITS_PER_HOUR,
    CREDITS_PER_DAY,
    UNITS_PER_MINUTE,
    UNITS_PER_HOUR,
    UNITS_PER_DAY,
}

Properties

---

ProductReference

Contains a unique reference to a Product

data class ProductReference(
    val id: String,
    val category: String,
    val provider: String,
)

Properties

---

ProductType

A classifier for a Product

enum class ProductType {
    STORAGE,
    COMPUTE,
    INGRESS,
    LICENSE,
    NETWORK_IP,
}

For more information, see the individual Products:

• STORAGE: See Product.Storage

• COMPUTE: See Product.Compute

• INGRESS: See Product.Ingress

• LICENSE: See Product.License

• NETWORK_IP: See Product.NetworkIP

Properties

---

AllocationRequestsGroup

enum class AllocationRequestsGroup {
    ALL,
    PERSONAL,
    PROJECT,
}

Properties

---

ProductsBrowseRequest

The base type for requesting paginated content.

data class ProductsBrowseRequest(
    val itemsPerPage: Int?,
    val next: String?,
    val consistency: PaginationRequestV2Consistency?,
    val itemsToSkip: Long?,
    val filterName: String?,
    val filterProvider: String?,
    val filterArea: ProductType?,
    val filterCategory: String?,
    val filterVersion: Int?,
    val showAllVersions: Boolean?,
    val includeBalance: Boolean?,
    val includeMaxBalance: Boolean?,
)

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

---

ProductsRetrieveRequest

data class ProductsRetrieveRequest(
    val filterName: String,
    val filterCategory: String,
    val filterProvider: String,
    val filterArea: ProductType?,
    val filterVersion: Int?,
    val includeBalance: Boolean?,
    val includeMaxBalance: Boolean?,
)

Properties

---