rostainer-deploy 0.0.3__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- rostainer_deploy/__init__.py +534 -0
- rostainer_deploy/api.py +242 -0
- rostainer_deploy/progress.py +129 -0
- rostainer_deploy/remote.py +531 -0
- rostainer_deploy-0.0.3.dist-info/METADATA +50 -0
- rostainer_deploy-0.0.3.dist-info/RECORD +8 -0
- rostainer_deploy-0.0.3.dist-info/WHEEL +4 -0
- rostainer_deploy-0.0.3.dist-info/entry_points.txt +2 -0
rostainer_deploy/api.py
ADDED
|
@@ -0,0 +1,242 @@
|
|
|
1
|
+
"""What other plugins may use of deploy: its targets, and running things on them.
|
|
2
|
+
|
|
3
|
+
A plugin that works with the robots ``[plugins.deploy]`` lists - fetching
|
|
4
|
+
their logs, say - builds on this rather than its own list of hosts. It
|
|
5
|
+
lists deploy in its ``requires`` (and ``rostainer-deploy`` in its package's
|
|
6
|
+
dependencies), and uses this module; nothing else in ``rostainer_deploy``
|
|
7
|
+
is a promise::
|
|
8
|
+
|
|
9
|
+
from rostainer_deploy import api
|
|
10
|
+
|
|
11
|
+
class Fetch(Command):
|
|
12
|
+
def add_arguments(self, parser):
|
|
13
|
+
api.add_target_arguments(parser) # TARGET_OR_GROUP ..., or all
|
|
14
|
+
|
|
15
|
+
def run(self, args, ctx):
|
|
16
|
+
def fetch(conn: api.Connection) -> int:
|
|
17
|
+
name = conn.package_container()
|
|
18
|
+
...
|
|
19
|
+
return 0 if conn.copy_from("logs/today.tar", Path("today.tar")) else 1
|
|
20
|
+
|
|
21
|
+
targets = api.targets(ctx, args.targets) # groups, 'enabled', as deploy does
|
|
22
|
+
return api.report(api.for_each(ctx, targets, fetch, title="Fetching"), "Fetching")
|
|
23
|
+
|
|
24
|
+
Targets are reached as deploy reaches them: ssh with the workspace's
|
|
25
|
+
``ssh_options``, never prompting, connecting with ``connect_attempts``
|
|
26
|
+
retries; several at once (``parallel``), each line of output prefixed
|
|
27
|
+
with the target's name (or, with a ``title``, a board of how each is doing). A target that can't be reached fails alone.
|
|
28
|
+
"""
|
|
29
|
+
|
|
30
|
+
from __future__ import annotations
|
|
31
|
+
|
|
32
|
+
import argparse
|
|
33
|
+
import os
|
|
34
|
+
import shlex
|
|
35
|
+
import subprocess
|
|
36
|
+
from pathlib import Path
|
|
37
|
+
from typing import Callable, List, NamedTuple, Optional, Sequence
|
|
38
|
+
|
|
39
|
+
from rostainer_cli.plugin_api import Context
|
|
40
|
+
from rostainer_deploy import remote
|
|
41
|
+
from rostainer_deploy.remote import Destination, Outcome
|
|
42
|
+
|
|
43
|
+
__all__ = [
|
|
44
|
+
"Connection",
|
|
45
|
+
"DeployTarget",
|
|
46
|
+
"Outcome",
|
|
47
|
+
"Result",
|
|
48
|
+
"add_target_arguments",
|
|
49
|
+
"for_each",
|
|
50
|
+
"report",
|
|
51
|
+
"targets",
|
|
52
|
+
]
|
|
53
|
+
|
|
54
|
+
#: A target, as :func:`targets` returns it: ``name``, ``host``, ``user``,
|
|
55
|
+
#: ``port`` (``None``: ssh's), and ``install_dir`` (where its package is
|
|
56
|
+
#: installed; relative to the ssh user's home unless absolute).
|
|
57
|
+
DeployTarget = Destination
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
class Result(NamedTuple):
|
|
61
|
+
"""How a command on a target went."""
|
|
62
|
+
|
|
63
|
+
returncode: int
|
|
64
|
+
output: str
|
|
65
|
+
"""Its standard output, with ``capture``; else ``""`` (it was shown)."""
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
def _deploy(ctx: Context) -> Context:
|
|
69
|
+
"""Deploy's context, from the calling plugin's (which must require it)."""
|
|
70
|
+
return ctx if ctx.plugin.name == "deploy" else ctx.plugin_context("deploy")
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
def add_target_arguments(parser: argparse.ArgumentParser, *, required: bool = False) -> None:
|
|
74
|
+
"""Add the targets argument deploy's own commands take, as ``targets``:
|
|
75
|
+
target names, group names, or ``all`` (the default, unless ``required``)."""
|
|
76
|
+
from rostainer_deploy import ALL
|
|
77
|
+
|
|
78
|
+
parser.add_argument(
|
|
79
|
+
"targets",
|
|
80
|
+
nargs="+" if required else "*",
|
|
81
|
+
metavar="TARGET_OR_GROUP",
|
|
82
|
+
help=f"Targets, groups, or '{ALL}' (every enabled target)"
|
|
83
|
+
+ ("" if required else f"; default: {ALL}"),
|
|
84
|
+
)
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
def targets(ctx: Context, selectors: Sequence[str] = ()) -> List[DeployTarget]:
|
|
88
|
+
"""The targets ``selectors`` pick, as ``rostainer deploy`` picks them:
|
|
89
|
+
by name or group, ``all`` (or none) for every enabled one; in the
|
|
90
|
+
order they're listed in ``[plugins.deploy.targets]``.
|
|
91
|
+
|
|
92
|
+
Args:
|
|
93
|
+
ctx: The calling plugin's context. It must list ``"deploy"`` in its
|
|
94
|
+
``requires``.
|
|
95
|
+
|
|
96
|
+
Raises:
|
|
97
|
+
ConfigError: If there are no targets, a selector is none of them,
|
|
98
|
+
or none is left (shown as an error, like deploy's own).
|
|
99
|
+
ValueError: If the calling plugin doesn't require deploy.
|
|
100
|
+
"""
|
|
101
|
+
from rostainer_deploy import destinations
|
|
102
|
+
|
|
103
|
+
return destinations(_deploy(ctx), selectors)
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
class Connection:
|
|
107
|
+
"""An open ssh connection to one target, for :func:`for_each`'s function."""
|
|
108
|
+
|
|
109
|
+
def __init__(self, target: DeployTarget, via: Sequence[str]) -> None:
|
|
110
|
+
self.target = target
|
|
111
|
+
"""The target: ``.name``, ``.host``, ``.install_dir``, ..."""
|
|
112
|
+
self._via = list(via)
|
|
113
|
+
|
|
114
|
+
def say(self, line: str) -> None:
|
|
115
|
+
"""Print a line of output for the target, prefixed with its name."""
|
|
116
|
+
remote.say(self.target.name, line)
|
|
117
|
+
|
|
118
|
+
def run(self, script: str, *, stdin: bytes = b"", capture: bool = False) -> Result:
|
|
119
|
+
"""Run ``script`` (``sh``) on the target, from the ssh user's home.
|
|
120
|
+
|
|
121
|
+
Without ``capture``, its output is shown as it comes, prefixed with
|
|
122
|
+
the target's name. With it, its standard output is returned; its
|
|
123
|
+
errors are still shown.
|
|
124
|
+
"""
|
|
125
|
+
if not capture:
|
|
126
|
+
outcome = remote.run_on(self.target, script, stdin=stdin, ssh_extra=self._via)
|
|
127
|
+
return Result(outcome.returncode, "")
|
|
128
|
+
process = subprocess.run(
|
|
129
|
+
self.target.ssh(*self._via) + ["sh", "-c", shlex.quote(script)],
|
|
130
|
+
input=stdin,
|
|
131
|
+
stdout=subprocess.PIPE,
|
|
132
|
+
stderr=subprocess.PIPE,
|
|
133
|
+
check=False,
|
|
134
|
+
)
|
|
135
|
+
for line in process.stderr.decode(errors="replace").splitlines():
|
|
136
|
+
self.say(line)
|
|
137
|
+
return Result(process.returncode, process.stdout.decode(errors="replace"))
|
|
138
|
+
|
|
139
|
+
def _manage(self, *arguments: str) -> str:
|
|
140
|
+
"""The script running the installed package's ``./rostainer``."""
|
|
141
|
+
return remote.manage_script(self.target.install_dir, " ".join(map(shlex.quote, arguments)))
|
|
142
|
+
|
|
143
|
+
def in_package(self, command: Sequence[str], *, capture: bool = False) -> Result:
|
|
144
|
+
"""Run ``command`` in the target's package container, with ROS and
|
|
145
|
+
the workspace sourced (``./rostainer shell -- command``) - e.g. a
|
|
146
|
+
script of the plugin's ``container_files``, under
|
|
147
|
+
``CONTAINER_PLUGINS_DIR``. Exits 3, saying so, without a package."""
|
|
148
|
+
return self.run(self._manage("shell", "--", *command), capture=capture)
|
|
149
|
+
|
|
150
|
+
def run_command(
|
|
151
|
+
self, plugin: str, command: str, args: Sequence[str] = (), *, capture: bool = False
|
|
152
|
+
) -> Result:
|
|
153
|
+
"""Run ``plugin``'s container command ``command`` (a
|
|
154
|
+
``ContainerCommand``) in the target's package, as ``./rostainer
|
|
155
|
+
<plugin> <command> ARGS`` there: with the settings that package
|
|
156
|
+
was made with. Exits 2, saying so, if the package has no such
|
|
157
|
+
command (e.g. one made before the plugin had it); 3 without a
|
|
158
|
+
package."""
|
|
159
|
+
return self.run(self._manage(plugin, command, *args), capture=capture)
|
|
160
|
+
|
|
161
|
+
def package_container(self) -> Optional[str]:
|
|
162
|
+
"""The name of the target's package container (``./rostainer
|
|
163
|
+
container``), e.g. for ``docker inspect``; ``None`` without a
|
|
164
|
+
package (or one from before rostainer-package had the command)."""
|
|
165
|
+
result = self.run(self._manage("container"), capture=True)
|
|
166
|
+
name = result.output.strip()
|
|
167
|
+
return name if result.returncode == 0 and name else None
|
|
168
|
+
|
|
169
|
+
def copy_from(self, path: str, destination: Path) -> bool:
|
|
170
|
+
"""Copy the file ``path`` on the target (relative to the ssh user's
|
|
171
|
+
home, or absolute) to ``destination`` here. Written to a ``.part``
|
|
172
|
+
file first, and renamed only once complete: ``destination`` is
|
|
173
|
+
never left half-written. Returns whether it worked (if not, the
|
|
174
|
+
reason was shown)."""
|
|
175
|
+
destination.parent.mkdir(parents=True, exist_ok=True)
|
|
176
|
+
partial = destination.with_name(destination.name + ".part")
|
|
177
|
+
try:
|
|
178
|
+
with partial.open("wb") as out:
|
|
179
|
+
process = subprocess.run(
|
|
180
|
+
self.target.ssh(*self._via) + ["cat", "--", shlex.quote(path)],
|
|
181
|
+
stdin=subprocess.DEVNULL,
|
|
182
|
+
stdout=out,
|
|
183
|
+
stderr=subprocess.PIPE,
|
|
184
|
+
check=False,
|
|
185
|
+
)
|
|
186
|
+
for line in process.stderr.decode(errors="replace").splitlines():
|
|
187
|
+
self.say(line)
|
|
188
|
+
if process.returncode != 0:
|
|
189
|
+
return False
|
|
190
|
+
os.replace(str(partial), str(destination))
|
|
191
|
+
return True
|
|
192
|
+
finally:
|
|
193
|
+
if partial.exists():
|
|
194
|
+
partial.unlink()
|
|
195
|
+
|
|
196
|
+
def copy_to(self, source: Path, path: str) -> bool:
|
|
197
|
+
"""Copy the file ``source`` here to ``path`` on the target (relative
|
|
198
|
+
to the ssh user's home, or absolute), through a temporary file
|
|
199
|
+
there renamed once complete. Returns whether it worked."""
|
|
200
|
+
quoted = shlex.quote(path)
|
|
201
|
+
script = f'tmp={quoted}.part.$$ && cat > "$tmp" && mv -f "$tmp" {quoted} || {{ rm -f "$tmp"; exit 1; }}'
|
|
202
|
+
return self.run(script, stdin=source.read_bytes()).returncode == 0
|
|
203
|
+
|
|
204
|
+
|
|
205
|
+
def for_each(
|
|
206
|
+
ctx: Context,
|
|
207
|
+
targets: Sequence[DeployTarget],
|
|
208
|
+
run: Callable[[Connection], int],
|
|
209
|
+
*,
|
|
210
|
+
title: Optional[str] = None,
|
|
211
|
+
) -> List[Outcome]:
|
|
212
|
+
"""Connect to each target and call ``run`` with the connection,
|
|
213
|
+
``parallel`` at a time (deploy's setting); its return value is the
|
|
214
|
+
target's exit code. A target that can't be connected to (after
|
|
215
|
+
deploy's retries) fails with 255, saying why, without ``run``; one
|
|
216
|
+
whose ``run`` raises fails with 1, showing the error. In ``targets``'
|
|
217
|
+
order.
|
|
218
|
+
|
|
219
|
+
With a ``title`` (e.g. ``"Fetching the archives"``), in a terminal,
|
|
220
|
+
it's shown as a board of how each target is doing, docker compose
|
|
221
|
+
style: each one's latest line of output, then the whole output of
|
|
222
|
+
those that failed. Without one, every line is shown as it comes."""
|
|
223
|
+
settings = _deploy(ctx).config
|
|
224
|
+
|
|
225
|
+
def one(target: DeployTarget) -> Outcome:
|
|
226
|
+
try:
|
|
227
|
+
with remote.connection(target) as via:
|
|
228
|
+
return Outcome(target.name, run(Connection(target, via)))
|
|
229
|
+
except remote.ConnectError as error:
|
|
230
|
+
remote.say(target.name, str(error))
|
|
231
|
+
return Outcome(target.name, 255)
|
|
232
|
+
except Exception as error: # noqa: BLE001 - one target's failure only.
|
|
233
|
+
remote.say(target.name, f"{type(error).__name__}: {error}")
|
|
234
|
+
return Outcome(target.name, 1)
|
|
235
|
+
|
|
236
|
+
return remote.run_on_all(list(targets), one, settings.parallel, title)
|
|
237
|
+
|
|
238
|
+
|
|
239
|
+
def report(outcomes: Sequence[Outcome], what: str) -> int:
|
|
240
|
+
"""Summarize ``outcomes`` as deploy does ("``what`` failed on robot2 (1
|
|
241
|
+
of 2 succeeded)"); the exit code: 0 only if every target succeeded."""
|
|
242
|
+
return remote.report(outcomes, what)
|
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
"""A live board of how each target is doing, docker compose style.
|
|
2
|
+
|
|
3
|
+
While something runs on several targets in a terminal, each gets a row
|
|
4
|
+
with its latest line of output, instead of every line streamed::
|
|
5
|
+
|
|
6
|
+
[+] Deploying '20261102-111227' 2/4
|
|
7
|
+
✔ diver81 [OK] Install complete. 34.2s
|
|
8
|
+
⠸ diver82 [INFO] Checking it keeps running for 20s... 21.0s
|
|
9
|
+
✘ diver83 [ERROR] No package was installed here before... 30.1s
|
|
10
|
+
· diver84 Waiting
|
|
11
|
+
|
|
12
|
+
Once all are done, the whole output of those that failed is printed (as
|
|
13
|
+
lines prefixed with the target's name), and the warnings of the others.
|
|
14
|
+
Without a terminal (or rich), there's no board: every line is printed as
|
|
15
|
+
it comes, prefixed with the target's name.
|
|
16
|
+
"""
|
|
17
|
+
|
|
18
|
+
from __future__ import annotations
|
|
19
|
+
|
|
20
|
+
import os
|
|
21
|
+
import re
|
|
22
|
+
import sys
|
|
23
|
+
import threading
|
|
24
|
+
import time
|
|
25
|
+
from typing import Any, Dict, List, Optional, Sequence
|
|
26
|
+
|
|
27
|
+
#: A line of a target that succeeded still shown after the board.
|
|
28
|
+
_WARNING = re.compile(r"warn", re.IGNORECASE)
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
class _Row:
|
|
32
|
+
"""One target's progress."""
|
|
33
|
+
|
|
34
|
+
def __init__(self) -> None:
|
|
35
|
+
self.lines: List[str] = []
|
|
36
|
+
self.started: Optional[float] = None
|
|
37
|
+
self.finished: Optional[float] = None
|
|
38
|
+
self.returncode: Optional[int] = None
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
class Board:
|
|
42
|
+
"""The rows of :func:`board`'s targets, rendered by rich's ``Live``."""
|
|
43
|
+
|
|
44
|
+
def __init__(self, title: str, names: Sequence[str], console: Any = None) -> None:
|
|
45
|
+
from rich.console import Console
|
|
46
|
+
from rich.spinner import Spinner
|
|
47
|
+
|
|
48
|
+
self.title = title
|
|
49
|
+
self.rows: Dict[str, _Row] = {name: _Row() for name in names}
|
|
50
|
+
self.console = console or Console()
|
|
51
|
+
self._spinners = {name: Spinner("dots", style="cyan") for name in names}
|
|
52
|
+
self._lock = threading.Lock()
|
|
53
|
+
|
|
54
|
+
def start(self, name: str) -> None:
|
|
55
|
+
with self._lock:
|
|
56
|
+
self.rows[name].started = time.monotonic()
|
|
57
|
+
|
|
58
|
+
def add(self, name: str, line: str) -> None:
|
|
59
|
+
with self._lock:
|
|
60
|
+
self.rows[name].lines.append(line)
|
|
61
|
+
|
|
62
|
+
def finish(self, name: str, returncode: int) -> None:
|
|
63
|
+
with self._lock:
|
|
64
|
+
row = self.rows[name]
|
|
65
|
+
row.finished = time.monotonic()
|
|
66
|
+
row.returncode = returncode
|
|
67
|
+
|
|
68
|
+
def live(self) -> Any:
|
|
69
|
+
"""The ``with`` block showing the board, updated as it goes."""
|
|
70
|
+
from rich.live import Live
|
|
71
|
+
|
|
72
|
+
return Live(self, console=self.console, refresh_per_second=10)
|
|
73
|
+
|
|
74
|
+
def __rich__(self) -> Any:
|
|
75
|
+
from rich.console import Group
|
|
76
|
+
from rich.table import Table
|
|
77
|
+
from rich.text import Text
|
|
78
|
+
|
|
79
|
+
with self._lock:
|
|
80
|
+
done = sum(row.returncode is not None for row in self.rows.values())
|
|
81
|
+
table = Table.grid(padding=(0, 1), expand=True)
|
|
82
|
+
table.add_column(no_wrap=True)
|
|
83
|
+
table.add_column(no_wrap=True, style="bold")
|
|
84
|
+
table.add_column(no_wrap=True, overflow="ellipsis", ratio=1)
|
|
85
|
+
table.add_column(no_wrap=True, justify="right", style="dim")
|
|
86
|
+
now = time.monotonic()
|
|
87
|
+
for name, row in self.rows.items():
|
|
88
|
+
latest = next((line for line in reversed(row.lines) if line.strip()), "")
|
|
89
|
+
status = Text.from_ansi(latest.strip())
|
|
90
|
+
if row.started is None:
|
|
91
|
+
mark: Any = Text("·", style="dim")
|
|
92
|
+
status = Text("Waiting", style="dim")
|
|
93
|
+
elif row.returncode is None:
|
|
94
|
+
mark = self._spinners[name]
|
|
95
|
+
elif row.returncode == 0:
|
|
96
|
+
mark = Text("✔", style="green")
|
|
97
|
+
else:
|
|
98
|
+
mark = Text("✘", style="red")
|
|
99
|
+
if not latest:
|
|
100
|
+
status = Text(f"Failed (exit code {row.returncode})", style="red")
|
|
101
|
+
elapsed = (
|
|
102
|
+
f"{(row.finished or now) - row.started:.1f}s" if row.started is not None else ""
|
|
103
|
+
)
|
|
104
|
+
table.add_row(mark, name, status, elapsed)
|
|
105
|
+
return Group(Text(f"[+] {self.title} {done}/{len(self.rows)}", style="bold"), table)
|
|
106
|
+
|
|
107
|
+
def print_details(self) -> None:
|
|
108
|
+
"""After the board: the whole output of the targets that failed,
|
|
109
|
+
and the warnings of those that didn't."""
|
|
110
|
+
shown = []
|
|
111
|
+
for name, row in self.rows.items():
|
|
112
|
+
failed = row.returncode != 0
|
|
113
|
+
for line in row.lines:
|
|
114
|
+
if failed or _WARNING.search(line):
|
|
115
|
+
shown.append(f"[{name}] {line}")
|
|
116
|
+
if shown:
|
|
117
|
+
print()
|
|
118
|
+
print("\n".join(shown), flush=True)
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
def board(title: Optional[str], names: Sequence[str]) -> Optional[Board]:
|
|
122
|
+
"""A :class:`Board` for ``names`` if there's a terminal to show it in
|
|
123
|
+
(and a ``title``, and rich); else ``None``: stream the lines."""
|
|
124
|
+
if not title or not sys.stdout.isatty() or os.environ.get("TERM") == "dumb":
|
|
125
|
+
return None
|
|
126
|
+
try:
|
|
127
|
+
return Board(title, names)
|
|
128
|
+
except ImportError:
|
|
129
|
+
return None
|