Last updated: 2024-11-21 22:05:49.411594 File source: link on GitLab

dms

• Project README

• Release/Build Status

• Changelog

• License

• Contribution Guidelines

• Code of Conduct

• Secure Coding Guidelines

Table of Contents

1. Description

2. Structure and Organisation

3. Functionality

4. Data Types

5. Testing

6. References

Specification

Description

The hardware package is responsible for handling the hardware related functionalities of the DMS.

Structure and Organisation

Here is quick overview of the contents of this package:

cpu: This package contains the functionality related to the CPU of the device.

ram.go: This file contains the functionality related to the RAM.

disk.go: This file contains the functionality related to the Disk.

gpu: This package contains the functionality related to the GPU of the device.

Functionality

GetMachineResources()

• signature: GetMachineResources() (types.MachineResources, error)

• input: None

• output: types.MachineResources

• output(error): error

GetCPU()

• signature: GetCPU() (types.CPU, error)

• input: None

• output: types.CPU

• output(error): error

GetRAM()

• signature: GetRAM() (types.RAM, error)

• input: None

• output: types.RAM

• output(error): error

GetDisk()

• signature: GetDisk() (types.Disk, error)

• input: None

• output: types.Disk

• output(error): error

Data Types

The hardware types can be found in the types package.

Testing

The tests can be found in the *_test.go files in the respective packages.

References

Last updated: 2024-11-21 22:05:50.863676 File source: link on GitLab

onboarding

• Project README

• Release/Build Status

• Changelog

• License

• Contribution Guidelines

• Code of Conduct

• Secure Coding Guidelines

Table of Contents

1. Description

2. Structure and Organisation

3. Class Diagram

4. Functionality

5. Data Types

6. Testing

7. Proposed Functionality/Requirements

8. References

Specification

Description

This file explains the onboarding functionality of Device Management Service (DMS). This functionality is catered towards compute providers who wish provide their hardware resources to Nunet for running computational tasks as well as developers who are contributing to platform development.

Structure and Organisation

Here is quick overview of the contents of this directory:

• README: Current file which is aimed towards developers who wish to modify the onboarding functionality and build on top of it.

• handler: This is main file where the code for onboarding functionality exists.

• addresses: This file houses functions to generate Cardano wallet addresses along with its private key.

• addresses_test: This file houses functions to test the address generation functions defined in addresses.

• available_resources: This file houses functions to get the total capacity of the machine being onboarded.

• init: This files initializes the loggers associated with onboarding package.

Class Diagram

The class diagram for the onboarding package is shown below.

Source file

onboarding Class Diagram

Rendered from source file

!$rootUrlGitlab = "https://gitlab.com/nunet/device-management-service/-/raw/main"
!$packageRelativePath = "/dms/onboarding"
!$packageUrlGitlab = $rootUrlGitlab + $packageRelativePath
 
!include $packageUrlGitlab/specs/class_diagram.puml

Functionality

Onboard

• signature: Onboard(ctx context.Context, config types.OnboardingConfig) error

• input #1: Context object

• input #2: types.OnboardingConfig

• output (error): Error message

Onboard function executes the onboarding process for a compute provider based on the configuration provided.

Offboard

• signature: Offboard(ctx context.Context, force bool) error

• input #1: Context object

• input #2: force parameter

• output: None

• output (error): Error message

Offboard removes the resources onboarded to Nunet. If the force parameter is True, then offboarding process will continue even in the presence of errors.

IsOnboarded

• signature: IsOnboarded(ctx context.Context) (bool, error)

• input #1: Context object

• output #1: bool

• output #2: error

IsOnboarded checks if the compute provider is onboarded.

Info

• signature: Info(ctx context.Context) (types.OnboardingConfig, error)

• input #1: Context object

• output #1: types.OnboardingConfig

• output #2: error

Info returns the configuration of the onboarding process.

Data Types

• types.OnboardingConfig: Holds the configuration for onboarding a compute provider.

Testing

• All the tests for the onboarding package can be found in the onboarding_test.go file.

Proposed Functionality / Requirements

List of issues

All issues that are related to the implementation of dms package can be found below. These include any proposals for modifications to the package or new functionality needed to cover the requirements of other packages.

• dms package implementation

References

Last updated: 2024-11-21 22:05:49.879408 File source: link on GitLab

jobs

• Project README

• Release/Build Status

• Changelog

• License

• Contribution Guidelines

• Code of Conduct

• Secure Coding Guidelines

• EnsembleConfig Documentation

Table of Contents

1. Description

2. Structure and Organisation

3. Class Diagram

4. Functionality

5. Data Types

6. Testing

7. Proposed Functionality/Requirements

8. References

Specification

Description

This pacakge manages local jobs and their allocation, including relation to execution environments, etc. It will manage jobs through whatever executor it's running (Vontainer, VM, Direct_exe, Java etc).

Structure and Organisation

Here is quick overview of the contents of this directory:

TBD

Class Diagram

The class diagram for the jobs package is shown below.

Source file

jobs Class Diagram

Rendered from source file

!$rootUrlGitlab = "https://gitlab.com/nunet/device-management-service/-/raw/main"
!$packageRelativePath = "/dms/jobs"
!$packageUrlGitlab = $rootUrlGitlab + $packageRelativePath
 
!include $packageUrlGitlab/specs/class_diagram.puml

Functionality

TBD

Note: the functionality of DMS is being currently developed. See the proposed section for the suggested design of interfaces and methods.

Data Types

TBD

Note: the functionality of DMS is being currently developed. See the proposed section for the suggested data types.

Testing

TBD

Proposed Functionality / Requirements

List of issues

All issues that are related to the implementation of dms package can be found below. These include any proposals for modifications to the package or new functionality needed to cover the requirements of other packages.

• dms package implementation

Interfaces & Methods

proposed Job interface

type Job_interface interface {
	// extends graph.Vertex interface in order to be able to build 
	// job structure as a special instantiation of a graph
	// commented it since it not shown in the class diagram
    //graph.Vertex

	// additional methods
	getPods() []jobs.Pod
}

getPods: will fetch list of pods currently running on the machine

proposed Pod interface

type Pod_interface interface {
	combineCapabilities() dms.Capability
}

combineCapabilities: will combine the capability requirements of different jobs to calculate total capabality needed for a Pod.

proposed JobLink interface

type JobLink_interface interface {
	// extends graph.Edge interface
	// commented as it is not shown in class diagram
    // dms.graph.Edge

    validateRelations()
}

validateRelations: It validates the JobLink properties provided.

proposed Allocation interface

type Allocation_interface interface {
	// start the allocation execution via the executor package
    start()                
    
    // send message to another actor
    sendMessage(telemetry.Message)
    
    // register the allocation with the node
    register()
}

start: starts the allocation execution

sendMessage: sends a message to another actor (Node/Allocation)

register: registers the allocation with the node that it is running on

Data types

• proposed dms.jobs.Job: Nunet job which will be sent to the network wrapped as a BidRequest. If needed it will have child jobs to be executed. The relation between parent and child job needs to be specified.

type Job struct {
	// JobID is the unique identifier of the job 
	JobId 				types.ID
    
    // all information that is needed to convert a job description into ExecutionRequest
	// in principle, the logic of inputs and outputs can be expressed 
	// within graph structure, when (and if) we develop general interface 
	// of storage.StorageProvider and make it extend Vertex interface
	// until that we need to use special structures outside Graph interface
	inputs 		Slice[types.SpecConfig]
	outputs		Slice[types.SpecConfig]

    RequiredCapability dms.Capability

    // child jobs that have to be executed as part of this job
    // specified using JobLink structure
    children Slice[dms.jobs.JobLink] // in graph.Vertex type this is outEdge

    // extend graph.Vertex type 
    // given that, all children jobs will be expressed via the this interface
	// just expanding on that here
	// clearly saying that a job can have only one parent but many children
    // commented it as we have not included this in the class diagram
    // dms.graph.Vertex
}

• proposed dms.jobs.JobLink: specifies the properties that relate parent and child job.

type JobLink struct {
	// extends Edge struct
	// commented as it is not shown in class diagram
    // dms.graph.Edge // but types Vertexes on both end of the link to Jobs...

	// RelationProperties captures the relation between the parent and the child job
    RelationProperties types.SpecConfig
	
    // Child job that is linked to the parent job
    RelatedJob dms.jobs.Job
}

• proposed dms.jobs.Pod: collection of jobs that need to be executed on the same machine.

type Pod struct {
	// identifer of the Pod
    ID types.ID 
	
    // Combined capability required by the Pod
    podCapability dms.Capability
	
    // Jobs that are part of the Pod
    jobs Slice[dms.jobs.Job]
}

• proposed dms.jobs.Allocation: maps the job to the process on a executor. Each Allocation is an Actor.

type Allocation struct {
    // allocation is an actor (so extends Actor struct)
    // commented since it is not shown in class diagram
    // dms.orchestrator.Actor 
	
    // identifier for the allocation
    ID      dms.jobs.AllocationID
	
    // identifier of the job that had led to this allocation
    jobID   dms.jobs.Job.JobID

    // identifier of the node that is executing the allocation
	NodeID  dms.node.NodeID
	
    // identifier of the node that created the job
    Source  types.ID

    // Mailbox of the Allocation
    Mailbox    dms.orchestrator.Mailbox
}

• proposed dms.jobs.AllocationID: identifier for Allocation objects.

type AllocationID struct {
	// UUID is the unique identifier of the Allocation
    UUID types.ID.UUID

	// CID is a Content identifier that can be used in DHT or otherwise;
	// CIDs may be especially useful for routing messages directly to allocations via Kademlia DHT
	// it is not clear if we are going to use it now
	CID string 
}

References

Allocation as an Actor: As per initial specification of NuNet ontology / nomenclature, Allocation is considered as an Actor. That makes a running job a first class citizen of NuNet's Actor model, so being able to send and receive messages and maintain state.

Last updated: 2024-11-21 22:05:48.920505 File source: link on GitLab

dms

• Project README

• Release/Build Status

• Changelog

• License

• Contribution Guidelines

• Code of Conduct

• Secure Coding Guidelines

Table of Contents

1. Description

2. Structure and Organisation

3. Class Diagram

4. Functionality

5. Data Types

6. Testing

7. Proposed Functionality/Requirements

8. References

Specification

Description

This package is responsible for starting the whole application. It also contains various core functionality of DMS:

• Onboarding compute provider devices

• Job orchestration and management

• Resource management

• Actor implementation for each node

Structure and Organisation

Here is quick overview of the contents of this pacakge:

• README: Current file which is aimed towards developers who wish to use and modify the dms functionality.

• dms: This file contains code to initialize the DMS by loading configuration, starting REST API server etc

• init: This file creates a new logger instance.

• sanity_check: This file defines a method for performing consistency check before starting the DMS. proposed Note that the functionality of this method needs to be developed as per refactored DMS design.

Subpackages

• jobs: Deals with the management of local jobs on the machine.

• node: Contains implementation of Node as an actor.

• onboarding: Code related to onboarding of compute provider machines to the network.

• orchestrator: Contains job orchestration logic.

• resources: Deals with the management of resources on the machine.

proposed: All files with *_test.go naming convention contain unit tests with respect to the specific implementation.

Class Diagram

The class diagram for the dms package is shown below.

Source file

dms Class diagram

Rendered from source file

!$rootUrlGitlab = "https://gitlab.com/nunet/device-management-service/-/raw/main"
!$packageRelativePath = "/dms"
!$packageUrlGitlab = $rootUrlGitlab + $packageRelativePath
 
!include $packageUrlGitlab/specs/class_diagram.puml

Functionality

TBD

Note: the functionality of DMS is being currently developed. See the proposed section for the suggested design of interfaces and methods.

Data Types

TBD

Note: the functionality of DMS is being currently developed. See the proposed section for the suggested data types.

Testing

proposed Refer to *_test.go files for unit tests of different functionalities.

Proposed Functionality / Requirements

List of issues

All issues that are related to the implementation of dms package can be found below. These include any proposals for modifications to the package or new functionality needed to cover the requirements of other packages.

• dms package implementation

Interfaces & Methods

proposed Capability_interface

type Capability_interface interface {
	add()
	subtract()
}

add method will combine capabilities of two nodes. Example usage - When two jobs have to be run on a single machine, the capability requirements of each will need to be combined.

subtract method will subtract two capabilities. Example usage - When resources are locked for a job, the available capability of a machine will need to be reduced.

Data types

proposed dms.Capability

The Capability struct will capture all the relevant data that defines the capability of a node to perform the job. At the same time this will be used to define capability requirements that a job requires from a node.

An initial data model for Capability is defined below.

type Capability struct {
	// Executor is the type of executor available on the machine or the executor 
    // required for the job (example - Docker, VM, WASM etc)
    Executor    string           
	
    // Type specifies the details of type of job (One time, batch, recurring,
    // long running)
    Type        dms.jobs.JobType        
	
    // Resources specifies the description of the resources required
    Resources   dms.resources.Resource

    // Libraries specifies the libraries needed for the job        
	Libraries   []string         
	
    // Locality contains preferred localities of the machine for execution
    Locality    []string         
	
    // Storage specifies the preferred storage options that the machine should have
    Storage         []string         
	
    // Connectivity specifies the network configuration required
    Connectivity    dms.Connectivity          
	
    // Price specifies the price information of the job / machine
    Price           dms.PriceInformation 
	
    // Time specifies the time information of the job / machine
	Time            dms.TimeInformation 
	
    // KYC specifies the KYC requirements or KYC status of the machine 
    KYC  []string        
}

proposed dms.Connectivity

type Connectivity struct {

// Ports contains the ports that need to be open for the job to run
Ports []int

// VPN specifies whether VPN is required
VPN       bool  

}

proposed dms.PriceInformation

type PriceInformation struct {
	// Currency holds which currency is used for pricing ex - NTX
	Currency   string 
	
    // CurrencyPerHour is the price of the machine per hour
    CurrencyPerHour int   
	
    // TotalPerJob is the maximum total price or budget of the job
	TotalPerJob   int 
	
    // Preference is Pricing preference as compared to time
    Preference int 
}

proposed dms.TimeInformation

type TimeInformation struct { // Units holds the units of time ex - hours, days, weeks Units string

// MaxTime holds the maximum time that the job should run
MaxTime    int

// Preference holds the time preference as compared to price
Preference int    

}

References

Last updated: 2024-11-21 22:05:50.377198 File source: link on GitLab

node

• Project README

• Release/Build Status

• Changelog

• License

• Contribution Guidelines

• Code of Conduct

• Secure Coding Guidelines

Table of Contents

1. Description

2. Structure and Organisation

3. Class Diagram

4. Functionality

5. Data Types

6. Testing

7. Proposed Functionality/Requirements

8. References

Specification

proposed Description

This package is responsible for creation of a Node object which is the main actor residing on the machine as long as DMS is running. The Node gets created when the DMS is onboarded.

The Node is responsible for:

• Communicating with other actors (nodes and allocations) via messages. This will include sending bid requests, bids, invocations, job status etc

• Checking used and free resource before creating allocations

• Continuous monitoring of the machine

Structure and Organisation

Here is quick overview of the contents of this pacakge:

• README: Current file which is aimed towards developers who wish to use and modify the DMS functionality.

Class Diagram

The class diagram for the node package is shown below.

Source file

node Class Diagram

Rendered from source file

!$rootUrlGitlab = "https://gitlab.com/nunet/device-management-service/-/raw/main"
!$packageRelativePath = "/dms/node"
!$packageUrlGitlab = $rootUrlGitlab + $packageRelativePath
 
!include $packageUrlGitlab/specs/class_diagram.puml

Functionality

TBD

Note: the functionality of DMS is being currently developed. See the proposed section for the suggested design of interfaces and methods.

Data Types

TBD

Note: the functionality of DMS is being currently developed. See the proposed section for the suggested data types.

Testing

proposed Refer to *_test.go files for unit tests of different functionalities.

Proposed Functionality / Requirements

List of issues

All issues that are related to the implementation of dms package can be found below. These include any proposals for modifications to the package or new functionality needed to cover the requirements of other packages.

• dms package implementation

Interfaces & Methods

proposed Node_interface

type Node_interface interface {
	// Extends Actor interface from types package;
	// which implements message passing logic

	// Somewhat similar to the libp2p.Host interface in the current implementation;
	// (however, network.libp2p package is too low level for this interface in the 
	// new architecture)
	
	types.Actor

    // extends the Orchestrator interface from orchestrator sub-package
	dms.orchestrator.Orchestrator

	// extends Vertex interface, so connecting Actor model with Graph computing model...
	dms.graph.Vertex_interface

	// each node will hold a structure with allocations that will be running on it
	// allocation type is specified in jobs package
	getAllocation(allocationID dms.jobs.Allocation.allocationID) dms.jobs.Allocation

	// allocations will be short-lived objects (depending on the requirements of a job pertaining to that allocation)
	// but (ideally) all allocations that have ever been initiated on a node
	// need to be logged into the local database
	checkAllocationStatus()
	
	// routes message to the allocation of the job that is running on the machine
	// routeToAllocation()

	// below methods related to COMPUTE PROVIDER functionality (mostly)
	// All setters and getters are not included into global dms class diagram to make
	// it more compact

	// benchmark Capability of the machine on which the Node is running
	benchmarkCapability()

	// save benchmarked Capability into persistent data store for further retrieval
	setRegisteredCapability()

	// get all registered capability of the node
	getRegisteredCapability()

	// set available Capability, given the registered Capability and the new allocation
	setAvailableCapability()

	// return currently available capability of the node
	getAvailableCapability()

    // reserve resources for a job
	lockCapability(dms.jobs.Pod, dms.Capability)

	// get all locked Capabilities
	getLockedCapabilities()

	// set preferences of a node in the form of Capability Comparator
	setPreferences()

	getPreferences() dms.orchestrator.CapabilityComparator

	// below methods are related to SERVICE PROVIDER functionality (mostly)
	getRegisteredBids(bidRequestID types.ID) []dms.orchestrator.Bid

	// start a new allocation
	startAllocation(dms.orchestrator.Invocation) 

}

getAllocation method retrieves an Allocation on the machine based on the provided AllocationID.

checkAllocationStatus method will retrieve status of an Allocation.

routeToAllocation method will route a message to the Allocation of the job that is running on the machine.

benchmarkCapability method will perform machine benchmarking

setRegisteredCapability method will record the benchmarked Capability of the machine into a persistent data store for retrieval and usage (mostly in job orchestration functionality)

getRegisteredCapability method will retrieve the benchmarked Capability of the machine from the persistent data store.

setAvailableCapability method changes the available capability of the machine when resources are locked

getAvailableCapability method will return currently available capability of the node

lockCapability method will lock certain amount of resources for a job. This can happen during bid submission. But it must happen once job is accepted and before invocation.

getLockedCapabilities method retrieves the locked capabilities of the machine.

setPreferences method sets the preferences of a node as dms.orchestrator.CapabilityComparator

getPreferences method retrieves the node preferences as dms.orchestrator.CapabilityComparator

getRegisteredBids method retrieves list of bids receieved for a job.

startAllocation method will create an allocation based on the invocation received.

Data types

proposed dms.node.Node

An initial data model for Node is defined below.

type Node struct {
	// unique identifier
	id dms.node.nodeID

	// unique mailbox
	mailbox types.Mailbox
	
	// access to the local events database on the node
	db db.LocalDatabaseCollector // a type allowing to issue queries to our local database

	// registered capability will be a slow changing value
	// most probably it will not change for the whole lifecycle of a DMS
	// therefore it will be written into the persistent database
	// however it is good to have it in the cache, since it may be used often
	registeredCapability dms.Capability

	// available capability can be always calculated / recalculated
	// by: (1) taking the value of registered Capability (from persistent database)
	// (2) adding all capabilities of current Allocations of the node and locked capabilities
	// available capability will be (1) - (2)..
	// it can also extracted via database queries
	// lets consider that the current available capability will always be cached as a variable too
	// readily available for the Node interface
	availableCapability dms.Capability

	// part of the machine that is reserved for future jobs
	// it is the difference between registered capability and available capability
	// can be calculated readily, but it is good to have it cached too.
	// for orchestration purposes
	lockedCapabilities map[dms.jobs.Job]dms.Capability

	// each node has its preferences encoded into CapabilityComparator type
	// which will be used directly in the functions which compare job requirements with availableCapabilities
	// note that Capabilities include price
	// these types and variables are introduced in order to create ability for each node
	// to autonomously 'choose' best options as per individually defined preferences
	// the initial implementation based on these types could be pretty trivial
	// but we want this to be extendable to unlimited complexity of behaviors
	preferences dms.orchestrator.CapabilityComparator

	allocations slice[dms.jobs.AllocationID] // list of all allocations running on the node

	// indices of activity
	// we may need to have more indexes
	// note, that all information in these indexes in principle
	// should be re-constructable from the local database 
	jobIndex dms.jobs.JobIndex // index of all accepted job posts

 	// index of all sent/received bid requests
	// (note that a Node can both receive and send bids depending on the mode)
	// (if to implement this in one or more data structure -- shall be decided by developers)
	bidRequestsSentIndex dms.orchestrator.BidRequestsSentIndex
	
    bidRequestsReceivedIndex dms.orchestrator.BidRequestsReceivedIndex

	// index of all received/sent bids
	// (note, that a dms can both receive and send bids, depending on which role
	// it takes in the orchestration -- compute provider or service provider;
    // both, however are available via the same dms package
	// and may even be combined -- possibly in the future)
	bidsSentIndex dms.orchestrator.BidsSentIndex
	
    bidsReceivedIndex dms.orchestrator.BidsReceivedIndex

}

proposed dms.node.NodeID

type NodeID struct {
	// ID is unique identifier created by DMS 
    ID types.ID.UUID
   
    // CID is a Content identifier that can be used in DHT or otherwise
    CID types.ID.CID

    // libp2p peerID
	PeerID string

	// DID is the decentralized identifier that can be used for authentication and authorization
	DID string 
}

References

Last updated: 2024-11-21 22:05:51.116314 File source: link on GitLab

orchestrator

• Project README

• Release/Build Status

• Changelog

• License

• Contribution Guidelines

• Code of Conduct

• Secure Coding Guidelines

Table of Contents

1. Description

2. Structure and Organisation

3. Class Diagram

4. Functionality

5. Data Types

6. Testing

7. Proposed Functionality/Requirements

8. References

Specification

Description

The orchestrator is responsible for job scheduling and management (manages jobs on other DMSs).

A key distinction to note is the option of two types of orchestration mechanisms: push and pull. Broadly speaking pull orchestration works on the premise that resource providers bid for jobs available in the network, while push orchestration works when a job is pushed directly to a known resource provider -- constituting to a more centralized orchestration. push orchestration develops on the idea that users choose from the available providers and their resources. However, given the decentralized and open nature of the platform, it may be required to engage the providers to get their current (latest) state and preferences. This leads to an overlap with the pull orchestration approach.

The default setting is to use pull based orchestration, which is developed in the present proposed specification.

proposed Job Orchestration

The proposed lifecyle of a job on Nunet platform consists of various operations from job posting to settlement of the contract. Below is a brief explanation of the steps involved in the job orchestration:

1. Job Posting: The user posts a job request to the DMS. The job request is validated and a Nunet job is created in the DMS.

2. Search and Match:

   a. The Service provider DMS requests for bids from other nodes in the network.

   b. DMS on compute provider compares the capability of the available resources against job requirements. If all the requirements are met, it then decides whether to submit a bid.

   c. The received bids are assessed and the best bid is selected.

3. Job Request: In case the shortlisted compute provider has not locked the resources while submitting the bid, the job request workflow is executed. This requires the compute provider DMS to lock the necessary resources required for the job and re-submit the bid. Note that at this stage compute provider can still decline the job request.

4. Contract Closure: The service provider and the shortlisted compute provider verify that the counterparty is a verified entity and approved by Nunet Solutions to participate in the network. This in an important step to establish trust before any work is performed.

   If job does not require any payment (Volunteer Compute), contract is generated by both Service Provider and Compute Provider DMS. This is then verified by Contract-Database. Otherwise, proof of contract needs to be received from the Contract-Database before start of work.

5. Invocation and Allocation: When the contract closure workflow is completed, both the service provider and compute provider DMS have an agreement and proof of contract with them. Then the service provider DMS will send an invocation to the compute provider DMS which results in job allocation being created. Allocation can be understood as an execution space / environment on actual hardware that enables a Job to be executed.

6. Job Execution: Once allocation is created, the job execution starts on the compute provider machine.

7. Contract Settlement: After job is completed, service provider DMS verifies the work done. If the work is correct, the Contract-Database makes the necessary transactions to settle the the contract.

See References section for research blogs with more details on this topic.

Structure and Organisation

Here is quick overview of the contents of this directory:

• README: Current file which is aimed towards developers who wish to use and modify the orchestrator functionality.

• specs: Directory containing package specifications, including package class diagram.

Subpackages

• graph: Defines and implements interfaces of Graph logic for network topology awareness (proposed).

Class Diagram

Source

orchestrator class diagram

Rendered from source file

!$rootUrlGitlab = "https://gitlab.com/nunet/device-management-service/-/raw/main"
!$packageRelativePath = "/dms/orchestrator"
!$packageUrlGitlab = $rootUrlGitlab + $packageRelativePath
 
!include $packageUrlGitlab/specs/class_diagram.puml

Functionality

TBD

Note: the functionality of DMS is being currently developed. See the proposed section for the suggested design of interfaces and methods.

Data Types

TBD

Note: the functionality of DMS is being currently developed. See the proposed section for the suggested data types.

Testing

TBD

Proposed Functionality / Requirements

List of issues

All issues that are related to the implementation of dms package can be found below. These include any proposals for modifications to the package or new functionality needed to cover the requirements of other packages.

• dms package implementation

Interfaces & Methods

proposed Orchestrator interface

type Orchestrator_interface interface {

	publishBidRequest(dms.node.Node, dms.orchestrator.BidRequest, dms.node.NodeID, ..String)

	compareCapability(dms.Capability, dms.Capability) dms.orchestrator.CapabilityComparison
	
    acceptJob(dms.orchestrator.CapabilityComparison, dms.orchestrator.CapabilityComparator) bool
	
    sendBid(dms.node.Node, dms.orchestrator.BidRequest)

    selectBestBid(dms.node.Node, dms.orchestrator.BidRequest) dms.orchestrator.Bid

    sendJobRequest(dms.node.Node, dms.jobs.Pod, dms.node.NodeID)

    sendInvocation(dms.node.Node, dms.jobs.Invocation, dms.node.NodeId)
    
	orchestrateJob(dms.node.Node, dms.jobs.Job)

	// considering that for workflows involving more than one job connected
	// via different levels of connections between nodes
	// an orchestrator needs to be able to calculate network configurations
	// that involve estimation or connections between candidate nodes
	// in the whole workflow. Two next methods are proposed for that purpose.
	
    // takes BidRequest and all bids received as a result of it
	// and calculates all possible network configurations for it
	// and outputting graph structures having all relevant information
	// MOST PROBABLY WILL NOT IMPLEMENT IN dms 0.5.x 
	constructConfigurations(dms.orchestrator.BidRequest, []dms.orchestrator.Bid) []NetworkConfiguration
	
    // takes a set of Network Configurations and Comparator variable and selects best configuration
	based on the comparator supplied
	// MOST PROBABLY WILL NOT IMPLEMENT IN dms 0.5.x 
	selectBestNetworkConfiguration([]NetworkConfiguration, ConfigurationComparator) NetworkConfigurationComparison
}

publishBidRequest: sends a request for bid to the network for a particular job. This will depend on the network package for propagation of the request to other nodes in the network.

compareCapability: compares two capabilities and returns a CapabilityComparison object. Expected usage is to compare capability required in a job with the available capability of a node.

acceptJob: looks at the comparison between capabilities and preferences of a node in the form of CapabilityComparator object and decides whether to accept a job or not.

sendBid: sends a bid to the node that propagated the BidRequest.

selectBestBid: looks at all the bids received and selects the best one.

sendJobRequest: sends a job request to the shortlisted node whose bid was selected. The compute provider node needs to accept the job request and lock its resources for the job. In case resources are already locked while submitting the bid, this step may be skipped.

sendInvocation: sends an invocation request (as a message) to the node that accepted the job. This message should have all the necessary information to start an Allocation for the job.

orchestrateJob: this will be called when a job is received via postJob endpoint. It will start the orchestration process. It is also possible that this method could be called via a timer for jobs scheduled in the future.

proposed Actor interface

type Actor_interface interface {
	// commented as it not shown in the class diagram
	// getMailbox() dms.orchestrator.Mailbox

	sendMessage(message telemetry.Message, ...target any)

    processMessage() telemetry.Message

	// as per actor model, each actor can create another actor and it makes sense to identify this method here 
	// However, this method does not need to be implemented separately 
    // commented as it is not shown in the class diagram
	//createActor()
}

sendMessage: sends a message to another actor (Node / Allocation).

processMessage: processes the message received and decides on what action to take.

proposed Mailbox interface

type Mailbox_interface interface {
	// in order for this to work, we need to have message in the format of telemetry.Message from 
	// coming from the network by implementing 'processMessage()' methods network.P2P and network.Gossipsub  
	// alternatively, we can implement `receiveMessage(payload any)` method here and process both in mailbox interface
	// providing here the proposal for the second option
	
	receiveMessage(payload any) telemetry.Message
	
    handleMessage(telemetry.Message)

	triggerBehavior()

    getKnownTopics()

    getSubscribedTopics()

    subscribeToTopic()

    unsubscribeFromTopic()
}

receiveMessage: receives a message from another Node and converts it into a telemetry.Message object.

handleMessage: processes the message received.

triggerBehavior: this is where actions taken by the actor based on the message received will be defined.

getKnownTopics: retrieves the gossip sub topics known to the node.

getSubscribedTopics: retrieves the gossip sub topics subscribed by the node.

subscribeToTopic: subscribes to a gossip sub topic.

unsubscribeFromTopic: un-subscribes from a gossip sub topic.

proposed Other methods

• Methods for job request functionality a. check whether resources are locked b. lock resources c. accept job request

• Methods for contract closure a. validate other node as a registered entity b. generate contract c. kyc validation

• Methods for job exeuction a. handle job updates

• Methods for contract settlement a. job verification

Note that the above methods not an exhaustive list. These are to be considered as suggestions. The developer implementing the orchestrator functionality is free to make modifications as necessary.

Data types

• proposed dms.orchestrator.Actor: Actor has a identifier and a mailbox to send/receive messages.

type Actor struct {
	id types.ID
	mailbox dms.orchestrator.Mailbox
}

• proposed dms.orchestrator.Bid: Consists of information sent by the compute provider node to the requestor node as a bid for the job broadcasted to the network.

// Bid represents a bid made by the compute provider DMS
type Bid struct {
	// BidRequest is the request for bid against which this bid is made
    BidRequest                  dms.orchestrator.BidRequest
	
    // JobID is ID of the job
    JobID                       int 
	
    // Bidder is the identifier of the node sending the bid
    Bidder                      dms.node.nodeID
	
    // PriceBid is the price information of the bid
    PriceBid                    dms.orchestrator.PriceBid 
	
    // TimeBid is the time information of the bid
    TimeBid                     dms.orchestrator.TimeBid  
	
    // Timeout is the timestamp until which compute provider will be waiting for the job request
    Timeout                     int64    

    // ValidOffer is a flag to indicate whether the bid offer is valid
	ValidOffer                  bool     
	
    // ResourcesLockedUntilTimeout is whether the resources are locked until timeout
    ResourcesLockedUntilTimeout     bool     
}

• proposed dms.orchestrator.BidRequest: A bid request is a message sent by a node to the network to request for bids.

type BidRequest struct {

    // id is unique identifier for this bid request
	ID types.ID
	
	// request for bids are done with Pods, as pods combine capacities, required from a single machine
	Pod dms.jobs.Pod

	// a requestor could be dms or an allocation; both types are accepted;
	Requestor types.ID

	ResourceRequirements dms.resource.ResourceRequirements

	// comparator specifies the type of constraints and preferences to be used while making a bid
	Comparator dms.orchestrator.CapabilityComparator
}

• proposed dms.orchestrator.PriceBid: Contains price related information of the bid.

// PriceBid represents the pricing parameters of the bid
type PriceBid struct {
	priceBidType string // perResult or perTimeUnit
	currency     string
	perTimeUnit  string  // if the bid is per time unit, what is unit of time?
	perResult    bool    // if the bid is for the result of computation this is true, default is false
	amount       float64 // the amount in selected currency
}

• proposed dms.orchestrator.TimeBid: Contains time related information of the bid.

// TimeBid represents time parameters of the bid
type TimeBid struct {
	timeBidType string // duration or fixed time (or other?)
	units       string // units of time
	duration    int
	timeStart   int // or timestamp or whatever
	timeFinish  int // or timestamp or unix time
}

• proposed dms.orchestrator.CapabilityComparator: Preferences of the node which has an influence on the comparison operation.

TBD

• proposed dms.orchestrator.CapabilityComparison: Result of the comparison operation.

TBD

• proposed dms.orchestrator.Invocation: An invocation is a message sent by the orchestrator to the node that accepted the job. It contains the job details and the contract.

type Invocation struct {
	// Pod is a cluster of jobs which are to be run on the same machine
	pod dms.jobs.Pod

	// Contract contains jobID, IDs of both DMS and proof of contract
	contract      tokenomics.Contract
	source        types.ID // since an invocation can in principe be done by any Actor (node or an allocation)
}

• proposed dms.orchestrator.Mailbox: A mailbox is a communication channel between two actors. It uses network package functionality to send and receive messages.

type Mailbox struct {
	// Access to NuNet p2p network implemented via the network package
	// Whether we need these or not depends on how we implement the send/receive Message methods here;
	// it would be better not to implement them here
	// for proper architectural separation;
	p2p network.P2P	
	gossipsub network.Gossipsub // Access to NuNet gossip network -- same comment as above
}

proposed Other data types

Data types related to allocation, contract settlement, job updates etc are currently omitted. These should be added as applicable while implementation.

References

Orchestration steps research blogs

The orchestrator functionality of DMS is being developed based on the research done in the following blogs:

• Detailed Job Orchestration Sequences I

• Detailed job orchestration sequences II

Last updated: 2024-11-21 22:05:51.856381 File source:

resources

Table of Contents

Specification

Description

resources deals with resource management for the machine. This includes calculation of available resources for new jobs or bid requests.

Structure and Organisation

Here is quick overview of the contents of this pacakge:

All files with *_test.go contains unit tests for the corresponding functionality.

Class Diagram

The class diagram for the resources package is shown below.

Source file

Rendered from source file

Functionality

Manager Interface

The interface methods are explained below.

AllocateResources

• signature: AllocateResources(context.Context, ResourceAllocation) error

• input: Context

• output (error): Error message

AllocateResources allocates the resources to the job.

DeallocateResources

• signature: DeallocateResources(context.Context, string) error

• input: Context

• output (error): Error message

DeallocateResources deallocates the resources from the job.

GetTotalAllocation

• signature: GetTotalAllocation() (Resources, error)

• input: Context

• output: types.Resource

• output (error): Error message

GetTotalAllocation returns the total resources allocated to the jobs.

GetFreeResources

• signature: GetFreeResources() (FreeResources, error)

• input: None

• output: FreeResources

• output (error): Error message

GetFreeResources returns the available resources in the allocation pool.

GetOnboardedResources

• signature: GetOnboardedResources(context.Context) (OnboardedResources, error)

• input: Context

• output: OnboardedResources

• output (error): Error message

GetOnboardedResources returns the resources onboarded to dms.

UpdateOnboardedResources

• signature: UpdateOnboardedResources(context.Context, OnboardedResources) error

• input: Context

• input: OnboardedResources

• output (error): Error message

UpdateOnboardedResources updates the resources onboarded to dms.

UsageMonitor

• signature: UsageMonitor() types.UsageMonitor

• input: None

• output: types.UsageMonitor instance

• output (error): None

UsageMonitor returns the types.UsageMonitor instance.

UsageMonitor Interface

This interface defines methods to monitor the system usage. The methods are explained below.

GetUsage

• signature: GetUsage(context.Context) (types.Resource, error)

• input: Context

• output: types.Resource

• output (error): Error message

GetUsage returns the resources currently used by the machine.

Data Types

• types.Resources: resources defined for the machine.

• types.AvailableResources: resources onboarded to Nunet.

• types.FreeResources: resources currently available for new jobs.

• types.ResourceAllocation: resources allocated to a job.

• types.MachineResources: resources available on the machine.

• types.GPUVendor: GPU vendors available on the machine.

• types.GPU: GPU details.

• types.GPUs: A slice of GPU.

• types.CPU: CPU details.

• types.RAM: RAM details.

• types.Disk: Disk details.

• types.NetworkInfo: Network details.

Last updated: 2024-11-21 22:05:51.381333 File source:

graph

This whole package is proposed status and therefore documentation is missing, save for the proposed functionality part.

Table of Contents

Specification

Description

TBD

Structure and organisation

TBD

Class Diagram

Source

Rendered from source file

Functionality

TBD

Types

TBD

Testing

TBD

Proposed Functionality / Requirements

List of issues

All issues that are filed in GitLab related to the implementation of dms/orchestrator package can be found below. These include any proposals for modifications to the package or new functionality needed to cover the requirements of other packages.

Proposed functionalities

TBD

Data types

• proposed LocalNetworkTopology more complex deployments may need a data structure, which considers local network topology of a node / dms -- i.e. for reasoning about speed of connection (as well as capabilities) between neighbors.

References

Related research blogs

TBD