feat(container-engine): reach rootful Podman like Docker (NetOrk/netork#818) #123
No files matched your search
@@ -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///<host>/…`, 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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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,
|
||||
)
|
||||
@@ -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")
|
||||
|
||||
|
||||
Reference in new issue
Block a user