operations: modernize apt.key to replace deprecated apt-key command

Replace deprecated apt-key usage with modern GPG operations that store
keys in /etc/apt/keyrings/ as required by newer Debian/Ubuntu versions.

Changes:
- Replace apt-key commands with gpg.key operations
- Store keys in /etc/apt/keyrings/<name>.gpg format
- Automatically derive keyring names from sources or key IDs
- Maintain backward compatibility for existing key detection
- Update documentation to reflect modern best practices

Users must now reference keys via signed-by= in their apt sources.

This is part 3/3 of modernizing APT key management and completes
the transition away from deprecated apt-key.

Author: maisim

src/pyinfra/operations/apt.py

@@ -4,11 +4,13 @@
 
 from __future__ import annotations
 
+import re
 from datetime import timedelta
 from urllib.parse import urlparse
 
 from pyinfra import host
-from pyinfra.api import OperationError, operation
+from pyinfra.api import operation
+from pyinfra.api.exceptions import OperationError
 from pyinfra.facts.apt import (
     AptKeys,
     AptSources,
@@ -20,8 +22,8 @@
 from pyinfra.facts.files import File
 from pyinfra.facts.gpg import GpgKey
 from pyinfra.facts.server import Date
+from pyinfra.operations import files, gpg
 
-from . import files
 from .util.packaging import ensure_packages
 
 APT_UPDATE_FILENAME = "/var/lib/apt/periodic/update-success-stamp"
@@ -45,76 +47,143 @@ def _simulate_then_perform(command: str):
         yield noninteractive_apt(command)
 
 
-@operation()
-def key(src: str | None = None, keyserver: str | None = None, keyid: str | list[str] | None = None):
+def _sanitize_apt_keyring_name(name: str) -> str:
     """
-    Add apt gpg keys with ``apt-key``.
-
-    + src: filename or URL
-    + keyserver: URL of keyserver to fetch key from
-    + keyid: key ID or list of key IDs when using keyserver
-
-    keyserver/id:
-        These must be provided together.
+    Produce a filesystem-friendly name from an URL host/basename or a local filename.
+    """
+    name = name.strip().lower()
+    name = re.sub(r"[^\w.-]+", "_", name)
+    name = re.sub(r"_+", "_", name).strip("_.")
+    return name or "apt-keyring"
 
-    .. warning::
-        ``apt-key`` is deprecated in Debian, it is recommended NOT to use this
-        operation and instead follow the instructions here:
 
-        https://wiki.debian.org/DebianRepository/UseThirdParty
+def _derive_dest_from_src_and_keyids(
+    src: str | None, keyids: list[str] | None, dest: str | None
+) -> str:
+    """
+    Compute a stable destination path in /etc/apt/keyrings/.
+    Priority:
+      1) explicit dest if provided
+      2) from src (URL host + basename, or local basename)
+      3) from keyids (joined)
+      4) fallback "apt-keyring.gpg"
+    """
+    if dest:
+        # Ensure it ends with .gpg and is absolute under /etc/apt/keyrings
+        if not dest.endswith(".gpg"):
+            dest += ".gpg"
+        if not dest.startswith("/"):
+            dest = f"/etc/apt/keyrings/{dest}"
+        return dest
+
+    base = None
+    if src:
+        parsed = urlparse(src)
+        if parsed.scheme and parsed.netloc:
+            host_name = _sanitize_apt_keyring_name(parsed.netloc.replace(":", "_"))
+            bn = _sanitize_apt_keyring_name(
+                (parsed.path.rsplit("/", 1)[-1] or "key").replace(".asc", "").replace(".gpg", "")
+            )
+            base = f"{host_name}-{bn}"
+        else:
+            bn = _sanitize_apt_keyring_name(
+                src.rsplit("/", 1)[-1].replace(".asc", "").replace(".gpg", "")
+            )
+            base = bn or "key"
+    elif keyids:
+        base = "keyserver-" + _sanitize_apt_keyring_name("-".join(keyids))
+    else:
+        base = "apt-keyring"
 
-    **Examples:**
+    return f"/etc/apt/keyrings/{base}.gpg"
 
-    .. code:: python
 
-        # Note: If using URL, wget is assumed to be installed.
+@operation()
+def key(
+    src: str | None = None,
+    keyserver: str | None = None,
+    keyid: str | list[str] | None = None,
+    dest: str | None = None,
+):
+    """
+    Add apt GPG keys *without* apt-key:
+      - Keys are stored under /etc/apt/keyrings/<name>.gpg (binary, dearmored if needed).
+      - You must reference the resulting file in your apt source via `signed-by=...`.
+
+    Args:
+        src: filename or URL to a key (ASCII .asc or binary .gpg)
+        keyserver: keyserver URL for fetching keys by ID
+        keyid: key ID or list of key IDs (required with keyserver)
+        dest: optional keyring filename/path ('.gpg' will be enforced, defaults under /etc/apt/keyrings)
+
+    Behavior:
+        - Idempotent via AptKeys: if the key IDs are already present in any apt keyring, nothing is changed.
+        - If src is ASCII (.asc), it will be dearmored; if binary (.gpg), it's copied as-is.
+        - Keyserver flow uses a temporary GNUPGHOME, then exports and dearmors to the destination keyring.
+
+    Examples:
         apt.key(
-            name="Add the Docker apt gpg key",
-            src="https://download.docker.com/linux/ubuntu/gpg",
+            name="Add Docker apt GPG key",
+            src="https://download.docker.com/linux/debian/gpg",
+            dest="docker.gpg",
         )
 
         apt.key(
             name="Install VirtualBox key",
             src="https://www.virtualbox.org/download/oracle_vbox_2016.asc",
+            dest="oracle-virtualbox.gpg",
+        )
+
+        apt.key(
+            name="Fetch keys from keyserver",
+            keyserver="hkps://keyserver.ubuntu.com",
+            keyid=["0xD88E42B4", "0x7EA0A9C3"],
+            dest="vendor-archive.gpg",
         )
     """
 
+    # Gather currently installed keys (across trusted.gpg.d/, keyrings/, etc.)
     existing_keys = host.get_fact(AptKeys)
 
+    # Check idempotency for src branch
     if src:
-        key_data = host.get_fact(GpgKey, src=src)
-        if key_data:
-            keyid = list(key_data.keys())
-
-        if not keyid or not all(kid in existing_keys for kid in keyid):
-            # If URL, wget the key to stdout and pipe into apt-key, because the "adv"
-            # apt-key passes to gpg which doesn't always support https!
-            if urlparse(src).scheme:
-                yield "(wget -O - {0} || curl -sSLf {0}) | apt-key add -".format(src)
-            else:
-                yield "apt-key add {0}".format(src)
-        else:
-            host.noop("All keys from {0} are already available in the apt keychain".format(src))
+        key_data = host.get_fact(GpgKey, src=src)  # Parses the key(s) from src to extract key IDs
+        keyids_from_src = list(key_data.keys()) if key_data else []
+
+        # If we don't know the IDs (eg. unreachable URL), we cannot determine idempotency -> try to install.
+        # Otherwise, skip if all key IDs are already present.
+        if keyids_from_src and all(kid in existing_keys for kid in keyids_from_src):
+            host.noop(f"All keys from {src} are already available in the apt keychain")
+            return
 
-    if keyserver:
+        dest_path = _derive_dest_from_src_and_keyids(src, keyids_from_src or None, dest)
+
+    # Check idempotency for keyserver branch
+    elif keyserver:
         if not keyid:
             raise OperationError("`keyid` must be provided with `keyserver`")
 
         if isinstance(keyid, str):
             keyid = [keyid]
 
         needed_keys = sorted(set(keyid) - set(existing_keys.keys()))
-        if needed_keys:
-            yield "apt-key adv --keyserver {0} --recv-keys {1}".format(
-                keyserver,
-                " ".join(needed_keys),
-            )
-        else:
-            host.noop(
-                "Keys {0} are already available in the apt keychain".format(
-                    ", ".join(keyid),
-                ),
-            )
+        if not needed_keys:
+            host.noop(f"Keys {', '.join(keyid)} are already available in the apt keychain")
+            return
+
+        dest_path = _derive_dest_from_src_and_keyids(None, needed_keys, dest)
+        # Only install the needed keys
+        keyid = needed_keys
+
+    # Use the generic GPG operation to install the key
+    yield from gpg.key._inner(
+        src=src,
+        dest=dest_path,
+        keyserver=keyserver,
+        keyid=keyid,
+        dearmor=True,
+        mode="0644",
+    )
 
 
 @operation()

tests/facts/apt.AptKeys/keys.json

@@ -1,6 +1,6 @@
 {
-    "command": "! command -v gpg || apt-key list --with-colons",
-    "requires_command": "apt-key",
+    "command": "for f in   /etc/apt/trusted.gpg   /etc/apt/trusted.gpg.d/*.gpg /etc/apt/trusted.gpg.d/*.asc   /etc/apt/keyrings/*.gpg /etc/apt/keyrings/*.asc   /usr/share/keyrings/*.gpg /usr/share/keyrings/*.asc ; do   [ -e \"$f\" ] || continue;   case \"$f\" in     *.asc)       gpg --batch --show-keys --with-colons --keyid-format LONG \"$f\"       ;;     *)       gpg --batch --no-default-keyring --keyring \"$f\"           --list-keys --with-colons --keyid-format LONG       ;;   esac; done",
+    "requires_command": "gpg",
     "output": [
         "tru:t:1:1601454628:0:3:1:5",
         "pub:-:4096:1:3B4FE6ACC0B21F32:1336770936:::-:::scSC::::::23::0:",

tests/operations/apt.key/add.json

@@ -6,9 +6,20 @@
             "src=mykey": {
                 "abc": {}
             }
+        },
+        "files.Directory": {
+            "path=/etc/apt/keyrings": null
+        },
+        "files.File": {
+            "path=/etc/apt/keyrings/mykey.gpg": null
         }
     },
     "commands": [
-        "apt-key add mykey"
+        "mkdir -p /etc/apt/keyrings",
+        "chmod 755 /etc/apt/keyrings",
+        "if grep -q \"BEGIN PGP PUBLIC KEY BLOCK\" \"mykey\"; then gpg --batch --dearmor -o \"/etc/apt/keyrings/mykey.gpg\" \"mykey\"; else cp \"mykey\" \"/etc/apt/keyrings/mykey.gpg\"; fi",
+        "mkdir -p /etc/apt/keyrings",
+        "touch /etc/apt/keyrings/mykey.gpg",
+        "chmod 644 /etc/apt/keyrings/mykey.gpg"
     ]
 }

tests/operations/apt.key/add_exists.json

@@ -8,6 +8,9 @@
             "src=mykey": {
                 "abc": {}
             }
+        },
+        "files.Directory": {
+            "path=/etc/apt/keyrings": null
         }
     },
     "commands": [],

tests/operations/apt.key/add_keyserver.json

@@ -4,9 +4,24 @@
         "keyid": "abc"
     },
     "facts": {
-        "apt.AptKeys": {}
+        "apt.AptKeys": {},
+        "files.Directory": {
+            "path=/etc/apt/keyrings": null,
+            "path=/tmp/pyinfra-gpg-empfile_": null
+        },
+        "files.File": {
+            "path=/etc/apt/keyrings/keyserver-abc.gpg": null
+        }
     },
     "commands": [
-        "apt-key adv --keyserver key-server.net --recv-keys abc"
+        "mkdir -p /etc/apt/keyrings",
+        "chmod 755 /etc/apt/keyrings",
+        "mkdir -p /tmp/pyinfra-gpg-empfile_",
+        "chmod 700 /tmp/pyinfra-gpg-empfile_",
+        "export GNUPGHOME=\"/tmp/pyinfra-gpg-empfile_\" && gpg --batch --keyserver \"key-server.net\" --recv-keys abc",
+        "export GNUPGHOME=\"/tmp/pyinfra-gpg-empfile_\" && gpg --batch --export abc | gpg --batch --dearmor -o \"/etc/apt/keyrings/keyserver-abc.gpg\"",
+        "mkdir -p /etc/apt/keyrings",
+        "touch /etc/apt/keyrings/keyserver-abc.gpg",
+        "chmod 644 /etc/apt/keyrings/keyserver-abc.gpg"
     ]
 }

tests/operations/apt.key/add_keyserver_exists.json

@@ -7,6 +7,9 @@
         "apt.AptKeys": {
             "abc": {},
             "def": {}
+        },
+        "files.Directory": {
+            "path=/etc/apt/keyrings": null
         }
     },
     "commands": [],

tests/operations/apt.key/add_keyserver_multiple.json

@@ -4,9 +4,24 @@
         "keyid": ["abc", "def"]
     },
     "facts": {
-        "apt.AptKeys": {}
+        "apt.AptKeys": {},
+        "files.Directory": {
+            "path=/etc/apt/keyrings": null,
+            "path=/tmp/pyinfra-gpg-empfile_": null
+        },
+        "files.File": {
+            "path=/etc/apt/keyrings/keyserver-abc-def.gpg": null
+        }
     },
     "commands": [
-        "apt-key adv --keyserver key-server.net --recv-keys abc def"
+        "mkdir -p /etc/apt/keyrings",
+        "chmod 755 /etc/apt/keyrings",
+        "mkdir -p /tmp/pyinfra-gpg-empfile_",
+        "chmod 700 /tmp/pyinfra-gpg-empfile_",
+        "export GNUPGHOME=\"/tmp/pyinfra-gpg-empfile_\" && gpg --batch --keyserver \"key-server.net\" --recv-keys abc def",
+        "export GNUPGHOME=\"/tmp/pyinfra-gpg-empfile_\" && gpg --batch --export abc def | gpg --batch --dearmor -o \"/etc/apt/keyrings/keyserver-abc-def.gpg\"",
+        "mkdir -p /etc/apt/keyrings",
+        "touch /etc/apt/keyrings/keyserver-abc-def.gpg",
+        "chmod 644 /etc/apt/keyrings/keyserver-abc-def.gpg"
     ]
 }

tests/operations/apt.key/add_keyserver_multiple_partial.json

@@ -5,10 +5,17 @@
     },
     "facts": {
         "apt.AptKeys": {
-            "abc": {}
+            "abc": {},
+            "def": {}
+        },
+        "files.Directory": {
+            "path=/etc/apt/keyrings": null,
+            "path=/tmp/pyinfra-gpg-empfile_": null
+        },
+        "files.File": {
+            "path=/etc/apt/keyrings/keyserver-abc-def.gpg": null
         }
     },
-    "commands": [
-        "apt-key adv --keyserver key-server.net --recv-keys def"
-    ]
+    "commands": [],
+    "noop_description": "Keys abc, def are already available in the apt keychain"
 }

tests/operations/apt.key/add_keyserver_no_keyid.json

@@ -3,7 +3,10 @@
         "keyserver": "key-server.net"
     },
     "facts": {
-        "apt.AptKeys": {}
+        "apt.AptKeys": {},
+        "files.Directory": {
+            "path=/etc/apt/keyrings": null
+        }
     },
     "exception": {
         "name": "OperationError",

tests/operations/apt.key/add_no_gpg.json

@@ -4,10 +4,21 @@
         "apt.AptKeys": {},
         "gpg.GpgKey": {
             "src=mykey": null
+        },
+        "files.Directory": {
+            "path=/etc/apt/keyrings": null
+        },
+        "files.File": {
+            "path=/etc/apt/keyrings/mykey.gpg": null
         }
     },
     "commands": [
-        "apt-key add mykey"
+        "mkdir -p /etc/apt/keyrings",
+        "chmod 755 /etc/apt/keyrings", 
+        "if grep -q \"BEGIN PGP PUBLIC KEY BLOCK\" \"mykey\"; then gpg --batch --dearmor -o \"/etc/apt/keyrings/mykey.gpg\" \"mykey\"; else cp \"mykey\" \"/etc/apt/keyrings/mykey.gpg\"; fi",
+        "mkdir -p /etc/apt/keyrings",
+        "touch /etc/apt/keyrings/mykey.gpg",
+        "chmod 644 /etc/apt/keyrings/mykey.gpg"
     ],
     "idempotent": false,
     "disable_idempotent_warning_reason": "the key will always be added if gpg cant check whether it exists"