diff --git a/CHANGELOG.md b/CHANGELOG.md index 6ed0b21..99b32fc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,10 @@ recorded here; their history is the git log. ## [Unreleased] ### Added +- Podman as a container engine (NetOrk/netork#818): `container_engines()` lists it with the + API `podman-libpod`, and `open_container_engine("podman")` reaches it with `podman system + dial-stdio` (Podman 4.0 and later). It is the host's rootful Podman, so the connection + runs every call as root (`ContainerEngineConnection.privileged`, `ROOT_ENGINES`). - `apt_sources`: apt's https sources through the package cache, in the form apt-cacher-ng fetches over https itself and stores (`http://HTTPS////…`, with `AllowUserPorts=80 443` on the cache). `cacheable_https_hosts(report)` names the hosts this applies to, and @@ -18,6 +22,8 @@ recorded here; their history is the git log. - `get_package_proxy_report()` reports those hosts as `not_cached`. ### Changed +- `container_engines()` lists an engine only when its CLI names itself on `--version`: + podman-docker's `docker` is podman, and is no longer listed as Docker. - `configure_package_proxy(url)` has a step `cache` before `https`. It rewrites the https sources it can, fetches one of them through *url*, and turns them all back to https where *url* cannot. The `fetch` step proves the proxy with a plain http source only. diff --git a/README.md b/README.md index 99c3aab..fb507e9 100644 --- a/README.md +++ b/README.md @@ -403,10 +403,11 @@ but not revert sets `revert_config_revision = None`. The mixin sits in `DeviceTypeDriver` and only declares, so `hasattr(driver, "run_command")` is true exactly where a driver implements it. For SSH drivers, `channel.run_on_transport` and `channel.open_stream_on_transport` are the implementation over a paramiko exec channel: no PTY, stderr kept apart, a real exit code. How a command gains root stays with the driver. **`ContainerEngineMixin` is deliberately different from `SystemdServicesMixin`.** The systemd mixin owns its command and its parse; this one owns neither. -- `container_engines()` says which engines the host offers (`[{"engine": "docker", "api": "docker-engine"}]`). +- `container_engines()` says which engines the host offers (`[{"engine": "docker", "api": "docker-engine"}, {"engine": "podman", "api": "podman-libpod"}]`). An engine is listed when its CLI answers `--version` with its own name; podman-docker's `docker` says it is podman and is left out. - `open_container_engine(engine)` returns a `ContainerEngineConnection`: - - `open_api()` is a stream to the engine's API (`docker system dial-stdio`); + - `open_api()` is a stream to the engine's API (`docker system dial-stdio`, `podman system dial-stdio`); - `run_cli(args)` and `stream_cli(args)` run the engine's CLI with arguments the caller chooses. With `privileged=True` the driver runs it the way `run_command` gains root, for an engine that refuses the login user. +- **Podman is reached as root** (`ROOT_ENGINES`, `connection.privileged`): the host's rootful Podman, the engine of the system's containers and of Quadlet's units, whose API `podman.socket` serves. A login user's rootless containers are that user's own and invisible to others. `podman system dial-stdio` exists from Podman 4.0 on and needs the socket listening (`systemctl enable --now podman.socket`) (NetOrk/netork#818). - The driver decides only *how* the engine is reached. Its hook `_container_engine_binary(engine)` returns, for QNAP, the Container Station path, and the caller never sees it. **What runs on the engine, and what to do with it, is netOrk's** (NetOrk/netork#765): the container model, the Engine API requests, compose, updates. Above the connection everything is specific to the service, so this package abstracts the connection and nothing more. diff --git a/napalm_device_types/container_engine.py b/napalm_device_types/container_engine.py index f0e35f7..8b30e32 100644 --- a/napalm_device_types/container_engine.py +++ b/napalm_device_types/container_engine.py @@ -23,6 +23,22 @@ Mixed in by a driver, not by a role base: a Windows host is an :class:`~napalm_device_types.os.OSDriver` too, and without a shell channel it has no ``dial-stdio`` to offer. ``hasattr(driver, "open_container_engine")`` stays truthful. + +**Which engine a CLI is.** An engine is listed when its CLI answers +``--version`` with its own name: ``Docker version 29.0.1, build …``, ``podman +version 5.2.2``. podman-docker installs a ``docker`` that is podman; listed as +Docker it would be read twice, the second time as the login user's rootless +Podman (NetOrk/netork#818). + +**Podman as root.** The Podman this reaches is the host's *rootful* one: the +engine of the system's containers, whose units Quadlet generates from +``/etc/containers/systemd`` and whose API ``podman.socket`` serves at +``/run/podman/podman.sock``. Rootless containers belong to the user who runs +them, in that user's own storage, and no other login sees them. So the +connection to Podman runs every call as root (``privileged``), the way the +driver gains root for any command: root itself, or sudo. ``podman system +dial-stdio`` exists from Podman 4.0 on; it reaches the API socket, which has +to be listening (``systemctl enable --now podman.socket``). """ from __future__ import annotations @@ -34,8 +50,11 @@ from typing import TYPE_CHECKING, Any, cast from napalm_device_types.channel import ByteStream, CommandResult from napalm_device_types.models import ContainerEngineDict, FixResultDict -#: Engines this package knows how to reach, and the API each speaks. -ENGINES: dict[str, str] = {"docker": "docker-engine"} +#: Engines this package knows how to reach, and the API each speaks. Podman's +#: is its own service, which serves Docker's API next to libpod's. +ENGINES: dict[str, str] = {"docker": "docker-engine", "podman": "podman-libpod"} +#: Engines reached as root: rootful Podman's socket is root's (see above). +ROOT_ENGINES: frozenset[str] = frozenset({"podman"}) _PROBE_TIMEOUT = 15 _CLI_TIMEOUT = 120 @@ -52,17 +71,24 @@ class ContainerEngineConnection: arguments; binary, quoting and the channel are the driver's. """ - def __init__(self, driver: Any, engine: str, binary: str) -> None: + def __init__(self, driver: Any, engine: str, binary: str, *, privileged: bool = False) -> None: self._driver = driver self._binary = binary self.engine = engine + #: Every call runs as root: the engine is root's (rootful Podman). + self.privileged = privileged def _command(self, args: Sequence[str]) -> str: return shlex.join([self._binary, *args]) def open_api(self) -> ByteStream: """A stream to the engine's API: HTTP/1.1 over ``system dial-stdio``.""" - return cast(ByteStream, self._driver.open_stream(self._command(["system", "dial-stdio"]))) + return cast( + ByteStream, + self._driver.open_stream( + self._command(["system", "dial-stdio"]), privileged=self.privileged + ), + ) def run_cli( self, @@ -80,7 +106,10 @@ class ContainerEngineConnection: return cast( CommandResult, self._driver.run_command( - self._command(args), privileged=privileged, timeout=timeout, stdin=stdin + self._command(args), + privileged=privileged or self.privileged, + timeout=timeout, + stdin=stdin, ), ) @@ -96,7 +125,8 @@ class ContainerEngineConnection: return cast( ByteStream, self._driver.open_stream( - f"{command} 2>&1" if merge_stderr else command, privileged=privileged + f"{command} 2>&1" if merge_stderr else command, + privileged=privileged or self.privileged, ), ) @@ -134,20 +164,32 @@ class ContainerEngineMixin: * engine (string) - e.g. "docker" * api (string) - what its API is, e.g. "docker-engine" - An engine is listed when its CLI exists on the host. Whether the login - user may use it is decided by the first API call, which says - "permission denied" in the stream's stderr. + An engine is listed when its CLI exists on the host and names itself + when asked for its version: podman-docker's ``docker`` says it is podman, + and is left out. Whether the login user may use the engine is decided by + the first API call, which says "permission denied" in the stream's stderr. """ - found: list[ContainerEngineDict] = [] - for engine, api in ENGINES.items(): - probe = shlex.join(["command", "-v", self._container_engine_binary(engine)]) - result = self.run_command(probe, timeout=_PROBE_TIMEOUT) - if result.exit_code == 0 and result.stdout.strip(): - found.append({"engine": engine, "api": api}) - return found + return [ + {"engine": engine, "api": api} + for engine, api in ENGINES.items() + if self._answers_as(engine) + ] + + def _answers_as(self, engine: str) -> bool: + """Whether *engine*'s CLI is on the host and says it is *engine*.""" + binary = shlex.quote(self._container_engine_binary(engine)) + probe = f"command -v {binary} >/dev/null 2>&1 && {binary} --version" + result = self.run_command(probe, timeout=_PROBE_TIMEOUT) + words = result.stdout.split() + return result.exit_code == 0 and bool(words) and words[0].lower() == engine def open_container_engine(self, engine: str) -> ContainerEngineConnection: """The connection to *engine*; :class:`ContainerEngineUnavailable` if unknown.""" if engine not in ENGINES: raise ContainerEngineUnavailable(f"no way to reach container engine {engine!r}") - return ContainerEngineConnection(self, engine, self._container_engine_binary(engine)) + return ContainerEngineConnection( + self, + engine, + self._container_engine_binary(engine), + privileged=engine in ROOT_ENGINES, + ) diff --git a/tests/test_container_engine.py b/tests/test_container_engine.py index 24db7da..ce7d006 100644 --- a/tests/test_container_engine.py +++ b/tests/test_container_engine.py @@ -19,30 +19,40 @@ from napalm_device_types.container_engine import ( ContainerEngineUnavailable, ) +#: What each engine's CLI says to ``--version``. +VERSIONS = { + "docker": "Docker version 29.0.1, build 1a2b3c4", + "podman": "podman version 5.2.2", +} + class FakeDriver(ContainerEngineMixin): - """A driver with a channel: records what it is asked to run.""" + """A driver with a channel: records what it is asked to run. - def __init__(self, present=("docker",), binary=None): + *present* are the engines whose CLI is installed; *says* overrides what an + engine's CLI answers to ``--version`` (podman-docker's ``docker`` is podman). + """ + + def __init__(self, present=("docker",), binary=None, says=None): self.present = set(present) self.binary = binary + self.says = dict(says or {}) self.commands = [] self.streams = [] def run_command(self, command, *, privileged=False, timeout=60, stdin=None): self.commands.append((command, privileged, timeout, stdin)) - found = any(command == f"command -v {b}" for b in self._binaries()) - return CommandResult( - stdout="/usr/bin/x\n" if found else "", stderr="", exit_code=0 if found else 1 - ) + for engine in self.present: + b = self._container_engine_binary(engine) + if command == f"command -v {b} >/dev/null 2>&1 && {b} --version": + answer = self.says.get(engine, VERSIONS[engine]) + return CommandResult(stdout=answer + "\n", stderr="", exit_code=0) + return CommandResult(stdout="", stderr="", exit_code=1) def open_stream(self, command, *, privileged=False): self.streams.append((command, privileged)) return object() - def _binaries(self): - return {self._container_engine_binary(e) for e in self.present} - def _container_engine_binary(self, engine): return self.binary or super()._container_engine_binary(engine) @@ -123,6 +133,60 @@ def test_an_unknown_engine_is_refused(): FakeDriver().open_container_engine("rkt") +class TestPodman: + """Podman, reached the way Docker is (NetOrk/netork#818). + + Its API is Podman's own service, which also speaks Docker's: netOrk reads the + host's *rootful* Podman, the engine of the system's containers (Quadlet units + in ``/etc/containers/systemd``, ``podman.socket``). A login user's rootless + containers are that user's own and invisible to anybody else, so the + connection to Podman runs as root, the way the driver gains root for any command. + """ + + def test_a_host_with_podman_lists_it_with_its_api(self): + driver = FakeDriver(present=("podman",)) + + assert driver.container_engines() == [{"engine": "podman", "api": "podman-libpod"}] + + def test_a_host_with_both_lists_both(self): + driver = FakeDriver(present=("docker", "podman")) + + assert driver.container_engines() == [ + {"engine": "docker", "api": "docker-engine"}, + {"engine": "podman", "api": "podman-libpod"}, + ] + + def test_podman_docker_is_not_docker(self): + """podman-docker installs a ``docker`` that runs podman: listing it as + Docker would read the login user's rootless Podman a second time.""" + driver = FakeDriver(present=("docker", "podman"), says={"docker": VERSIONS["podman"]}) + + assert driver.container_engines() == [{"engine": "podman", "api": "podman-libpod"}] + + def test_the_api_stream_runs_as_root(self): + driver = FakeDriver(present=("podman",)) + + driver.open_container_engine("podman").open_api() + + assert driver.streams == [("podman system dial-stdio", True)] + + def test_the_cli_runs_as_root_too(self): + driver = FakeDriver(present=("podman",)) + conn = driver.open_container_engine("podman") + + conn.run_cli(["pull", "nginx"]) + conn.stream_cli(["pull", "nginx"]) + + assert driver.commands[-1][:2] == ("podman pull nginx", True) + assert driver.streams == [("podman pull nginx", True)] + + def test_the_connection_says_it_runs_as_root(self): + driver = FakeDriver(present=("docker", "podman")) + + assert driver.open_container_engine("podman").privileged is True + assert driver.open_container_engine("docker").privileged is False + + def test_the_connection_names_its_engine(): conn = FakeDriver().open_container_engine("docker")