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,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,2 @@
1
+ [rostainer.plugins]
2
+ instances = rostainer_instances:InstancesPlugin