microvm-ctl 0.1.0__py3-none-any.whl

microvm/__init__.py

@@ -0,0 +1,28 @@
+"""microvm-ctl: control and execution plane for AWS Lambda MicroVMs.
+
+Control plane  : build images, run/suspend/resume/terminate, scale fleets.
+Execution plane: authenticated calls into the microVM endpoint, in-VM hook server.
+"""
+
+from microvm.client import lambda_client, microvm_client
+from microvm.config import PlaneConfig
+from microvm.endpoint import EndpointClient, EndpointError
+from microvm.fleet import Fleet, FleetManager
+from microvm.images import ImageBuilder, ImageBuildError
+from microvm.monitor import CostModel, FleetMonitor
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "microvm_client",
+    "lambda_client",
+    "PlaneConfig",
+    "ImageBuilder",
+    "ImageBuildError",
+    "Fleet",
+    "FleetManager",
+    "EndpointClient",
+    "EndpointError",
+    "FleetMonitor",
+    "CostModel",
+]

microvm/bootstrap.py

@@ -0,0 +1,99 @@
+"""One-time account bootstrap: artifact bucket + build/execution IAM roles.
+
+Build role  — assumed by the image build infrastructure: reads the code
+              artifact zip from S3 and writes build logs.
+Execution   — assumed by the running microVM (credentials are vended inside
+role          the VM): runtime logs plus whatever your workload needs.
+              Build vs execution role separation is deliberate — never let
+              the sandbox role read your artifact bucket.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+
+from microvm.client import lambda_client
+from microvm.config import PlaneConfig
+
+TRUST = {
+    "Version": "2012-10-17",
+    "Statement": [
+        {
+            "Effect": "Allow",
+            "Principal": {"Service": "lambda.amazonaws.com"},
+            "Action": ["sts:AssumeRole", "sts:TagSession"],
+        }
+    ],
+}
+
+
+def _ensure_role(iam, name: str, policy_doc: dict) -> str:
+    try:
+        arn = iam.get_role(RoleName=name)["Role"]["Arn"]
+    except iam.exceptions.NoSuchEntityException:
+        arn = iam.create_role(
+            RoleName=name,
+            AssumeRolePolicyDocument=json.dumps(TRUST),
+            Description="microvm-ctl control plane",
+        )["Role"]["Arn"]
+        time.sleep(8)  # IAM eventual consistency before first use
+    iam.put_role_policy(
+        RoleName=name, PolicyName=f"{name}-inline", PolicyDocument=json.dumps(policy_doc)
+    )
+    return arn
+
+
+def bootstrap(cfg: PlaneConfig, prefix: str = "microvm-ctl") -> dict:
+    """Create (idempotently) the artifact bucket and the two IAM roles.
+
+    Returns the three values the rest of the plane needs, ready to export as
+    MVM_ARTIFACT_BUCKET / MVM_BUILD_ROLE_ARN / MVM_EXECUTION_ROLE_ARN.
+    """
+    sts = lambda_client("sts", cfg.region, cfg.profile)
+    account = sts.get_caller_identity()["Account"]
+    bucket = cfg.artifact_bucket or f"{prefix}-artifacts-{account}-{cfg.region}"
+
+    s3 = lambda_client("s3", cfg.region, cfg.profile)
+    try:
+        s3.head_bucket(Bucket=bucket)
+    except Exception:
+        params = {"Bucket": bucket}
+        if cfg.region != "us-east-1":
+            params["CreateBucketConfiguration"] = {"LocationConstraint": cfg.region}
+        s3.create_bucket(**params)
+        s3.put_public_access_block(
+            Bucket=bucket,
+            PublicAccessBlockConfiguration={
+                "BlockPublicAcls": True, "IgnorePublicAcls": True,
+                "BlockPublicPolicy": True, "RestrictPublicBuckets": True,
+            },
+        )
+
+    iam = lambda_client("iam", cfg.region, cfg.profile)
+    logs_stmt = {
+        "Effect": "Allow",
+        "Action": ["logs:CreateLogGroup", "logs:CreateLogStream", "logs:PutLogEvents"],
+        "Resource": f"arn:aws:logs:{cfg.region}:{account}:log-group:/aws/lambda/microvms/*",
+    }
+    build_role = _ensure_role(
+        iam,
+        f"{prefix}-build-role",
+        {
+            "Version": "2012-10-17",
+            "Statement": [
+                {"Effect": "Allow", "Action": "s3:GetObject", "Resource": f"arn:aws:s3:::{bucket}/*"},
+                logs_stmt,
+            ],
+        },
+    )
+    execution_role = _ensure_role(
+        iam,
+        f"{prefix}-execution-role",
+        {"Version": "2012-10-17", "Statement": [logs_stmt]},
+    )
+    return {
+        "artifact_bucket": bucket,
+        "build_role_arn": build_role,
+        "execution_role_arn": execution_role,
+    }

microvm/cli.py

@@ -0,0 +1,382 @@
+"""`mvm`: the microvm-ctl command line.
+
+    mvm bootstrap                          one-time: S3 artifact bucket + build/execution roles
+    mvm quotas                             applied vs published quotas for this account
+    mvm image build NAME DIR               zip -> S3 -> build -> ACTIVE version
+    mvm image ls | versions NAME
+    mvm run IMAGE [-n 5]                   spin up microVM(s)
+    mvm ls [--image NAME]                  fleet listing
+    mvm scale IMAGE N                      converge fleet to N
+    mvm suspend|resume|terminate ID...     lifecycle control
+    mvm drain IMAGE                        terminate the whole fleet
+    mvm call ID /path [-X POST -d '{}']    authenticated request into the VM
+    mvm top [--image NAME] [--watch]       live fleet dashboard
+    mvm logs IMAGE                         CloudWatch tail
+    mvm cost [--memory-gb 2 ...]           session economics
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import time
+
+from rich.console import Console
+from rich.table import Table
+
+from microvm import __version__
+from microvm.config import TPS, PlaneConfig
+from microvm.endpoint import EndpointClient
+from microvm.fleet import Fleet, FleetManager, IdlePolicy, applied_quotas
+from microvm.images import ImageBuilder
+from microvm.monitor import CostModel, FleetMonitor
+
+console = Console()
+
+STATE_STYLE = {
+    "PENDING": "yellow",
+    "RUNNING": "bold green",
+    "SUSPENDING": "yellow",
+    "SUSPENDED": "cyan",
+    "TERMINATING": "red",
+    "TERMINATED": "dim",
+}
+
+
+def _cfg(args) -> PlaneConfig:
+    kw = {}
+    if args.region:
+        kw["region"] = args.region
+    if args.profile:
+        kw["profile"] = args.profile
+    return PlaneConfig(**kw)
+
+
+def _state(s: str) -> str:
+    return f"[{STATE_STYLE.get(s, 'white')}]{s}[/]"
+
+
+# ---------------------------------------------------------------- bootstrap
+def cmd_bootstrap(args):
+    from microvm.bootstrap import bootstrap
+    out = bootstrap(_cfg(args), prefix=args.prefix)
+    console.print("[bold green]✓ control plane bootstrapped[/]")
+    for k, v in out.items():
+        console.print(f"  [cyan]{k}[/] = {v}")
+    console.print(
+        "\nExport these (or put them in your shell profile):\n"
+        f"  export MVM_ARTIFACT_BUCKET={out['artifact_bucket']}\n"
+        f"  export MVM_BUILD_ROLE_ARN={out['build_role_arn']}\n"
+        f"  export MVM_EXECUTION_ROLE_ARN={out['execution_role_arn']}"
+    )
+
+
+def cmd_quotas(args):
+    cfg = _cfg(args)
+    applied = applied_quotas(cfg)
+    t = Table(title=f"Lambda MicroVMs quotas in {cfg.region}", header_style="bold magenta")
+    for c in ("quota", "published default", "applied to this account", "plane throttles at"):
+        t.add_column(c)
+    for op, default in TPS.items():
+        if op in ("GetMicrovm", "CreateMicrovmAuthToken"):
+            continue
+        got = applied.get(op)
+        eff = (got or default) * FleetManager.QUOTA_HEADROOM
+        t.add_row(f"{op} (TPS)", str(default), str(got) if got is not None else "[dim]unknown[/]",
+                  f"{eff:g}/s")
+    mem = applied.get("MaxMemoryGb")
+    t.add_row("Max allocated microVM memory (GB)", "1024",
+              str(mem) if mem is not None else "[dim]unknown[/]", "-")
+    console.print(t)
+    if not applied:
+        console.print("[dim]Service Quotas did not answer (missing servicequotas:GetServiceQuota?); "
+                      "showing published defaults.[/]")
+
+
+# ---------------------------------------------------------------- images
+def cmd_image_build(args):
+    cfg = _cfg(args)
+    builder = ImageBuilder(cfg)
+    env = dict(kv.split("=", 1) for kv in args.env) if args.env else None
+    with console.status(f"[bold]building image [cyan]{args.name}[/] from {args.dir}…"):
+        built = builder.build(
+            args.name,
+            args.dir,
+            memory_mib=args.memory,
+            environment=env,
+            os_capabilities_all=args.caps_all,
+            description=args.description,
+        )
+    console.print(f"[bold green]✓ {built.name}:{built.version}[/] ({built.build_seconds}s)")
+    if built.memory_snapshot_bytes:
+        console.print(
+            f"  memory snapshot: {built.memory_snapshot_bytes/1e6:.0f} MB   "
+            f"disk snapshot: {(built.disk_snapshot_bytes or 0)/1e6:.0f} MB"
+        )
+
+
+def cmd_image_ls(args):
+    t = Table(title="MicroVM images", header_style="bold magenta")
+    for c in ("name", "state", "active version", "created"):
+        t.add_column(c)
+    for img in ImageBuilder(_cfg(args)).list_images():
+        t.add_row(
+            img["name"], img["state"], img.get("latestActiveImageVersion", "-"),
+            str(img["createdAt"])[:19],
+        )
+    console.print(t)
+
+
+def cmd_image_versions(args):
+    t = Table(title=f"versions of {args.name}", header_style="bold magenta")
+    for c in ("version", "build state", "status", "created"):
+        t.add_column(c)
+    for v in ImageBuilder(_cfg(args)).list_versions(args.name):
+        t.add_row(v["imageVersion"], v["state"], v["status"], str(v["createdAt"])[:19])
+    console.print(t)
+
+
+# ---------------------------------------------------------------- lifecycle
+def cmd_run(args):
+    cfg = _cfg(args)
+    fm = FleetManager(cfg)
+    policy = IdlePolicy(max_idle=args.idle, suspended_for=args.suspended_ttl)
+    for _ in range(args.count):
+        vm = fm.run(
+            args.image,
+            version=args.version,
+            idle_policy=policy,
+            run_payload=args.payload,
+            max_duration=args.max_duration,
+        )
+        console.print(
+            f"[bold green]✓[/] {vm.microvm_id}  {_state(vm.state)}  "
+            f"[link=https://{vm.endpoint}]{vm.endpoint}[/link]"
+        )
+        if args.wait:
+            vm = fm.wait_until(vm.microvm_id, "RUNNING")
+            console.print(f"  now {_state(vm.state)}")
+
+
+def cmd_ls(args):
+    fm = FleetManager(_cfg(args))
+    vms = fm.list(args.image)
+    if not args.all:
+        vms = [v for v in vms if v.state != "TERMINATED"]
+    t = Table(title="microVMs", header_style="bold magenta")
+    for c in ("microvm id", "state", "image", "version", "started"):
+        t.add_column(c)
+    for vm in vms:
+        t.add_row(
+            vm.microvm_id, _state(vm.state),
+            vm.image_arn.split(":")[-1], vm.image_version, str(vm.started_at)[:19],
+        )
+    console.print(t)
+
+
+def cmd_get(args):
+    vm = FleetManager(_cfg(args)).api.get_microvm(microvmIdentifier=args.id)
+    vm.pop("ResponseMetadata", None)
+    console.print_json(json.dumps(vm, default=str))
+
+
+def _lifecycle(args, verb: str):
+    fm = FleetManager(_cfg(args))
+    for vid in args.ids:
+        getattr(fm, verb)(vid)
+        console.print(f"[bold green]✓[/] {verb} {vid}")
+
+
+def cmd_scale(args):
+    cfg = _cfg(args)
+    fleet = Fleet(FleetManager(cfg), args.image, idle_policy=IdlePolicy(max_idle=args.idle))
+    before = fleet.size()
+    with console.status(f"[bold]scaling [cyan]{args.image}[/] {before} → {args.n}…"):
+        fleet.scale_to(args.n, wait_running=args.wait)
+    console.print(f"[bold green]✓[/] fleet [cyan]{args.image}[/]: {before} → {fleet.size()} microVMs")
+
+
+def cmd_drain(args):
+    n = Fleet(FleetManager(_cfg(args)), args.image).drain()
+    console.print(f"[bold green]✓[/] terminated {n} microVMs of [cyan]{args.image}[/]")
+
+
+# ---------------------------------------------------------------- execution plane
+def cmd_call(args):
+    cfg = _cfg(args)
+    client = EndpointClient(cfg, args.id, ports=[args.port] if args.port else None)
+    resp = client.request(
+        args.method, args.path,
+        port=args.port,
+        data=args.data.encode() if args.data else None,
+        headers={"Content-Type": "application/json"} if args.data else {},
+    )
+    console.print(f"[bold]{resp.status_code}[/] in {resp.elapsed.total_seconds()*1000:.0f} ms")
+    try:
+        console.print_json(json.dumps(resp.json()))
+    except ValueError:
+        console.print(resp.text[:2000])
+
+
+# ---------------------------------------------------------------- monitor
+def _top_table(mon: FleetMonitor, image: str | None) -> Table:
+    snap = mon.snapshot(image)
+    counts = "  ".join(f"{_state(s)}×{n}" for s, n in sorted(snap["by_state"].items()))
+    t = Table(
+        title=f"fleet: {image or 'all images'} — {snap['total']} VMs   {counts}",
+        header_style="bold magenta",
+    )
+    for c in ("microvm id", "state", "image", "started"):
+        t.add_column(c)
+    for vm in snap["members"]:
+        t.add_row(
+            vm["microvmId"], _state(vm["state"]),
+            vm["imageArn"].split(":")[-1], str(vm["startedAt"])[:19],
+        )
+    return t
+
+
+def cmd_top(args):
+    mon = FleetMonitor(_cfg(args))
+    if not args.watch:
+        console.print(_top_table(mon, args.image))
+        return
+    from rich.live import Live
+    with Live(_top_table(mon, args.image), refresh_per_second=0.5, console=console) as live:
+        while True:
+            time.sleep(args.interval)
+            live.update(_top_table(mon, args.image))
+
+
+def cmd_logs(args):
+    mon = FleetMonitor(_cfg(args))
+    events = mon.tail_logs(args.image, minutes=args.minutes)
+    if not events:
+        console.print(f"[dim]no events in /aws/lambda/microvms/{args.image}[/]")
+    for e in events:
+        console.print(f"[dim]{e['stream'][:20]}[/] {e['message']}")
+
+
+def cmd_cost(args):
+    model = CostModel(memory_gb=args.memory_gb, snapshot_gb=args.snapshot_gb)
+    s = model.session(args.active * 60, args.suspended * 60, args.cycles)
+    t = Table(title=f"session economics: {args.memory_gb} GB / {model.vcpu:g} vCPU",
+              header_style="bold magenta")
+    t.add_column("dimension")
+    t.add_column("USD", justify="right")
+    t.add_row("running compute", f"${s['running_usd']:.6f}")
+    t.add_row(f"suspend cycles x{args.cycles}", f"${s['suspend_cycles_usd']:.6f}")
+    t.add_row("suspended storage", f"${s['suspended_storage_usd']:.6f}")
+    t.add_row("[bold]total[/]", f"[bold]${s['total_usd']:.6f}[/]")
+    t.add_row("[dim]always-on equivalent[/]", f"[dim]${s['vs_always_on_usd']:.6f}[/]")
+    t.add_row("[bold green]savings[/]", f"[bold green]{s['savings_pct']}%[/]")
+    console.print(t)
+
+
+# ---------------------------------------------------------------- parser
+def main(argv: list[str] | None = None):
+    p = argparse.ArgumentParser(prog="mvm",
+                                description="Control and execution plane for AWS Lambda MicroVMs")
+    p.add_argument("--version", action="version", version=f"microvm-ctl {__version__}")
+    p.add_argument("--region", default=None, help="service region (default: MVM_REGION or us-east-1)")
+    p.add_argument("--profile", default=None, help="AWS profile (default: MVM_PROFILE or AWS_PROFILE)")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    b = sub.add_parser("bootstrap", help="provision S3 bucket + IAM roles")
+    b.add_argument("--prefix", default="microvm-ctl", help="name prefix for the bucket and roles")
+    b.set_defaults(fn=cmd_bootstrap)
+
+    q = sub.add_parser("quotas", help="applied vs published quotas for this account")
+    q.set_defaults(fn=cmd_quotas)
+
+    img = sub.add_parser("image", help="image factory").add_subparsers(dest="sub", required=True)
+    ib = img.add_parser("build", help="zip -> S3 -> build -> ACTIVE version")
+    ib.add_argument("name")
+    ib.add_argument("dir")
+    ib.add_argument("--memory", type=int, default=2048, help="minimum memory in MiB")
+    ib.add_argument("--env", action="append", metavar="K=V",
+                    help="image-level env var (shared by every clone)")
+    ib.add_argument("--caps-all", action="store_true",
+                    help="additionalOsCapabilities=ALL (EFS/FUSE/containerd/eBPF)")
+    ib.add_argument("--description")
+    ib.set_defaults(fn=cmd_image_build)
+    il = img.add_parser("ls", help="list images")
+    il.set_defaults(fn=cmd_image_ls)
+    iv = img.add_parser("versions", help="list versions of one image")
+    iv.add_argument("name")
+    iv.set_defaults(fn=cmd_image_versions)
+
+    r = sub.add_parser("run", help="spin up microVM(s)")
+    r.add_argument("image")
+    r.add_argument("--version", help="image version (default: latest ACTIVE)")
+    r.add_argument("-n", "--count", type=int, default=1)
+    r.add_argument("--idle", type=int, default=300, help="suspend after N idle seconds")
+    r.add_argument("--suspended-ttl", type=int, default=3600, help="auto-terminate after N suspended seconds")
+    r.add_argument("--payload", help="runHookPayload (per-VM context)")
+    r.add_argument("--max-duration", type=int, default=None, help="hard lifetime cap in seconds")
+    r.add_argument("--wait", action="store_true", help="poll until RUNNING")
+    r.set_defaults(fn=cmd_run)
+
+    ls = sub.add_parser("ls", help="list microVMs")
+    ls.add_argument("--image")
+    ls.add_argument("--all", action="store_true", help="include TERMINATED")
+    ls.set_defaults(fn=cmd_ls)
+
+    g = sub.add_parser("get", help="raw GetMicrovm JSON")
+    g.add_argument("id")
+    g.set_defaults(fn=cmd_get)
+
+    for verb in ("suspend", "resume", "terminate"):
+        v = sub.add_parser(verb, help=f"{verb} one or more microVMs")
+        v.add_argument("ids", nargs="+")
+        v.set_defaults(fn=lambda a, _v=verb: _lifecycle(a, _v))
+
+    sc = sub.add_parser("scale", help="converge fleet to N")
+    sc.add_argument("image")
+    sc.add_argument("n", type=int)
+    sc.add_argument("--idle", type=int, default=300)
+    sc.add_argument("--wait", action="store_true", help="wait for new members to reach RUNNING")
+    sc.set_defaults(fn=cmd_scale)
+
+    d = sub.add_parser("drain", help="terminate every microVM of an image")
+    d.add_argument("image")
+    d.set_defaults(fn=cmd_drain)
+
+    c = sub.add_parser("call", help="authenticated request into a microVM")
+    c.add_argument("id")
+    c.add_argument("path")
+    c.add_argument("-X", "--method", default="GET")
+    c.add_argument("-d", "--data", help="request body (sent as application/json)")
+    c.add_argument("--port", type=int, default=None, help="non-default app port")
+    c.set_defaults(fn=cmd_call)
+
+    tp = sub.add_parser("top", help="live fleet dashboard")
+    tp.add_argument("--image")
+    tp.add_argument("--watch", action="store_true")
+    tp.add_argument("--interval", type=float, default=3)
+    tp.set_defaults(fn=cmd_top)
+
+    lg = sub.add_parser("logs", help="tail CloudWatch logs for an image")
+    lg.add_argument("image")
+    lg.add_argument("--minutes", type=int, default=15)
+    lg.set_defaults(fn=cmd_logs)
+
+    co = sub.add_parser("cost", help="session economics")
+    co.add_argument("--memory-gb", type=float, default=2)
+    co.add_argument("--snapshot-gb", type=float, default=None,
+                    help="suspended snapshot size (default: memory)")
+    co.add_argument("--active", type=float, default=30, help="active minutes")
+    co.add_argument("--suspended", type=float, default=480, help="suspended minutes")
+    co.add_argument("--cycles", type=int, default=1, help="suspend/resume cycles")
+    co.set_defaults(fn=cmd_cost)
+
+    args = p.parse_args(argv)
+    try:
+        args.fn(args)
+    except KeyboardInterrupt:
+        sys.exit(130)
+
+
+if __name__ == "__main__":
+    main()

microvm/client.py

@@ -0,0 +1,60 @@
+"""boto3 client factory with a vendored `lambda-microvms` service model.
+
+The service model ships inside this package (microvm/data), so the control
+plane works even on boto3/botocore versions that predate the service —
+botocore's loader picks up our data directory first.
+"""
+
+from __future__ import annotations
+
+import threading
+from pathlib import Path
+
+import boto3
+import botocore.session
+
+_DATA_DIR = str(Path(__file__).parent / "data")
+_lock = threading.Lock()
+_sessions: dict[tuple[str | None, str], boto3.Session] = {}
+
+
+def _session(profile: str | None, region: str) -> boto3.Session:
+    """One boto3 Session per (profile, region), with our model dir on the loader path."""
+    key = (profile, region)
+    with _lock:
+        if key not in _sessions:
+            bc = botocore.session.Session()
+            loader = bc.get_component("data_loader")
+            if _DATA_DIR not in loader.search_paths:
+                loader.search_paths.insert(0, _DATA_DIR)
+            _sessions[key] = boto3.Session(
+                profile_name=profile, region_name=region, botocore_session=bc
+            )
+        return _sessions[key]
+
+
+def microvm_client(region: str = "us-east-1", profile: str | None = None):
+    """A `lambda-microvms` client (RunMicrovm, SuspendMicrovm, images, tokens…)."""
+    return _session(profile, region).client("lambda-microvms")
+
+
+def lambda_client(service: str, region: str = "us-east-1", profile: str | None = None):
+    """Any other client (s3, iam, logs, cloudwatch…) on the same session/credentials."""
+    return _session(profile, region).client(service)
+
+
+_accounts: dict[tuple[str | None, str], str] = {}
+
+
+def account_id(region: str = "us-east-1", profile: str | None = None) -> str:
+    key = (profile, region)
+    if key not in _accounts:
+        _accounts[key] = _session(profile, region).client("sts").get_caller_identity()["Account"]
+    return _accounts[key]
+
+
+def image_arn(name_or_arn: str, region: str, profile: str | None = None) -> str:
+    """The API's imageIdentifier params want full ARNs; accept a bare name anywhere."""
+    if name_or_arn.startswith("arn:"):
+        return name_or_arn
+    return f"arn:aws:lambda:{region}:{account_id(region, profile)}:microvm-image:{name_or_arn}"

microvm/config.py

@@ -0,0 +1,81 @@
+"""Shared configuration for the control plane.
+
+Lambda MicroVMs is available in: us-east-1, us-east-2, us-west-2,
+eu-west-1, ap-northeast-1. All microVMs are ARM64 (Graviton).
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+
+SUPPORTED_REGIONS = ("us-east-1", "us-east-2", "us-west-2", "eu-west-1", "ap-northeast-1")
+
+# AWS-managed network connector ARNs (account-agnostic, per region).
+INGRESS_ALL = "arn:aws:lambda:{region}:aws:network-connector:aws-network-connector:ALL_INGRESS"
+INGRESS_NONE = "arn:aws:lambda:{region}:aws:network-connector:aws-network-connector:NO_INGRESS"
+INGRESS_SHELL = "arn:aws:lambda:{region}:aws:network-connector:aws-network-connector:SHELL_INGRESS"
+EGRESS_INTERNET = "arn:aws:lambda:{region}:aws:network-connector:aws-network-connector:INTERNET_EGRESS"
+
+# Lambda-managed base image every microVM image builds on.
+MANAGED_BASE_IMAGE = "arn:aws:lambda:{region}:aws:microvm-image:al2023-1"
+
+# Reserved proxy headers on the microVM endpoint.
+AUTH_HEADER = "X-aws-proxy-auth"
+PORT_HEADER = "X-aws-proxy-port"
+FORCE_H2_HEADER = "X-aws-proxy-force-h2"
+
+# In-VM runtime hook base path (served BY your app, called by Lambda).
+HOOK_BASE_PATH = "/aws/lambda-microvms/runtime/v1"
+
+# Published TPS quotas the control plane throttles around (soft, raisable).
+TPS = {
+    "RunMicrovm": 5,
+    "SuspendMicrovm": 2,
+    "ResumeMicrovm": 5,
+    "TerminateMicrovm": 10,
+    "GetMicrovm": 100,
+    "CreateMicrovmAuthToken": 50,
+}
+
+MAX_DURATION_SECONDS = 28_800  # 8 h hard ceiling across RUNNING + SUSPENDED
+
+
+@dataclass
+class PlaneConfig:
+    """Everything the control plane needs to know about one deployment."""
+
+    region: str = field(default_factory=lambda: os.environ.get("MVM_REGION", "us-east-1"))
+    profile: str | None = field(
+        default_factory=lambda: os.environ.get("MVM_PROFILE") or os.environ.get("AWS_PROFILE")
+    )
+    artifact_bucket: str | None = field(default_factory=lambda: os.environ.get("MVM_ARTIFACT_BUCKET"))
+    build_role_arn: str | None = field(default_factory=lambda: os.environ.get("MVM_BUILD_ROLE_ARN"))
+    execution_role_arn: str | None = field(default_factory=lambda: os.environ.get("MVM_EXECUTION_ROLE_ARN"))
+
+    def __post_init__(self) -> None:
+        if self.region not in SUPPORTED_REGIONS:
+            raise ValueError(
+                f"Lambda MicroVMs is not available in {self.region}; pick one of {SUPPORTED_REGIONS}"
+            )
+
+    # Convenience per-region ARNs -------------------------------------------------
+    @property
+    def base_image_arn(self) -> str:
+        return MANAGED_BASE_IMAGE.format(region=self.region)
+
+    @property
+    def ingress_all(self) -> str:
+        return INGRESS_ALL.format(region=self.region)
+
+    @property
+    def ingress_none(self) -> str:
+        return INGRESS_NONE.format(region=self.region)
+
+    @property
+    def ingress_shell(self) -> str:
+        return INGRESS_SHELL.format(region=self.region)
+
+    @property
+    def egress_internet(self) -> str:
+        return EGRESS_INTERNET.format(region=self.region)