feat(operations.docker): add login/logout operations (#1694)

Author: wowi42

src/pyinfra/facts/docker.py

@@ -392,3 +392,27 @@ def command(self, image_id) -> str:
         return (
             "docker image history --no-trunc --format '{{{{json .}}}}' {0} 2>&- || true"
         ).format(image_id)
+
+
+class DockerAuths(FactBase[list[str]]):
+    """
+    Returns the list of registry servers the current user is authenticated
+    against, read from ``${DOCKER_CONFIG:-$HOME/.docker}/config.json``.
+
+    Returns an empty list if no config file exists or no auths are stored.
+    """
+
+    @override
+    def command(self) -> str:
+        return (
+            'config="${DOCKER_CONFIG:-$HOME/.docker}/config.json"; '
+            '[ -r "$config" ] && cat "$config" || echo "{}"'
+        )
+
+    @override
+    def process(self, output: list[str]) -> list[str]:
+        try:
+            data = json.loads("".join(output))
+        except json.JSONDecodeError:
+            return []
+        return list(data.get("auths", {}).keys())

src/pyinfra/operations/docker.py

@@ -6,16 +6,21 @@
 
 from __future__ import annotations
 
+from shlex import quote as shlex_quote
+
 from pyinfra import host
-from pyinfra.api import operation
+from pyinfra.api import MaskString, OperationError, QuoteString, StringCommand, operation
 from pyinfra.facts.docker import (
+    DockerAuths,
     DockerContainer,
     DockerImage,
     DockerNetwork,
     DockerPlugin,
     DockerVolume,
 )
 
+DOCKER_HUB_SERVER = "https://index.docker.io/v1/"
+
 from .util.docker import ContainerSpec, handle_docker, parse_image_reference
 
 
@@ -554,3 +559,112 @@ def plugin(
             command="remove",
             plugin=plugin_name,
         )
+
+
+@operation()
+def login(
+    username: str,
+    password: str,
+    server: str | None = None,
+    force: bool = False,
+):
+    """
+    Log in to a Docker registry.
+
+    + username: username to authenticate with
+    + password: password to authenticate with
+    + server: registry server to log in to (defaults to Docker Hub)
+    + force: log in even if ``~/.docker/config.json`` already has an entry for the server
+
+    Idempotency is checked against the ``auths`` section of
+    ``${DOCKER_CONFIG:-$HOME/.docker}/config.json``: if the server is already
+    present, the operation is a no-op. Use ``force=True`` to re-run ``docker
+    login`` (e.g. after rotating credentials).
+
+    The password is piped to ``docker login --password-stdin`` so it is not
+    exposed on the command line, and is masked in pyinfra's command log.
+
+    **Examples:**
+
+    .. code:: python
+
+        from pyinfra.operations import docker
+
+        # Log in to a private registry
+        docker.login(
+            name="Log in to private registry",
+            server="myregistry.io:5000",
+            username="ci",
+            password="s3cret",
+        )
+
+        # Log in to Docker Hub
+        docker.login(
+            name="Log in to Docker Hub",
+            username="ci",
+            password="s3cret",
+        )
+    """
+    if not username:
+        raise OperationError("docker.login requires a username")
+    if not password:
+        raise OperationError("docker.login requires a password")
+
+    target_server = server or DOCKER_HUB_SERVER
+
+    if not force:
+        existing_auths = host.get_fact(DockerAuths)
+        if target_server in existing_auths:
+            host.noop(f"Already logged in to Docker registry {target_server}")
+            return
+
+    command_bits: list = [
+        "printf '%s'",
+        MaskString(shlex_quote(password)),
+        "| docker login --username",
+        QuoteString(username),
+        "--password-stdin",
+    ]
+    if server:
+        command_bits.append(QuoteString(server))
+
+    yield StringCommand(*command_bits)
+
+
+@operation()
+def logout(server: str | None = None):
+    """
+    Log out of a Docker registry.
+
+    + server: registry server to log out of (defaults to Docker Hub)
+
+    No-ops when the server is not present in
+    ``${DOCKER_CONFIG:-$HOME/.docker}/config.json``.
+
+    **Examples:**
+
+    .. code:: python
+
+        from pyinfra.operations import docker
+
+        # Log out of a private registry
+        docker.logout(
+            name="Log out of private registry",
+            server="myregistry.io:5000",
+        )
+
+        # Log out of Docker Hub
+        docker.logout(name="Log out of Docker Hub")
+    """
+    target_server = server or DOCKER_HUB_SERVER
+
+    existing_auths = host.get_fact(DockerAuths)
+    if target_server not in existing_auths:
+        host.noop(f"Not logged in to Docker registry {target_server}")
+        return
+
+    command_bits: list = ["docker logout"]
+    if server:
+        command_bits.append(QuoteString(server))
+
+    yield StringCommand(*command_bits)

tests/facts/docker.DockerAuths/malformed_config.json

@@ -0,0 +1,5 @@
+{
+    "command": "config=\"${DOCKER_CONFIG:-$HOME/.docker}/config.json\"; [ -r \"$config\" ] && cat \"$config\" || echo \"{}\"",
+    "output": ["not json at all"],
+    "fact": []
+}

tests/facts/docker.DockerAuths/no_config_file.json

@@ -0,0 +1,5 @@
+{
+    "command": "config=\"${DOCKER_CONFIG:-$HOME/.docker}/config.json\"; [ -r \"$config\" ] && cat \"$config\" || echo \"{}\"",
+    "output": ["{}"],
+    "fact": []
+}

tests/facts/docker.DockerAuths/with_auths.json

@@ -0,0 +1,7 @@
+{
+    "command": "config=\"${DOCKER_CONFIG:-$HOME/.docker}/config.json\"; [ -r \"$config\" ] && cat \"$config\" || echo \"{}\"",
+    "output": [
+        "{\"auths\": {\"https://index.docker.io/v1/\": {\"auth\": \"xxx\"}, \"myregistry.io:5000\": {\"auth\": \"yyy\"}}}"
+    ],
+    "fact": ["https://index.docker.io/v1/", "myregistry.io:5000"]
+}

tests/operations/docker.login/login_force_reauth.json

@@ -0,0 +1,14 @@
+{
+    "kwargs": {
+        "username": "ci",
+        "password": "newpw",
+        "server": "myregistry.io:5000",
+        "force": true
+    },
+    "commands": [
+        {
+            "raw": "printf '%s' newpw | docker login --username ci --password-stdin myregistry.io:5000",
+            "masked": "printf '%s' *** | docker login --username ci --password-stdin myregistry.io:5000"
+        }
+    ]
+}

tests/operations/docker.login/login_noop_docker_hub_when_already_authenticated.json

@@ -0,0 +1,11 @@
+{
+    "kwargs": {
+        "username": "ci",
+        "password": "s3cret"
+    },
+    "facts": {
+        "docker.DockerAuths": ["https://index.docker.io/v1/"]
+    },
+    "commands": [],
+    "noop_description": "Already logged in to Docker registry https://index.docker.io/v1/"
+}

tests/operations/docker.login/login_noop_when_already_authenticated.json

@@ -0,0 +1,12 @@
+{
+    "kwargs": {
+        "username": "ci",
+        "password": "s3cret",
+        "server": "myregistry.io:5000"
+    },
+    "facts": {
+        "docker.DockerAuths": ["myregistry.io:5000"]
+    },
+    "commands": [],
+    "noop_description": "Already logged in to Docker registry myregistry.io:5000"
+}

tests/operations/docker.login/login_to_docker_hub.json

@@ -0,0 +1,15 @@
+{
+    "kwargs": {
+        "username": "ci",
+        "password": "s3cret"
+    },
+    "facts": {
+        "docker.DockerAuths": []
+    },
+    "commands": [
+        {
+            "raw": "printf '%s' s3cret | docker login --username ci --password-stdin",
+            "masked": "printf '%s' *** | docker login --username ci --password-stdin"
+        }
+    ]
+}

tests/operations/docker.login/login_to_private_registry.json

@@ -0,0 +1,16 @@
+{
+    "kwargs": {
+        "username": "ci",
+        "password": "s3cret",
+        "server": "myregistry.io:5000"
+    },
+    "facts": {
+        "docker.DockerAuths": []
+    },
+    "commands": [
+        {
+            "raw": "printf '%s' s3cret | docker login --username ci --password-stdin myregistry.io:5000",
+            "masked": "printf '%s' *** | docker login --username ci --password-stdin myregistry.io:5000"
+        }
+    ]
+}