Python 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 Python SDK provides easy access from the container (workload) point-of-view to manage the Ankaios system. A workload can use the Python SDK to start, stop and update other workloads and configs and get the state of the Ankaios system.

Installation

Install via pip

pip install ankaios-sdk

Clone and Local Build

# Clone repository
git clone https://github.com/eclipse-ankaios/ank-sdk-python.git
cd ank-sdk-python

# Install in editable mode
pip install -e .

# If you plan on contributing or running tests locally
pip install -e ".[dev]"

Note:
Depending on your Linux distribution, it could be that you need to create and activate a virtual environment to run the pip commands.

Compatibility

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

Usage

After installation, 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 managed by Ankaios workload with configured control interface access:

from ankaios_sdk import Workload, Ankaios, WorkloadStateEnum, AnkaiosException

# Create a new Ankaios object.
# The connection to the control interface is automatically done at this step.
# The Ankaios class supports context manager syntax:
with Ankaios() as ankaios:

  # Create a new workload
  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()

  try:
    # Run the workload
    update_response = ankaios.apply_workload(workload)

    # Get the WorkloadInstanceName to check later if the workload is running
    workload_instance_name = update_response.added_workloads[0]

    # Request the execution state based on the workload instance name
    ret = ankaios.get_execution_state_for_instance_name(workload_instance_name)
    if ret is not None:
      print(f"State: {ret.state}, substate: {ret.substate}, info: {ret.additional_info}")

    # Wait until the workload reaches the running state
    try:
      ankaios.wait_for_workload_to_reach_state(
        workload_instance_name,
        state=WorkloadStateEnum.RUNNING,
        timeout=5
        )
    except TimeoutError:
      print("Workload didn't reach the required state in time.")
    else:
      print("Workload reached the RUNNING state.")

  # Catch the AnkaiosException in case something went wrong with apply_workload
  except AnkaiosException as e:
    print("Ankaios Exception occurred: ", e)

  # Request the state of the system, filtered with the workloadStates
  complete_state = ankaios.get_state(
    timeout=5,
    field_masks=["workloadStates"])

  # Get the workload states present in the complete_state
  workload_states_dict = complete_state.get_workload_states().get_as_dict()

  # Print the states of the workloads:
  for agent_name in workload_states_dict:
    for workload_name in workload_states_dict[agent_name]:
      for workload_id in workload_states_dict[agent_name][workload_name]:
        print(f"Workload {workload_name} on agent {agent_name} has the state "
              + str(workload_states_dict[agent_name] \
                    [workload_name][workload_id].state))

For more details, please visit:

• Ankaios documentation
• Python SDK documentation

Especially the Ankaios fleet management tutorial gives a great overview on the usage of the SDK.

Contributing

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

License

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