Metadata-Version: 2.2
Name: ankaios-sdk
Version: 0.5.0
Summary: Eclipse Ankaios Python SDK - provides a convenient Python interface for interacting with the Ankaios platform.
Home-page: https://eclipse-ankaios.github.io/ankaios/latest/
Author: Elektrobit Automotive GmbH and Ankaios contributors
License: Apache-2.0
Project-URL: Documentation, https://eclipse-ankaios.github.io/ank-sdk-python/
Project-URL: Source, https://github.com/eclipse-ankaios/ank-sdk-python
Project-URL: Bug Tracker, https://github.com/eclipse-ankaios/ank-sdk-python/issues
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: protobuf==5.27.2
Requires-Dist: PyYAML
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: pylint; extra == "dev"
Requires-Dist: pycodestyle; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: sphinx-rtd-theme; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints; extra == "docs"
Requires-Dist: sphinx-mdinclude; extra == "docs"
Requires-Dist: google-api-python-client; extra == "docs"
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

<picture style="padding-bottom: 1em;">
  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/eclipse-ankaios/ankaios/refs/heads/main/logo/Ankaios__logo_for_dark_bgrd_clipped.png">
  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/eclipse-ankaios/ankaios/refs/heads/main/logo/Ankaios__logo_for_light_bgrd_clipped.png">
  <img alt="Shows Ankaios logo" src="https://raw.githubusercontent.com/eclipse-ankaios/ankaios/refs/heads/main/logo/Ankaios__logo_for_light_bgrd_clipped.png">
</picture>

# Python SDK for Eclipse Ankaios

![Build](https://github.com/eclipse-ankaios/ank-sdk-python/actions/workflows/build.yml/badge.svg?job=build)
![PyPI - Version](https://img.shields.io/pypi/v/ankaios_sdk)
![Python](https://img.shields.io/badge/python-3.9%20|%203.10%20|%203.11%20|%203.12%20|%203.13-blue)

![License](https://img.shields.io/badge/license-Apache%202.0-blue)
[![Ankaios](https://img.shields.io/badge/main_project-repo-blue)](https://github.com/eclipse-ankaios/ankaios)
[![Slack](https://img.shields.io/badge/slack-join-blue?logo=slack)](https://join.slack.com/t/ankaios/shared_invite/zt-2inyhbehh-iVp3YZD09VIgybv8D1gDpQ)

[Eclipse Ankaios](https://github.com/eclipse-ankaios/ankaios) provides workload and container orchestration for automotive
High Performance Computers (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

```sh
pip install ankaios-sdk
```

### Clone and Local Build

```sh
# 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](https://docs.python.org/3/library/venv.html) 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:

| Ankaios    | Python SDK |
| -------- | ------- |
| 0.4.x and below | No Python SDK available. Please update Ankaios. |
| 0.5.x | 0.5.x     |

## 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:

```python
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](https://eclipse-ankaios.github.io/ankaios/latest/)
* [Python SDK documentation](https://eclipse-ankaios.github.io/ank-sdk-python/)

Especially the Ankaios [fleet management tutorial](https://eclipse-ankaios.github.io/ankaios/latest/usage/tutorial-fleet-management/) 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](https://github.com/eclipse-ankaios/ank-sdk-python/blob/main/CONTRIBUTING.md).

## License

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