Metadata-Version: 2.4
Name: ankaios-sdk
Version: 1.1.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: 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
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: protobuf==6.33.5; python_version < "3.15"
Requires-Dist: protobuf==7.36.2; python_version >= "3.15"
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"
Requires-Dist: grpcio-tools==1.76.0; python_version < "3.15" and extra == "dev"
Requires-Dist: grpcio-tools==1.84.0; python_version >= "3.15" and 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: sphinx-versioned-docs; extra == "docs"
Requires-Dist: google-api-python-client; extra == "docs"
Provides-Extra: command
Requires-Dist: grpcio-tools==1.76.0; python_version < "3.15" and extra == "command"
Requires-Dist: grpcio-tools==1.84.0; python_version >= "3.15" and extra == "command"
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
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/pypi/pyversions/ankaios_sdk)

![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-38857n3r5-1nXR7gSAMDtTdYjz_LBmzg)

[Eclipse Ankaios](https://github.com/eclipse-ankaios/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

```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                                           |
| 0.6.x           | 0.6.x                                           |
| 0.7.x           | 0.7.x                                           |
| 1.0.x           | 1.0.x                                           |
| 1.1.x           | 1.1.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.

### Connecting over The Control Interface

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))
```

### Connecting over The Command Interface

To connect to an Ankaios server directly from outside a workload (e.g. from
a CI job or a management tool), use the Command Interface instead, which
uses a direct gRPC connection:

```python
from ankaios_sdk import Ankaios, ConnectionType

with Ankaios(
    connection_type=ConnectionType.COMMAND_INTERFACE,
    server_url="http://127.0.0.1:25551",
) as ankaios:
    ...
```

This requires the `command` extra:

```sh
pip install ankaios-sdk[command]
```

For mTLS-secured connections, also pass `ca_pem`, `crt_pem` and `key_pem`
(the PEM-encoded CA certificate, client certificate and client key content).

### Resources

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.
