Metadata-Version: 2.5
Name: lakebench-k8s
Version: 1.7.1
Summary: Deploy and benchmark lakehouse stacks on Kubernetes
Project-URL: Homepage, https://github.com/PureStorage-OpenConnect/lakebench-k8s
Project-URL: Documentation, https://github.com/PureStorage-OpenConnect/lakebench-k8s/tree/main/docs
Project-URL: Repository, https://github.com/PureStorage-OpenConnect/lakebench-k8s
Author: Andrew Sillifant
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: benchmark,iceberg,kubernetes,lakehouse,spark
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: System :: Clustering
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.10
Requires-Dist: boto3>=1.35.2
Requires-Dist: botocore>=1.34.0
Requires-Dist: click>=8.3.3
Requires-Dist: httpx>=0.27.0
Requires-Dist: jinja2>=3.1.6
Requires-Dist: kubernetes<37,>=29.0.0
Requires-Dist: prometheus-client>=0.20.0
Requires-Dist: pydantic-core>=2.14.1
Requires-Dist: pydantic>=2.5.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.7.0
Requires-Dist: typer<0.28,>=0.12.0
Requires-Dist: urllib3>=1.25.4
Provides-Extra: aml
Requires-Dist: joblib==1.5.2; extra == 'aml'
Requires-Dist: numpy==2.2.6; extra == 'aml'
Requires-Dist: pandas==2.3.3; extra == 'aml'
Requires-Dist: pyarrow>=14; extra == 'aml'
Requires-Dist: scikit-learn==1.7.2; extra == 'aml'
Requires-Dist: scipy==1.15.3; extra == 'aml'
Requires-Dist: threadpoolctl==3.6.0; extra == 'aml'
Provides-Extra: build
Requires-Dist: pyinstaller>=6.0.0; extra == 'build'
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: coverage==7.13.2; extra == 'dev'
Requires-Dist: hatchling>=1.21; extra == 'dev'
Requires-Dist: joblib==1.5.2; extra == 'dev'
Requires-Dist: moto>=5.0.0; extra == 'dev'
Requires-Dist: mypy==1.19.1; extra == 'dev'
Requires-Dist: numpy==2.2.6; extra == 'dev'
Requires-Dist: packaging>=23.0; extra == 'dev'
Requires-Dist: pandas==2.3.3; extra == 'dev'
Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
Requires-Dist: pyarrow>=14; extra == 'dev'
Requires-Dist: pydantic==2.12.5; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov==7.0.0; extra == 'dev'
Requires-Dist: pytest-xdist==3.8.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff==0.15.1; extra == 'dev'
Requires-Dist: scikit-learn==1.7.2; extra == 'dev'
Requires-Dist: scipy==1.15.3; extra == 'dev'
Requires-Dist: threadpoolctl==3.6.0; extra == 'dev'
Requires-Dist: tomli>=2.0; (python_version < '3.11') and extra == 'dev'
Requires-Dist: types-boto3==1.42.38; extra == 'dev'
Requires-Dist: types-pyyaml==6.0.12.20250915; extra == 'dev'
Description-Content-Type: text/markdown

# Lakebench

[![Python 3.10+](https://img.shields.io/badge/python-3.10%20|%203.11%20|%203.12%20|%203.13-blue)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-Apache%202.0-green)](https://github.com/PureStorage-OpenConnect/lakebench-k8s/blob/main/LICENSE)

**Evaluate lakehouse architectures through the workloads they execute.**

Lakebench runs defined data workloads against configurable lakehouse
architectures on Kubernetes. It measures how the assembled system behaves,
where time and resources are consumed, and how results change when
architectural choices or operating conditions change.

Rather than benchmarking individual components in isolation, Lakebench
evaluates the behaviour of the architecture as a whole.

## Why Lakebench?

A lakehouse is a composition of technologies. Its behaviour depends on how
those technologies work together, the workload being executed and the
infrastructure underneath them.

Component benchmarks cannot tell you how the complete architecture will
behave when ingesting, transforming, analyzing and maintaining data.

Lakebench provides a repeatable way to investigate three questions:

1. **How does the architecture behave?** Execute a defined workload and
   measure its outcomes, processing stages and resource consumption.
2. **Where are the constraints?** Examine where execution time is spent and
   which system resources contribute to observed behaviour.
3. **What changes when the architecture changes?** Repeat the workload with
   different supported components, configurations or operating conditions
   and compare the evidence.

Lakebench produces measurements and supporting context. It does not
automatically determine the best architecture or establish production
suitability.

## How Lakebench Works

Every Lakebench experiment brings together four elements:

**Workload:** The data, processing, queries and outcomes that exercise the
architecture.

**Architecture:** The supported composition of processing engines, table
formats, catalogs and query engines.

**System:** The Kubernetes, compute, network and storage environment on
which the architecture runs.

**Execution conditions:** The scale, resource allocations, execution mode
and other controls under which the workload executes.

Together, these produce evidence of how the workload behaved.

`Workload x Architecture x System x Execution conditions -> Evidence`

Lakebench automates supported deployment and execution activities, collects
measurements and produces reports for examining the results.

## Workloads

Lakebench currently provides two synthetic workloads.

### Customer 360

Customer 360 exercises a retail analytics workload. Customer interactions
are ingested, validated, transformed and aggregated into analytical datasets
that are queried for business insights.

It exercises the architecture through data preparation, transformation,
aggregation and analytical querying.

### Financial Crime / AML

The financial-crime workload exercises transaction-monitoring data
processing using synthetic financial transactions.

It combines ingestion, transformation, detection and analytical activity to
examine both processing behaviour and detection outcomes.

Its purpose is to evaluate how the architecture executes the workload, not
to establish the effectiveness of a production AML detection system.

The two workloads exercise different data-processing behaviours while using
the same underlying architectural composition model.

## Running an Experiment

Lakebench supports a workflow that:

1. Defines the workload, architecture and execution configuration.
2. Deploys the required supported components onto Kubernetes.
3. Generates synthetic workload data.
4. Executes the workload.
5. Collects measurements and produces results.
6. Supports subsequent investigation and comparison.

### Install

```bash
pip install lakebench-k8s
```

Binaries that need no Python are on
[GitHub Releases](https://github.com/PureStorage-OpenConnect/lakebench-k8s/releases).

### Run

```bash
lakebench init --endpoint http://your-s3-endpoint:80    # writes lakebench.yaml
export LAKEBENCH_S3_ACCESS_KEY=...
export LAKEBENCH_S3_SECRET_KEY=...
lakebench admin install --component all lakebench.yaml  # once per cluster
lakebench plan lakebench.yaml                           # what the run needs (read-only)
lakebench run lakebench.yaml --generate --yes           # deploy, generate, run workload
lakebench report lakebench.yaml                         # print results
lakebench destroy lakebench.yaml                        # remove what this deployment created
```

- `init` writes a minimal configuration. `--recipe <name>` selects an
  architectural composition; `--workload financial` selects the AML
  workload. There are 11 supported recipes. `lakebench config recipes`
  lists them.
- `admin install` places shared cluster components (Spark Operator,
  Stackable operators for Hive recipes, scratch StorageClass). Run once
  per cluster.
- `plan` checks whether the cluster has room for the workload. It changes
  nothing.
- `--generate` fills the bronze bucket with synthetic data. Without it,
  `run` refuses (exit 4).
- `--yes` lets `run` deploy the namespace and components. Without it, run
  `lakebench deploy` first.
- `destroy` removes only what this deployment created. It asks for
  confirmation unless `--yes` is passed.

The full walkthrough is [Getting Started](docs/getting-started.md).

## Understanding Results

Lakebench records how the workload executed under the specified conditions.

Depending on the workload and available instrumentation, this can include:

- Workload outcomes and correctness.
- Execution time and processing-stage behaviour.
- Throughput and resource efficiency.
- Query or detection performance.
- Compute, memory and storage observations.

Results describe observed behaviour under particular conditions. They are
not universal performance claims.

Comparing results requires understanding what changed between runs and
whether their execution conditions and workload semantics are equivalent.

`lakebench report` prints a summary and the path to the HTML report.
`--render` writes a fresh copy; `--format json` or `csv` for scripts.

## Prerequisites

Lakebench requires a supported Kubernetes environment and access to
compatible storage. It does not provision the underlying infrastructure.

**Host tooling:**

- `kubectl` and `helm` on PATH.

**Kubernetes:**

- Kubernetes 1.26+.
- Permission to create a namespace.

**Storage:**

- S3-compatible object storage with an endpoint URL, access key and secret
  key. Validated on FlashBlade and Garage; expected to work on AWS S3,
  MinIO and other S3-compatible stores. `lakebench config storage` checks
  yours.

**Cluster capacity:**

- Room for the workload. Scale 1 batch needs about 41 cores and 544 GB.
  Requirements grow with scale and differ by workload and execution mode.
  `lakebench plan` checks the cluster;
  [Sizing](docs/sizing.md) has every combination.

The [Prerequisites](docs/prerequisites.md) page lists every check and its
fix.

## Documentation

- [Getting Started](docs/getting-started.md): install, first run, teardown
- [Documentation index](docs/README.md): full navigation
- [Configuration](docs/configuration.md): every YAML field
- [CLI Reference](docs/cli-reference.md): every command and flag
- [Workloads](docs/README.md#workloads): Customer 360 and AML
- [Recipes](docs/recipes.md): supported architectural compositions
- [Results & Comparison](docs/README.md#results--comparison): measurements
  and interpretation
- [Upgrading to 1.7](UPGRADING-1.7.md): every breaking change from 1.6

## License

Apache 2.0
