portainer-redeploy-cli 0.1.0__py3-none-any.whl

portainer_redeploy_cli/__main__.py

@@ -0,0 +1,972 @@
+"""Redeploy a Portainer stack.
+The tool first checks that the new version exists. Then it watches the rollout.
+
+Usage:
+    redeploy [options] [INSTANCE] STACK [VERSION]
+    portainer-redeploy [options] [INSTANCE] STACK [VERSION]
+
+The config file is ~/.config/portainer-redeploy.json.
+To use a different file, set $PORTAINER_REDEPLOY_CONFIG to its path.
+
+In the config file, map each instance name to its URL and API key:
+    {
+        "prod": {
+            "url": "https://portainer.example.com",
+            "api_key_file": "/run/secrets/portainer_prod"
+        }
+    }
+
+Give each value inline ("url", "api_key") or in a file ("url_file", "api_key_file").
+{"insecure": true} skips TLS certificate verification.
+{"tag_var": "APP_VERSION"} changes the stack variable that the tool sets to VERSION.
+The default variable is IMAGE_TAG.
+
+Environment variables can also configure a single instance, but you cannot give it a name.
+Environment variables:
+    PORTAINER_URL       Portainer base URL.
+    PORTAINER_API_KEY   API key (Portainer > My account > Access tokens).
+    PORTAINER_INSECURE  Set to 1 to skip TLS certificate verification.
+    PORTAINER_TAG_VAR   Stack variable that the tool sets to VERSION (default: IMAGE_TAG).
+"""
+
+import argparse
+import base64
+import contextlib
+import difflib
+import json
+import os
+import re
+import signal
+import ssl
+import sys
+import threading
+import time
+from collections import Counter, namedtuple
+
+import httpx
+import yaml
+from expandvars import ExpandvarsException, expand
+from rich.console import Console, Group
+from rich.live import Live
+from rich.padding import Padding
+from rich.progress_bar import ProgressBar
+from rich.spinner import Spinner
+from rich.table import Table
+from rich.text import Text
+
+from . import __version__
+
+# ── config ────────────────────────────────────────────────────────────────────
+
+CONFIG = os.environ.get("PORTAINER_REDEPLOY_CONFIG") or os.path.join(
+    os.environ.get("XDG_CONFIG_HOME") or os.path.expanduser("~/.config"),
+    "portainer-redeploy.json",
+)
+HOME = os.path.expanduser("~")
+CONFIG_SHOWN = "~" + CONFIG[len(HOME) :] if CONFIG.startswith(HOME + os.sep) else CONFIG
+EXAMPLE = '{ "prod": { "url": "https://portainer.example.com", "api_key_file": "/run/secrets/portainer" } }'
+DEFAULT_TAG_VAR = "IMAGE_TAG"
+SETUP_HINT = f"Set PORTAINER_URL and PORTAINER_API_KEY, or describe your instances in {CONFIG_SHOWN}. For example:\n  {EXAMPLE}"
+
+POLL_INTERVAL = 2  # seconds between looks at the stack's containers
+STABLE_POLLS = 4  # looks in a row without changes for the rollout to count as settled
+MIN_WATCH = 10  # seconds to watch after the deploy is done (swarm rolls out lazily)
+
+# Stack.Status values. "Deploying" and "error" only exist since Portainer 2.36,
+# which deploys in the background instead of answering once it's done.
+DEPLOYING, DEPLOY_ERROR = 3, 4
+
+Instance = namedtuple("Instance", "name url api_key insecure tag_var")
+Row = namedtuple("Row", "kind service replaced total running label")
+
+# ── helpers ───────────────────────────────────────────────────────────────────
+
+
+def die(msg):
+    error = Text.assemble(("Error:", "red"), f" {msg}")
+    Console(stderr=True).print(error, soft_wrap=True)
+    sys.exit(1)
+
+
+def fmt_dur(s):
+    s = int(s)
+    return f"{s // 60}m {s % 60:02d}s" if s >= 60 else f"{s}s"
+
+
+def join_names(names, word="and"):
+    *rest, last = names
+    return f"{', '.join(rest)} {word} {last}" if rest else last
+
+
+class Failure(Exception):
+    """Ends the run with a ✗ line, and any details under it."""
+
+    def __init__(self, msg, details="", status=0):
+        super().__init__(msg)
+        self.details, self.status = details, status
+
+
+class ApiError(Failure):
+    """A Portainer API call that failed; status is the HTTP one, or 0 without an answer."""
+
+
+class Job(threading.Thread):
+    """Runs fn(*args) in the background, keeping what it raises in error. On a daemon
+    thread, which - unlike an executor's - Ctrl-C needn't wait for."""
+
+    def __init__(self, fn, *args, **kwargs):
+        super().__init__(target=fn, args=args, kwargs=kwargs, daemon=True)
+        self.error = None
+        self.start()
+
+    def run(self):
+        try:
+            super().run()
+        except Exception as e:
+            self.error = e
+
+
+# ── setup ─────────────────────────────────────────────────────────────────────
+
+
+def load_config():
+    try:
+        with open(CONFIG) as f:
+            config = json.load(f)
+    except FileNotFoundError:
+        return {}
+    except (OSError, ValueError) as e:
+        die(f"Cannot read {CONFIG}: {e}")
+    valid = isinstance(config, dict) and all(
+        isinstance(v, dict) for v in config.values()
+    )
+    if not valid:
+        die(
+            f"{CONFIG} should map each instance name to its settings. For example:\n  {EXAMPLE}"
+        )
+    return config
+
+
+def setting(entry, key, instance):
+    """A config value, given inline ("api_key") or as a file to read it from ("api_key_file")."""
+    path = entry.get(f"{key}_file")
+    if entry.get(key) or not path:
+        return str(entry.get(key) or "").strip()
+    try:
+        with open(os.path.expanduser(path)) as f:
+            return f.read().strip()
+    except OSError as e:
+        die(f'Cannot read the {key} of instance "{instance}" from {path}: {e.strerror}')
+
+
+def base_url(url):
+    url = url.strip().rstrip("/")
+    url = url if "://" in url else f"https://{url}"
+    try:
+        httpx.URL(url)
+    except httpx.InvalidURL as e:
+        die(f"{url} is not a valid URL ({e})")
+    return url
+
+
+def resolve_instance(name, config, insecure):
+    if name is None and os.environ.get("PORTAINER_URL"):
+        url = base_url(os.environ["PORTAINER_URL"])
+        key = os.environ.get("PORTAINER_API_KEY", "").strip()
+        if not key:
+            die("PORTAINER_URL is set, but PORTAINER_API_KEY is not set.")
+        on = os.environ.get("PORTAINER_INSECURE", "").lower() not in (
+            "",
+            "0",
+            "false",
+            "no",
+        )
+        tag_var = os.environ.get("PORTAINER_TAG_VAR", "").strip() or DEFAULT_TAG_VAR
+        return Instance(httpx.URL(url).host or url, url, key, insecure or on, tag_var)
+    known = ", ".join(sorted(config))
+    if name is None and not config:
+        die(f"No Portainer instance is configured.\n{SETUP_HINT}")
+    if name is None and len(config) > 1:
+        die(
+            f"More than one Portainer instance is configured. Give one of these instance names: {known}."
+        )
+    name = next(iter(config)) if name is None else name
+    if name not in config and not config:
+        die(f'Unknown instance "{name}". There is no {CONFIG_SHOWN}.\n{SETUP_HINT}')
+    if name not in config:
+        die(f'Unknown instance "{name}". Known instances: {known}.')
+    entry = config[name]
+    url, key = setting(entry, "url", name), setting(entry, "api_key", name)
+    if not url or not key:
+        die(
+            f'Instance "{name}" in {CONFIG_SHOWN} needs a "url" (or "url_file") and an "api_key" (or "api_key_file").'
+        )
+    tag_var = entry.get("tag_var") or DEFAULT_TAG_VAR
+    if not isinstance(tag_var, str):
+        die(
+            f'The "tag_var" of instance "{name}" in {CONFIG_SHOWN} must be a variable name in quotes, for example "IMAGE_TAG".'
+        )
+    return Instance(
+        name, base_url(url), key, insecure or bool(entry.get("insecure")), tag_var
+    )
+
+
+# ── portainer api ─────────────────────────────────────────────────────────────
+
+
+def unreachable(url, error):
+    if isinstance(error, httpx.TimeoutException):
+        return f"{url} did not answer in time"
+    while error.__context__:  # down to the socket or TLS error under httpx's
+        error = error.__context__
+    if isinstance(error, ssl.SSLCertVerificationError):
+        return (
+            f"the TLS certificate of {url} is not trusted ({error.verify_message}) - "
+            f'fix the certificate, or skip the check with -k or "insecure": true'
+        )
+    return f"could not reach {url} ({getattr(error, 'strerror', None) or error})"
+
+
+def http_error(resp, url):
+    try:
+        body = dict(resp.json())
+    except (ValueError, TypeError):
+        body = {}
+    status = f"HTTP {resp.status_code} {resp.reason_phrase}".strip()
+    msg = str(body.get("message") or body.get("error") or status)
+    details = str(body.get("details") or "")
+    if resp.status_code == 401:
+        msg = f"Portainer rejected the API key ({msg})"
+    elif resp.is_redirect:
+        # httpx doesn't follow redirects, which keeps the API key from going along.
+        target = str(resp.url.join(resp.headers["Location"]))
+        target = re.sub(r"/api(/.*)?$", "", target)
+        msg = f"{url} redirects to {target} - use {target} as the instance URL"
+    return ApiError(msg, "" if details == msg else details, resp.status_code)
+
+
+class Portainer:
+    def __init__(self, instance):
+        self.url = instance.url
+        self.http = httpx.Client(
+            base_url=f"{instance.url}/api",
+            headers={"X-API-Key": instance.api_key},
+            # The system's CA certificates rather than httpx's own, so private CAs work.
+            verify=False if instance.insecure else ssl.create_default_context(),
+            timeout=30,
+        )
+
+    @contextlib.contextmanager
+    def stream(self, method, path, **kwargs):
+        """Send a request to /api<path>; yields the response, unread."""
+        try:
+            with self.http.stream(method, path, **kwargs) as resp:
+                if not resp.is_success:
+                    resp.read()
+                    raise http_error(resp, self.url)
+                yield resp
+        except httpx.HTTPError as e:
+            raise ApiError(unreachable(self.url, e)) from None
+
+    def request(self, method, path, **kwargs):
+        """Call /api<path> and return the JSON reply."""
+        with self.stream(method, path, **kwargs) as resp:
+            data = resp.read()
+        try:
+            return json.loads(data) if data.strip() else None
+        except ValueError:
+            raise ApiError(
+                f"{self.url} sent a reply that is not JSON - check that this is the Portainer URL"
+            ) from None
+
+    def get(self, path):
+        return self.request("GET", path)
+
+
+# ── stack file ────────────────────────────────────────────────────────────────
+
+
+class ComposeLoader(yaml.SafeLoader):
+    """SafeLoader that also takes compose's own tags (!reset, !override)."""
+
+
+def _construct_tagged(loader, suffix, node):
+    if isinstance(node, yaml.MappingNode):
+        return loader.construct_mapping(node, deep=True)
+    if isinstance(node, yaml.SequenceNode):
+        return loader.construct_sequence(node, deep=True)
+    return loader.construct_scalar(node)
+
+
+ComposeLoader.add_multi_constructor("!", _construct_tagged)
+
+
+def tagged_images(stack_file, env, tag_var):
+    """The images in the stack file that use tag_var, with every variable filled in from
+    the stack env (anchors and merge keys resolved, so tags like "${IMAGE_TAG}-nginx" work).
+    """
+    try:
+        services = (yaml.load(stack_file, Loader=ComposeLoader) or {}).get("services")
+    except yaml.YAMLError as e:
+        raise Failure("Could not parse the stack file", str(e)) from None
+    uses_var, refs = re.compile(r"\$\{?" + re.escape(tag_var) + r"\b"), set()
+    for service in (services or {}).values():
+        image = (service or {}).get("image")
+        if isinstance(image, str) and uses_var.search(image):
+            try:
+                ref = expand(image, environ=env)
+            except ExpandvarsException as e:
+                raise Failure(
+                    f"Could not expand the variables in image {image}", str(e)
+                ) from None
+            # Untagged means :latest to compose, but to the pull API it means every tag.
+            tagged = "@" in ref or ":" in ref.rsplit("/", 1)[-1]
+            refs.add(ref if tagged else f"{ref}:latest")
+    return sorted(refs)
+
+
+# ── images ────────────────────────────────────────────────────────────────────
+
+DOCKER_HUB = (
+    "docker.io",
+    "index.docker.io",
+    "registry-1.docker.io",
+    "registry.hub.docker.com",
+)
+LAYER_DONE = ("Pull complete", "Already exists")
+
+
+def repository(ref):
+    """Where an image lives, as registry host/path - short names are on Docker Hub."""
+    repo = re.sub(r":[^:/]*$", "", ref.split("@")[0])
+    first, _, rest = repo.partition("/")
+    if not rest:
+        return f"docker.io/library/{repo}"
+    if first in DOCKER_HUB:
+        return f"docker.io/{rest}"
+    if "." not in first and ":" not in first and first != "localhost":
+        return f"docker.io/{repo}"
+    return repo
+
+
+def registry_for(ref, registries):
+    """Id of the Portainer registry whose credentials should pull ref: the longest matching
+    URL prefix wins, where a GitLab registry's own prefix includes its project path (it can
+    still match on just its host, but loses ties to a registry whose own URL that is).
+    """
+    repo, best = repository(ref), ((0, False), None)
+    for reg in registries:
+        url = re.sub(r"^[a-z]+://", "", reg.get("URL") or "").rstrip("/")
+        host, _, path = url.partition("/")
+        if host in DOCKER_HUB:
+            url = "/".join(filter(None, ("docker.io", path)))
+        project = (reg.get("Gitlab") or {}).get("ProjectPath")
+        own = f"{url}/{project}" if project else url
+        for key in {own, url} if reg.get("Authentication") else ():
+            rank = (len(key), key == own)
+            if key and (repo == key or repo.startswith(key + "/")) and rank > best[0]:
+                best = (rank, reg.get("Id"))
+    return best[1]
+
+
+def pull(api, endpoint_id, ref, registry_id, layers):
+    """Pull ref onto the environment through Portainer's Docker API, keeping each layer's
+    latest (status, progressDetail) in layers as the progress streams in. Returns Docker's
+    closing status ("Downloaded newer image", ...); raises ApiError when the pull fails.
+    """
+    # Portainer swaps a registryId for the credentials it has stored for that registry -
+    # the same ones it deploys the stack with - so private registries work without this
+    # tool knowing any registry passwords.
+    auth = base64.b64encode(json.dumps({"registryId": registry_id}).encode()).decode()
+    headers = {} if registry_id is None else {"X-Registry-Auth": auth}
+    path, final = f"/endpoints/{endpoint_id}/docker/images/create", None
+    query = {"fromImage": ref}
+    with api.stream("POST", path, params=query, headers=headers, timeout=300) as resp:
+        try:
+            for line in resp.iter_lines():
+                msg = json.loads(line) if line.strip() else {}
+                error = msg.get("error") or msg.get("errorDetail", {}).get("message")
+                if error:
+                    raise ApiError(" ".join(str(error).split()))
+                status = msg.get("status") or ""
+                if msg.get("id") and "progressDetail" in msg:
+                    layers[msg["id"]] = (status, msg["progressDetail"] or {})
+                elif status.startswith("Status: "):
+                    final = re.sub(r" for .*$", "", status[len("Status: ") :])
+        except (httpx.HTTPError, ValueError) as e:
+            raise ApiError(f"the pull stopped before it completed ({e})") from None
+    if not final:  # only Docker's closing status counts, so a cut-off stream can't pass
+        raise ApiError("the pull ended, but Docker did not report success")
+    return final
+
+
+def pull_progress(layers):
+    """How far along a pull is, 0-1: downloading counts for 80 % of a layer, extracting the rest."""
+    done = 0
+    for status, detail in layers:
+        total = detail.get("total")
+        part = min((detail.get("current") or 0) / total, 1) if total else 0
+        if status in LAYER_DONE:
+            done += 1
+        elif status == "Downloading":
+            done += 0.8 * part
+        elif status in ("Download complete", "Verifying Checksum"):
+            done += 0.8
+        elif status == "Extracting":
+            done += 0.8 + 0.2 * part
+    return done / len(layers) if layers else 0
+
+
+# ── containers ────────────────────────────────────────────────────────────────
+
+
+def stack_containers(api, endpoint_id, stack_name):
+    """The stack's containers, with their service: compose labels them with the project,
+    swarm with the stack namespace (and prefixes its service names with "<stack>_")."""
+    name, found = stack_name.lower(), []
+    for c in api.get(f"/endpoints/{endpoint_id}/docker/containers/json?all=true"):
+        labels = c.get("Labels") or {}
+        if labels.get("com.docker.compose.project", "").lower() == name:
+            service = labels.get("com.docker.compose.service")
+        elif labels.get("com.docker.stack.namespace", "").lower() == name:
+            service = labels.get("com.docker.swarm.service.name") or ""
+            if service.lower().startswith(name + "_"):
+                service = service[len(name) + 1 :]
+        else:
+            continue
+        found.append({**c, "service": service or c["Names"][0].lstrip("/")})
+    return found
+
+
+def classify(c, new, swarm):
+    """(kind, label) for a container - or None to leave it out, as swarm keeps the
+    containers of replaced tasks around (exited) for history."""
+    state, status = c["State"], c["Status"]
+    if state == "running":
+        if "(unhealthy)" in status:
+            return "fail", "unhealthy"
+        if "(health: starting)" in status:
+            return "busy", "starting"
+        return "ok", "healthy" if "(healthy)" in status else "running"
+    if swarm and not new:
+        return None
+    if state == "exited":
+        # A one-off job exiting cleanly is fine; a new container failing is not. An old
+        # one that had already failed before the redeploy isn't this rollout's doing.
+        code = int((re.search(r"\((-?\d+)\)", status) or [0, 0])[1])
+        return ("fail" if code and new else "skip"), f"exited ({code})"
+    if state in ("created", "restarting", "removing"):
+        return "busy", state
+    return ("fail", "dead") if state == "dead" else ("skip", state or "unknown")
+
+
+SEVERITY = ("fail", "busy", "ok", "skip")  # a service shows its most pressing state
+
+
+def service_rows(containers, old_ids, swarm):
+    by_service = {}
+    for c in containers:
+        new = c["Id"] not in old_ids
+        if shown := classify(c, new, swarm):
+            entry = (*shown, new, c["State"] == "running")
+            by_service.setdefault(c["service"], []).append(entry)
+    rows = []
+    for service, entries in sorted(by_service.items()):
+        kinds = {label: kind for kind, label, _, _ in entries}
+        counts = Counter(label for _, label, _, _ in entries)
+        labels = sorted(counts, key=lambda l: (SEVERITY.index(kinds[l]), -counts[l]))
+        label = (
+            ", ".join(f"{counts[l]} {l}" for l in labels) if labels[1:] else labels[0]
+        )
+        kind = min(kinds.values(), key=SEVERITY.index)
+        replaced, running = sum(e[2] for e in entries), sum(e[3] for e in entries)
+        rows.append(Row(kind, service, replaced, len(entries), running, label))
+    return rows
+
+
+def totals(rows):
+    """How many containers have been replaced, how many there are, and how many run."""
+    return [sum(getattr(r, f) for r in rows) for f in ("replaced", "total", "running")]
+
+
+# ── rendering ─────────────────────────────────────────────────────────────────
+
+ICONS = {"ok": "✓", "fail": "✗", "busy": "●", "skip": "-", "info": "▶", "stop": "⊘"}
+STYLE = {
+    "ok": "green bold",
+    "fail": "red bold",
+    "busy": "yellow bold",
+    "skip": "dim",
+    "info": "blue",
+    "stop": "dim",
+}
+SPINNER = Spinner("dots")
+
+
+def spinner():
+    """The spinner's current frame, to put where a line's icon goes."""
+    return SPINNER.render(time.monotonic()).plain
+
+
+def item_line(kind, text, *cols, glyph=None, indent=4):
+    """✓  text  col  col      (cols are (text, style) pairs)"""
+    head = (f"{' ' * indent}{glyph or ICONS[kind]}  {text}", STYLE[kind])
+    return Text.assemble(head, *((f"  {col}", style) for col, style in cols))
+
+
+def status_line(kind, text, *meta, glyph=None, indent=2):
+    """✓  text  ·  meta  ·  meta"""
+    meta = ((f"·  {m}", "dim") for m in meta)
+    return item_line(kind, text, *meta, glyph=glyph, indent=indent)
+
+
+class Ui(Console):
+    """Rich keeps a live view redrawn at the bottom of a terminal; anywhere else (a pipe,
+    a CI log) the live view is skipped and only the lines printed for good show up."""
+
+    def __init__(self):
+        super().__init__(highlight=False)
+        self.soft_wrap = not self.is_terminal  # lines stay whole in a pipe or CI log
+        self.blank = True  # whether the last line printed for good was empty
+
+    def details(self, text, limit=15):
+        """Detail lines hanging under the line above; long ones wrap on a terminal."""
+        lines = [l.rstrip() for l in str(text or "").splitlines() if l.strip()]
+        if len(lines) > limit:
+            lines = ["…"] + lines[-limit:]
+        if self.soft_wrap:  # where Padding would cut them off instead
+            return [Text(f"     {line}", "dim") for line in lines]
+        return [Padding(Text("\n".join(lines), "dim"), (0, 0, 0, 5))] if lines else []
+
+    def say(self, *lines):
+        """Print lines for good, above the live view."""
+        for line in lines:
+            self.print(line)
+            self.blank = not str(line).strip()
+
+    def gap(self):
+        if not self.blank:
+            self.say("")
+
+    def live(self, view):
+        """Keep view() redrawn at the bottom for the length of a with block."""
+        return Live(
+            get_renderable=view, console=self, transient=True, refresh_per_second=12
+        )
+
+
+# ── redeploy ──────────────────────────────────────────────────────────────────
+
+PHASES = {
+    "sending": "redeploying",
+    "deploying": "Portainer is deploying the stack",
+    "settling": "waiting for the containers to settle",
+}
+
+
+class Redeploy:
+    def __init__(self, ui, api, instance, stack_name, version, args):
+        self.ui, self.api, self.instance = ui, api, instance
+        self.name, self.version, self.tag_var = stack_name, version, instance.tag_var
+        self.environment, self.timeout = args.environment, args.timeout
+        self.issued = False  # whether Portainer has been told to redeploy
+        self.phase = "sending"  # how far the redeploy is, as a key of PHASES
+        self.rows = []  # the rollout as last seen
+
+    def wait_for(self, label, fn, *args, fail=None):
+        """Run fn(*args) behind a spinner line and return its result."""
+        with self.ui.live(lambda: status_line("busy", f"{label}…", glyph=spinner())):
+            try:
+                return fn(*args)
+            except ApiError as e:
+                if not fail:
+                    raise
+                raise Failure(fail, f"{e}\n{e.details}".strip()) from None
+
+    def run(self):
+        title = f"{self.name} → {self.version}" if self.version else self.name
+        self.ui.rule(characters="═", style="cyan bold")
+        header = f"  Portainer Redeploy  ·  {title}  ·  {self.instance.name}"
+        self.ui.say(Text(header, "cyan bold"), "")
+
+        label, fail = f"Finding stack {self.name}", "Could not get the list of stacks"
+        stack, env_name = self.wait_for(label, self.lookup, fail=fail)
+        name, kind = stack["Name"], {1: "swarm", 2: "compose"}.get(stack["Type"])
+        if not kind:
+            raise Failure(
+                f"{name} is not a compose or swarm stack - the tool supports only those two types"
+            )
+        if stack["Status"] == DEPLOYING:
+            raise Failure(
+                f"Portainer is already deploying {name} - try again when that deploy is done"
+            )
+        git = bool(stack.get("GitConfig") or stack.get("WorkflowID"))
+        kind = f"{kind} from git" if git else kind
+        self.ui.say(status_line("ok", f"Stack {name}", kind, f"environment {env_name}"))
+
+        env = {pair["name"]: pair["value"] for pair in stack.get("Env") or []}
+        if self.version:
+            # Added when the stack env doesn't have it yet (say the stack file falls back
+            # to a default) - otherwise the version would be silently ignored.
+            old, env[self.tag_var] = env.get(self.tag_var), self.version
+            change = f"{'(unset)' if old is None else old} → {self.version}"
+            change = f"{self.version}  (unchanged)" if old == self.version else change
+            self.ui.say(status_line("info", f"{self.tag_var}  {change}"))
+
+        # File-based stacks are redeployed by sending their stack file back; git stacks
+        # only need it for checking the images.
+        stack_file = None
+        if self.version or not git:
+            label, fail = "Fetching the stack file", "Could not fetch the stack file"
+            path = f"/stacks/{stack['Id']}/file"
+            reply = self.wait_for(label, self.api.get, path, fail=fail)
+            stack_file = (reply or {}).get("StackFileContent")
+            if not stack_file:
+                raise Failure(f"Portainer sent an empty stack file for {name}")
+        if self.version:
+            self.check_images(stack, stack_file, env)
+        self.deploy(stack, stack_file, env, swarm=stack["Type"] == 1, git=git)
+
+    def lookup(self):
+        """Find the stack, and the name of its environment (runs behind a spinner)."""
+        stacks, envs = self.api.get("/stacks"), {}
+        with contextlib.suppress(ApiError):  # the key may not be allowed to list them
+            endpoints = self.api.get("/endpoints?excludeSnapshots=true")
+            envs = {e["Id"]: e["Name"] for e in endpoints}
+
+        def env_of(stack):
+            return envs.get(stack["EndpointId"]) or f"#{stack['EndpointId']}"
+
+        def in_env(stack):
+            want = (self.environment or "").lower()
+            return want in ("", str(stack["EndpointId"]), env_of(stack).lower())
+
+        named = [s for s in stacks if s["Name"].lower() == self.name.lower()]
+        matches = list(filter(in_env, named))
+        if not matches and named:
+            raise Failure(
+                f'There is no stack named "{self.name}" in environment {self.environment}',
+                f"There is a stack with that name in {join_names(sorted(map(env_of, named)))}.",
+            )
+        if not matches:
+            names = sorted({s["Name"] for s in stacks})
+            close = difflib.get_close_matches(self.name, names, n=3)
+            hint = "The API key does not see any stacks. Check what the user of the API key has access to."
+            if names:
+                more = ", …" if len(names) > 15 else ""
+                hint = f"Stacks on {self.instance.name}: {', '.join(names[:15])}{more}"
+            if close:
+                hint = f"Did you mean {join_names(close, 'or')}?"
+            raise Failure(
+                f'There is no stack named "{self.name}" on {self.instance.name}', hint
+            )
+        if len(matches) > 1:
+            raise Failure(
+                f'{len(matches)} environments have a stack named "{self.name}" - select the environment with --environment',
+                "\n".join(f"{env_of(s)}  (#{s['EndpointId']})" for s in matches),
+            )
+        return matches[0], env_of(matches[0])
+
+    def check_images(self, stack, stack_file, env):
+        """Pull the images that use the tag variable, at the new version, onto the stack's
+        environment: a version that doesn't exist then fails here, before the stack is
+        touched - and as the redeploy pulls these images anyway, a passing check just
+        saves it the download."""
+        refs, eid = tagged_images(stack_file, env, self.tag_var), stack["EndpointId"]
+        if not refs:
+            raise Failure(
+                f"No image in {stack['Name']} uses {self.tag_var}, so version {self.version} would have no effect",
+                f'If the image tag is in a different variable, put the name of that variable in "tag_var" in {CONFIG_SHOWN} or in PORTAINER_TAG_VAR.',
+            )
+        # The registries let each pull use the credentials Portainer has for its image.
+        # Best-effort: without them the pulls are anonymous, which still works for public images.
+        registries, path = None, f"/endpoints/{eid}/registries"
+        with contextlib.suppress(ApiError):
+            registries = self.wait_for("Listing the registries", self.api.get, path)
+
+        self.ui.say("", Text("    ── images", "dim"))
+        width = max(map(len, refs))
+        for ref in refs:
+            registry_id = registry_for(ref, registries or [])
+            name, layers = ref.ljust(width), {}
+            try:
+                with self.ui.live(lambda: self.pull_line(name, list(layers.values()))):
+                    result = pull(self.api, eid, ref, registry_id, layers)
+            except ApiError as e:
+                self.ui.say(item_line("fail", name, (str(e), "red")))
+                hint = ""
+                if registry_id is None:
+                    hint = "No registry in Portainer matches this image, so the pull was anonymous."
+                if registries is None:
+                    hint = "Could not list the registries in Portainer, so the pull was anonymous."
+                raise Failure(
+                    f"Version {self.version} is not available for {stack['Name']} - nothing was redeployed",
+                    hint,
+                ) from None
+            self.ui.say(item_line("ok", name, (result[:1].lower() + result[1:], "dim")))
+
+    @staticmethod
+    def pull_line(name, layers):
+        line = item_line("busy", name, glyph=spinner())
+        if not layers:
+            return line.append("  pulling…", "dim")
+        done = sum(status in LAYER_DONE for status, _ in layers)
+        grid = Table.grid(padding=(0, 2))
+        bar = ProgressBar(1, pull_progress(layers), 20, complete_style="blue")
+        grid.add_row(line, bar, Text(f"{done}/{len(layers)} layers", "dim"))
+        return grid
+
+    def deploy(self, stack, stack_file, env, swarm, git):
+        sid, eid, name = stack["Id"], stack["EndpointId"], stack["Name"]
+        # PullImage is what Portainer called RepullImageAndRedeploy before 2.36; send both.
+        # Prune goes along unchanged, as 2.36+ saves whatever it gets as the stack's setting.
+        body = {
+            "Env": [{"name": k, "value": v} for k, v in env.items()],
+            "Prune": bool((stack.get("Option") or {}).get("Prune")),
+            "PullImage": True,
+            "RepullImageAndRedeploy": True,
+        }
+        if git:
+            # Updating a git stack like a file-based one would detach it from its repository,
+            # so it goes through the git redeploy - with the ref and credentials it already
+            # has (a blank password keeps the stored one).
+            repo = stack.get("GitConfig") or {}
+            auth = repo.get("Authentication") or {}
+            body.update(
+                RepositoryReferenceName=repo.get("ReferenceName") or "",
+                RepositoryAuthentication=bool(auth),
+                RepositoryUsername=auth.get("Username") or "",
+                RepositoryPassword="",
+                RepositoryGitCredentialID=auth.get("GitCredentialID") or 0,
+            )
+        else:
+            body["StackFileContent"] = stack_file
+        path = f"/stacks/{sid}{'/git/redeploy' if git else ''}?endpointId={eid}"
+
+        # The containers from before the redeploy: one with a new Id has been replaced.
+        label = "Listing the current containers"
+        fail = f"Could not list the containers of {name} - nothing was redeployed"
+        before = self.wait_for(label, stack_containers, self.api, eid, name, fail=fail)
+        old_ids = {c["Id"] for c in before}
+
+        self.ui.say("", Text("    ── rollout", "dim"))
+        start = time.monotonic()
+        put = Job(self.api.request, "PUT", path, json=body, timeout=self.timeout)
+        self.issued = True
+
+        # Watch until the rollout settles: the deploy is done, the set of containers has
+        # stopped changing and none is still starting. That's keyed on stability rather
+        # than "all running", as some services are one-off jobs that rightly exit.
+        containers, ids, stable, deployed_at, shown = before, None, 0, 0, None
+        lost = timed_out = False
+        with self.ui.live(lambda: self.rollout_view(time.monotonic() - start)):
+            while True:
+                now = time.monotonic()
+                if put and not put.is_alive():
+                    error, put, self.phase = put.error, None, "deploying"
+                    if isinstance(error, ApiError) and error.status in (0, 502, 504):
+                        # A proxy in front of Portainer gave up waiting (or the connection
+                        # dropped), but Portainer carries on - and moves the stack's
+                        # UpdateDate once it's done.
+                        lost = True
+                        why = f"Portainer's reply did not arrive ({error}) - the redeploy continues in Portainer, and the tool keeps following it"
+                        self.ui.say(item_line("busy", why))
+                    elif isinstance(error, ApiError):
+                        details = f"{error}\n{error.details}".strip()
+                        raise Failure(f"The redeploy of {name} failed", details)
+                    elif error:
+                        raise error
+                if self.phase == "deploying":
+                    with contextlib.suppress(ApiError):  # tries again next time
+                        if self.deployed(stack, lost):
+                            self.phase, deployed_at, stable = "settling", now, 0
+
+                with contextlib.suppress(ApiError):  # keeps showing the last look
+                    containers = stack_containers(self.api, eid, name)
+                    new_ids = {c["Id"] for c in containers}
+                    stable, ids = (stable + 1 if new_ids == ids else 0), new_ids
+                self.rows = rows = service_rows(containers, old_ids, swarm)
+
+                watched = now - deployed_at >= MIN_WATCH
+                if self.phase == "settling" and stable >= STABLE_POLLS and watched:
+                    if rows and not any(r.kind == "busy" for r in rows):
+                        break
+                    if not rows and not swarm:
+                        # Compose has created the containers by the time the deploy is
+                        # done, so none showing up now means there's nothing to watch
+                        # (swarm can be slower).
+                        raise Failure(
+                            f"Portainer deployed {name}, but the tool found no containers of the stack",
+                            f'The tool searches for containers that have the com.docker.compose.project label "{name.lower()}".',
+                        )
+                if now - start >= self.timeout:
+                    timed_out = True
+                    break
+                if not self.ui.is_interactive and self.phase != shown:
+                    phase = (f"{PHASES[self.phase]}…", (fmt_dur(now - start), "dim"))
+                    self.ui.say(item_line("busy", *phase))
+                    shown = self.phase
+                (put.join if put else time.sleep)(POLL_INTERVAL)  # put.join ends early
+
+        took = time.monotonic() - start
+        self.ui.say(*self.row_lines(rows), "")
+        replaced, total, running = totals(rows)
+        if timed_out:
+            why = "no containers appeared"
+            if total:
+                why = "containers were still starting or restarting"
+            if self.phase != "settling":
+                why = "Portainer did not report that the deploy was done"
+            raise Failure(
+                f"{name} did not settle within {fmt_dur(self.timeout)} ({why})",
+                f"If {name} only needs more time, increase --timeout.",
+            )
+        if failing := [r.service for r in rows if r.kind == "fail"]:
+            are = "are" if failing[1:] else "is"
+            raise Failure(
+                f"{name} redeployed, but {join_names(failing)} {are} failing - check their logs"
+            )
+        done, meta = f"Redeployed {name}", [f"{replaced}/{total} containers replaced"]
+        if not replaced:
+            done, meta = (
+                f"{name} is up to date - no containers needed to be replaced",
+                [],
+            )
+        meta += [f"{running}/{total} running", fmt_dur(took)]
+        self.ui.say(status_line("ok", done, *meta))
+
+    def deployed(self, stack, lost):
+        """Whether Portainer has finished deploying the stack - before 2.36 it answers
+        the redeploy only then; newer ones answer right away, and mark it as deploying.
+        """
+        found = self.api.get(f"/stacks/{stack['Id']}")
+        if found["Status"] == DEPLOY_ERROR:
+            statuses = found.get("DeploymentStatus") or []
+            message = next(
+                (s["Message"] for s in reversed(statuses) if s["Message"]), ""
+            )
+            raise Failure(f"Portainer could not deploy {stack['Name']}", message)
+        unchanged = lost and found["UpdateDate"] == stack["UpdateDate"]
+        return found["Status"] != DEPLOYING and not unchanged
+
+    def rollout_view(self, elapsed):
+        rows, meta = self.rows, [f"{fmt_dur(elapsed)}"]
+        replaced, total, running = totals(rows)
+        if total:
+            meta.append(f"{replaced}/{total} replaced  ·  {running}/{total} running")
+        hint = "       Ctrl-C stops watching - the redeploy continues in Portainer"
+        return Group(
+            item_line(
+                "busy",
+                PHASES[self.phase],
+                *((f"·  {m}", "dim") for m in meta),
+                glyph=spinner(),
+            ),
+            *(self.row_lines(rows) or [Text("       no containers yet", "dim")]),
+            Text(hint, "dim"),
+        )
+
+    @staticmethod
+    def row_lines(rows):
+        width, lines = max([12] + [len(r.service) for r in rows]), []
+        for r in rows:
+            replaced = f"{r.replaced}/{r.total} replaced".ljust(14)
+            cols = [(replaced, "" if r.replaced else "dim"), (r.label, STYLE[r.kind])]
+            lines.append(item_line(r.kind, r.service.ljust(width), *cols))
+        return lines
+
+
+# ── entry point ───────────────────────────────────────────────────────────────
+
+EPILOG = f"""\
+Describe your instances in {CONFIG_SHOWN}:
+  {{ "prod": {{ "url": "https://portainer.example.com",
+              "api_key_file": "/run/secrets/portainer_api_key" }},
+    "lab":  {{ "url_file": "/run/secrets/lab_url", "api_key": "ptr_...",
+              "insecure": true }} }}
+Or, for a single instance, set PORTAINER_URL and PORTAINER_API_KEY.
+To skip TLS verification for that instance, also set PORTAINER_INSECURE=1."""
+
+
+def parse_args():
+    """The options, and the config. The instance can be left out of the arguments: of
+    two, the first is only taken as one (into args.instance) if it's a configured one.
+    """
+    prog = os.path.basename(sys.argv[0])
+    parser = argparse.ArgumentParser(
+        prog="portainer-redeploy" if prog in ("", "__main__.py") else prog,
+        usage="%(prog)s [options] [INSTANCE] STACK [VERSION]",
+        description=__doc__,
+        epilog=EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    add = parser.add_argument
+    add("target", nargs="+", metavar="STACK", help=argparse.SUPPRESS)
+    add(
+        "-i",
+        "--instance",
+        help="Portainer instance from the config file (you can also give it as the first argument)",
+    )
+    add(
+        "-E",
+        "--environment",
+        metavar="NAME|ID",
+        help="Portainer environment that has the stack, if stacks in several environments have the same name",
+    )
+    add(
+        "--timeout",
+        type=int,
+        default=600,
+        metavar="SECONDS",
+        help="how long to wait for the rollout to settle (default: %(default)s)",
+    )
+    add(
+        "-k",
+        "--insecure",
+        action="store_true",
+        help="skip TLS certificate verification",
+    )
+    add("-V", "--version", action="version", version=f"%(prog)s {__version__}")
+    args = parser.parse_args()
+    if args.timeout <= 0:
+        parser.error("--timeout must be a positive number")
+    config, target = load_config(), args.target
+    if len(target) > 3:
+        parser.error("too many arguments")
+    if len(target) == 3 or (
+        len(target) == 2 and args.instance is None and target[0] in config
+    ):
+        if args.instance is not None:
+            parser.error(
+                "you gave the instance twice: with -i and as the first argument"
+            )
+        args.instance = target.pop(0)
+    return args, config
+
+
+def main():
+    args, config = parse_args()
+    instance = resolve_instance(args.instance, config, args.insecure)
+    stack, version = args.target[0], args.target[1] if len(args.target) > 1 else None
+    signal.signal(signal.SIGTERM, lambda *_: sys.exit(143))  # still restore the cursor
+
+    ui = Ui()
+    run = Redeploy(ui, Portainer(instance), instance, stack, version, args)
+    try:
+        run.run()
+    except Failure as f:
+        ui.gap()
+        ui.say(status_line("fail", str(f)), *ui.details(f.details))
+        sys.exit(1)
+    except KeyboardInterrupt:
+        if run.issued:
+            stop = "Stopped watching - the redeploy continues in Portainer"
+            ui.say(*run.row_lines(run.rows), "", status_line("stop", stop))
+        else:
+            ui.gap()
+            ui.say(status_line("stop", "Cancelled - nothing was redeployed"))
+        sys.exit(130)
+
+
+if __name__ == "__main__":
+    main()