Metadata-Version: 2.4
Name: harbor-aws
Version: 0.4.0
Summary: AWS EKS/Fargate execution backend for Harbor benchmarks
License-Expression: Apache-2.0
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: aiohttp>=3.10.0
Requires-Dist: boto3>=1.35.0
Requires-Dist: harbor>=0.1.43
Requires-Dist: kubernetes>=31.0.0
Requires-Dist: tenacity>=8.0.0
Provides-Extra: cdk
Requires-Dist: aws-cdk-lambda-layer-kubectl-v31>=2.0.0; extra == 'cdk'
Requires-Dist: aws-cdk-lib>=2.150.0; extra == 'cdk'
Requires-Dist: constructs>=10.0.0; extra == 'cdk'
Provides-Extra: dev
Requires-Dist: mypy>=1.13; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.12; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8.0; extra == 'dev'
Description-Content-Type: text/markdown

# harbor-aws

[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)

AWS EKS/Fargate execution backend for [Harbor](https://github.com/harbor-framework/harbor) benchmarks. Run thousands of sandbox trials in parallel with per-second billing and VM-level isolation.

## How it works

```
Orchestrator (laptop / CI)
    |  HTTPS via NLB
    v
harbor-control pod (in-cluster gateway)
    |  TCP via /dev/tcp
    v
Trial pods (one per task, Fargate)
```

Each trial pod runs a small **bash runner** (`runner.sh`) as PID 1 — no Python needed in the trial image. The runner dials the in-cluster **harbor-control** gateway over plain TCP. The orchestrator talks to harbor-control over an NLB. The K8s API server is only used for pod create/delete, never in the exec data path.

## Install

```bash
pip install "harbor-aws[cdk]"
```

## Quick start

### 1. Deploy (~15 min, one-time)

```bash
python -m harbor_aws deploy --region us-east-1
```

Creates everything: VPC, EKS, harbor-control, NLB, Load Balancer Controller.

### 2. Run benchmarks

```bash
harbor jobs start -p ./task -a nop -n 2500 \
  --environment-import-path harbor_aws.adapter:AWSEnvironment \
  --ek stack_name=harbor-aws --ek ecr_cache=true
```

The adapter auto-discovers the NLB endpoint and admin token from the stack. No env vars needed.

### 3. Clean up

```bash
python -m harbor_aws stop      # delete trial pods, keep infra
python -m harbor_aws destroy   # tear down everything
```

## Cost

| Component | Cost |
|---|---|
| EKS control plane | ~$73/mo (fixed) |
| Fargate trial pods | per-second, only when running |
| harbor-control pod | ~$5/mo (always-on) |
| NLB | ~$16/mo |

## Development

```bash
pip install -e ".[dev,cdk]"
ruff check src/
mypy src/
```

## License

Apache License 2.0 — see [LICENSE](LICENSE).
