Hera (hera-workflows)

The Argo was constructed by the shipwright Argus,
and its crew were specially protected by the goddess Hera.

(https://en.wikipedia.org/wiki/Argo)

Hera is a Python framework for constructing and submitting Argo Workflows. The main goal of Hera is to make Argo Workflows more accessible by abstracting away some setup that is typically necessary for constructing workflows.

Python functions are first class citizens in Hera - they are the atomic units (execution payload) that are submitted for remote execution. The framework makes it easy to wrap execution payloads into Argo Workflow tasks, set dependencies, resources, etc.

You can watch the introductory Hera presentation at the "Argo Workflows and Events Community Meeting 20 Oct 2021" here!

Table of content

Assumptions
Installation
Examples
Contributing
Concepts
Comparison

Assumptions

Hera is exclusively dedicated to remote workflow submission and execution. Therefore, it requires an Argo server to be deployed to a Kubernetes cluster. Currently, Hera assumes that the Argo server sits behind an authentication layer that can authenticate workflow submission requests by using the Bearer token on the request. To learn how to deploy Argo to your own Kubernetes cluster you can follow the Argo Workflows guide!

Another option for workflow submission without the authentication layer is using port forwarding to your Argo server deployment and submitting workflows to localhost:2746 (2746 is the default, but you are free to use yours). Please refer to the documentation of Argo Workflows to see the command for port forward!

In the future some of these assumptions may either increase or decrease depending on the direction of the project. Hera is mostly designed for practical data science purposes, which assumes the presence of a DevOps team to set up an Argo server for workflow submission.

Installation

There are multiple ways to install Hera:

You can install from PyPi:
```
pip install hera-workflows
```

You can install from conda:

conda install -c conda-forge hera-workflows

Install it directly from this repository using:

python -m pip install git+https://github.com/argoproj-labs/hera-workflows  --ignore-installed

Alternatively, you can clone this repository and then run the following to install:
```
pip install .
```

Examples

A very primitive example of submitting a task within a workflow through Hera is:

from hera import Task, Workflow, WorkflowService


def say(m: str):
    print(m)


with Workflow('my-workflow', service=WorkflowService(host='my-argo-domain.com', token='my-argo-server-token')) as w:
    Task('say', say, func_params=[{'m': 'Hello, world!'}]) >> Task('say', say, func_params=[{'m': 'Goodbye, world!'}])

w.create()

See the examples directory for a collection of Argo workflow construction and submission via Hera!

Contributing

If you plan to submit contributions to Hera you can install Hera in a virtual environment managed by poetry:

poetry install

In you activated poetry shell, you can utilize the tasks found in tox.ini, e.g.:

To run tests on all supported python versions with coverage run tox:

tox

To list all available tox envs run:

tox -a

To run selected tox envs, e.g. for a specific python version with coverage run:

tox -e py37,coverage

As coverage depends on py37, it will run after py37

See project tox.ini for more details

Also, see the contributing guide!

Concepts

Currently, Hera is centered around two core concepts. These concepts are also used by Argo, which Hera aims to stay consistent with:

Task - the object that holds the Python function for remote execution/the atomic unit of execution;
Workflow - the higher level representation of a collection of tasks.

Comparison

There are other libraries currently available for structuring and submitting Argo Workflows:

Couler, which aims to provide a unified interface for constructing and managing workflows on different workflow engines;
Argo Python DSL, which allows you to programmaticaly define Argo worfklows using Python.

While the aforementioned libraries provide amazing functionality for Argo workflow construction and submission, they require an advanced understanding of Argo concepts. When Dyno Therapeutics started using Argo Workflows, it was challenging to construct and submit experimental machine learning workflows. Scientists and engineers at Dyno Therapeutics used a lot of time for workflow definition rather than the implementation of the atomic unit of execution - the Python function - that performed, for instance, model training.

Hera presents a much simpler interface for task and workflow construction, empowering users to focus on their own executable payloads rather than workflow setup. Here's a side by side comparison of Hera, Argo Python DSL, and Couler:

Hera	Couler	Argo Python DSL
from hera import Task, Workflow, WorkflowService def say(message: str): print(message) with Workflow('diamond', WorkflowService(host='my-argo-server.com', token='my-auth-token')) as w: a = Task('A', say, func_params=[{'message': 'This is task A!'}]) b = Task('B', say, func_params=[{'message': 'This is task B!'}]) c = Task('C', say, func_params=[{'message': 'This is task C!'}]) d = Task('D', say, func_params=[{'message': 'This is task D!'}]) a >> b >> d a >> c >> d w.create()	import couler.argo as couler from couler.argo_submitter import ArgoSubmitter def job(name): couler.run_container( image="docker/whalesay:latest", command=["cowsay"], args=[name], step_name=name, ) def diamond(): couler.dag( [ [lambda: job(name="A")], [lambda: job(name="A"), lambda: job(name="B")], # A -> B [lambda: job(name="A"), lambda: job(name="C")], # A -> C [lambda: job(name="B"), lambda: job(name="D")], # B -> D [lambda: job(name="C"), lambda: job(name="D")], # C -> D ] ) diamond() submitter = ArgoSubmitter() couler.run(submitter=submitter)	from argo.workflows.dsl import Workflow from argo.workflows.dsl.tasks import * from argo.workflows.dsl.templates import * class DagDiamond(Workflow): @task @parameter(name="message", value="A") def A(self, message: V1alpha1Parameter) -> V1alpha1Template: return self.echo(message=message) @task @parameter(name="message", value="B") @dependencies(["A"]) def B(self, message: V1alpha1Parameter) -> V1alpha1Template: return self.echo(message=message) @task @parameter(name="message", value="C") @dependencies(["A"]) def C(self, message: V1alpha1Parameter) -> V1alpha1Template: return self.echo(message=message) @task @parameter(name="message", value="D") @dependencies(["B", "C"]) def D(self, message: V1alpha1Parameter) -> V1alpha1Template: return self.echo(message=message) @template @inputs.parameter(name="message") def echo(self, message: V1alpha1Parameter) -> V1Container: container = V1Container( image="alpine:3.7", name="echo", command=["echo", "{{inputs.parameters.message}}"], ) return container

Hera

Couler

Argo Python DSL

from hera import Task, Workflow, WorkflowService


def say(message: str):
    print(message)


with Workflow('diamond', WorkflowService(host='my-argo-server.com', token='my-auth-token')) as w:
    a = Task('A', say, func_params=[{'message': 'This is task A!'}])
    b = Task('B', say, func_params=[{'message': 'This is task B!'}])
    c = Task('C', say, func_params=[{'message': 'This is task C!'}])
    d = Task('D', say, func_params=[{'message': 'This is task D!'}])
    a >> b >> d
    a >> c >> d

w.create()

import couler.argo as couler
from couler.argo_submitter import ArgoSubmitter


def job(name):
    couler.run_container(
        image="docker/whalesay:latest",
        command=["cowsay"],
        args=[name],
        step_name=name,
    )


def diamond():
    couler.dag(
        [
            [lambda: job(name="A")],
            [lambda: job(name="A"), lambda: job(name="B")],  # A -> B
            [lambda: job(name="A"), lambda: job(name="C")],  # A -> C
            [lambda: job(name="B"), lambda: job(name="D")],  # B -> D
            [lambda: job(name="C"), lambda: job(name="D")],  # C -> D
        ]
    )


diamond()
submitter = ArgoSubmitter()
couler.run(submitter=submitter)

from argo.workflows.dsl import Workflow

from argo.workflows.dsl.tasks import *
from argo.workflows.dsl.templates import *


class DagDiamond(Workflow):

    @task
    @parameter(name="message", value="A")
    def A(self, message: V1alpha1Parameter) -> V1alpha1Template:
        return self.echo(message=message)

    @task
    @parameter(name="message", value="B")
    @dependencies(["A"])
    def B(self, message: V1alpha1Parameter) -> V1alpha1Template:
        return self.echo(message=message)

    @task
    @parameter(name="message", value="C")
    @dependencies(["A"])
    def C(self, message: V1alpha1Parameter) -> V1alpha1Template:
        return self.echo(message=message)

    @task
    @parameter(name="message", value="D")
    @dependencies(["B", "C"])
    def D(self, message: V1alpha1Parameter) -> V1alpha1Template:
        return self.echo(message=message)

    @template
    @inputs.parameter(name="message")
    def echo(self, message: V1alpha1Parameter) -> V1Container:
        container = V1Container(
            image="alpine:3.7",
            name="echo",
            command=["echo", "{{inputs.parameters.message}}"],
        )

        return container

melihme/hera-workflows