Crate ankaios_sdk

Expand description

§Rust SDK for Eclipse Ankaios

Eclipse Ankaios provides workload and container orchestration for automotive High Performance Computing Platforms (HPCs). While it can be used for various fields of applications, it is developed from scratch for automotive use cases and provides a slim yet powerful solution to manage containerized applications.

The Rust SDK provides easy access from the container (workload) point-of-view to manage the Ankaios system. A workload can use the Rust SDK to start, stop and update other workloads and configs and get the state of the Ankaios system.

§Setup

§Setup via crates.io

Add the following to your Cargo.toml:

[dependencies]
ankaios_sdk = "0.6.0"

§Clone and link as vendor

Create a vendor folder and clone the crate inside:

mkdir -p vendor
git clone git@github.com:eclipse-ankaios/ank-sdk-rust.git vendor/ankaios_sdk

Then add it to your Cargo.toml:

[dependencies]
ankaios_sdk = { path = "vendor/ankaios_sdk" }

§Compatibility

Please make sure the Rust SDK is compatible with the version of Ankaios you are using. For information regarding versioning, please refer to this table:

Ankaios	Rust SDK
0.4.x and below	No Rust SDK available. Please update Ankaios.
0.5.x	0.5.x
0.6.x	0.6.x

§Usage

After setup, you can use the Ankaios SDK to configure and run workloads and request the state of the Ankaios system and the connected agents.

The following example assumes that the code is running in a workload managed by Ankaios with configured control interface access. This can also be tested from the examples folder by running ./run_example.sh hello_ankaios.

use ankaios_sdk::{Ankaios, AnkaiosError, Workload, WorkloadStateEnum};
use tokio::time::Duration;

#[tokio::main]
async fn main() {
    // Create a new Ankaios object.
    // The connection to the control interface is automatically done at this step.
    let mut ank = Ankaios::new().await.expect("Failed to initialize");

    // Create a new workload
    let workload = Workload::builder()
        .workload_name("dynamic_nginx")
        .agent_name("agent_A")
        .runtime("podman")
        .restart_policy("NEVER")
        .runtime_config(
            "image: docker.io/library/nginx\ncommandOptions: [\"-p\", \"8080:80\"]"
        ).build().expect("Failed to build workload");
     
    // Run the workload
    let response = ank.apply_workload(workload).await.expect("Failed to apply workload");

    // Get the WorkloadInstanceName to check later if the workload is running
    let workload_instance_name = response.added_workloads[0].clone();

    // Request the execution state based on the workload instance name
    match ank.get_execution_state_for_instance_name(&workload_instance_name).await {
        Ok(state) => {
            let exec_state = state.execution_state;
            println!("State: {:?}, substate: {:?}, info: {:?}", exec_state.state, exec_state.substate, exec_state.additional_info);
        }
        Err(err) => {
            println!("Error while getting workload state: {err:?}");
        }
    }

    // Wait until the workload reaches the running state
    match ank.wait_for_workload_to_reach_state(workload_instance_name, WorkloadStateEnum::Running).await {
        Ok(_) => {
            println!("Workload reached the RUNNING state.");
        }
        Err(AnkaiosError::TimeoutError(_)) => {
            println!("Workload didn't reach the required state in time.");
        }
        Err(err) => {
            println!("Error while waiting for workload to reach state: {err:?}");
        }
    }

    // Request the state of the system, filtered with the workloadStates
    let complete_state = ank.get_state(vec!["workloadStates".to_owned()]).await.expect("Failed to get the state");

    // Get the workload states present in the complete state
    let workload_states_dict = complete_state.get_workload_states().get_as_list();

    // Print the states of the workloads
    for workload_state in workload_states_dict {
        println!("Workload {} on agent {} has the state {:?}",
            workload_state.workload_instance_name.workload_name,
            workload_state.workload_instance_name.agent_name,
            workload_state.execution_state.state
        );
    }
}

For more details, please visit:

§Contributing

This project welcomes contributions and suggestions. Before contributing, make sure to read the contribution guideline.

§License

Ankaios Rust SDK is licensed using the Apache License Version 2.0.

Structs§

Ankaios: This struct is used to interact with Ankaios using an intuitive API. The struct automatically handles the session creation and the requests and responses sent and received over the Control Interface.
CompleteState: Struct encapsulating the complete state of the Ankaios system.
File: Represents a file that can be mounted to a workload.
LogCampaignResponse: Struct that represents a response of a log request.
LogEntry: Struct that represents a log entry.
LogsRequest: Struct that represents a logs request.
Manifest: Struct represents a manifest file.
Workload: Represents a workload with various attributes and methods to update them.
WorkloadBuilder: A builder struct for the Workload struct.
WorkloadState: Struct that contains the instance name and the execution state of the workload.
WorkloadStateCollection: Helper struct that specializes in managing a collection of WorkloadStates.

Enums§

AnkaiosError: An enumeration of possible errors that can occur in the Ankaios application.
ControlInterfaceState: Enum representing the state of the control interface.
FileContent: Represents the content type of a File.
LogResponse: Enum that represents the type of log responses that are available in a LogCampaignResponse.
WorkloadStateEnum: Enum representing the state of a Workload.

Crate ankaios_sdkCopy item path