« Previous section Next section »
UCloud Developer Guide / Orchestration of Resources / Compute / Software Licenses
Software Licenses
Licenses act as a key to certain restricted software.
Rationale
📝 NOTE: This API follows the standard Resources API. We recommend that you have already read and understood the concepts described here .
Users must attach a license to a Job
for it to work. When attached, the software should be available. In most cases, a license is a parameter of an Application
.
📝 NOTE: UCloud does not store any information about license keys, servers or any other credentials. It is the responsibility of the provider to store this information.
Table of Contents
1. Examples 2. Remote Procedure Calls 3. Data Models Example: Create and configure a license
Frequency of use Common
An authenticated user (user
)
Communication Flow: Kotlin
Copy
/* In this example we will see how to create and manage a software license */
Licenses.retrieveProducts. call (
Unit,
user
). orThrow ()
/*
SupportByProvider(
productsByProvider = mapOf("example" to listOf(ResolvedSupport(
product = Product.License(
allowAllocationRequestsFrom = AllocationRequestsGroup.ALL,
category = ProductCategoryId(
id = "example-license",
name = "example-license",
provider = "example",
),
chargeType = ChargeType.ABSOLUTE,
description = "An example license",
freeToUse = false,
hiddenInGrantApplications = false,
name = "example-license",
pricePerUnit = 1,
priority = 0,
productType = ProductType.LICENSE,
tags = emptyList(),
unitOfPrice = ProductPriceUnit.PER_UNIT,
version = 1,
balance = null,
id = "example-license",
maxUsableBalance = null,
),
support = LicenseSupport(
maintenance = null,
product = ProductReference(
category = "example-license",
id = "example-license",
provider = "example",
),
),
))),
)
*/
Licenses.create. call (
bulkRequestOf ( LicenseSpecification (
product = ProductReference (
category = "example-license" ,
id = "example-license" ,
provider = "example" ,
),
)),
user
). orThrow ()
/*
BulkResponse(
responses = listOf(FindByStringId(
id = "5123",
)),
)
*/
Licenses.retrieve. call (
ResourceRetrieveRequest (
flags = LicenseIncludeFlags (
filterCreatedAfter = null ,
filterCreatedBefore = null ,
filterCreatedBy = null ,
filterIds = null ,
filterProductCategory = null ,
filterProductId = null ,
filterProvider = null ,
filterProviderIds = null ,
hideProductCategory = null ,
hideProductId = null ,
hideProvider = null ,
includeOthers = false ,
includeProduct = false ,
includeSupport = false ,
includeUpdates = false ,
),
id = "5123" ,
),
user
). orThrow ()
/*
License(
createdAt = 1635170395571,
id = "5123",
owner = ResourceOwner(
createdBy = "user",
project = null,
),
permissions = null,
specification = LicenseSpecification(
product = ProductReference(
category = "example-license",
id = "example-license",
provider = "example",
),
),
status = LicenseStatus(
boundTo = emptyList(),
resolvedProduct = null,
resolvedSupport = null,
state = LicenseState.READY,
),
updates = emptyList(),
providerGeneratedId = "5123",
)
*/
Communication Flow: Curl
Copy # ------------------------------------------------------------------------------------------------------
# $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
# ------------------------------------------------------------------------------------------------------
# In this example we will see how to create and manage a software license
# Authenticated as user
curl -XGET -H "Authorization: Bearer $accessToken" "$host/api/licenses/retrieveProducts"
# {
# "productsByProvider": {
# "example": [
# {
# "product": {
# "balance": null,
# "maxUsableBalance": null,
# "name": "example-license",
# "pricePerUnit": 1,
# "category": {
# "name": "example-license",
# "provider": "example"
# },
# "description": "An example license",
# "priority": 0,
# "tags": [
# ],
# "version": 1,
# "freeToUse": false,
# "allowAllocationRequestsFrom": "ALL",
# "unitOfPrice": "PER_UNIT",
# "chargeType": "ABSOLUTE",
# "hiddenInGrantApplications": false,
# "productType": "LICENSE"
# },
# "support": {
# "product": {
# "id": "example-license",
# "category": "example-license",
# "provider": "example"
# },
# "maintenance": null
# }
# }
# ]
# }
# }
curl -XPOST -H "Authorization: Bearer $accessToken" -H "Content-Type: content-type: application/json; charset=utf-8" "$host/api/licenses" -d '{
"items" : [
{
"product" : {
"id" : "example-license" ,
"category" : "example-license" ,
"provider" : "example"
}
}
]
}'
# {
# "responses": [
# {
# "id": "5123"
# }
# ]
# }
curl -XGET -H "Authorization: Bearer $accessToken" "$host/api/licenses/retrieve?includeOthers=false&includeUpdates=false&includeSupport=false&includeProduct=false&id=5123"
# {
# "id": "5123",
# "specification": {
# "product": {
# "id": "example-license",
# "category": "example-license",
# "provider": "example"
# }
# },
# "owner": {
# "createdBy": "user",
# "project": null
# },
# "createdAt": 1635170395571,
# "status": {
# "state": "READY",
# "resolvedSupport": null,
# "resolvedProduct": null,
# "boundTo": [
# ]
# },
# "updates": [
# ],
# "permissions": null
# }
Communication Flow: VisualRemote Procedure Calls
browse
Browses the catalog of available resources
retrieve
Retrieve a single resource
retrieveProducts
Retrieve product support for all accessible providers
This endpoint will determine all providers that which the authenticated user has access to, in the current workspace. A user has access to a product, and thus a provider, if the product is either free or if the user has been granted credits to use the product.
See also:
search
Searches the catalog of available resources
create
Creates one or more resources
delete
Deletes one or more resources
init
Request (potential) initialization of resources
This request is sent by the client, if the client believes that initialization of resources might be needed. NOTE: This request might be sent even if initialization has already taken place. UCloud/Core does not check if initialization has already taken place, it simply validates the request.
updateAcl
Updates the ACL attached to a resource
Data Models
License
A License
for use in Job
s
Copy data class License (
val id: String ,
val specification: LicenseSpecification ,
val owner: ResourceOwner ,
val createdAt: Long ,
val status: LicenseStatus ,
val updates: List < LicenseUpdate >?,
val permissions: ResourcePermissions ?,
val providerGeneratedId: String ?,
)
PropertiesLicenseIncludeFlags
Copy data class LicenseIncludeFlags (
val includeOthers: Boolean ?,
val includeUpdates: Boolean ?,
val includeSupport: Boolean ?,
val includeProduct: Boolean ?,
val filterCreatedBy: String ?,
val filterCreatedAfter: Long ?,
val filterCreatedBefore: Long ?,
val filterProvider: String ?,
val filterProductId: String ?,
val filterProductCategory: String ?,
val filterProviderIds: String ?,
val filterIds: String ?,
val hideProductId: String ?,
val hideProductCategory: String ?,
val hideProvider: String ?,
)
PropertiesLicenseSpecification
Copy data class LicenseSpecification (
val product: ProductReference ,
)
PropertiesLicenseState
Copy enum class LicenseState {
PREPARING,
READY,
UNAVAILABLE,
}
PropertiesLicenseStatus
The status of an License
Copy data class LicenseStatus (
val state: LicenseState ,
val resolvedSupport: ResolvedSupport < Product . License , LicenseSupport >?,
val resolvedProduct: Product .License?,
val boundTo: List < String >?,
)
PropertiesLicenseSupport
Copy data class LicenseSupport (
val product: ProductReference ,
val maintenance: Maintenance ?,
)
PropertiesLicenseUpdate
Copy data class LicenseUpdate (
val timestamp: Long ?,
val state: LicenseState ?,
val status: String ?,
val binding: JobBinding ?,
)
Properties