multicloud-cli 0.1.0__py3-none-any.whl

multicloud_cli/orgopt.py

@@ -0,0 +1,28 @@
+"""``--org`` on a command group and on each of its subcommands.
+
+The error for several organizations says "Name one with --org". A user types it
+after the subcommand (``mctl pool list --org acme``), so every subcommand takes it
+too. The one after the subcommand wins over the one on the group.
+"""
+import click
+
+
+def _store(key):
+    def callback(ctx, param, value):
+        if value is not None:
+            ctx.ensure_object(dict)
+            ctx.obj[key] = value
+        return None
+    return callback
+
+
+def org_group(key):
+    """A click Group class whose subcommands accept --org and store it in ctx.obj[key]."""
+    class OrgGroup(click.Group):
+        def add_command(self, cmd, name=None):
+            if not any("--org" in getattr(p, "opts", ()) for p in cmd.params):
+                cmd.params.append(click.Option(
+                    ["--org"], default=None, expose_value=False, callback=_store(key),
+                    help="Organization slug (default: MULTICLOUD_ORG)"))
+            super().add_command(cmd, name)
+    return OrgGroup

multicloud_cli/output.py

@@ -0,0 +1,40 @@
+"""Output helpers shared by the command groups: the plain table, the JSON dump and the common options."""
+import json
+import sys
+from typing import Any, Callable, Dict, List, Tuple
+
+import click
+
+from . import exitcodes
+
+
+def plain(data: Dict[str, Any]) -> Dict[str, Any]:
+    data = dict(data)
+    data.pop("_status", None)
+    return data
+
+
+def dump(data: Dict[str, Any]) -> None:
+    click.echo(json.dumps(plain(data), indent=2, sort_keys=True))
+
+
+def table(header: Tuple[str, ...], rows: List[Tuple[str, ...]], headers: bool = True) -> str:
+    rows = ([header] if headers else []) + rows
+    if not rows:
+        return ""
+    widths = [max(len(r[i]) for r in rows) for i in range(len(header))]
+    return "\n".join("  ".join(c.ljust(w) for c, w in zip(r, widths)).rstrip() for r in rows)
+
+
+def run(org, fn: Callable[[Any], Any], errors: Tuple[type, ...]) -> Any:
+    """Run ``fn(org)``; an error of ``errors`` prints ``Error: <text>`` and exits with its exit code."""
+    try:
+        return fn(org)
+    except errors as ex:
+        click.echo(f"Error: {ex}", err=True)
+        sys.exit(exitcodes.of(ex))
+
+
+json_option = click.option("--json", "as_json", is_flag=True, help="Print the raw JSON")
+quiet_option = click.option("-q", "--quiet", is_flag=True, help="Print only the IDs, one per line")
+no_headers_option = click.option("--no-headers", is_flag=True, help="Leave the header line out of the table")

multicloud_cli/pool.py

@@ -0,0 +1,454 @@
+"""``mctl pool``: create and manage the CI pools of an organization.
+
+These commands call ``/api/v1/orgs/{slug}/pools`` with an API key. Reads need ``org:read``, create and
+update need ``org:write``, delete, hibernate, wake and rotate-credentials need ``org:admin``.
+The key comes from ``mctl auth`` (or ``MULTICLOUD_API_KEY``); org and URL from ``--org``/``MULTICLOUD_ORG``/
+``MULTICLOUD_API_URL`` or the saved config.
+A ``<pool>`` argument is the numeric id or the exact name of the pool.
+"""
+import json
+import sys
+import time
+import uuid
+from pathlib import Path
+from typing import Any, Callable, Dict, Optional, Tuple
+
+import click
+
+from . import api, exitcodes
+from .duration import duration_option, interval_option, parse_duration  # noqa: F401  (parse_duration: tests)
+from .orgopt import org_group
+from .output import dump as _dump, json_option, no_headers_option, plain as _plain, quiet_option, run, table as _table
+
+READ, WRITE, ADMIN = "org:read", "org:write", "org:admin"
+EXIT_OK, EXIT_TIMEOUT, EXIT_DELETED = exitcodes.OK, exitcodes.PENDING, exitcodes.GONE
+_sleep = time.sleep  # tests patch this name
+# PoolView.status values in which a wake is finished, and in which the pool is gone.
+UP = ("ready", "at_cost_cap")
+GONE = ("deleting", "deleted")
+
+
+class PoolError(exitcodes.CliError):
+    pass
+
+
+def _stdin_is_tty() -> bool:
+    return sys.stdin.isatty()
+
+
+def _fail(ex: api.ApiError, text: Optional[str] = None) -> PoolError:
+    return PoolError(text or str(ex), ex.exit_code)
+
+
+def _call(org, method: str, path: str, scope: str, **kw) -> Dict[str, Any]:
+    try:
+        return api.call(method, org, path, scope=scope, **kw)
+    except api.ApiError as ex:
+        raise _fail(ex)
+
+
+def resolve(org, ref: str) -> int:
+    """The id for a numeric ``ref``, else for the pool with that exact name (one list call)."""
+    if ref.isascii() and ref.isdigit():
+        return int(ref)
+    pools = _call(org, "GET", "/pools", READ).get("pools", [])
+    found = [p for p in pools if p.get("name") == ref]
+    if not found:
+        raise PoolError(f"No pool named '{ref}'. Run: mctl pool list", exitcodes.NOT_FOUND)
+    if len(found) > 1:
+        ids = ", ".join(str(p.get("pool_id")) for p in found)
+        raise PoolError(f"Several pools are named '{ref}' (ids {ids}). Use the id.")
+    return int(found[0]["pool_id"])
+
+
+def _money(value) -> str:
+    return "-" if value is None else f"{value:.2f}"
+
+
+def _status(p: Dict[str, Any]) -> str:
+    out = str(p.get("status", "unknown"))
+    if p.get("status_message"):
+        out += f" ({p['status_message']})"
+    return out
+
+
+def _clouds(p: Dict[str, Any]) -> str:
+    parts = []
+    for c in p.get("clouds") or []:
+        regions = c.get("regions") or []
+        part = f"{c.get('type')}: " + (", ".join(regions) if regions else "all regions")
+        if c.get("exclude_regions"):
+            part += " except " + ", ".join(c["exclude_regions"])
+        parts.append(part)
+    return "; ".join(parts)
+
+
+def _readable(p: Dict[str, Any]) -> str:
+    lines = [
+        f"Pool {p.get('pool_id')} ({p.get('name')})",
+        ("Type", p.get("type")),
+        f"Status: {_status(p)}",
+        ("Clouds", _clouds(p)),
+        ("Classes", ", ".join(p["classes"]) if p.get("classes") else None),
+        ("GitHub org", p.get("github_org")),
+        ("Spot policy", p.get("spot_policy")),
+        ("CPU units requests", p.get("cpu_units_requests")),
+        ("Nodes", p.get("node_count")),
+        ("Cost per hour", f"{_money(p.get('current_cost_per_hour'))} of {_money(p.get('max_cost_per_hour'))} allowed"),
+        ("Hibernated since", p.get("hibernated_since")),
+        ("Hibernated reason", p.get("hibernated_reason")),
+    ]
+    return "\n".join(l if isinstance(l, str) else f"{l[0]}: {l[1]}"
+                     for l in lines if isinstance(l, str) or l[1] not in (None, ""))
+
+
+def format_pools(pools, headers: bool = True) -> str:
+    return _table(("ID", "NAME", "TYPE", "STATUS", "NODES", "COST/H"), [
+        (str(p.get("pool_id")), str(p.get("name")), str(p.get("type")), str(p.get("status")),
+         str(p.get("node_count")), f"{_money(p.get('current_cost_per_hour'))}/{_money(p.get('max_cost_per_hour'))}")
+        for p in pools], headers)
+
+
+@click.group(cls=org_group("pool_org"))
+@click.option("--org", default=None, help="Organization slug (default: MULTICLOUD_ORG)")
+@click.pass_context
+def pool(ctx, org):
+    """Manage CI pools (sign in first: mctl auth login)."""
+    ctx.ensure_object(dict)
+    ctx.obj["pool_org"] = org
+
+
+def _run(ctx, fn):
+    return run(ctx.obj.get("pool_org"), fn, (PoolError, api.ApiError))
+
+
+@pool.command()
+@json_option
+@no_headers_option
+@click.pass_context
+def classes(ctx, as_json, no_headers):
+    """List the runner classes a pool can use."""
+    data = _run(ctx, lambda org: _call(org, "GET", "/pool-classes", READ))
+    if as_json:
+        return _dump(data)
+    rows = []
+    for c in data.get("classes", []):
+        price = c.get("price_per_hour")
+        gpu = c.get("gpu")
+        size = f"{gpu['count']}x {gpu['name']}" if gpu else f"{c.get('cores')} cores"
+        rows.append((str(c.get("name")), str(c.get("kind")), size, str(c.get("purchase")),
+                     "yes" if c.get("enabled") else "no",
+                     f"{price['min']:.2f}-{price['max']:.2f}" if price else "-"))
+    click.echo(_table(("CLASS", "KIND", "SIZE", "PURCHASE", "ENABLED", "USD/H"), rows, not no_headers))
+
+
+@pool.command(name="list")
+@json_option
+@quiet_option
+@no_headers_option
+@click.pass_context
+def list_(ctx, as_json, quiet, no_headers):
+    """List the pools of the organization."""
+    data = _run(ctx, lambda org: _call(org, "GET", "/pools", READ))
+    if as_json:
+        return _dump(data)
+    if quiet:
+        for p in data.get("pools", []):
+            click.echo(p.get("pool_id"))
+        return
+    click.echo(format_pools(data.get("pools", []), not no_headers))
+
+
+@pool.command()
+@click.argument("pool_ref", metavar="POOL")
+@json_option
+@click.pass_context
+def show(ctx, pool_ref, as_json):
+    """Show one pool (id or name)."""
+    def go(org):
+        return _call(org, "GET", f"/pools/{resolve(org, pool_ref)}", READ)
+    data = _run(ctx, go)
+    click.echo(json.dumps(_plain(data), indent=2, sort_keys=True) if as_json else _readable(data))
+
+
+def _read_stdin() -> str:
+    return sys.stdin.read()
+
+
+def _json_value(ctx, param, value):
+    """A JSON value, or ``@path`` to read it from a file (``@-``: standard input)."""
+    if value is None:
+        return None
+    try:
+        if value == "@-":
+            text = _read_stdin()
+        else:
+            text = Path(value[1:]).read_text() if value.startswith("@") else value
+        return json.loads(text)
+    except (OSError, ValueError) as ex:
+        raise click.BadParameter(f"Not valid JSON ({ex}). Give JSON, or @file.json (@- for standard input).")
+
+
+def _classes_list(ctx, param, value):
+    names = [n.strip() for v in value for n in v.split(",") if n.strip()]
+    return names or None
+
+
+def _collect(**given) -> Dict[str, Any]:
+    return {k: v for k, v in given.items() if v is not None}
+
+
+@pool.command()
+@click.argument("name", required=False)
+@click.option("--github-org", default=None, help="GitHub organization the runners serve")
+@click.option("--clouds", callback=_json_value, default=None,
+              help="JSON list of clouds, or @file.json. Cloud keys belong in --from-file, not in a command line")
+@click.option("--classes", "classes_", multiple=True, callback=_classes_list,
+              help="Runner class; repeat or separate with commas (see: mctl pool classes)")
+@click.option("--max-cost-per-hour", type=float, default=None, help="Cost ceiling in USD per hour")
+@click.option("--image-by-class", callback=_json_value, default=None, help="JSON object, or @file.json")
+@click.option("--egress-by-class", callback=_json_value, default=None, help="JSON object, or @file.json")
+@click.option("--class-headroom", callback=_json_value, default=None, help="JSON object, or @file.json")
+@click.option("--spot-policy", default=None, help="Spot policy name")
+@click.option("--cpu-units-requests/--no-cpu-units-requests", default=None,
+              help="Runner pods request cpu-units instead of cpu")
+@click.option("--from-file", "from_file", type=click.Path(dir_okay=False, allow_dash=True), default=None,
+              help="JSON file with the request body (- for standard input); flags override its fields")
+@click.option("--idempotency-key", default=None,
+              help="Same key and body within 24 hours creates one pool (default: a new random key)")
+@json_option
+@click.pass_context
+def create(ctx, name, github_org, clouds, classes_, max_cost_per_hour, image_by_class, egress_by_class,
+           class_headroom, spot_policy, cpu_units_requests, from_file, idempotency_key, as_json):
+    """Create a CI pool."""
+    body: Dict[str, Any] = {}
+    if from_file:
+        try:
+            body = json.loads(_read_stdin() if from_file == "-" else Path(from_file).read_text())
+        except (OSError, ValueError) as ex:
+            raise click.BadParameter(f"Could not read {from_file} as JSON: {ex}", param_hint="--from-file")
+        if not isinstance(body, dict):
+            raise click.BadParameter("The file must hold a JSON object.", param_hint="--from-file")
+    body.update(_collect(name=name, github_org=github_org, clouds=clouds, classes=classes_,
+                         max_cost_per_hour=max_cost_per_hour, image_by_class=image_by_class,
+                         egress_by_class=egress_by_class, class_headroom=class_headroom,
+                         spot_policy=spot_policy, cpu_units_requests=cpu_units_requests))
+    missing = [f for f in ("name", "github_org", "clouds", "classes", "max_cost_per_hour") if f not in body]
+    if missing:
+        raise click.UsageError("Missing: " + ", ".join("--" + m.replace("_", "-") if m != "name" else "NAME"
+                                                       for m in missing))
+    key = idempotency_key or str(uuid.uuid4())
+
+    def go(org):
+        try:
+            return api.call("POST", org, "/pools", body=body, headers={"Idempotency-Key": key}, scope=WRITE)
+        except api.ApiError as ex:
+            if ex.status is None or ex.status >= 500:
+                # The pool may exist already: the same key and body make the retry safe.
+                raise _fail(ex, f"{ex} To retry safely, run the same command with --idempotency-key {key}")
+            raise _fail(ex)
+    made = _run(ctx, go)
+    if as_json:
+        return _dump(made)
+    click.echo(f"Pool {made.get('pool_id')} ({made.get('name')}) created. Status: {_status(made)}")
+    click.echo(f"Next: mctl pool show {made.get('pool_id')}")
+
+
+@pool.command()
+@click.argument("pool_ref", metavar="POOL")
+@click.option("--spot-policy", default=None, help="Spot policy name")
+@click.option("--cpu-units-requests/--no-cpu-units-requests", default=None,
+              help="Runner pods request cpu-units instead of cpu")
+@click.option("--max-cost-per-hour", type=float, default=None, help="Cost ceiling in USD per hour")
+@click.option("--classes", "classes_", multiple=True, callback=_classes_list,
+              help="Runner classes of the pool; repeat or separate with commas")
+@click.option("--clouds", callback=_json_value, default=None,
+              help="JSON list of {type, regions, exclude_regions} for clouds the pool has, or @file.json")
+@json_option
+@click.pass_context
+def update(ctx, pool_ref, spot_policy, cpu_units_requests, max_cost_per_hour, classes_, clouds, as_json):
+    """Change a pool. Only the options you give are sent."""
+    body = _collect(spot_policy=spot_policy, cpu_units_requests=cpu_units_requests,
+                    max_cost_per_hour=max_cost_per_hour, classes=classes_, clouds=clouds)
+    if not body:
+        raise click.UsageError("Give at least one option to change.")
+
+    def go(org):
+        return _call(org, "PATCH", f"/pools/{resolve(org, pool_ref)}", WRITE, body=body)
+    data = _run(ctx, go)
+    if as_json:
+        return _dump(data)
+    click.echo(f"Pool {data.get('pool_id')} updated ({', '.join(sorted(body))}).")
+
+
+@pool.command()
+@click.argument("pool_ref", metavar="POOL")
+@json_option
+@click.pass_context
+def hibernate(ctx, pool_ref, as_json):
+    """Pause a pool: remove its nodes and stop the control plane. The pool keeps its name."""
+    def go(org):
+        return _call(org, "POST", f"/pools/{resolve(org, pool_ref)}/hibernate", ADMIN)
+    data = _run(ctx, go)
+    if as_json:
+        return _dump(data)
+    click.echo(f"Pool {data.get('pool_id')}: {_status(data)}. Resume it with: mctl pool wake {data.get('pool_id')}")
+
+
+def wait_for_wake(fetch: Callable[[], Dict[str, Any]], *, timeout_s: int,
+                  interval_s: int = 10) -> Tuple[int, str, Dict[str, Any]]:
+    """Poll the pool until it is ready (exit 0), deleted meanwhile (exit 6) or ``timeout_s`` passed (exit 5).
+
+    A poll without an answer or with a 5xx is retried until the timeout; other errors raise. Progress goes to
+    stderr, so stdout holds only the result."""
+    waited = 0
+    p: Dict[str, Any] = {}
+    while True:
+        try:
+            p = fetch()
+        except api.ApiError as ex:
+            if ex.status is not None and ex.status < 500:
+                raise
+            click.echo(f"Check failed ({ex}). Retrying.", err=True)
+        else:
+            status = p.get("status")
+            if status in UP:
+                return EXIT_OK, f"Ready: pool {p.get('pool_id')} is {status}.", p
+            if status in GONE:
+                return EXIT_DELETED, f"Pool {p.get('pool_id')} is {status}. It cannot wake.", p
+        if waited >= timeout_s:
+            return EXIT_TIMEOUT, (f"Timed out after {waited}s. Last status: {_status(p) if p else 'unknown'}. "
+                                  f"Check later with: mctl pool show {p.get('pool_id', '')}".rstrip()), p
+        step = max(1, min(interval_s, timeout_s - waited))
+        if p:
+            click.echo(f"Status {_status(p)}. Checking again in {step}s ...", err=True)
+        _sleep(step)
+        waited += step
+
+
+@pool.command()
+@click.argument("pool_ref", metavar="POOL")
+@click.option("-w", "--wait", is_flag=True, help="Wait until the pool is ready")
+@click.option("-t", "--timeout", default="15m", show_default=True, callback=duration_option,
+              help="How long to wait with --wait (90, 90s, 15m, 1h)")
+@click.option("--interval", default="10s", show_default=True, callback=interval_option,
+              help="Time between checks with --wait (90, 90s, 15m, 1h)")
+@json_option
+@click.pass_context
+def wake(ctx, pool_ref, wait, timeout, interval, as_json):
+    """Wake a hibernated pool. Exit 0 ready, 5 --wait timeout, 6 pool deleted, 1 other error."""
+    def go(org):
+        pool_id = resolve(org, pool_ref)
+        data = _call(org, "POST", f"/pools/{pool_id}/wake", ADMIN)
+        if as_json and not wait:
+            _dump(data)
+            return EXIT_OK
+        click.echo(f"Pool {pool_id}: {_status(data)}.", err=as_json)
+        if not wait:
+            click.echo(f"Wait for it with: mctl pool wake {pool_id} --wait")
+            return EXIT_OK
+        try:
+            code, text, last = wait_for_wake(lambda: api.call("GET", org, f"/pools/{pool_id}", scope=READ),
+                                             timeout_s=timeout, interval_s=interval)
+        except api.ApiError as ex:
+            raise _fail(ex)
+        if as_json:
+            click.echo(text, err=True)
+            if last:
+                _dump(last)
+        else:
+            click.echo(text, err=code != EXIT_OK)
+        return code
+    sys.exit(_run(ctx, go))
+
+
+@pool.command()
+@click.argument("pool_ref", metavar="POOL")
+@click.option("-y", "--yes", is_flag=True, help="Delete without asking")
+@json_option
+@click.pass_context
+def delete(ctx, pool_ref, yes, as_json):
+    """Delete a pool for good: its nodes stop and are removed. To pause it instead, use: mctl pool hibernate."""
+    if not yes and not _stdin_is_tty():
+        click.echo("Error: Refusing to delete without confirmation. Run again with --yes.", err=True)
+        sys.exit(exitcodes.ERROR)
+
+    def go(org):
+        pool_id = resolve(org, pool_ref)
+        if not yes and not click.confirm(
+                f"This deletes pool {pool_ref} and stops its nodes. It cannot be undone "
+                f"(to pause it, use: mctl pool hibernate {pool_ref}). Delete it?", default=False):
+            click.echo("Nothing deleted.", err=True)
+            return exitcodes.ERROR
+        data = _call(org, "DELETE", f"/pools/{pool_id}", ADMIN)
+        if as_json:
+            _dump(data)
+        else:
+            click.echo(f"Pool {pool_id}: {_status(data)}. The nodes are removed in the background.")
+        return 0
+    sys.exit(_run(ctx, go))
+
+
+@pool.command()
+@click.argument("pool_ref", metavar="POOL")
+@json_option
+@no_headers_option
+@click.pass_context
+def cluster(ctx, pool_ref, as_json, no_headers):
+    """Show the cluster of a pool and its nodes."""
+    def go(org):
+        return _call(org, "GET", f"/pools/{resolve(org, pool_ref)}/cluster", READ)
+    data = _run(ctx, go)
+    if as_json:
+        return _dump(data)
+    click.echo(f"Pool {data.get('pool_id')} ({data.get('pool_name')}): {_status(data)}")
+    click.echo(f"Nodes: {data.get('node_count')}. Cost per hour: {_money(data.get('current_cost_per_hour'))} "
+               f"of {_money(data.get('max_cost_per_hour'))} allowed.")
+    nodes = data.get("nodes") or []
+    if nodes:
+        click.echo(_table(("NODE", "SERVER TYPE", "CLOUD", "REGION", "CAPACITY", "STATUS", "USD/H"), [
+            (str(n.get("name")), str(n.get("server_type") or "-"), str(n.get("cloud") or "-"),
+             str(n.get("region") or "-"), str(n.get("capacity") or "-"), str(n.get("status")),
+             _money(n.get("price_per_hour"))) for n in nodes], not no_headers))
+
+
+def _rotation_text(r: Dict[str, Any]) -> str:
+    steps = r.get("steps") or {}
+    out = f"Rotation {r.get('id')}: {r.get('status')}"
+    if r.get("message"):
+        out += f" ({r['message']})"
+    done = ", ".join(f"{k} {v}" for k, v in steps.items())
+    return out + (f"\nSteps: {done}" if done else "")
+
+
+def _rotation(ctx, pool_ref, method, as_json):
+    def go(org):
+        return _call(org, method, f"/pools/{resolve(org, pool_ref)}/rotate-credentials", ADMIN)
+    data = _run(ctx, go)
+    if as_json:
+        return _dump(data)
+    click.echo(_rotation_text(data))
+
+
+@pool.command(name="rotate-credentials")
+@click.argument("pool_ref", metavar="POOL")
+@click.option("--status", "only_status", is_flag=True, hidden=True,
+              help="Deprecated: use 'mctl pool rotation-status POOL'")
+@json_option
+@click.pass_context
+def rotate_credentials(ctx, pool_ref, only_status, as_json):
+    """Start a rotation of the pool's credentials. To see its progress, use: mctl pool rotation-status."""
+    if only_status:
+        click.echo(f"Note: --status is deprecated. Use: mctl pool rotation-status {pool_ref}", err=True)
+    _rotation(ctx, pool_ref, "GET" if only_status else "POST", as_json)
+    if not only_status and not as_json:
+        click.echo(f"Check progress with: mctl pool rotation-status {pool_ref}")
+
+
+@pool.command(name="rotation-status")
+@click.argument("pool_ref", metavar="POOL")
+@json_option
+@click.pass_context
+def rotation_status(ctx, pool_ref, as_json):
+    """Show the latest rotation of the pool's credentials."""
+    _rotation(ctx, pool_ref, "GET", as_json)