microvm-ctl 0.1.0__py3-none-any.whl

microvm/data/lambda-microvms/2025-09-09/paginators-1.json

@@ -0,0 +1,40 @@
+{
+  "pagination": {
+    "ListManagedMicrovmImageVersions": {
+      "input_token": "nextToken",
+      "output_token": "nextToken",
+      "limit_key": "maxResults",
+      "result_key": "items"
+    },
+    "ListManagedMicrovmImages": {
+      "input_token": "nextToken",
+      "output_token": "nextToken",
+      "limit_key": "maxResults",
+      "result_key": "items"
+    },
+    "ListMicrovmImageBuilds": {
+      "input_token": "nextToken",
+      "output_token": "nextToken",
+      "limit_key": "maxResults",
+      "result_key": "items"
+    },
+    "ListMicrovmImageVersions": {
+      "input_token": "nextToken",
+      "output_token": "nextToken",
+      "limit_key": "maxResults",
+      "result_key": "items"
+    },
+    "ListMicrovmImages": {
+      "input_token": "nextToken",
+      "output_token": "nextToken",
+      "limit_key": "maxResults",
+      "result_key": "items"
+    },
+    "ListMicrovms": {
+      "input_token": "nextToken",
+      "output_token": "nextToken",
+      "limit_key": "maxResults",
+      "result_key": "items"
+    }
+  }
+}

microvm/endpoint.py

@@ -0,0 +1,136 @@
+"""Execution plane: authenticated HTTP into a microVM's dedicated endpoint.
+
+Every microVM gets its own HTTPS endpoint
+(`<microvm-id>.lambda-microvm.<region>.on.aws`). There is no unauthenticated
+mode: each request carries a port-scoped, expiring JWE token in the
+`X-aws-proxy-auth` header, minted via CreateMicrovmAuthToken. Non-default
+ports are selected with `X-aws-proxy-port`.
+
+This client mints tokens lazily, caches them until ~80% of their TTL, and
+retries the two endpoint errors you must design for:
+  429 — endpoint rate limit         -> jittered backoff
+  502 — app down or VM auto-resuming -> patient retry (first request after
+        suspend pays the resume; subsequent ones are warm)
+"""
+
+from __future__ import annotations
+
+import random
+import time
+
+import requests
+
+from microvm.client import microvm_client
+from microvm.config import PORT_HEADER, PlaneConfig
+
+
+class EndpointError(RuntimeError):
+    pass
+
+
+class EndpointClient:
+    def __init__(
+        self,
+        config: PlaneConfig,
+        microvm_id: str,
+        endpoint: str | None = None,
+        *,
+        ports: list[int] | None = None,
+        all_ports: bool = False,
+        token_ttl_minutes: int = 15,
+    ):
+        self.cfg = config
+        self.api = microvm_client(config.region, config.profile)
+        self.microvm_id = microvm_id
+        self.endpoint = endpoint or self._discover_endpoint()
+        self.ports = ports or [8080]
+        self.all_ports = all_ports
+        self.ttl_minutes = token_ttl_minutes
+        self._token: dict[str, str] | None = None
+        self._token_expiry = 0.0
+        self.http = requests.Session()
+
+    def _discover_endpoint(self) -> str:
+        vm = self.api.get_microvm(microvmIdentifier=self.microvm_id)
+        return vm["endpoint"]
+
+    # -- token lifecycle ---------------------------------------------------------
+    def _auth_headers(self) -> dict[str, str]:
+        if self._token is None or time.time() > self._token_expiry:
+            spec = [{"allPorts": {}}] if self.all_ports else [{"port": p} for p in self.ports]
+            resp = self.api.create_microvm_auth_token(
+                microvmIdentifier=self.microvm_id,
+                expirationInMinutes=self.ttl_minutes,
+                allowedPorts=spec,
+            )
+            # authToken maps header names to values (e.g. "X-aws-proxy-auth").
+            self._token = dict(resp["authToken"])
+            self._token_expiry = time.time() + self.ttl_minutes * 60 * 0.8
+        return self._token
+
+    # -- requests ----------------------------------------------------------------
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        port: int | None = None,
+        timeout: float = 60,
+        max_attempts: int = 6,
+        resume_patience: float = 30,
+        **kwargs,
+    ) -> requests.Response:
+        """HTTP request to the microVM. 502s are retried for `resume_patience`
+        seconds to ride out an auto-resume; 429s back off with jitter."""
+        url = f"https://{self.endpoint}{path if path.startswith('/') else '/' + path}"
+        base_headers = dict(kwargs.pop("headers", None) or {})
+        if port and port != 8080:
+            base_headers[PORT_HEADER] = str(port)
+        started, delay = time.time(), 0.5
+        last: requests.Response | None = None
+        for attempt in range(1, max_attempts + 1):
+            # Auth headers are merged per attempt so a re-minted token after a
+            # 403 is picked up without losing the caller's own headers.
+            headers = {**base_headers, **self._auth_headers()}
+            last = self.http.request(method, url, headers=headers, timeout=timeout, **kwargs)
+            if last.status_code == 429:
+                time.sleep(delay + random.uniform(0, delay))
+                delay = min(delay * 2, 8)
+                continue
+            if last.status_code == 502 and time.time() - started < resume_patience:
+                time.sleep(2)
+                continue
+            if last.status_code == 403 and attempt < max_attempts:
+                # token may have been revoked/expired server-side; re-mint and retry
+                self._token = None
+                continue
+            return last
+        return last  # type: ignore[return-value]
+
+    def get(self, path: str, **kw) -> requests.Response:
+        return self.request("GET", path, **kw)
+
+    def post(self, path: str, **kw) -> requests.Response:
+        return self.request("POST", path, **kw)
+
+    # -- conveniences ------------------------------------------------------------
+    def wait_ready(self, path: str = "/healthz", timeout: float = 90) -> float:
+        """Poll until the app answers 200; returns time-to-first-byte seconds."""
+        started = time.time()
+        deadline = started + timeout
+        while time.time() < deadline:
+            try:
+                if self.get(path, timeout=10, max_attempts=1).status_code == 200:
+                    return round(time.time() - started, 2)
+            except requests.RequestException:
+                pass
+            time.sleep(1)
+        raise EndpointError(f"{self.microvm_id} not serving {path} after {timeout}s")
+
+    def shell_token(self, minutes: int = 15) -> dict[str, str]:
+        """Token for interactive shell access (VM must run with SHELL_INGRESS)."""
+        return dict(
+            self.api.create_microvm_shell_auth_token(
+                microvmIdentifier=self.microvm_id, expirationInMinutes=minutes
+            )["authToken"]
+        )

microvm/fleet.py

@@ -0,0 +1,291 @@
+"""Fleet manager: run, suspend, resume, terminate, and scale microVM fleets.
+
+A *fleet* is the set of microVMs launched from one image (optionally pinned
+to a version). One endpoint == one microVM — there is no load balancer in
+the service — so horizontal scale is literally more RunMicrovm calls, and
+routing across the fleet is the control plane's job (see endpoint.py).
+
+Every mutating call is throttled to the service's published TPS quotas and
+retried with jittered backoff, so `scale_to(50)` is safe to call in one shot.
+"""
+
+from __future__ import annotations
+
+import concurrent.futures as futures
+import time
+from dataclasses import dataclass, field
+from typing import Callable
+
+from microvm.client import image_arn, microvm_client
+from microvm.config import TPS, PlaneConfig
+from microvm.throttle import Throttled
+
+ACTIVE_STATES = {"PENDING", "RUNNING", "SUSPENDING", "SUSPENDED"}
+
+
+@dataclass
+class Microvm:
+    microvm_id: str
+    state: str
+    image_arn: str
+    image_version: str
+    started_at: object = None  # datetime from the API, or None
+    endpoint: str | None = None
+
+    @property
+    def started_epoch(self) -> float:
+        """startedAt as a POSIX timestamp (0.0 when unknown) - safe to sort on."""
+        ts = getattr(self.started_at, "timestamp", None)
+        return float(ts()) if callable(ts) else 0.0
+
+    @classmethod
+    def from_api(cls, d: dict) -> Microvm:
+        return cls(
+            microvm_id=d["microvmId"],
+            state=d["state"],
+            image_arn=d["imageArn"],
+            image_version=d["imageVersion"],
+            started_at=d.get("startedAt"),
+            endpoint=d.get("endpoint"),
+        )
+
+
+@dataclass
+class IdlePolicy:
+    """Suspend after `max_idle` seconds without endpoint traffic; auto-resume on
+    the next request; auto-TERMINATE after `suspended_for` seconds suspended."""
+
+    max_idle: int = 300
+    suspended_for: int = 3600
+    auto_resume: bool = True
+
+    def to_api(self) -> dict:
+        return {
+            "maxIdleDurationSeconds": self.max_idle,
+            "suspendedDurationSeconds": self.suspended_for,
+            "autoResumeEnabled": self.auto_resume,
+        }
+
+
+# Service Quotas codes for the applied (per-account) API rates — new accounts
+# run reduced profiles (e.g. RunMicrovm 1/s instead of 5/s), so the published
+# defaults are the wrong thing to throttle against.
+QUOTA_CODES = {
+    "RunMicrovm": "L-535CA9B6",
+    "SuspendMicrovm": "L-90045317",
+    "ResumeMicrovm": "L-118C44B3",
+    "TerminateMicrovm": "L-74787B8A",
+    "MaxMemoryGb": "L-CD1C0CC4",
+}
+
+
+def applied_quotas(config: PlaneConfig) -> dict[str, float]:
+    """Best-effort lookup of this account's *applied* microVM quotas."""
+    from microvm.client import lambda_client
+    try:
+        sq = lambda_client("service-quotas", config.region, config.profile)
+        out = {}
+        for name, code in QUOTA_CODES.items():
+            try:
+                out[name] = sq.get_service_quota(ServiceCode="lambda", QuotaCode=code)[
+                    "Quota"]["Value"]
+            except Exception:
+                pass
+        return out
+    except Exception:
+        return {}
+
+
+class FleetManager:
+    """Low-level lifecycle operations, one instance per (account, region)."""
+
+    #: fraction of the applied TPS quota the token buckets are allowed to use
+    QUOTA_HEADROOM = 0.8
+
+    def __init__(self, config: PlaneConfig, quota_aware: bool = True):
+        self.cfg = config
+        self.api = microvm_client(config.region, config.profile)
+        self.quotas = applied_quotas(config) if quota_aware else {}
+        self._run = Throttled(self.api.run_microvm, self.tps("RunMicrovm"))
+        self._suspend = Throttled(self.api.suspend_microvm, self.tps("SuspendMicrovm"))
+        self._resume = Throttled(self.api.resume_microvm, self.tps("ResumeMicrovm"))
+        self._terminate = Throttled(self.api.terminate_microvm, self.tps("TerminateMicrovm"))
+
+    def tps(self, op: str) -> float:
+        """Effective rate for one mutating API: applied quota (or the published
+        default when Service Quotas is unavailable) times QUOTA_HEADROOM."""
+        return (self.quotas.get(op) or TPS[op]) * self.QUOTA_HEADROOM
+
+    @property
+    def memory_quota_gb(self) -> float | None:
+        """Applied 'max allocated microVM memory' quota, if Service Quotas answered."""
+        return self.quotas.get("MaxMemoryGb")
+
+    # -- single VM ---------------------------------------------------------------
+    def run(
+        self,
+        image: str,
+        *,
+        version: str | None = None,
+        idle_policy: IdlePolicy | None = None,
+        run_payload: str | None = None,
+        max_duration: int | None = None,
+        ingress: list[str] | None = None,
+        egress: list[str] | None = None,
+        execution_role: str | None = None,
+    ) -> Microvm:
+        params: dict = {"imageIdentifier": image_arn(image, self.cfg.region, self.cfg.profile)}
+        if version:
+            params["imageVersion"] = version
+        params["idlePolicy"] = (idle_policy or IdlePolicy()).to_api()
+        if run_payload is not None:
+            params["runHookPayload"] = run_payload
+        if max_duration:
+            params["maximumDurationInSeconds"] = max_duration
+        if ingress:
+            params["ingressNetworkConnectors"] = ingress
+        if egress:
+            params["egressNetworkConnectors"] = egress
+        role = execution_role or self.cfg.execution_role_arn
+        if role:
+            params["executionRoleArn"] = role
+        return Microvm.from_api(self._run(**params))
+
+    def get(self, microvm_id: str) -> Microvm:
+        return Microvm.from_api(self.api.get_microvm(microvmIdentifier=microvm_id))
+
+    def suspend(self, microvm_id: str) -> None:
+        self._suspend(microvmIdentifier=microvm_id)
+
+    def resume(self, microvm_id: str) -> None:
+        self._resume(microvmIdentifier=microvm_id)
+
+    def terminate(self, microvm_id: str) -> None:
+        self._terminate(microvmIdentifier=microvm_id)
+
+    def wait_until(self, microvm_id: str, state: str, timeout: int = 120) -> Microvm:
+        deadline = time.time() + timeout
+        while time.time() < deadline:
+            vm = self.get(microvm_id)
+            if vm.state == state:
+                return vm
+            if vm.state == "TERMINATED" and state != "TERMINATED":
+                raise RuntimeError(f"{microvm_id} terminated while waiting for {state}")
+            time.sleep(2)
+        raise TimeoutError(f"{microvm_id} did not reach {state} in {timeout}s")
+
+    def list(self, image: str | None = None, version: str | None = None) -> list[Microvm]:
+        kwargs: dict = {}
+        if image:
+            kwargs["imageIdentifier"] = image_arn(image, self.cfg.region, self.cfg.profile)
+        if version:
+            kwargs["imageVersion"] = version
+        out = self.api.get_paginator("list_microvms").paginate(**kwargs).build_full_result()
+        return [Microvm.from_api(d) for d in out.get("items", [])]
+
+
+@dataclass
+class Fleet:
+    """Declarative fleet of microVMs from one image: scale up, down, drain."""
+
+    manager: FleetManager
+    image: str
+    version: str | None = None
+    idle_policy: IdlePolicy = field(default_factory=IdlePolicy)
+    max_duration: int | None = None
+    #: called with the launch index (0..n-1) to produce that VM's runHookPayload
+    run_payload_factory: Callable[[int], str] | None = None
+    ingress: list[str] | None = None
+    egress: list[str] | None = None
+    execution_role: str | None = None
+    _pool: futures.ThreadPoolExecutor = field(
+        default_factory=lambda: futures.ThreadPoolExecutor(max_workers=8), repr=False
+    )
+
+    # -- observation -------------------------------------------------------------
+    def members(self) -> list[Microvm]:
+        return [
+            vm
+            for vm in self.manager.list(self.image, self.version)
+            if vm.state in ACTIVE_STATES
+        ]
+
+    def size(self) -> int:
+        return len(self.members())
+
+    # -- scaling -----------------------------------------------------------------
+    def scale_to(self, desired: int, wait_running: bool = False) -> list[Microvm]:
+        """Converge the fleet to `desired` active microVMs.
+
+        Scale-up launches new VMs (throttled to the RunMicrovm quota).
+        Scale-down terminates SUSPENDED VMs first (they cost only snapshot
+        storage but count against the regional memory quota), then the
+        youngest RUNNING VMs, sparing the oldest — they hold the warmest state.
+        """
+        current = self.members()
+        delta = desired - len(current)
+        if delta > 0:
+            launched = list(
+                self._pool.map(lambda i: self._launch_one(i), range(delta))
+            )
+            if wait_running:
+                launched = [
+                    self.manager.wait_until(vm.microvm_id, "RUNNING") for vm in launched
+                ]
+            return launched
+        if delta < 0:
+            for vm in self.scale_down_victims(current, -delta):
+                self.manager.terminate(vm.microvm_id)
+        return []
+
+    @staticmethod
+    def scale_down_victims(members: list[Microvm], count: int) -> list[Microvm]:
+        """Pick `count` members to terminate: every SUSPENDED VM first (storage
+        cost only, but they hold memory quota), then RUNNING VMs youngest first
+        so the oldest, warmest members survive."""
+        suspended = [v for v in members if v.state == "SUSPENDED"]
+        running = [v for v in members if v.state != "SUSPENDED"]
+        running.sort(key=lambda vm: vm.started_epoch, reverse=True)  # youngest first
+        return (suspended + running)[:count]
+
+    def _launch_one(self, index: int) -> Microvm:
+        payload = self.run_payload_factory(index) if self.run_payload_factory else None
+        return self.manager.run(
+            self.image,
+            version=self.version,
+            idle_policy=self.idle_policy,
+            run_payload=payload,
+            max_duration=self.max_duration,
+            ingress=self.ingress,
+            egress=self.egress,
+            execution_role=self.execution_role,
+        )
+
+    def suspend_all(self) -> int:
+        vms = [v for v in self.members() if v.state == "RUNNING"]
+        list(self._pool.map(lambda v: self.manager.suspend(v.microvm_id), vms))
+        return len(vms)
+
+    def resume_all(self) -> int:
+        vms = [v for v in self.members() if v.state == "SUSPENDED"]
+        list(self._pool.map(lambda v: self.manager.resume(v.microvm_id), vms))
+        return len(vms)
+
+    def drain(self) -> int:
+        """Terminate every member of the fleet."""
+        vms = self.members()
+        list(self._pool.map(lambda v: self.manager.terminate(v.microvm_id), vms))
+        return len(vms)
+
+    # -- reaper ------------------------------------------------------------------
+    def reap(self, max_age_seconds: int) -> list[str]:
+        """Terminate members older than `max_age_seconds` (belt-and-braces on top
+        of maximumDurationInSeconds and the idle policy's auto-terminate)."""
+        now = time.time()
+        reaped = []
+        for vm in self.members():
+            started = vm.started_epoch
+            if started and now - started > max_age_seconds:
+                self.manager.terminate(vm.microvm_id)
+                reaped.append(vm.microvm_id)
+        return reaped

microvm/hooks/__init__.py

@@ -0,0 +1,3 @@
+from microvm.hooks.server import HookApp
+
+__all__ = ["HookApp"]

microvm/hooks/server.py

@@ -0,0 +1,168 @@
+"""Zero-dependency in-VM hook server implementing the Lambda MicroVMs contract.
+
+Lambda drives the microVM lifecycle by calling HTTP hooks that *your app*
+serves (stdlib only — nothing to install inside the image):
+
+  build-time   GET/POST /aws/lambda-microvms/runtime/v1/ready     503 until warm, 200 => snapshot now
+               GET/POST /aws/lambda-microvms/runtime/v1/validate  runs on a fresh VM from the image
+  runtime      POST     /aws/lambda-microvms/runtime/v1/run       after clone; traffic starts on 200
+               POST     /aws/lambda-microvms/runtime/v1/resume    VM stays SUSPENDED until 200
+               POST     /aws/lambda-microvms/runtime/v1/suspend   flush before snapshot
+               POST     /aws/lambda-microvms/runtime/v1/terminate cleanup before teardown
+
+Because every VM is cloned from one snapshot, the /run hook is where you
+restore uniqueness (reseed RNG, regenerate IDs, fetch per-tenant secrets from
+the runHookPayload) — never at build time. Return fast; Lambda retries /ready
+on 503, and a held-open hook request at timeout fails the build.
+
+Usage:
+    app = HookApp()
+
+    @app.on_run
+    def on_run(ctx):            # ctx = {"microvmId": ..., "runHookPayload": ...}
+        seed_rng(); load_tenant(ctx.get("runHookPayload"))
+
+    @app.route("POST", "/execute")
+    def execute(body, headers):
+        return 200, {"result": run(body["code"])}
+
+    app.serve(port=8080)
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import random
+import threading
+import traceback
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+HOOK_BASE = "/aws/lambda-microvms/runtime/v1"
+
+
+class HookApp:
+    def __init__(self):
+        self._hooks: dict[str, object] = {}
+        self._routes: dict[tuple[str, str], object] = {}
+        self.ready = False
+        self.microvm_id: str | None = None
+        self.run_payload: str | None = None
+
+        @self.route("GET", "/healthz")
+        def _healthz(body, headers):
+            return 200, {"ok": True, "microvmId": self.microvm_id}
+
+    # -- decorators --------------------------------------------------------------
+    def on_ready(self, fn):
+        """Return truthy when warm enough to snapshot (else 503 -> retried)."""
+        self._hooks["ready"] = fn
+        return fn
+
+    def on_validate(self, fn):
+        """Exercise real code paths here: Lambda records the snapshot regions the
+        validate run touches and prefetches them, cutting launch latency.
+        Return False (or raise) to fail the build."""
+        self._hooks["validate"] = fn
+        return fn
+
+    def on_run(self, fn):
+        self._hooks["run"] = fn
+        return fn
+
+    def on_resume(self, fn):
+        self._hooks["resume"] = fn
+        return fn
+
+    def on_suspend(self, fn):
+        self._hooks["suspend"] = fn
+        return fn
+
+    def on_terminate(self, fn):
+        self._hooks["terminate"] = fn
+        return fn
+
+    def route(self, method: str, path: str):
+        def deco(fn):
+            self._routes[(method.upper(), path)] = fn
+            return fn
+        return deco
+
+    # -- hook dispatch -----------------------------------------------------------
+    def _dispatch_hook(self, name: str, ctx: dict) -> int:
+        if name == "ready":
+            fn = self._hooks.get("ready")
+            ok = fn(ctx) if fn else True
+            self.ready = bool(ok) if fn else True
+            return 200 if self.ready else 503
+        if name == "validate":
+            fn = self._hooks.get("validate")
+            if fn is None:
+                return 200
+            ok = fn(ctx)
+            # None (no return statement) means "ran fine"; an explicit False
+            # rejects the image version so a bad build never becomes ACTIVE.
+            return 200 if ok is None or ok else 500
+        if name == "run":
+            self.microvm_id = ctx.get("microvmId") or os.environ.get("AWS_MICROVM_ID")
+            self.run_payload = ctx.get("runHookPayload")
+            # Restore entropy uniqueness for every clone before user code runs.
+            random.seed()
+        fn = self._hooks.get(name)
+        if fn:
+            fn(ctx)
+        return 200
+
+    # -- server ------------------------------------------------------------------
+    def serve(self, port: int = 8080, background: bool = False):
+        app = self
+
+        class Handler(BaseHTTPRequestHandler):
+            protocol_version = "HTTP/1.1"
+
+            def _read_json(self):
+                n = int(self.headers.get("Content-Length") or 0)
+                raw = self.rfile.read(n) if n else b""
+                try:
+                    return json.loads(raw) if raw else {}
+                except json.JSONDecodeError:
+                    return {"_raw": raw.decode("utf-8", "replace")}
+
+            def _send(self, status: int, payload):
+                body = (payload if isinstance(payload, (bytes, bytearray))
+                        else json.dumps(payload).encode())
+                self.send_response(status)
+                self.send_header("Content-Type", "application/json")
+                self.send_header("Content-Length", str(len(body)))
+                self.end_headers()
+                self.wfile.write(body)
+
+            def _handle(self, method: str):
+                path = self.path.split("?", 1)[0]
+                try:
+                    if path.startswith(HOOK_BASE + "/"):
+                        hook = path[len(HOOK_BASE) + 1:]
+                        status = app._dispatch_hook(hook, self._read_json())
+                        return self._send(status, {"hook": hook, "status": status})
+                    fn = app._routes.get((method, path))
+                    if fn is None:
+                        return self._send(404, {"error": f"no route {method} {path}"})
+                    status, payload = fn(self._read_json(), dict(self.headers))
+                    return self._send(status, payload)
+                except Exception:
+                    return self._send(500, {"error": traceback.format_exc(limit=5)})
+
+            def do_GET(self):
+                self._handle("GET")
+
+            def do_POST(self):
+                self._handle("POST")
+
+            def log_message(self, *a):  # keep container logs for the app, not access noise
+                pass
+
+        server = ThreadingHTTPServer(("0.0.0.0", port), Handler)
+        if background:
+            threading.Thread(target=server.serve_forever, daemon=True).start()
+            return server
+        server.serve_forever()