Hera

Warnings

• breaking The experimental decorator feature for `DAG`, `Steps`, `Container`, and `script` (introduced in v5.16) has been removed in v6.0.0. This means users should revert to the context manager pattern or the standard `@script()` decorator if they were using the `Workflow.dag()` or `Workflow.steps()` decorators.
  Fix: Migrate code using `Workflow.dag()`, `Workflow.steps()`, etc., decorators back to using context managers (e.g., `with DAG(...)`) or standard `@script()` for functions. The base `@script()` decorator remains supported.
• breaking Hera v6.0.0 migrates core Hera classes to Python dataclasses and uses Pydantic v2 API models internally where Pydantic is still needed, removing support for Pydantic v1. If your custom script functions relied on Hera's internal Pydantic v1 models or if your project mixes Hera with Pydantic v1 models, you must upgrade your Pydantic dependency to v2 and address any compatibility issues.
  Fix: Upgrade Pydantic to v2 across your project. Review Pydantic's official migration guide for v1 to v2 breaking changes. Hera's internal models are now dataclasses, impacting direct interaction with `hera.workflows.models` classes.
• breaking Hera v5.27.0 dropped support for Python 3.9. Users on Python 3.9 will need to upgrade their Python environment to 3.10 or newer to use Hera versions 5.27.0 and later.
  Fix: Upgrade your Python environment to version 3.10 or higher. Python 3.9 is also End-of-Life upstream, making an upgrade advisable regardless.
• gotcha Hera requires an active Argo Workflows server in a Kubernetes cluster for workflow submission. It does not run workflows locally or manage Argo deployments. Proper authentication (e.g., Bearer token) and server accessibility (e.g., port-forwarding) must be configured.
  Fix: Ensure an Argo Workflows server is deployed and accessible. Configure `hera.shared.global_config.host` and `global_config.token` with the correct server address and authentication token, or ensure necessary port-forwarding is active for local development.
• gotcha The Python package name for Hera changed from `hera-workflows` to `hera` for versions 5.0.0 and above. Attempting to install `hera-workflows` for newer Hera versions will result in an outdated installation.
  Fix: For Hera versions 5.0.0 and later, use `pip install hera`. If you need to install versions prior to 5.0.0, use `pip install hera-workflows`.
• gotcha Functions decorated with `@script()` are executed as containerized templates on Argo. This means the Docker image specified in the decorator (or default global image) must contain the Python environment and all dependencies required by the decorated function. Local imports and non-standard libraries need to be bundled into the image.
  Fix: Specify a Docker image in the `@script(image="...")` decorator that includes all necessary Python dependencies (e.g., `numpy`, custom modules) for your function. Alternatively, build and use a custom Docker image from your project's codebase.

Install

• pip install hera Install latest version
• pip install hera[yaml] Install with YAML support

Imports

• Workflow

  from hera.workflows import Workflow

• script

  from hera.workflows import script

• DAG

  from hera.workflows import DAG

• Steps

  from hera.workflows import Steps

• global_config

  from hera.shared import global_config

  Configuration is now managed via `hera.shared.global_config` for broader applicability, rather than instantiating `WorkflowService` directly for host/token setup.

Quickstart

This quickstart demonstrates how to define a DAG (Directed Acyclic Graph) workflow using Hera, where tasks 'B' and 'C' run in parallel after 'A' completes, and 'D' runs after both 'B' and 'C' are finished. The `echo` function is converted into an Argo script template using the `@script` decorator. The workflow is then submitted to an Argo Workflows server configured via environment variables or a default local endpoint.

import os
from hera.workflows import DAG, Workflow, script
from hera.shared import global_config

# Configure Hera to connect to your Argo Workflows server
# Set ARGO_SERVER_HOST and ARGO_SERVER_TOKEN environment variables
# For local testing, ensure Argo Server is port-forwarded (e.g., kubectl -n argo port-forward service/argo-server 2746:2746)
global_config.host = os.environ.get("ARGO_SERVER_HOST", "http://localhost:2746")
global_config.token = os.environ.get("ARGO_SERVER_TOKEN", "") # Use actual token if required

@script(image="python:3.11")
def echo(message: str):
    """A simple Python function to echo a message."""
    print(message)

with Workflow(
    generate_name="hera-dag-diamond-",
    entrypoint="diamond",
    namespace="argo", # Ensure this matches your Argo Workflows namespace
    labels={
        "example": "true",
        "sdk": "hera",
    }
) as w:
    with DAG(name="diamond"):
        A = echo(name="A", arguments={"message": "Task A"})
        B = echo(name="B", arguments={"message": "Task B"})
        C = echo(name="C", arguments={"message": "Task C"})
        D = echo(name="D", arguments={"message": "Task D"})

        A >> [B, C] >> D

# Submit the workflow
try:
    submitted_workflow = w.create()
    print(f"Workflow '{submitted_workflow.metadata.name}' submitted successfully.")
    print(f"Access UI at {global_config.host}/workflows/{submitted_workflow.metadata.namespace}/{submitted_workflow.metadata.name}")
except Exception as e:
    print(f"Error submitting workflow: {e}")
    print("Please ensure your Argo Workflows server is running and accessible, and ARGO_SERVER_HOST/TOKEN are configured correctly.")