Argo Workflows Python Client

Common errors

• argo_workflows.ApiException: (401) Reason: Unauthorized

  cause The API client failed to authenticate with the Argo Workflows server.
  fix Check that the `ARGO_WORKFLOWS_TOKEN` environment variable is set and contains a valid bearer token for the Argo Workflows API. Ensure the token has the necessary permissions. If using other authentication methods, verify those credentials.

• urllib3.exceptions.MaxRetryError: HTTPSConnectionPool(...) Read timed out. (Caused by SSLError(CertificateError("hostname '...' doesn't match '...'",)))

  cause SSL certificate verification failed, often due to a mismatch between the hostname in the certificate and the host URL or an untrusted certificate.
  fix Set `verify_ssl=True` in your `Configuration` and provide the path to your CA certificate via `ssl_ca_cert`. Alternatively, if you understand the security risks and for development purposes, set `verify_ssl=False`.

• AttributeError: module 'argo_workflows.model.io_argoproj_workflow_v1alpha1_workflow_spec' has no attribute 'entrypoint'

  cause The client version used has a different API specification (e.g., a newer or older Argo Workflows server version) than expected, or there's a typo in the attribute name.
  fix Verify that your `argo-workflows` client version is compatible with your Argo Workflows server version. Update or downgrade the client as necessary. Double-check the attribute name against the official Argo Workflows API documentation.

• TypeError: 'NoneType' object is not subscriptable

  cause Attempting to access an item (e.g., `workflow.metadata['name']`) on an object that is `None`, often because a required nested object was not initialized or returned `None` from an API call.
  fix Ensure all required nested objects (e.g., `metadata`, `spec`, `templates`) are properly initialized when constructing workflow requests. For API responses, add checks for `None` before accessing attributes or dict keys.

Warnings

• gotcha The `argo-workflows` Python client is auto-generated and its version needs to be compatible with the Argo Workflows server it connects to. Significant version mismatches can lead to API errors or `AttributeError` for missing/changed fields in models.
  Fix: Always use a client version that is recent and intended for your Argo Workflows server version. Consult the official Argo Workflows GitHub for recommendations or regenerate the client if you are tracking custom API changes.
• gotcha Incorrect host URL or authentication details are common causes of connection failures. SSL certificate verification can also be an issue in non-standard environments.
  Fix: Verify `ARGO_WORKFLOWS_HOST` (e.g., `http://localhost:2746` or `https://argo.example.com`). Ensure `ARGO_WORKFLOWS_TOKEN` (for bearer token auth) or other credentials are correct. For SSL issues, either configure `verify_ssl=True` with `ssl_ca_cert` pointing to your CA certificate or, for development, set `verify_ssl=False` (not recommended for production).
• gotcha When constructing workflow objects, it's easy to miss required fields or provide incorrect types, leading to validation errors (either client-side or server-side). The client-side validation is enabled by default.
  Fix: Refer to the Argo Workflows API documentation for the exact schema of workflow objects. Check error messages carefully for missing fields. For advanced use cases or custom resource definitions, consider setting `client_side_validation=False` on the Configuration object if you understand the implications.

Install

• pip install argo-workflows Install stable version

Imports

• Configuration

  from argo_workflows import Configuration

• ApiClient

  from argo_workflows import ApiClient

• WorkflowServiceApi

  from argo_workflows.api import workflow_service_api

• IoArgoprojWorkflowV1alpha1Workflow

  from argo_workflows.model import io_argoproj_workflow_v1alpha1_workflow

  Commonly imported for constructing workflow definitions, along with other 'io_argoproj_workflow_v1alpha1_*' models.
• ApiException

  from argo_workflows import ApiException

  The base exception class for API errors.

Quickstart

This quickstart demonstrates how to configure the `argo-workflows` client for authentication (using a bearer token from an environment variable), instantiate the `WorkflowServiceApi`, and list workflows in a specified namespace. Ensure `ARGO_WORKFLOWS_HOST` and `ARGO_WORKFLOWS_TOKEN` (if using auth) are set.

import argo_workflows
from argo_workflows.api import workflow_service_api
import os

# Configure API client
configuration = argo_workflows.Configuration(
    host=os.environ.get("ARGO_WORKFLOWS_HOST", "http://localhost:2746"),
    verify_ssl=os.environ.get("ARGO_WORKFLOWS_VERIFY_SSL", "false").lower() == "true",
)

# Bearer Token Authentication (common for Argo Workflows)
token = os.environ.get("ARGO_WORKFLOWS_TOKEN")
if token:
    configuration.api_key["Authorization"] = token
    configuration.api_key_prefix["Authorization"] = "Bearer"
else:
    print("Warning: ARGO_WORKFLOWS_TOKEN not set. API calls might fail without authentication.")

# Enter a context with an instance of the API client
with argo_workflows.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = workflow_service_api.WorkflowServiceApi(api_client)
    namespace = os.environ.get("ARGO_WORKFLOWS_NAMESPACE", "argo") # Example namespace

    try:
        # Example: List workflows in a given namespace
        api_response = api_instance.list_workflows(namespace=namespace)
        print(f"Successfully listed {len(api_response.items)} workflows in namespace '{namespace}'.")
        if api_response.items:
            print(f"First workflow: {api_response.items[0].metadata.name}")
    except argo_workflows.ApiException as e:
        print(f"Exception when calling WorkflowServiceApi->list_workflows: {e}\n")