Products¶

Products define the services exposed by a Provider.

Rationale¶

Providers expose services into UCloud. But, different Providers expose different services. UCloud uses ProductV2s 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)	Price
`example-slim-1`	1	4	0,100 DKK/hr
`example-slim-2`	2	8	0,200 DKK/hr
`example-slim-4`	4	16	0,400 DKK/hr
`example-slim-8`	8	32	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 ProductV2, defines the behavior of a ProductV2.
ProductCategory: A group of similar Products. In most cases, Products in a category run on identical hardware.
ProductV2: Defines a concrete service exposed by a Provider

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

Figure: All ProductV2s 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. The payment model is defined in the ProductCategory Here the provider will define the AccountingUnit and AccountingFrequency The unit describes the unit in which the provider reports usage. This unit is opaque to UCloud/Core and UCloud/Core will not attempt to convert or in any way interpret the meaning of this unit. The frequency describes how often a charge occurs. These are either periodic or non-periodic. UCloud’s accounting system has slightly different rules depending on if a product is periodic or non-periodic. Providers are not required to report once for have period. The frequency simply tells UCloud/Core how to interpret the unit. For example a combination of unit = Core and frequency = PERIODIC_MINUTE should be interpreted as core-minutes. UCloud’s frontend may choose to convert this into core-hours for better readability, but the internal numbers are stored in minutes.

Table of Contents¶

1. Remote Procedure Calls

Name	Description
`browse`	Browse a set of products
`retrieve`	Retrieve a single product
`create`	Creates a new [`Product`](/docs/reference/dk.sdu.cloud.accounting.api.Product.md) in UCloud

2. Data Models

Name	Description
`AccountingFrequency`	No description
`AccountingUnit`	No description
`ProductCategory`	No description
`ProductType`	A classifier for a [`Product`](/docs/reference/dk.sdu.cloud.accounting.api.Product.md)
`ProductV2`	Products define the services exposed by a Provider.
`ProductV2.Compute`	Products define the services exposed by a Provider.
`ProductV2.Ingress`	Products define the services exposed by a Provider.
`ProductV2.License`	Products define the services exposed by a Provider.
`ProductV2.NetworkIP`	Products define the services exposed by a Provider.
`ProductV2.Storage`	Products define the services exposed by a Provider.
`ProductsV2BrowseRequest`	The base type for requesting paginated content.
`ProductsV2RetrieveRequest`	No description

Remote Procedure Calls¶

`browse`¶

Browse a set of products

Request	Response	Error
`ProductsV2BrowseRequest`	`PageV2<ProductV2>`	`CommonErrorMessage`

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

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
`ProductsV2RetrieveRequest`	`ProductV2`	`CommonErrorMessage`

Examples:

Example
Retrieving a single product by ID

`create`¶

Creates a new Product in UCloud

Request	Response	Error
`BulkRequest<ProductV2>`	`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 the existing product is overwritten.

Data Models¶

`AccountingFrequency`¶

enum class AccountingFrequency {
    ONCE,
    PERIODIC_MINUTE,
    PERIODIC_HOUR,
    PERIODIC_DAY,
}

Properties

ONCE

PERIODIC_MINUTE

PERIODIC_HOUR

PERIODIC_DAY

`AccountingUnit`¶

data class AccountingUnit(
    val name: String,
    val namePlural: String,
    val floatingPoint: Boolean,
    val displayFrequencySuffix: Boolean,
)

Properties

name: String

namePlural: String

floatingPoint: Boolean

displayFrequencySuffix: Boolean

`ProductCategory`¶

data class ProductCategory(
    val name: String,
    val provider: String,
    val productType: ProductType,
    val accountingUnit: AccountingUnit,
    val accountingFrequency: AccountingFrequency,
    val freeToUse: Boolean?,
    val allowSubAllocations: Boolean?,
)

Properties

name: String

provider: String

productType: ProductType

accountingUnit: AccountingUnit

accountingFrequency: AccountingFrequency

freeToUse: Boolean? Indicates that a Wallet is not required to use this Product category

Under normal circumstances, a Wallet is always required. This is required even if a Product has a pricePerUnit of 0. If freeToUse = true then the Wallet requirement is dropped.

allowSubAllocations: Boolean?

`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

STORAGE See Product.Storage

COMPUTE See Product.Compute

INGRESS See Product.Ingress

LICENSE See Product.License

NETWORK_IP See Product.NetworkIP

`ProductV2`¶

Products define the services exposed by a Provider.

sealed class ProductV2 {
    abstract val category: ProductCategory
    abstract val description: String
    abstract val hiddenInGrantApplications: Boolean
    abstract val name: String
    abstract val price: Long
    abstract val productType: ProductType
    abstract val usage: Long?

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

For more information see this page.

Properties

category: ProductCategory The category groups similar products together, it also defines which provider owns the product

description: String A short (single-line) description of the Product

hiddenInGrantApplications: Boolean Flag to indicate that this Product is not publicly available

⚠️ WARNING: This doesn’t make the Product secret. In only hides the Product from the grant system’s UI.

name: String A unique name associated with this Product

price: Long Price is for usage of a single product in the accountingFrequency period specified by the product category.

productType: ProductType Classifier used to explain the type of Product

usage: Long? Included only with certain endpoints which support `includeBalance`

`ProductV2.Compute`¶

Products define the services exposed by a Provider.

data class Compute(
    val name: String,
    val price: Long,
    val category: ProductCategory,
    val description: String?,
    val cpu: Int?,
    val memoryInGigs: Int?,
    val gpu: Int?,
    val cpuModel: String?,
    val memoryModel: String?,
    val gpuModel: String?,
    val hiddenInGrantApplications: Boolean?,
    val productType: ProductType,
    val usage: Long?,
    val type: String /* "compute" */,
)

For more information see this page.

Properties

name: String A unique name associated with this Product

price: Long Price is for usage of a single product in the accountingFrequency period specified by the product category.

category: ProductCategory The category groups similar products together, it also defines which provider owns the product

description: String? A short (single-line) description of the Product

cpu: Int?

memoryInGigs: Int?

gpu: Int?

cpuModel: String?

memoryModel: String?

gpuModel: String?

hiddenInGrantApplications: Boolean? Flag to indicate that this Product is not publicly available

⚠️ WARNING: This doesn’t make the Product secret. In only hides the Product from the grant system’s UI.

productType: ProductType

usage: Long? Included only with certain endpoints which support `includeBalance`

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

`ProductV2.Ingress`¶

Products define the services exposed by a Provider.

data class Ingress(
    val name: String,
    val price: Long,
    val category: ProductCategory,
    val description: String?,
    val hiddenInGrantApplications: Boolean?,
    val productType: ProductType,
    val usage: Long?,
    val type: String /* "ingress" */,
)

For more information see this page.

Properties

name: String A unique name associated with this Product

price: Long Price is for usage of a single product in the accountingFrequency period specified by the product category.

category: ProductCategory The category groups similar products together, it also defines which provider owns the product

description: String? A short (single-line) description of the Product

hiddenInGrantApplications: Boolean? Flag to indicate that this Product is not publicly available

⚠️ WARNING: This doesn’t make the Product secret. In only hides the Product from the grant system’s UI.

productType: ProductType

usage: Long? Included only with certain endpoints which support `includeBalance`

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

`ProductV2.License`¶

Products define the services exposed by a Provider.

data class License(
    val name: String,
    val price: Long,
    val category: ProductCategory,
    val description: String?,
    val tags: List<String>?,
    val hiddenInGrantApplications: Boolean?,
    val productType: ProductType,
    val usage: Long?,
    val type: String /* "license" */,
)

For more information see this page.

Properties

name: String A unique name associated with this Product

price: Long Price is for usage of a single product in the accountingFrequency period specified by the product category.

category: ProductCategory The category groups similar products together, it also defines which provider owns the product

description: String? A short (single-line) description of the Product

tags: List<String>?

hiddenInGrantApplications: Boolean? Flag to indicate that this Product is not publicly available

⚠️ WARNING: This doesn’t make the Product secret. In only hides the Product from the grant system’s UI.

productType: ProductType

usage: Long? Included only with certain endpoints which support `includeBalance`

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

`ProductV2.NetworkIP`¶

Products define the services exposed by a Provider.

data class NetworkIP(
    val name: String,
    val price: Long,
    val category: ProductCategory,
    val description: String?,
    val hiddenInGrantApplications: Boolean?,
    val productType: ProductType,
    val usage: Long?,
    val type: String /* "network_ip" */,
)

For more information see this page.

Properties

name: String A unique name associated with this Product

price: Long Price is for usage of a single product in the accountingFrequency period specified by the product category.

category: ProductCategory The category groups similar products together, it also defines which provider owns the product

description: String? A short (single-line) description of the Product

hiddenInGrantApplications: Boolean? Flag to indicate that this Product is not publicly available

⚠️ WARNING: This doesn’t make the Product secret. In only hides the Product from the grant system’s UI.

productType: ProductType

usage: Long? Included only with certain endpoints which support `includeBalance`

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

`ProductV2.Storage`¶

Products define the services exposed by a Provider.

data class Storage(
    val name: String,
    val price: Long,
    val category: ProductCategory,
    val description: String?,
    val hiddenInGrantApplications: Boolean?,
    val productType: ProductType,
    val usage: Long?,
    val type: String /* "storage" */,
)

For more information see this page.

Properties

name: String A unique name associated with this Product

price: Long Price is for usage of a single product in the accountingFrequency period specified by the product category.

category: ProductCategory The category groups similar products together, it also defines which provider owns the product

description: String? A short (single-line) description of the Product

hiddenInGrantApplications: Boolean? Flag to indicate that this Product is not publicly available

⚠️ WARNING: This doesn’t make the Product secret. In only hides the Product from the grant system’s UI.

productType: ProductType

usage: Long? Included only with certain endpoints which support `includeBalance`

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

`ProductsV2BrowseRequest`¶

The base type for requesting paginated content.

data class ProductsV2BrowseRequest(
    val itemsPerPage: Int?,
    val next: String?,
    val consistency: PaginationRequestV2Consistency?,
    val itemsToSkip: Long?,
    val filterName: String?,
    val filterProvider: String?,
    val filterProductType: ProductType?,
    val filterCategory: String?,
    val filterUsable: 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

itemsPerPage: Int? Requested number of items per page. Supported values: 10, 25, 50, 100, 250.

next: String? A token requesting the next page of items

consistency: PaginationRequestV2Consistency? Controls the consistency guarantees provided by the backend

itemsToSkip: Long? Items to skip ahead

filterName: String?

filterProvider: String?

filterProductType: ProductType?

filterCategory: String?

filterUsable: Boolean?

includeBalance: Boolean?

includeMaxBalance: Boolean?

`ProductsV2RetrieveRequest`¶

data class ProductsV2RetrieveRequest(
    val filterName: String,
    val filterCategory: String,
    val filterProvider: String,
    val filterProductType: ProductType?,
    val filterUsable: Boolean?,
    val includeBalance: Boolean?,
    val includeMaxBalance: Boolean?,
)

Properties

filterName: String

filterCategory: String

filterProvider: String

filterProductType: ProductType?

filterUsable: Boolean?

includeBalance: Boolean?

includeMaxBalance: Boolean?

Products¶

Rationale¶

Concepts¶

Payment Model¶

Table of Contents¶

Remote Procedure Calls¶

browse¶

retrieve¶

create¶

Data Models¶

AccountingFrequency¶

AccountingUnit¶

ProductCategory¶

ProductType¶

ProductV2¶

ProductV2.Compute¶

ProductV2.Ingress¶

ProductV2.License¶

ProductV2.NetworkIP¶

ProductV2.Storage¶

ProductsV2BrowseRequest¶

ProductsV2RetrieveRequest¶

`browse`¶

`retrieve`¶

`create`¶

`AccountingFrequency`¶

`AccountingUnit`¶

`ProductCategory`¶

`ProductType`¶

`ProductV2`¶

`ProductV2.Compute`¶

`ProductV2.Ingress`¶

`ProductV2.License`¶

`ProductV2.NetworkIP`¶

`ProductV2.Storage`¶

`ProductsV2BrowseRequest`¶

`ProductsV2RetrieveRequest`¶