Skip to content

hailctl emr: AWS EMR support (CHANGELOG) - #15612

Draft
hmkim wants to merge 18 commits into
hail-is:mainfrom
hmkim:hailctl-emr-pr
Draft

hailctl emr: AWS EMR support (CHANGELOG)#15612
hmkim wants to merge 18 commits into
hail-is:mainfrom
hmkim:hailctl-emr-pr

Conversation

@hmkim

@hmkim hmkim commented Jul 25, 2026

Copy link
Copy Markdown

Change Description

Adds hailctl emr, a command group (start / stop / list / submit) for provisioning and running Hail on Amazon EMR, bringing AWS toward parity with hailctl dataproc and hailctl hdinsight.

Design was discussed with the Hail team on the forum first: https://hail.zulipchat.com/#narrow/channel/127634-Feature-Requests/topic/Contributing.20.60hailctl.20emr.60.20.28AWS.20EMR.20support.29/near/612285285

What it does

  • Pure-Python Typer module (hailtop/hailctl/emr/) that drives EMR through the boto3 control plane (native Configurations/BootstrapActions, ClusterRunning/StepComplete waiters — no aws CLI shell-out). All s3:// file I/O routes through RouterAsyncFS; boto3 is used for the EMR control plane only.
  • One-line change in RouterFS.scala: HAIL_CLOUD=aws returns an all-None CloudStorageConfig, so the router falls back to HadoopFS and EMRFS/hadoop-aws resolve s3:///s3a://. (Per the forum discussion, a native S3StorageFS is intentionally left for the Batch backend and is out of scope here.)
  • Bootstrap script shipped in the wheel via package_data, uploaded to the user's S3 scratch bucket at start time; installs Hail from PyPI (pyspark excluded, since EMR provides it).
  • EMR-release → Spark compatibility table (patch differences within 3.5.x allowed, minor mismatch is a hard error, unknown label warns). Default release emr-7.3.0 (Spark 3.5.x).
  • Installs Hail into Python 3.11 (shipped with EMR 7.1+) and points spark.pyspark.python / PYSPARK_PYTHON there, since EMR's system python3 is 3.9 and Hail requires >= 3.10.
  • Two config variables (emr/region, emr/remote_tmpdir), user docs, and a preflight check for the default EMR IAM roles.

Testing

  • 62 unit tests (boto3 Stubber/Mock), plus ruff clean.
  • Validated on real AWS: the tutorial GWAS on the 1000 Genomes subset (matches the published tutorial, min p 3.5e-9 @ 8:19600329), a full-autosome GWAS (1000G phase 3, ~81M variants × 2,504 samples, through PCA-adjusted regression), and a gnomAD annotation + Parquet export.

Open item (from the forum thread)

  • Wheel distribution currently uses pip install hail==$VERSION from PyPI. If the team prefers pushing a wheel to a known bucket (as with Dataproc), the bootstrap is easy to switch. Marked draft pending that decision.

Note: the (hail#XXXXX) reference in the change log entry is a placeholder for this PR's number.

Security Assessment

  • This change cannot impact the Hail Batch instance as deployed by Broad Institute in GCP

Impact Rating

  • This change has no security impact

Impact Description

New hailctl client-side command group for AWS EMR plus a one-line JVM FS routing arm for HAIL_CLOUD=aws. It adds no code paths to the Hail Batch service deployed in GCP; it only affects users who run hailctl emr against their own AWS accounts with their own credentials.

@ehigham ehigham self-assigned this Jul 27, 2026
Hyunmin Kim added 15 commits July 30, 2026 03:17
(cherry picked from commit f4012cd)
…em python3 is 3.9)

(cherry picked from commit f6a5151)
'aws emr create-default-roles' returns [] when the roles already exist, which
reads as if nothing happened. hailctl emr start now verifies EMR_DefaultRole
and EMR_EC2_DefaultRole before launch: it prints 'Using existing EMR default
roles: ...' when present, or raises an actionable error naming any missing
role. Runs only for --use-default-roles and after --dry-run returns (no AWS
call on dry runs). Adds unit tests (present/missing/unexpected-error).

(cherry picked from commit 631bbf7)
Hyunmin Kim added 2 commits July 30, 2026 03:29
Add a change log entry for the new hailctl emr command group. The
hail#XXXXX reference is a placeholder to be replaced with the PR number
once the pull request is opened.
EMR 7.x officially ships only Python 3.9 and 3.11; its default python3
is 3.9, too old for Hail. Explain in the EMR_PYSPARK_PYTHON constant and
the user docs why the bootstrap installs into 3.11 and how to update the
target if a future EMR release ships a newer supported Python.
Hail is standardising on Python 3.12/3.13/3.14 (hail#15603), so point the EMR
bootstrap and PySpark at python3.12 instead of python3.11. Amazon Linux 2023
(EMR 7.x) packages python3.12 in its dnf repositories, so no source build is
needed; verified on a real cluster with the smoke test and the GWAS tutorial
(driver on 3.12, results identical to 3.11).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants