rostainer-instances 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.
|
@@ -0,0 +1,367 @@
|
|
|
1
|
+
"""Instances: several copies of a target, for simulation and testing.
|
|
2
|
+
|
|
3
|
+
``[plugins.instances] count = N`` in ``.rostainer.toml`` lets ``rostainer
|
|
4
|
+
instances start`` run N copies of a target next to its dev container,
|
|
5
|
+
named ``<container>-0`` .. ``<container>-<N-1>`` (see :func:`instance_name`).
|
|
6
|
+
Each gets ``ROSTAINER_INSTANCE`` (its number) in its environment, e.g. to
|
|
7
|
+
namespace a launch in ``command``.
|
|
8
|
+
|
|
9
|
+
Instances run what the dev container last built, and never build
|
|
10
|
+
themselves: starting them when none is running takes a *snapshot* -- the
|
|
11
|
+
dev container committed to an image (with what the pre-build script and
|
|
12
|
+
rosdep installed in it), and its build-state volumes copied into each
|
|
13
|
+
instance's own. So a rebuild in the dev container never changes running
|
|
14
|
+
instances; ``rostainer instances restart`` takes a new snapshot.
|
|
15
|
+
|
|
16
|
+
``connected`` says whether they share a ROS graph (with each other and
|
|
17
|
+
the dev container) or each has its own. With DDS that's the domain ID
|
|
18
|
+
(one per instance when not connected). ROS 1 and Zenoh nodes use the
|
|
19
|
+
master/router on their container's ``localhost``, so the network
|
|
20
|
+
decides: under host networking they always share one, on a Docker
|
|
21
|
+
network each container has its own (see :func:`network_problem`).
|
|
22
|
+
"""
|
|
23
|
+
|
|
24
|
+
from __future__ import annotations
|
|
25
|
+
|
|
26
|
+
import argparse
|
|
27
|
+
import re
|
|
28
|
+
import subprocess
|
|
29
|
+
from typing import Dict, List, Optional, Sequence
|
|
30
|
+
|
|
31
|
+
from pydantic import Field
|
|
32
|
+
|
|
33
|
+
from rostainer_cli.plugin_api import (
|
|
34
|
+
MAX_ROS_DOMAIN_ID,
|
|
35
|
+
Command,
|
|
36
|
+
Context,
|
|
37
|
+
DevContainer,
|
|
38
|
+
Plugin,
|
|
39
|
+
PluginConfig,
|
|
40
|
+
RostainerConfig,
|
|
41
|
+
Target,
|
|
42
|
+
bring_up_container,
|
|
43
|
+
core_command,
|
|
44
|
+
is_running,
|
|
45
|
+
log,
|
|
46
|
+
plugin_containers,
|
|
47
|
+
snapshot_dev_container,
|
|
48
|
+
stop_container,
|
|
49
|
+
targets,
|
|
50
|
+
wait_until_healthy,
|
|
51
|
+
warn_about_shared_graph,
|
|
52
|
+
)
|
|
53
|
+
|
|
54
|
+
#: The most instances ``count`` allows.
|
|
55
|
+
MAX_INSTANCES = 64
|
|
56
|
+
|
|
57
|
+
#: Holds an instance's number in its environment.
|
|
58
|
+
INSTANCE_ENV_VAR = "ROSTAINER_INSTANCE"
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
class InstancesConfig(PluginConfig):
|
|
62
|
+
"""The ``[plugins.instances]`` table."""
|
|
63
|
+
|
|
64
|
+
count: int = Field(
|
|
65
|
+
3,
|
|
66
|
+
ge=1,
|
|
67
|
+
le=MAX_INSTANCES,
|
|
68
|
+
description="How many instances of a target 'rostainer instances start' runs.",
|
|
69
|
+
)
|
|
70
|
+
connected: bool = Field(
|
|
71
|
+
True,
|
|
72
|
+
description=(
|
|
73
|
+
"true: one ROS graph for them all and the dev container; false: one each.\n"
|
|
74
|
+
'ROS 1 and Zenoh need network_mode = "host" for true, "bridge" for false.'
|
|
75
|
+
),
|
|
76
|
+
)
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
def instance_name(cfg: RostainerConfig, target: Target, index: int) -> str:
|
|
80
|
+
"""The name of a target's instance ``index``, e.g. ``jazzy-zenoh_my_ws-3``."""
|
|
81
|
+
return f"{cfg.container_name(target)}-{index}"
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
def snapshot_image(cfg: RostainerConfig, target: Target) -> str:
|
|
85
|
+
"""The image a target's instances run: a snapshot of its dev container."""
|
|
86
|
+
repository = re.sub(r"[^a-z0-9._-]+", "-", cfg.container_name(target).lower())
|
|
87
|
+
return f"rostainer-instances/{repository.strip('-._') or 'workspace'}:latest"
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
def domain_id(ctx: Context, index: int) -> int:
|
|
91
|
+
"""An instance's ``ROS_DOMAIN_ID``: the workspace's if instances are
|
|
92
|
+
connected, else one of its own after it (the dev container keeps
|
|
93
|
+
``ros_domain_id``)."""
|
|
94
|
+
settings = ctx.config
|
|
95
|
+
if settings.connected:
|
|
96
|
+
return ctx.cfg.ros_domain_id
|
|
97
|
+
return ctx.cfg.ros_domain_id + 1 + index
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
def network_problem(ctx: Context, target: Target) -> Optional[str]:
|
|
101
|
+
"""Why instances can't work as configured for ``target``, if they can't."""
|
|
102
|
+
cfg, settings = ctx.cfg, ctx.config
|
|
103
|
+
core_on_localhost = target.profile == "ros1" or target.middleware == "rmw_zenoh_cpp"
|
|
104
|
+
core = "roscore" if target.profile == "ros1" else "Zenoh router"
|
|
105
|
+
host = cfg.network_mode == "host"
|
|
106
|
+
if core_on_localhost and settings.connected and not host:
|
|
107
|
+
return (
|
|
108
|
+
f"Connected {target.describe()} instances need network_mode = \"host\": "
|
|
109
|
+
f"on a Docker network each container runs its own {core}, so they can't "
|
|
110
|
+
"share one. Use host networking, or [plugins.instances] connected = false."
|
|
111
|
+
)
|
|
112
|
+
if core_on_localhost and not settings.connected and host:
|
|
113
|
+
return (
|
|
114
|
+
f"Independent {target.describe()} instances need a Docker network "
|
|
115
|
+
f"(network_mode = \"bridge\"): under host networking they all use the "
|
|
116
|
+
f"first {core} on the host's localhost. Use bridge, or "
|
|
117
|
+
"[plugins.instances] connected = true."
|
|
118
|
+
)
|
|
119
|
+
last = domain_id(ctx, settings.count - 1)
|
|
120
|
+
if last > MAX_ROS_DOMAIN_ID:
|
|
121
|
+
return (
|
|
122
|
+
f"Independent instances use ROS_DOMAIN_ID {cfg.ros_domain_id + 1} to {last}, "
|
|
123
|
+
f"past ROS 2's limit of {MAX_ROS_DOMAIN_ID}: lower ros_domain_id or "
|
|
124
|
+
"[plugins.instances] count."
|
|
125
|
+
)
|
|
126
|
+
return None
|
|
127
|
+
|
|
128
|
+
|
|
129
|
+
def instances_of(
|
|
130
|
+
ctx: Context, target: Target, *, all_states: bool = True
|
|
131
|
+
) -> Dict[int, DevContainer]:
|
|
132
|
+
"""The target's instances, by number."""
|
|
133
|
+
return {
|
|
134
|
+
int(container.role): container
|
|
135
|
+
for container in plugin_containers(ctx, target, all_states=all_states)
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
|
|
139
|
+
def start_instances(ctx: Context, target: Target, *, verbose: bool) -> int:
|
|
140
|
+
"""Start the target's ``count`` instances; its dev container must run.
|
|
141
|
+
|
|
142
|
+
When none of them is running, they're all (re)created from a new
|
|
143
|
+
snapshot of the dev container. Otherwise the missing or stopped ones
|
|
144
|
+
are started next to them, from the snapshot they run.
|
|
145
|
+
"""
|
|
146
|
+
cfg, settings = ctx.cfg, ctx.config
|
|
147
|
+
dev = cfg.container_name(target)
|
|
148
|
+
if not is_running(dev):
|
|
149
|
+
log.error(
|
|
150
|
+
f"'{dev}' isn't running: instances run its build. Start it first with "
|
|
151
|
+
"'rostainer start'."
|
|
152
|
+
)
|
|
153
|
+
return 1
|
|
154
|
+
existing = instances_of(ctx, target)
|
|
155
|
+
running = {i for i, c in existing.items() if is_running(c.name)}
|
|
156
|
+
image = snapshot_image(cfg, target)
|
|
157
|
+
if not running:
|
|
158
|
+
for container in existing.values():
|
|
159
|
+
stop_container(ctx, container, remove=True)
|
|
160
|
+
existing = {}
|
|
161
|
+
log.info(f"Waiting for '{dev}' to finish starting...")
|
|
162
|
+
if not wait_until_healthy(dev):
|
|
163
|
+
log.error(f"'{dev}' isn't healthy, so there's no build to run in instances.")
|
|
164
|
+
return 1
|
|
165
|
+
if not snapshot_dev_container(ctx, target, image):
|
|
166
|
+
return 1
|
|
167
|
+
|
|
168
|
+
names = [instance_name(cfg, target, i) for i in range(settings.count)]
|
|
169
|
+
if settings.connected:
|
|
170
|
+
warn_about_shared_graph(
|
|
171
|
+
ctx,
|
|
172
|
+
target,
|
|
173
|
+
name=names[0],
|
|
174
|
+
domain_hint="give this workspace another ros_domain_id",
|
|
175
|
+
isolate_hint="use [plugins.instances] connected = false with a Docker network",
|
|
176
|
+
expected=[dev, *names],
|
|
177
|
+
)
|
|
178
|
+
|
|
179
|
+
for index in range(settings.count):
|
|
180
|
+
if index in running:
|
|
181
|
+
log.info(f"Instance {index} ({names[index]}) is already running.")
|
|
182
|
+
continue
|
|
183
|
+
create = index not in existing
|
|
184
|
+
log.info(
|
|
185
|
+
f"{'Creating' if create else 'Resuming'} instance {index} ({names[index]})..."
|
|
186
|
+
)
|
|
187
|
+
exit_code = bring_up_container(
|
|
188
|
+
ctx,
|
|
189
|
+
target,
|
|
190
|
+
role=str(index),
|
|
191
|
+
name=names[index],
|
|
192
|
+
image=image,
|
|
193
|
+
create=create,
|
|
194
|
+
environment={INSTANCE_ENV_VAR: str(index)},
|
|
195
|
+
ros_domain_id=domain_id(ctx, index),
|
|
196
|
+
verbose=verbose,
|
|
197
|
+
)
|
|
198
|
+
if exit_code:
|
|
199
|
+
return exit_code
|
|
200
|
+
|
|
201
|
+
extra = sorted(i for i in existing if i >= settings.count)
|
|
202
|
+
if extra:
|
|
203
|
+
log.warning(
|
|
204
|
+
f"Instances {', '.join(map(str, extra))} are past [plugins.instances] count = "
|
|
205
|
+
f"{settings.count}; 'rostainer instances stop' stops them."
|
|
206
|
+
)
|
|
207
|
+
how = (
|
|
208
|
+
"sharing a ROS graph with the dev container"
|
|
209
|
+
if settings.connected
|
|
210
|
+
else "each on a ROS graph of its own"
|
|
211
|
+
)
|
|
212
|
+
log.ok(f"{settings.count} instances of {target.describe()} are running, {how}.")
|
|
213
|
+
print(
|
|
214
|
+
" 'rostainer instances shell N' opens a shell in instance N; 'rostainer "
|
|
215
|
+
"instances restart' replaces them with the dev container's current build."
|
|
216
|
+
)
|
|
217
|
+
return 0
|
|
218
|
+
|
|
219
|
+
|
|
220
|
+
def remove_instances(ctx: Context, target: Target) -> None:
|
|
221
|
+
"""Remove all of the target's instances, with their copies of the build."""
|
|
222
|
+
for container in instances_of(ctx, target).values():
|
|
223
|
+
stop_container(ctx, container, remove=True)
|
|
224
|
+
|
|
225
|
+
|
|
226
|
+
class InstancesCommand(Command):
|
|
227
|
+
"""``rostainer instances <start|restart|stop|status|shell|logs>``."""
|
|
228
|
+
|
|
229
|
+
name = "instances"
|
|
230
|
+
summary = "Run copies of a ROS environment next to it, for simulation and tests"
|
|
231
|
+
|
|
232
|
+
def add_arguments(self, parser: argparse.ArgumentParser) -> None:
|
|
233
|
+
actions = parser.add_subparsers(dest="action", metavar="ACTION")
|
|
234
|
+
actions.required = True
|
|
235
|
+
for action, help_text in (
|
|
236
|
+
("start", "Start the target's instances (from a new snapshot if none runs)"),
|
|
237
|
+
("restart", "Replace the target's instances with the dev container's current build"),
|
|
238
|
+
):
|
|
239
|
+
sub = actions.add_parser(action, help=help_text)
|
|
240
|
+
targets.add_arguments(sub)
|
|
241
|
+
sub.add_argument(
|
|
242
|
+
"-v", "--verbose", action="store_true", help="Stream container output"
|
|
243
|
+
)
|
|
244
|
+
stop = actions.add_parser("stop", help="Stop instances (all, or instance N)")
|
|
245
|
+
stop.add_argument("index", nargs="?", type=int, metavar="N")
|
|
246
|
+
stop.add_argument(
|
|
247
|
+
"--rm", action="store_true", help="Remove them, with their copies of the build"
|
|
248
|
+
)
|
|
249
|
+
actions.add_parser("status", help="List the workspace's instances")
|
|
250
|
+
for action in ("shell", "logs"):
|
|
251
|
+
sub = actions.add_parser(
|
|
252
|
+
action, help=f"{'A shell in' if action == 'shell' else 'The logs of'} instance N"
|
|
253
|
+
)
|
|
254
|
+
sub.add_argument("index", type=int, metavar="N")
|
|
255
|
+
sub.add_argument("rest", nargs=argparse.REMAINDER, help=argparse.SUPPRESS)
|
|
256
|
+
|
|
257
|
+
def run(self, args: argparse.Namespace, ctx: Optional[Context]) -> int:
|
|
258
|
+
assert ctx is not None
|
|
259
|
+
if args.action in ("start", "restart"):
|
|
260
|
+
return self._start(args, ctx, replace=args.action == "restart")
|
|
261
|
+
if args.action == "stop":
|
|
262
|
+
return self._stop(args, ctx)
|
|
263
|
+
if args.action == "status":
|
|
264
|
+
return self._status(ctx)
|
|
265
|
+
return self._enter(args, ctx)
|
|
266
|
+
|
|
267
|
+
def _start(self, args: argparse.Namespace, ctx: Context, *, replace: bool) -> int:
|
|
268
|
+
target = targets.select_target(ctx.cfg, args.distro, args.middleware)
|
|
269
|
+
if target is None:
|
|
270
|
+
return 1
|
|
271
|
+
problem = network_problem(ctx, target)
|
|
272
|
+
if problem:
|
|
273
|
+
log.error(problem)
|
|
274
|
+
return 1
|
|
275
|
+
if replace:
|
|
276
|
+
remove_instances(ctx, target)
|
|
277
|
+
return start_instances(ctx, target, verbose=args.verbose)
|
|
278
|
+
|
|
279
|
+
def _stop(self, args: argparse.Namespace, ctx: Context) -> int:
|
|
280
|
+
pool = [
|
|
281
|
+
container
|
|
282
|
+
for container in plugin_containers(ctx, all_states=args.rm)
|
|
283
|
+
if args.index is None or container.role == str(args.index)
|
|
284
|
+
]
|
|
285
|
+
if not pool:
|
|
286
|
+
what = "No instances" if args.index is None else f"No instance {args.index}"
|
|
287
|
+
print(f"{what} {'exist' if args.rm else 'running'}.")
|
|
288
|
+
return 0
|
|
289
|
+
for container in pool:
|
|
290
|
+
stop_container(ctx, container, remove=args.rm)
|
|
291
|
+
return 0
|
|
292
|
+
|
|
293
|
+
def _status(self, ctx: Context) -> int:
|
|
294
|
+
containers = plugin_containers(ctx)
|
|
295
|
+
if not containers:
|
|
296
|
+
print("No instances exist. 'rostainer instances start' starts them.")
|
|
297
|
+
return 0
|
|
298
|
+
for container in containers:
|
|
299
|
+
state = "running" if is_running(container.name) else "stopped"
|
|
300
|
+
log.info(f"{container.describe()}: {state}")
|
|
301
|
+
return 0
|
|
302
|
+
|
|
303
|
+
def _enter(self, args: argparse.Namespace, ctx: Context) -> int:
|
|
304
|
+
matches = [
|
|
305
|
+
container
|
|
306
|
+
for container in plugin_containers(ctx, all_states=False)
|
|
307
|
+
if container.role == str(args.index)
|
|
308
|
+
]
|
|
309
|
+
if not matches:
|
|
310
|
+
log.error(f"No instance {args.index} is running.")
|
|
311
|
+
return 1
|
|
312
|
+
if len(matches) > 1:
|
|
313
|
+
log.error(
|
|
314
|
+
f"Instance {args.index} of several targets is running: "
|
|
315
|
+
f"'rostainer {args.action}' asks which."
|
|
316
|
+
)
|
|
317
|
+
return 1
|
|
318
|
+
return core_command(args.action, [matches[0].name, *args.rest])
|
|
319
|
+
|
|
320
|
+
|
|
321
|
+
class InstancesPlugin(Plugin):
|
|
322
|
+
"""Several copies of a target next to its dev container."""
|
|
323
|
+
|
|
324
|
+
name = "instances"
|
|
325
|
+
api_version = 1
|
|
326
|
+
summary = "Several copies of a ROS environment, for simulation and testing"
|
|
327
|
+
config_model = InstancesConfig
|
|
328
|
+
|
|
329
|
+
def commands(self) -> Sequence[Command]:
|
|
330
|
+
return [InstancesCommand()]
|
|
331
|
+
|
|
332
|
+
def owns_container(self, ctx: Context, container: DevContainer) -> bool:
|
|
333
|
+
"""Only under the name its instance has now (not, e.g., from before a
|
|
334
|
+
``ros_container_suffix`` change)."""
|
|
335
|
+
return (
|
|
336
|
+
container.target is not None
|
|
337
|
+
and container.role.isdigit()
|
|
338
|
+
and container.name == instance_name(ctx.cfg, container.target, int(container.role))
|
|
339
|
+
)
|
|
340
|
+
|
|
341
|
+
def prunable_images(self, ctx: Context, removed: Sequence[str]) -> List[str]:
|
|
342
|
+
"""Snapshots no container uses: starting instances when none runs
|
|
343
|
+
takes a new one anyway."""
|
|
344
|
+
snapshots = _lines(
|
|
345
|
+
[
|
|
346
|
+
"docker",
|
|
347
|
+
"image",
|
|
348
|
+
"ls",
|
|
349
|
+
"--filter",
|
|
350
|
+
"reference=rostainer-instances/*",
|
|
351
|
+
"--format",
|
|
352
|
+
"{{.Repository}}:{{.Tag}}",
|
|
353
|
+
]
|
|
354
|
+
)
|
|
355
|
+
if not snapshots:
|
|
356
|
+
return []
|
|
357
|
+
used = {
|
|
358
|
+
line.split("\t")[1]
|
|
359
|
+
for line in _lines(["docker", "ps", "-a", "--format", "{{.Names}}\t{{.Image}}"])
|
|
360
|
+
if "\t" in line and line.split("\t")[0] not in removed
|
|
361
|
+
}
|
|
362
|
+
return [image for image in snapshots if image not in used]
|
|
363
|
+
|
|
364
|
+
|
|
365
|
+
def _lines(args: List[str]) -> List[str]:
|
|
366
|
+
proc = subprocess.run(args, capture_output=True, text=True, check=False)
|
|
367
|
+
return [line for line in proc.stdout.splitlines() if line.strip()]
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: rostainer-instances
|
|
3
|
+
Version: 0.0.3
|
|
4
|
+
Summary: rostainer plugin: run several copies of a ROS environment, for simulation and testing
|
|
5
|
+
Project-URL: Homepage, https://git.whoi.edu/bmillerklugman/rostainer
|
|
6
|
+
Project-URL: Documentation, https://bmillerklugman.pages.whoi.edu/rostainer/
|
|
7
|
+
Author: rostainer contributors
|
|
8
|
+
License-Expression: MIT
|
|
9
|
+
Keywords: docker,ros,ros2,rostainer,simulation
|
|
10
|
+
Requires-Python: >=3.7
|
|
11
|
+
Requires-Dist: rostainer
|
|
12
|
+
Description-Content-Type: text/markdown
|
|
13
|
+
|
|
14
|
+
# rostainer-instances
|
|
15
|
+
|
|
16
|
+
A [rostainer](https://bmillerklugman.pages.whoi.edu/rostainer/) plugin that runs
|
|
17
|
+
several copies ("instances") of a ROS environment next to its dev container, for
|
|
18
|
+
simulation or parallel tests. Each runs the dev container's last build.
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
pip install rostainer[instances] # or: pip install rostainer-instances
|
|
22
|
+
rostainer init --with instances # adds [plugins.instances] to .rostainer.toml
|
|
23
|
+
rostainer start # the dev container builds the workspace
|
|
24
|
+
rostainer instances start # then the instances run that build
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
```toml
|
|
28
|
+
[plugins.instances]
|
|
29
|
+
count = 3 # how many
|
|
30
|
+
connected = true # one ROS graph for them all and the dev container (false: one each)
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
| Command | What it does |
|
|
34
|
+
|---|---|
|
|
35
|
+
| `rostainer instances start [DISTRO]` | Start the target's instances. When none runs, they're (re)created from a new snapshot of the dev container. |
|
|
36
|
+
| `rostainer instances restart [DISTRO]` | Replace them with the dev container's current build. |
|
|
37
|
+
| `rostainer instances stop [N] [--rm]` | Stop them (or instance N); `--rm` removes them. |
|
|
38
|
+
| `rostainer instances status` | List them. |
|
|
39
|
+
| `rostainer instances shell N` / `logs N` | A shell in instance N, or its logs. |
|
|
40
|
+
|
|
41
|
+
Each instance gets `$ROSTAINER_INSTANCE` (0, 1, ...) to tell them apart, e.g. in
|
|
42
|
+
`command`. ROS 1 and Zenoh need `network_mode = "host"` for connected instances,
|
|
43
|
+
and a Docker network (`"bridge"`) for independent ones.
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
rostainer_instances/__init__.py,sha256=_tGsEA55bKOohoxKH2JSWOYkdhZ0_ldhWZSWVUolXhQ,14129
|
|
2
|
+
rostainer_instances-0.0.3.dist-info/METADATA,sha256=fEFweUQzSxsX2xSZYJ3QI-RUc6h7Be1jrikCupv31xY,1960
|
|
3
|
+
rostainer_instances-0.0.3.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
|
|
4
|
+
rostainer_instances-0.0.3.dist-info/entry_points.txt,sha256=XbaKXyINX00vl5mGmoHfDC0P8o4XGof2TSGNQ0Frd8w,68
|
|
5
|
+
rostainer_instances-0.0.3.dist-info/RECORD,,
|