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

firecracker

• 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 sub-package contains functionality including drivers and api for the Firecracker executor.

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 Firecracker functionality.

• client: This file provides a high level wrapper around the Firecracker library.

• executor: This is the main implementation of the executor interface for Firecracker. It is the entry point of the sub-package. It is intended to be used as a singleton.

• handler: This file contains a handler implementation to manage the lifecycle of a single job.

• init: This file is responsible for initialization of the package. Currently it only initializes a logger to be used through out the sub-package.

• types: This file contains Models that are specifically related to the Firecracker executor. Mainly it contains the engine spec model that describes a Firecracker job.

Files with *_test.go suffix contain unit tests for the functionality in corresponding file.

Class Diagram

Source

firecracker class diagram

Rendered from source file

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

Functionality

Below methods have been implemented in this package:

NewExecutor

• signature: NewExecutor(_ context.Context, id string) -> (executor.firecracker.Executor, error)

• input #1: Go context

• input #2: identifier of the executor

• output (sucess): Executor instance of type executor.firecracker.Executor

• output (error): error

NewExecutor function initializes a new Executor instance for Firecracker VMs.

It is expected that NewExecutor would be called prior to calling any other executor functions. The Executor instance returned would then be used to call other functions like Start, Stop etc.

Start

For function signature refer to the package readme

Start function begins the execution of a request by starting a Firecracker VM. It creates the VM based on the configuration parameters provided in the execution request. It returns an error message if

• execution is already started

• execution is already finished

• there is failure is creation of a new VM

Wait

For function signature refer to the package readme

Wait initiates a wait for the completion of a specific execution using its executionID. The function returns two channels: one for the result and another for any potential error.

If the executionID is not found, an error is immediately sent to the error channel.

Otherwise, an internal goroutine is spawned to handle the asynchronous waiting. The entity calling should use the two returned channels to wait for the result of the execution or an error. If there is a cancellation request (context is done) before completion, an error is relayed to the error channel. When the execution is finished, both the channels are closed.

Cancel

For function signature refer to the package readme

Cancel tries to terminate an ongoing execution identified by its executionID. It returns an error if the execution does not exist.

Run

For function signature refer to the package readme

Run initiates and waits for the completion of an execution in one call. This method serves as a higher-level convenience function that internally calls Start and Wait methods. It returns the result of the execution as executor.ExecutionResult type.

It returns an error in case of:

• failure in starting the VM

• failure in waiting

• context is cancelled

Cleanup

• signature: Cleanup(ctx context.Context) -> error

• input: Go context

• output (sucess): None

• output (error): error

Cleanup removes all firecracker resources associated with the executor. This includes stopping and removing all running VMs and deleting their socket paths. It returns an error it it is unable to remove the containers.

Data Types

executor.firecracker.Executor: This is the instance of the executor created by NewExecutor function. It contains the firecracker client and other resources required to execute requests.

// Executor manages the lifecycle of Firecracker VMs for execution requests
type Executor struct {
	// ID is the identifier of the executor instance
	ID string

	// handlers maps execution IDs to their handlers
	handlers SyncMap[string, executor.firecracker.executionHandler]

	// client is Firecracker client for VM management
	client Client
}

// Client wraps the Firecracker SDK to provide high-level operations on Firecracker VMs.
type Client struct{}

// A SyncMap is a concurrency-safe sync.Map that uses strongly-typed
// method signatures to ensure the types of its stored data are known.
type SyncMap[K comparable, V any] struct {
	sync.Map
}

executor.firecracker.executionHandler: This contains necessary information to manage the execution of a firecracker VM.

// executionHandler is a struct that holds the necessary information to 
// manage the execution of a firecracker VM.
type executionHandler struct {
	// provided by the executor
	ID string

	// Firecracker client for container management
	client Client 

	// meta data about the task
	jobID       string
	executionID string
	machine     *firecracker.Machine
	// Directory to store execution results
	resultsDir  string 

	// synchronization
	// Blocks until the container starts running
	activeCh chan bool    
	
	// BLocks until execution completes or fails
	waitCh   chan bool   
	
	// Indicates if the container is currently running.
	running  *atomic.Bool 

	// result of the execution
	result executor.ExecutionResult
}

Refer to package readme for other data types.

Testing

Unit tests for each functionality are defined in files with *_test.go naming convention.

Proposed Functionality / Requirements

List of issues

All issues that are related to the implementation of executor 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.

• executor package implementation

References

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

docker

• 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 sub-package contains functionality including drivers and api for the Docker executor.

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 docker functionality.

• client: This file provides a high level wrapper around the docker library.

• executor: This is the main implementation of the executor interface for docker. It is the entry point of the sub-package. It is intended to be used as a singleton.

• handler: This file contains a handler implementation to manage the lifecycle of a single job.

• init: This file is responsible for initialization of the package. Currently it only initializes a logger to be used through out the sub-package.

• types: This file contains Models that are specifically related to the docker executor. Mainly it contains the engine spec model that describes a docker job.

Files with *_test.go suffix contain unit tests for the functionality in corresponding file.

Class Diagram

Source

docker class diagram

Rendered from source file

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

Functionality

Below methods have been implemented in this package:

NewExecutor

• signature: NewExecutor(ctx context.Context, id string) -> (executor.docker.Executor, error)

• input #1: Go context

• input #2: identifier of the executor

• output (sucess): Executor instance of type executor.docker.Executor

• output (error): error

NewExecutor function initializes a new Executor instance with a Docker client. It returns an error if Docker client initialization fails.

It is expecte that NewExecutor would be called prior to calling any other executor functions. The Executor instance returned would then be used to call other functions like Start, Stop etc.

Start

For function signature refer to the package readme

Start function begins the execution of a request by starting a Docker container. It creates the container based on the configuration parameters provided in the execution request. It returns an error message if

• container is already started

• container execution is finished

• there is failure is creation of a new container

Wait

For function signature refer to the package readme

Wait initiates a wait for the completion of a specific execution using its executionID. The function returns two channels: one for the result and another for any potential error.

If the executionID is not found, an error is immediately sent to the error channel.

Otherwise, an internal goroutine is spawned to handle the asynchronous waiting. The entity calling should use the two returned channels to wait for the result of the execution or an error. If there is a cancellation request (context is done) before completion, an error is relayed to the error channel. When the execution is finished, both the channels are closed.

Cancel

For function signature refer to the package readme

Cancel tries to terminate an ongoing execution identified by its executionID. It returns an error if the execution does not exist.

GetLogStream

For function signature refer to the package readme

GetLogStream provides a stream of output logs for a specific execution. Parameters tail and follow specified in executor.LogStreamRequest provided as input control whether to include past logs and whether to keep the stream open for new logs, respectively.

It returns an error if the execution is not found.

Run

For function signature refer to the package readme

Run initiates and waits for the completion of an execution in one call. This method serves as a higher-level convenience function that internally calls Start and Wait methods. It returns the result of the execution as executor.ExecutionResult type.

It returns an error in case of:

• failure in starting the container

• failure in waiting

• context is cancelled

ConfigureHostConfig

• signature: configureHostConfig(vendor types.GPUVendor, params *types.ExecutionRequest, mounts []mount.Mount) container.HostConfig

• input #1: GPU vendor (types.GPUVendor)

• input #2: Execution request parameters (types.ExecutionRequest)

• input #3: List of container mounts ([]mount.Mount)

• output: Host configuration for the Docker container (container.HostConfig)

The configureHostConfig function sets up the host configuration for the container based on the GPU vendor and resources requested by the execution. It supports configurations for different types of GPUs and CPUs.

The function performs the following steps:

1. NVIDIA GPUs:

   • Configures the DeviceRequests to include all GPUs specified in the execution request.

   • Sets the memory and CPU resources according to the request parameters.

2. AMD GPUs:

   • Binds the necessary device paths (/dev/kfd and /dev/dri) to the container.

   • Adds the video group to the container.

   • Sets the memory and CPU resources according to the request parameters.

3. Intel GPUs:

   • Binds the /dev/dri directory to the container, exposing all Intel GPUs.

   • Sets the memory and CPU resources according to the request parameters.

4. Default (CPU-only):

   • Configures the container with memory and CPU resources only, without any GPU-specific settings.

The function ensures that the appropriate resources and device paths are allocated to the container based on the available and requested GPU resources.

Cleanup

• signature: Cleanup(ctx context.Context) -> error

• input: Go context

• output (sucess): None

• output (error): error

Cleanup removes all Docker resources associated with the executor. This includes removing containers including networks and volumes with the executor's label. It returns an error it if unable to remove the containers.

Data Types

• executor.docker.Executor: This is the instance of the executor created by NewExecutor function. It contains the Docker client and other resources required to execute requests.

import (
	"sync"

	"github.com/docker/docker/client"
)

// Executor manages the lifecycle of Docker containers for execution requests
type Executor struct {
	// ID is the identifier of the executor instance
	ID string

	// handlers maps execution IDs to their handlers
	handlers SyncMap[string, executionHandler]

	// client embeds Docker client for container management
	client Client
}

// Client wraps the Docker client to provide high-level operations on Docker containers and networks
type Client struct {
	// client embeds the Docker client
	client *client.Client
}

// A SyncMap is a concurrency-safe sync.Map that uses strongly-typed
// method signatures to ensure the types of its stored data are known.
type SyncMap[K comparable, V any] struct {
	sync.Map
}

• executor.docker.executionHandler: This contains necessary information to manage the execution of a docker container.

// executionHandler manages the lifecycle and execution of a Docker container for a specific job.
type executionHandler struct {
	// provided by the executor
	ID string

	client Client // Docker client for container management.

	// meta data about the task
	jobID       string
	executionID string
	containerID string
	// Directory to store execution results
	resultsDir  string 

	// synchronization
	activeCh chan bool    // Blocks until the container starts running.
	waitCh   chan bool    // BLocks until execution completes or fails.
	running  *atomic.Bool // Indicates if the container is currently running.

	// result of the execution
	result executor.ExecutionResult
}

Refer to package readme for other data types.

Testing

Unit tests for each functionality are defined in files with *_test.go naming convention.

Proposed Functionality / Requirements

List of issues

All issues that are related to the implementation of executor 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.

• executor package implementation

References

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

executor

• 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 executor package is responsible for executing the jobs received by the device management service (DMS). It provides an unified interface to run various executors such as docker, firecracker etc

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 executor functionality.

• init: This file initializes a logger instance for the executor package.

• types: This file contains the interfaces that other packages in the DMS call to utilise functionality offered by the executor package.

• docker: This folder contains the implementation of docker executor.

• firecracker: This folder contains the implementation of firecracker executor.

Class Diagram

Source

executor class diagram

Rendered from source file

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

Functionality

The main functionality offered by the executor package is defined via the Executor interface.

type Executor interface {
	// Start initiates an execution for the given ExecutionRequest.
	// It returns an error if the execution already exists and is in a started or terminal state.
	// Implementations may also return other errors based on resource limitations or internal faults.
	Start(ctx context.Context, request *types.ExecutionRequest) error

	// Run initiates and waits for the completion of an execution for the given ExecutionRequest.
	// It returns a ExecutionResult and an error if any part of the operation fails.
	// Specifically, it will return an error if the execution already exists and is in a started or terminal state.
	Run(ctx context.Context, request *types.ExecutionRequest) (*types.ExecutionResult, error)

	// Wait monitors the completion of an execution identified by its executionID.
	// It returns two channels:
	// 1. A channel that emits the execution result once the task is complete.
	// 2. An error channel that relays any issues encountered, such as when the
	//    execution is non-existent or has already concluded.
	Wait(ctx context.Context, executionID string) (<-chan *types.ExecutionResult, <-chan error)

	// Cancel attempts to cancel an ongoing execution identified by its executionID.
	// Returns an error if the execution does not exist or is already in a terminal state.
	Cancel(ctx context.Context, executionID string) error

	// GetLogStream provides a stream of output for an ongoing or completed execution identified by its executionID.
	// The 'Tail' flag indicates whether to exclude hstorical data or not.
	// The 'follow' flag indicates whether the stream should continue to send data as it is produced.
	// Returns an io.ReadCloser to read the output stream and an error if the operation fails.
	// Specifically, it will return an error if the execution does not exist.
	GetLogStream(ctx context.Context, executionID string) (io.ReadCloser, error)
}

Its methods are explained below:

Start

• signature: Start(ctx context.Context, request executor.ExecutionRequest) -> error

• input #1: Go context

• input #2: executor.ExecutionRequest

• output: error

Start function takes a Go context object and a executor.ExecutionRequest type as input. It returns an error if the execution already exists and is in a started or terminal state. Implementations may also return other errors based on resource limitations or internal faults.

Run

• signature: Run(ctx context.Context, request executor.ExecutionRequest) -> (executor.ExecutionResult, error)

• input #1: Go context

• input #2: executor.ExecutionRequest

• output (success): executor.ExecutionResult

• output (error): error

Run initiates and waits for the completion of an execution for the given Execution Request. It returns a executor.ExecutionResult and an error if any part of the operation fails. Specifically, it will return an error if the execution already exists and is in a started or terminal state.

Wait

• signature: Wait(ctx context.Context, executionID string) -> (<-chan executor.ExecutionResult, <-chan error)

• input #1: Go context

• input #2: executor.ExecutionRequest.ExecutionID

• output #1: Channel that returns executor.ExecutionResult

• output #2: Channel that returns error

Wait monitors the completion of an execution identified by its executionID. It returns two channels:

1. A channel that emits the execution result once the task is complete;

2. An error channel that relays any issues encountered, such as when the execution is non-existent or has already concluded.

Cancel

• signature: Cancel(ctx context.Context, executionID string) -> error

• input #1: Go context

• input #2: executor.ExecutionRequest.ExecutionID

• output: error

Cancel attempts to terminate an ongoing execution identified by its executionID. It returns an error if the execution does not exist or is already in a terminal state.

GetLogStream

• signature: GetLogStream(ctx context.Context, request executor.LogStreamRequest, executionID string) -> (io.ReadCloser, error)

• input #1: Go context

• input #2: executor.LogStreamRequest

• input #3: executor.ExecutionRequest.ExecutionID

• output #1: io.ReadCloser

• output #2: error

GetLogStream provides a stream of output for an ongoing or completed execution identified by its executionID. There are two flags that can be used to modify the functionality:

• The Tail flag indicates whether to exclude historical data or not.

• The follow flag indicates whether the stream should continue to send data as it is produced.

It returns an io.ReadCloser object to read the output stream and an error if the operation fails. Specifically, it will return an error if the execution does not exist.

Data Types

• types.ExecutionRequest: This is the input that executor receives to initiate a job execution.

• types.ExecutionResult: This contains the result of the job execution.

• executor.LogStreamRequest: This contains input parameters sent to the executor to get job execution logs.

// LogStreamRequest is the request object for streaming logs from an execution
type LogStreamRequest struct {
	// ID of the job
	JobID string

	// ID of the execution
	ExecutionID string

	// Tail the logs
	Tail bool

	// Follow the logs
	Follow bool
}

• types.SpecConfig: This allows arbitrary configuration/parameters as needed during implementation of specific executor.

• types.Resources: This contains resources to be used for execution.

• storage.StorageVolume: This contains parameters of storage volume used during execution.

Testing

Unit tests are defined in subpackages which implement the interface defined in this package.

Proposed Functionality / Requirements

List of issues

All issues that are related to the implementation of executor 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.

• executor package implementation

References