Allocators are external parties that are entitled to manage projects and resource allocations in Puhuri Core. In the scope of Puhuri, resource allocators are typically organizations operating national portals or research communities.
Resource allocator is expected to:
- Be eligible to share specific resources, e.g. LUMI share.
- Be aware of the Researcher Access identifiers of the users, aka CUIDs.
Puhuri Core is based on Waldur orchestrator and as such some of the APIs use a different naming than agreed in Puhuri. Below is a mapping to reduce confusion.
|Puhuri||API / Waldur|
|Resource component||Offering component|
Puhuri Core SDK
If you are integrating a python-based application, you might find useful a python wrapper for typical operations.
Almost all operations require authentication. Authentication process is a two-step:
- Generation of authentication token using Authentication API.
- Passing that token in the Authorization header along with all other REST API calls.
Please note that all of the responses to the listing are paginated, by default up to 10 elements are returned.
You can request more by passing
page_size=<number> argument, number up to 200 will be respected. Information
about the whole set is contained in the response headers. Check example of a "get_all" function
to see how a full traversal can be done.
Puhuri Core implements a multi-tenant model to allow different organizations to allocate shared resources simultaneously and independently from each other. Each such organizaton is a customer of Puhuri Core and is able to create its own projects. Project allows us to create new allocations as well as connect users with the project.
Hence, to create a project, one needs first to have a reference to the customer. The reference is a stable one and can be cached by a REST API client.
Customers are created by Puhuri Core support team. Please reach out to firstname.lastname@example.org if you think you should have one.
In order to create a new project in an organization, user needs to provide the following fields:
customer- URL of the project's organization
name- project's name
description- description of a project description
end_date- optional date when the project and all allocations it contains will be scheduled for termination.
backend_id- optional identifier, which is intended to be unique in the resource allocator's project list. Can be used for connecting Puhuri Core projects with the client's project registry.
oecd_fos_2007_code- optional OECD Field of Science code. A code is represented by a string with two numbers separated by dot for a corresponding field of science. For example
"1.1"is code for Mathematics. More information can be found here.
Please note that the project becomes active at the moment of creation!
It is possible to update an existing project using its URL link. Name, description and backend_id can be updated.
User can list projects and filter them using the following query parameters:
name- project's name (uses 'contains' logic for lookup)
name_exact- project's exact name
description- project's description (uses 'contains' logic for lookup)
backend_id- project's exact backend ID
In case API user has access to more than one customer, extra filter by customer properties can be added:
customer- exact filter by customer UUID
customer_name- filter by partial match of the full name of a customer
abbreviation- filter by partial match of the abbreviation of a customer
Project membership management
Puhuri AAI user mapping lookup
Puhuri Core maintains its own set of user records. Project membership is essentially a link between a project and user, carrying also information about the role name.
A mapping from the Puhuri AAI CUID is implemented as a separate call. Resource allocator is able to send the CUID,
which would return a link to Puhuri Core user identity or error message, if this was not possible (e.g. CUID is
incorrect or connection with Puhuri AAI user registry has failed). Note that endpoint returns UUID, full URL of the user
is constructed as Puhuri Core URL +
Creating a membership for a user means creating a permission link. While multiple roles of a user per project are allowed, we recommed for clarity to have one active project role per user in a project.
The list of fields for creation are:
user- a user's UUID, looked up from a previous step.
role- a role of the user. Both role UUID and name are supported. By default the system roles 'PROJECT.MEMBER', 'PROJECT.ADMIN' and 'PROJECT.MANAGER' are supported. TODO: add reference to Puhuri terminology.
expiration_time- an optional field, if provided, it should contain date or ISO 8601 datetime.
To remove the permission, REST API client needs to send a HTTP request using the same payload as for permission creation,
delete_user endpoint .
It is also possible to list available project permissions along with a
- API call for allocating members to a project
- API call for removing members from a project
- API call to listing project permissions
Resource allocation management
Creating and managing resource allocations in Puhuri Core follows ordering logic.
All operations on resources, which lead to changes in allocations - e.g. creation, modification of allocated limits or termination - are wrapped in an order. It is possible to have multiple actions of the same type in one order. Such actions are called Order items.
To create a new Allocation, one must first choose a specific Offering from available. Offering corresponds to a specific part of a shared resource that Resource Allocator can allocate. For example, it can be a national share of LUMI resources. Offerings can be visible to multiple allocators, however in the first iteration we plan to limit allocators with access to only their owned shares.
User can fetch offerings and filter them by the following fields:
name- offering's name
name_exact- offering's exact name
customer- organization's URL
customer_uuid- organization's UUID
Generally Offering has a stable UUID, which can be used in Puhuri Core client configuration. Offering defines inputs that are required to provision an instance of the offering, available accounting plans (at least one should be present) as well as attributes that can or should be provided with each request.
Each Offering contains one or more plans, you will need to provide a reference (URL) to the plan when creating an allocation.
Selecting an offering (LUMI specific)
In case of LUMI allocation, there are several offerings available for each allocator corresponding to the access types defined by EuroHPC JU.
Offerings types are:
- Extreme Scale Access
- Regular Access
- Benchmark Access
- Development Access
- Fast Track Access for Academia
- Fast Track Access for Industry Access
During the integration period for convenience we use the following convention for offering names:
LUMI <Country name> / <access type>, e.g.
LUMI Sweden / Extreme Scale Access or
LUMI Finland / Regular Access.
Each of the offering will include a single plan.
Full details of the Offering contain expected attributes that should be passed when creating an allocation.
Orders, order items and resources
To create a new allocation, an order must be created contain order item with requested attributes: project as well as details about the allocations.
Order might require additional approval - in this case upon creation its status will be
REQUESTED FOR APPROVAL, which
can transition to
REJECTED if order is rejected.
Otherwise it will be switched to
EXECUTING, ending either in
DONE if all is good or
ERRED, if error happens during the processing.
Within an order, an order item is expected correspondingly to a single allocation to be created.
You can provide multiple order items within a single order, but all of them have to be of the same type,
As a result of successful processing of order item by Puhuri Core, it will create a new Resource. Its UUID will
be available as a
marketplace_resource_uuid field of the creation order item.
accepting_terms_of_service flag must be provided as a lightweight confirmation that allocator is
aware and agreeing with Terms of services of a specific Offering.
Example of the order payload sent with
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
Change resource limits
POST request to
the new values of limits, for example:
1 2 3 4 5 6 7
POST request to
- Creation of a resource allocation
- Modification of a resource allocation
- Termination of a resource allocation
- Lookup of available offerings in Puhuri Portal.
- Creation of a resource in Puhuri Portal.
- Changing allocated limits in Puhuri Portal.
- Deletion of a resource allocation in Puhuri Portal.
Information about Puhuri resources in Puhuri Core can change over time, for example, new components could be added. Puhuri Portal implements a method for dynamic import and upkeep of that information from Puhuri Core.
Getting usage data of a specific resource allocation
To get reported usage for resources, send
GET request to
https://puhuri-core-beta.neic.no/api/marketplace-component-usages/. If you want to get usage data of a specific resource, please add a filter, e.g.
https://puhuri-core-beta.neic.no/api/marketplace-component-usages/?resource_uuid=<UUID_OF_A_RESOURCE>. Note that responses are paginated.
Additional filters that can be used:
date_before- date of the returned usage records should be before or equal to provided, format YYYY-MM-DD, e.g. 2021-03-01.
date_after- date of the returned usage records should be later or equal to provided, format YYYY-MM-DD, e.g. 2021-03-01.
offering_uuid- return usage records only for a specified offering.
type- type of the usage record to return, e.g. 'cpu_k_hours'.
Response will contain a list of usage records with a separate record for each component per month, for example:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40