rostainer-deploy 0.0.3__py3-none-any.whl

rostainer_deploy/__init__.py

@@ -0,0 +1,534 @@
+"""Deploy: push package updates to robots over ssh, through a local registry.
+
+``rostainer deploy push`` sends the newest package (``rostainer package
+create``) to the workspace's targets - robots, listed in
+``[plugins.deploy.targets.<name>]`` and picked by name or by group
+(``[plugins.deploy.groups]``) - several at a time:
+
+1. the package's image goes into a registry on this machine
+   (``rostainer deploy registry``), which keeps every layer it has seen;
+2. each target pulls it through an ssh reverse tunnel, downloading only
+   the layers it doesn't have - after a code change, typically just the
+   workspace's build;
+3. the bundle's small files (settings, Compose files, the scripts) are
+   copied over the same ssh connection, and its ``./rostainer install`` installs
+   them into the target's install directory and restarts the container,
+   keeping the package it replaces for ``rostainer deploy rollback``.
+
+No image tar is copied or loaded. See :mod:`rostainer_deploy.remote` for
+what runs where.
+"""
+
+from __future__ import annotations
+
+import argparse
+import difflib
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Sequence
+
+from pydantic import Field, field_validator, model_validator
+from typing_extensions import Literal
+
+from rostainer_cli.plugin_api import (
+    Command,
+    ConfigError,
+    Context,
+    Plugin,
+    PluginConfig,
+    image_id,
+    log,
+)
+from rostainer_deploy import remote
+from rostainer_deploy.remote import Destination
+
+#: What a target's or group's name may look like: it's typed on the
+#: command line.
+TARGET_NAME = re.compile(r"[A-Za-z0-9][A-Za-z0-9_.-]*")
+
+#: The selector meaning every enabled target; no target or group has it.
+ALL = "all"
+
+
+class TargetConfig(PluginConfig):
+    """One ``[plugins.deploy.targets.<name>]`` table: a robot."""
+
+    host: str = Field(description="Host name, IP address, or a Host alias from ~/.ssh/config.")
+    user: str = Field("", description="ssh user (default: ssh's, e.g. from ~/.ssh/config).")
+    port: Optional[int] = Field(None, ge=1, le=65535, description="ssh port (default: ssh's).")
+    install_dir: str = Field(
+        "", description="Where the package is installed there (default: [plugins.deploy] install_dir)."
+    )
+    enabled: bool = Field(
+        True,
+        description="false: left out of 'all' and of its groups; deployed to only when named.",
+    )
+    ssh_options: List[str] = Field(
+        default_factory=list,
+        description="More ssh options for this target, before [plugins.deploy] ssh_options.",
+    )
+
+
+class DeployConfig(PluginConfig):
+    """The ``[plugins.deploy]`` table."""
+
+    install_dir: str = Field(
+        "rostainer/{workspace}",
+        description=(
+            "Where packages are installed on a target: relative to the ssh user's home,\n"
+            "or absolute. {workspace} is this workspace's directory name."
+        ),
+    )
+    enable: Literal["docker", "user_systemd", "system_systemd", "none"] = Field(
+        "docker",
+        description=(
+            "How a target starts the package at boot: docker (Docker's restart policy),\n"
+            "user_systemd (a systemd user unit: needs 'loginctl enable-linger' for the\n"
+            "ssh user), system_systemd (a system unit: needs passwordless sudo), or none."
+        ),
+    )
+    parallel: int = Field(4, ge=1, description="How many targets a push or status reaches at once.")
+    registry_port: int = Field(
+        5000, ge=1, le=65535, description="The local registry's port, on this machine's localhost."
+    )
+    tunnel_port: int = Field(
+        5000, ge=1, le=65535, description="The port targets reach it on, through ssh, on their localhost."
+    )
+    registry_image: str = Field(
+        "registry:2",
+        description="The registry's image: pull it once while online, for offline use.",
+    )
+    ssh_options: List[str] = Field(
+        default_factory=list,
+        description='More ssh options for every target, e.g. ["-J", "gateway"] for a jump host.',
+    )
+    connect_timeout: int = Field(
+        15, ge=1, description="Seconds to wait for a target's ssh connection."
+    )
+    connect_attempts: int = Field(
+        3,
+        ge=1,
+        description=(
+            "How many times to try connecting to a target (counting the first) before\n"
+            "giving up on it. Only connecting is retried, never a step that may have\n"
+            "changed the target; nor a refused login or host key."
+        ),
+    )
+    connect_retry_delay: int = Field(
+        10, ge=0, description="Seconds between those attempts."
+    )
+    accept_new_host_keys: bool = Field(
+        False,
+        description=(
+            "true: trust a target's host key the first time it's seen, rather than\n"
+            "failing until it's in ~/.ssh/known_hosts. A key that changed is still refused."
+        ),
+    )
+
+    verify_settle: int = Field(
+        20,
+        ge=0,
+        description=(
+            "After a push, each target is checked to come up: it keeps running this many\n"
+            "seconds, and its runtime_healthcheck (if any) passes. 0: don't check."
+        ),
+    )
+    rollback_on_failure: bool = Field(
+        True,
+        description=(
+            "Go back to the package a target ran before when the pushed one doesn't\n"
+            "come up (push --no-rollback: leave it, to look into)."
+        ),
+    )
+    prune_images: bool = Field(
+        True,
+        description=(
+            "After a push, remove the images of the packages installed in the target's\n"
+            "install_dir before, keeping the one before the new one, for a rollback."
+        ),
+    )
+
+    groups: Dict[str, List[str]] = Field(
+        default_factory=dict,
+        description=(
+            "Named groups of targets, to deploy to together, after the settings above:\n"
+            "  [plugins.deploy.groups]\n"
+            '  robots = ["robot1", "robot2"]'
+        ),
+    )
+    targets: Dict[str, TargetConfig] = Field(
+        default_factory=dict,
+        description=(
+            "The robots to deploy to, one table each, after the settings above:\n"
+            "  [plugins.deploy.targets.robot1]\n"
+            '  host = "10.0.0.5"   # or a ~/.ssh/config alias\n'
+            '  user = "ros"        # optional, as are port, install_dir, enabled, ssh_options'
+        ),
+    )
+
+    @field_validator("targets", "groups")
+    @classmethod
+    def _names(cls, value: Dict[str, Any]) -> Dict[str, Any]:
+        for name in value:
+            if not TARGET_NAME.fullmatch(name):
+                raise ValueError(f"{name!r} isn't a valid name (letters, digits, '.', '_', '-')")
+            if name == ALL:
+                raise ValueError(f"'{ALL}' is reserved: it selects every enabled target")
+        return value
+
+    @model_validator(mode="after")
+    def _group_members(self) -> "DeployConfig":
+        for group, members in self.groups.items():
+            if group in self.targets:
+                raise ValueError(f"group '{group}' has the name of a target: rename one of them")
+            unknown = [member for member in members if member not in self.targets]
+            if unknown:
+                raise ValueError(
+                    f"group '{group}': no target named "
+                    + ", ".join(_with_suggestion(name, self.targets) for name in unknown)
+                )
+        return self
+
+
+def _with_suggestion(name: str, known: Sequence[str]) -> str:
+    """``'name'``, and the closest of ``known`` if it looks like a typo."""
+    close = difflib.get_close_matches(name, list(known), n=1)
+    return f"'{name}'" + (f" (did you mean '{close[0]}'?)" if close else "")
+
+
+def select(settings: DeployConfig, selectors: Sequence[str]) -> List[str]:
+    """The targets ``selectors`` pick, by name, in the order they're listed.
+
+    A selector is a target, a group, or ``all``; none means ``all``. ``all``
+    and groups leave out targets with ``enabled = false``; a target named
+    itself is in, enabled or not. Each target is in once.
+
+    Raises:
+        ConfigError: If a selector is none of those, or none are left.
+    """
+    groups, targets = settings.groups, settings.targets
+    unknown = [s for s in selectors if s != ALL and s not in targets and s not in groups]
+    if unknown:
+        known = [*targets, *groups, ALL]
+        raise ConfigError(
+            "No deploy target or group named "
+            + ", ".join(_with_suggestion(name, known) for name in unknown)
+            + f" (targets: {', '.join(targets)}"
+            + (f"; groups: {', '.join(groups)})" if groups else ")")
+        )
+    picked = set()
+    for selector in selectors or [ALL]:
+        if selector == ALL:
+            picked.update(name for name, target in targets.items() if target.enabled)
+        elif selector in groups:
+            picked.update(name for name in groups[selector] if targets[name].enabled)
+        else:
+            picked.add(selector)
+    if not picked:
+        raise ConfigError(
+            f"No enabled targets in {' '.join(selectors) or ALL}: those with "
+            "'enabled = false' are only deployed to when named."
+        )
+    return [name for name in targets if name in picked]
+
+
+def destinations(ctx: Context, selectors: Sequence[str] = ()) -> List[Destination]:
+    """The targets ``selectors`` pick (see :func:`select`), ready to reach.
+
+    Raises:
+        ConfigError: If there are no targets, or see :func:`select`.
+    """
+    settings: DeployConfig = ctx.config
+    if not settings.targets:
+        raise ConfigError(
+            f"No deploy targets in {ctx.cfg.config_file}. Add one, e.g.:\n"
+            "  [plugins.deploy.targets.robot1]\n"
+            '  host = "10.0.0.5"'
+        )
+    names = select(settings, selectors)
+    connect = [
+        "-o",
+        f"ConnectTimeout={settings.connect_timeout}",
+        # A link that dies mid-push fails the push in a minute, not never.
+        "-o",
+        "ServerAliveInterval=15",
+        "-o",
+        "ServerAliveCountMax=4",
+    ]
+    if settings.accept_new_host_keys:
+        connect += ["-o", "StrictHostKeyChecking=accept-new"]
+    workspace = re.sub(r"[^A-Za-z0-9_.-]+", "_", ctx.cfg.workspace_root.name) or "workspace"
+    return [
+        Destination(
+            name=name,
+            host=target.host,
+            user=target.user,
+            port=target.port,
+            install_dir=(target.install_dir or settings.install_dir).replace("{workspace}", workspace),
+            # ssh takes an option's first value: the target's own win.
+            ssh_options=(*target.ssh_options, *settings.ssh_options, *connect),
+            # Per workspace, so two workspaces' packages on one target don't
+            # share (and replace each other's) systemd unit.
+            service=f"rostainer-{workspace}",
+            attempts=settings.connect_attempts,
+            retry_delay=settings.connect_retry_delay,
+        )
+        for name, target in ((name, settings.targets[name]) for name in names)
+    ]
+
+
+def bundle_for(ctx: Context, version: Optional[str]) -> Path:
+    """The package bundle to deploy: ``version``'s, else the newest.
+
+    Raises:
+        ConfigError: If there's none (with how to make one).
+    """
+    from rostainer_package import create
+
+    bundles = create.package_bundles(ctx.plugin_context("package"))
+    if version is not None:
+        bundles = [bundle for bundle in bundles if bundle.name == version]
+        if not bundles:
+            raise ConfigError(f"No package '{version}' in builds/package/.")
+    if not bundles:
+        raise ConfigError("No package to deploy yet: 'rostainer package create' makes one.")
+    return bundles[0]
+
+
+def bundle_image(bundle: Path) -> str:
+    """The image a bundle runs (from its ``manifest/image.json``)."""
+    try:
+        return json.loads((bundle / "manifest" / "image.json").read_text())["image"]
+    except (OSError, ValueError, KeyError) as error:
+        raise ConfigError(f"'{bundle}' isn't a package bundle: no manifest/image.json") from error
+
+
+class DeployCommand(Command):
+    """``rostainer deploy <push|setup|status|rollback|registry>``."""
+
+    name = "deploy"
+    summary = "Push package updates to robots over ssh, through a local registry"
+
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        actions = parser.add_subparsers(dest="action", metavar="ACTION")
+        actions.required = True
+        push = actions.add_parser(
+            "push", help="Send a package to targets: only the image layers they don't have"
+        )
+        push.add_argument(
+            "--version", help="The package to send (default: the newest in builds/package/)"
+        )
+        push.add_argument(
+            "--no-rollback",
+            action="store_true",
+            help="Leave a package that doesn't come up in place (rollback_on_failure)",
+        )
+        self._selectors(push)
+        setup = actions.add_parser(
+            "setup",
+            help=(
+                "Check targets have what deploying needs (key login, Docker, Python 3), "
+                "offering to copy your ssh key, then push"
+            ),
+        )
+        setup.add_argument("--version", help="The package to send (default: the newest)")
+        self._selectors(setup)
+        status = actions.add_parser("status", help="What each target runs, and whether it's up")
+        self._selectors(status)
+        rollback = actions.add_parser(
+            "rollback", help="Go back to the package a target ran before (again: forward)"
+        )
+        self._selectors(rollback, required=True)
+        registry = actions.add_parser("registry", help="The local registry pushes go through")
+        registry.add_argument("registry_action", choices=("start", "stop", "status"))
+
+    @staticmethod
+    def _selectors(parser: argparse.ArgumentParser, required: bool = False) -> None:
+        from rostainer_deploy import api
+
+        api.add_target_arguments(parser, required=required)
+
+    def run(self, args: argparse.Namespace, ctx: Optional[Context]) -> int:
+        assert ctx is not None
+        settings: DeployConfig = ctx.config
+        if args.action == "registry":
+            return registry(settings, args.registry_action)
+        targets = destinations(ctx, args.targets)
+        if args.action == "status":
+            return status(settings, targets)
+        if args.action == "rollback":
+            return rollback(settings, targets)
+        if args.action == "setup" and check(targets, settings.parallel) != 0:
+            return 1
+        rollback_on_failure = settings.rollback_on_failure and not getattr(args, "no_rollback", False)
+        return push(ctx, settings, targets, args.version, rollback_on_failure=rollback_on_failure)
+
+
+def registry(settings: DeployConfig, action: str) -> int:
+    """``rostainer deploy registry start|stop|status``."""
+    if action == "start":
+        if not remote.start_registry(settings.registry_image, settings.registry_port):
+            return 1
+        log.ok(f"The registry is running on localhost:{settings.registry_port}.")
+        return 0
+    if action == "stop":
+        return 0 if remote.stop_registry() else 1
+    state = remote.registry_state()
+    if state == "running":
+        log.ok(f"The registry is running on localhost:{settings.registry_port}.")
+        return 0
+    log.info(f"The registry is {state or 'not created'}: 'rostainer deploy registry start'.")
+    return 1
+
+
+def check(targets: List[Destination], parallel: int = 4) -> int:
+    """Check each target has what a push needs, first offering to copy
+    the user's ssh key to those that refuse key-based login."""
+    log.header(f"Checking {', '.join(target.name for target in targets)}...")
+    refused: List[Destination] = []
+
+    def probe(target: Destination) -> remote.Outcome:
+        outcome = run_over_connection(target, remote.check_script())
+        if outcome.returncode == remote.LOGIN_REFUSED:
+            refused.append(target)
+        return outcome
+
+    outcomes = {o.name: o for o in remote.run_on_all(targets, probe, parallel, "Checking")}
+    if refused and not sys.stdin.isatty():
+        log.error(
+            "Key-based login was refused by "
+            + ", ".join(target.name for target in refused)
+            + ": run 'rostainer deploy setup' in a terminal to copy your key, or "
+            "'ssh-copy-id' yourself."
+        )
+    elif refused:
+        # One at a time: each asks for its password.
+        for target in sorted(refused, key=targets.index):
+            log.info(f"Copying your ssh key to {target.name} (ssh-copy-id asks for its password)...")
+            if remote.copy_id(target) == 0:
+                outcomes[target.name] = run_over_connection(target, remote.check_script())
+    return remote.report([outcomes[target.name] for target in targets], "The check")
+
+
+def run_over_connection(
+    target: Destination, script: str, *, stdin: bytes = b"", forward: Sequence[str] = ()
+) -> remote.Outcome:
+    """Run ``script`` on ``target`` over a :func:`remote.connection`, with
+    its retries; a connection that fails is that target's failure."""
+    try:
+        with remote.connection(target, forward=forward) as via:
+            return remote.run_on(target, script, stdin=stdin, ssh_extra=via)
+    except remote.ConnectError as error:
+        remote.say(target.name, str(error))
+        return remote.Outcome(target.name, remote.LOGIN_REFUSED if error.refused else 255)
+
+
+def unsupported_options(bundle: Path, options: List[str]) -> List[str]:
+    """Those of ``options`` the bundle's ``./rostainer install`` doesn't
+    take: a package created by an older rostainer."""
+    script = (bundle / "rostainer").read_text(errors="replace")
+    return [option for option in options if f'"{option}"' not in script]
+
+
+def runs_as_the_targets_user(bundle: Path) -> bool:
+    """Whether the bundle's container takes the IDs of the user installing
+    it, rather than those of the machine it was made on."""
+    return "installing_user_ids" in (bundle / "rostainer").read_text(errors="replace")
+
+
+def push(
+    ctx: Context,
+    settings: DeployConfig,
+    targets: List[Destination],
+    version: Optional[str],
+    *,
+    rollback_on_failure: bool = True,
+) -> int:
+    """Send a package to the targets, check each comes up (going back to
+    the package it ran before if not, with ``rollback_on_failure``), and
+    remove their older images of it."""
+    bundle = bundle_for(ctx, version)
+    image = bundle_image(bundle)
+    if not image_id(image):
+        log.error(
+            f"The package's image '{image}' isn't on this machine (pruned?): "
+            f"'docker load -i' its tar in '{bundle}', or 'rostainer package create' again."
+        )
+        return 1
+    options = []
+    if settings.verify_settle > 0:
+        options += ["--verify", "--settle"] + (["--rollback-on-failure"] if rollback_on_failure else [])
+    if settings.prune_images:
+        options.append("--prune")
+    unsupported = unsupported_options(bundle, options)
+    if unsupported:
+        log.error(
+            f"Package '{bundle.name}' was created by an older rostainer: its './rostainer install' "
+            f"doesn't take {', '.join(unsupported)}. Run 'rostainer package create' again."
+        )
+        return 1
+    if not runs_as_the_targets_user(bundle):
+        log.warning(
+            f"Package '{bundle.name}' was created by an older rostainer: its container runs "
+            "with the user and group IDs of the machine it was made on, not the robots' "
+            "users'. Run 'rostainer package create' again for theirs."
+        )
+    log.header(f"Deploying package '{bundle.name}' ({image})...")
+    if not remote.start_registry(settings.registry_image, settings.registry_port):
+        return 1
+    if not remote.push_to_registry(image, settings.registry_port):
+        return 1
+    archive = remote.bundle_archive(bundle)
+
+    def install(target: Destination) -> remote.Outcome:
+        script = remote.install_script(
+            image,
+            settings.tunnel_port,
+            target.install_dir,
+            settings.enable,
+            target.service,
+            verify_settle=settings.verify_settle,
+            rollback_on_failure=rollback_on_failure,
+            prune=settings.prune_images,
+        )
+        forward = remote.forward(settings.tunnel_port, settings.registry_port)
+        return run_over_connection(target, script, stdin=archive, forward=forward)
+
+    outcomes = remote.run_on_all(targets, install, settings.parallel, f"Deploying '{bundle.name}'")
+    return remote.report(outcomes, f"Deploying '{bundle.name}'")
+
+
+def status(settings: DeployConfig, targets: List[Destination]) -> int:
+    """What each target runs."""
+    outcomes = remote.run_on_all(
+        targets,
+        lambda target: run_over_connection(target, remote.manage_script(target.install_dir, "status")),
+        settings.parallel,
+    )
+    return remote.report(outcomes, "Status")
+
+
+def rollback(settings: DeployConfig, targets: List[Destination]) -> int:
+    """Go back to the package each target ran before."""
+    outcomes = remote.run_on_all(
+        targets,
+        lambda target: run_over_connection(target, remote.manage_script(target.install_dir, "rollback")),
+        settings.parallel,
+        "Rolling back",
+    )
+    return remote.report(outcomes, "Rollback")
+
+
+class DeployPlugin(Plugin):
+    """Push package updates to robots."""
+
+    name = "deploy"
+    api_version = 1
+    summary = "Push package updates to robots over ssh, through a local registry"
+    config_model = DeployConfig
+    requires = ("package",)
+
+    def commands(self) -> Sequence[Command]:
+        return [DeployCommand()]