ascend ⬆️☁️

Kubernetes cloud execution for Python functions. Decorate with @ascend, run, done.

Blog post : https://ocramz.github.io/posts/2026-03-05-ascend.html

Use cases

• Machine Learning: Train models on GPU nodes without leaving your notebook, run hyperparameter searches in parallel
• Data Processing: Run intensive data transformations on compute- or memory-optimized nodes

from ascend import ascend

@ascend(cpu="2", memory="4Gi", requirements=["pandas", "scikit-learn"])
def train_model(data, epochs=10):
    import pandas as pd
    from sklearn.ensemble import RandomForestClassifier
    model = RandomForestClassifier()
    # ... training logic ...
    return model

result = train_model(my_data, epochs=20)  # runs on AKS

See the examples/ directory for some worked out use cases, e.g. hyperparameter search: examples/optuna_xgboost.py.

Quick Start

Prerequisites: Python 3.11–3.13, Azure CLI (az login), kubectl with cluster access.

pip install -e ".[azure]"          # or: make setup
az login
uv run ascend user init --cluster <cluster> --resource-group <rg>

This writes a .ascend.yaml config. You're ready to use @ascend.

Admin See docs/ADMIN_SETUP.md for bootstrap and user provisioning.

Decorator Reference

Parameter	Type	Default	Description
cpu	str	"1"	CPU request (e.g., "2", "4")
memory	str	"2Gi"	Memory request (e.g., "4Gi", "8Gi")
timeout	int	3600	Maximum execution time in seconds
stream_logs	bool	True	Stream pod logs to local terminal
requirements	list	None	Pip packages (e.g., ["numpy==1.24.0"])
node_type	str	None	Node type (e.g., "gpu_small")
project	bool	False	Run in shared project namespace (Git repo name)
git_check	bool	None	Validate clean Git tree (None defers to config)

Node Types

You can pass explicit Azure VM sizes (e.g., node_type="nc24ads_a100_v4"). See docs/GPU_SUPPORT.md for the full list.

Job Management

uv run ascend jobs list                    # list recent jobs
uv run ascend jobs status <job_id>         # detailed status
uv run ascend jobs logs <job_id> --follow  # stream logs
uv run ascend jobs cancel <job_id>         # cancel a job

Configuration

The .ascend.yaml file (generated by ascend user init):

username: alice
cluster_name: my-aks-cluster
resource_group: my-rg
namespace: ascend-users-alice
storage_account: mystorage
container_registry: myregistry.azurecr.io
auto_build_images: false               # opt-in Kaniko image builds

Auto image building installs your requirements into a cached container image via in-cluster Kaniko. Enable with auto_build_images: true or ASCEND_AUTO_BUILD_IMAGES=true. See docs/AUTOMATIC_IMAGE_BUILDING.md.

Library Design

• Synchrounous function execution
• No custom k8s resources needed (Controller etc.)
• User isolation via Kubernetes namespaces
• No CI/CD : automatic in-cluster image builds with Kaniko
• Content-addressable job IDs encoding metadata for filtering and traceability
• Cloud-agnostic backend design with Azure as the first supported provider

Further Reading

• Architecture — system design and decisions
• Admin Setup — infrastructure bootstrap and user provisioning
• GPU Support — full node type list and GPU configuration
• Automatic Image Building — Kaniko-based container builds
• Multi-Cloud — cloud-agnostic backend design
• Logging and Artifacts — structured logging and job IDs
• Examples — real-world workload examples
• Integration Testing — test infrastructure