Skip to content

podman

podman

Podman helpers shared by the terok packages.

Exposes helpers that spell podman arguments correctly for the host's podman release: user-namespace mapping for rootless invocations and the force-pull flag for image builds.

__all__ = ['podman_pull_always_args', 'podman_userns_args'] module-attribute

podman_userns_args()

Return user namespace args for rootless podman so UID 1000 maps correctly.

Maps the host user to container UID/GID 1000, the conventional non-root dev user in terok container images. Returns an empty list when running as root — root podman runs in the host user namespace and has no need to remap.

Podman releases older than 4.3 predate the keep-id:uid=… customization; for those the same mapping is spelled out as explicit --uidmap/--gidmap triples, assuming the standard 65536-ID subordinate allotment.

Source code in src/terok_util/podman.py 
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
def podman_userns_args() -> list[str]:
    """Return user namespace args for rootless podman so UID 1000 maps correctly.

    Maps the host user to container UID/GID 1000, the conventional non-root
    ``dev`` user in terok container images.  Returns an empty list when
    running as root — root podman runs in the host user namespace and
    has no need to remap.

    Podman releases older than 4.3 predate the ``keep-id:uid=…``
    customization; for those the same mapping is spelled out as explicit
    ``--uidmap``/``--gidmap`` triples, assuming the standard 65536-ID
    subordinate allotment.
    """
    if os.geteuid() == 0:
        return []
    if _podman_version() >= _KEEP_ID_UID_MIN:
        return [f"--userns=keep-id:uid={_DEV_ID},gid={_DEV_ID}"]
    mappings = (
        f"0:1:{_DEV_ID}",  # container 0..dev-1  <- subordinate IDs
        f"{_DEV_ID}:0:1",  # container dev       <- the host user itself
        f"{_DEV_ID + 1}:{_DEV_ID + 1}:{_ID_SPAN - _DEV_ID - 1}",  # the rest, identity
    )
    return [arg for flag in ("--uidmap", "--gidmap") for m in mappings for arg in (flag, m)]

podman_pull_always_args()

Return the podman build flags that force re-pulling base images.

Podman 4.0 turned --pull into a policy option (--pull=always); older releases take --pull as a boolean and reject the policy form outright, spelling the same request --pull-always instead.

Source code in src/terok_util/podman.py 
56
57
58
59
60
61
62
63
64
65
def podman_pull_always_args() -> list[str]:
    """Return the ``podman build`` flags that force re-pulling base images.

    Podman 4.0 turned ``--pull`` into a policy option (``--pull=always``);
    older releases take ``--pull`` as a boolean and reject the policy
    form outright, spelling the same request ``--pull-always`` instead.
    """
    if _podman_version() >= _PULL_POLICY_MIN:
        return ["--pull=always"]
    return ["--pull-always"]