cs-image-system-docker-runtime-plugin 0.1.6__py3-none-any.whl

cs_image_system/docker_runtime/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: 2026 Mykel Alvis <mykelalvis@infrastructurebuilder.org>
+#
+# SPDX-License-Identifier: Apache-2.0

cs_image_system/docker_runtime/bootstrap.py

@@ -0,0 +1,129 @@
+# SPDX-FileCopyrightText: 2026 Mykel Alvis <mykelalvis@infrastructurebuilder.org>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""The container-host section of the bootstrap (stage 103 item 15).
+
+A read-and-say section with no terraform module, because by decision
+nothing in it can be created: a docker daemon is a host somebody runs, and
+whoever reaches it is root on that host. What the section does instead is
+read the tree's docker runtime from the raw ``cfg/`` (never loading it, and
+never printing an address: a ``host`` may be an ``ENC[age:...]`` marker) and
+ask the one question the rest of the bootstrap needs answered, *can CI reach
+the daemon?*
+
+* **Yes** (an ``ssh://`` host, or the environment's daemon with an address
+  in the workflow, the transports the starters' workflow reaches): the two
+  repository secrets that workflow reads to reach it, the ssh private key and
+  the host's ``known_hosts`` line (``DOCKER_HOST_SSH_KEY`` and
+  ``DOCKER_HOST_KNOWN_HOSTS``, in the GitHub section's script with the rest),
+  are set from files, and the section says that neither is made here. The key
+  belongs to a user on the host who may use the daemon; it is made on your
+  machine, never by the system.
+* **No** (a local socket, a context, a ``tcp://`` host, or a host the YAML
+  keeps as a marker): CI never performs on the runtime, and the section says
+  to name it in ``GUARD_RUNTIME`` so a change to its declaration fails CI
+  loudly before anything runs (the GitHub section's default for that
+  variable already names a runtime CI cannot reach).
+
+The section also records what it does NOT make, in the audit the README
+tabulates: the daemon, the network it names, the docker CLI on the runner.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from cs_image_system.base.bootstrap.facts import Facts, ci_can_reach, real, runtime_of_type
+from cs_image_system.base.bootstrap.questions import BY_HAND, READ, Answers, Question, Rendered, Section
+
+RUNTIME_TYPE = "docker"
+GUIDE = "CI_SETUP.md 3.4a"
+
+def _runtime(facts: Facts) -> dict[str, Any]:
+    return runtime_of_type(facts, RUNTIME_TYPE) or {}
+
+
+def _runtime_default(facts: Facts, answers: Answers) -> str | None:
+    name = _runtime(facts).get("name")
+    return str(name) if name else None
+
+
+def _transport(runtime: dict[str, Any]) -> str:
+    """How the runtime names its daemon, from the raw YAML: ``ssh``, ``tcp``,
+    ``unix``, ``context``, ``marker`` (an encrypted host, unreadable here) or
+    ``environment`` (neither: the daemon of the machine that runs the tool)."""
+    host = str(runtime.get("host") or "").strip()
+    if host.startswith("ENC["):
+        return "marker"
+    if host:
+        scheme = host.split("://", 1)[0].lower() if "://" in host else "unix"
+        return scheme if scheme in ("ssh", "tcp", "unix") else "unix"
+    return "context" if real(runtime.get("context")) else "environment"
+
+
+def _reach_default(facts: Facts, answers: Answers) -> bool:
+    return ci_can_reach(_runtime(facts))
+
+
+QUESTIONS: tuple[Question, ...] = (
+    Question("runtime", "The docker runtime this section is about (a `name:` from cfg/runtime-builders.yml)", "text",
+             default=_runtime_default,
+             help="no runtime of type docker could be read from cfg/"),
+    Question("ci_reaches", "Can CI reach the docker daemon (an ssh:// host the workflow can log in to)?", "bool",
+             default=_reach_default,
+             help="the starters' workflow reaches an ssh:// host only; say no for a socket, a context or a tcp:// host"),
+)
+
+
+def render(answers: Answers, facts: Facts | None = None) -> Rendered:
+    name = str(answers.get("runtime") or "the docker runtime")
+    reaches = bool(answers.get("ci_reaches"))
+    transport = _transport(_runtime(facts)) if facts is not None else "environment"
+    by_hand: list[str] = [
+        f"The daemon of `{name}` is the team's: install, patch and secure it on its host; whoever can reach it is "
+        "root on that host, and the system says so rather than hiding it (CONFIGURATION.md section 4).",
+    ]
+    if reaches:
+        by_hand.append(
+            "CI's way in: make an ed25519 key for a user on the docker host who may use the daemon "
+            f"(`ssh-keygen -t ed25519 -f DOCKER_HOST_SSH_KEY -N ''`), authorize its public half there, put the private "
+            "half in the secrets directory as `DOCKER_HOST_SSH_KEY`, and the host's key line (`ssh-keyscan -t ed25519 "
+            f"HOST`, checked against the host by another route) as `DOCKER_HOST_KNOWN_HOSTS` ({GUIDE}).")
+    else:
+        by_hand.append(
+            f"CI cannot reach `{name}`: name it in the `GUARD_RUNTIME` Actions variable (the GitHub section's default "
+            "does) so a change to its declaration fails CI before anything runs, and keep PERFORM_RUNTIME on a "
+            "runtime CI can reach, or leave the `perform` job unconfigured (it skips, and says so).")
+    return Rendered(
+        by_hand=tuple(by_hand),
+        notes=(
+            f"the docker runtime `{name}`: its daemon is named by "
+            + {"ssh": "an ssh:// host", "tcp": "a tcp:// host", "unix": "a local socket", "context": "a docker context",
+               "marker": "an encrypted host", "environment": "the environment (DOCKER_HOST, else the local socket)"}.get(
+                   transport, "the environment"),
+            "CI " + ("reaches it over ssh with DOCKER_HOST_SSH_KEY and DOCKER_HOST_KNOWN_HOSTS"
+                     if reaches else "does not reach it: it is a runtime CI must never bake on"),
+            "nothing here is terraform: the section reads the declaration and says what remains",
+        ),
+        coverage=(
+            (f"the daemon of `{name}`", BY_HAND, "a host somebody runs; the system never installs or configures a daemon"),
+            ("the network the runtime names", BY_HAND, "referenced by name and never created or changed: the team's, by decision"),
+            ("the docker CLI on the runner", READ, "the runner image carries it (CI_RUNNER.md); the workflow only checks it is there"),
+            ("CI's key to the daemon's host" if reaches else "CI's performing run on the runtime",
+             BY_HAND,
+             "made on your machine and set by the script from a file; the system never makes a key" if reaches
+             else "not built: CI has no way into the daemon, so the runtime is guarded instead"),
+        ),
+    )
+
+
+def wanted(facts: Facts) -> bool:
+    """The tree declares a docker runtime."""
+    return runtime_of_type(facts, RUNTIME_TYPE) is not None
+
+
+def docker_section() -> Section:
+    return Section(name="docker", title="Container host", questions=QUESTIONS, render=render, wanted=wanted,
+                   wants_facts=True,
+                   description="the docker daemon CI can or cannot reach, the secrets that reach it, the runtime to guard")

cs_image_system/docker_runtime/docker_names.py

@@ -0,0 +1,136 @@
+# SPDX-FileCopyrightText: 2026 Mykel Alvis <mykelalvis@infrastructurebuilder.org>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""The spellings a container daemon accepts (stage 103), mapped ONCE here.
+
+* a **repository** name is lowercase: ``[a-z0-9]`` with single ``.``, ``_``,
+  ``__`` or ``-`` separators, path components joined by ``/``;
+* a **tag** is ``[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}``: at most 128
+  characters, and a build's final name (``<prefix>-<timestamp>``) is written
+  as one, so a name that would be cut is refused rather than cut (the cut
+  would fall where the timestamp is);
+* a **label** key is a string without whitespace or ``=``; the OCI convention
+  is lowercase reverse-DNS, but the system's ``csis_*`` keys and a tree's
+  own are accepted as written.
+
+A build is identified by its IMAGE ID (``sha256:<64 hex>``), which tags
+move around; the lineage build id on this runtime is that id.
+"""
+from __future__ import annotations
+
+import re
+
+TAG_MAX = 128
+_TAG_BAD = re.compile(r"[^A-Za-z0-9_.-]+")
+_REPO_BAD = re.compile(r"[^a-z0-9._/-]+")
+_IMAGE_ID = re.compile(r"^(sha256:)?[0-9a-f]{64}$")
+_DIGEST_REF = re.compile(r"^[^@\s]+@sha256:[0-9a-f]{64}$")
+
+
+def tag_name(value: str) -> str:
+    """A valid docker tag derived deterministically from ``value``: what it
+    cannot keep becomes ``-``, a separator may not lead. Not shortened."""
+    v = _TAG_BAD.sub("-", str(value)).strip(".-")
+    if not v:
+        return "i"
+    if not (v[0].isalnum() or v[0] == "_"):
+        v = f"i{v}"
+    return v
+
+
+def tag_problem(name: str) -> str | None:
+    """Why ``name``, once made a tag, cannot be one: only its length."""
+    made = tag_name(name)
+    if len(made) > TAG_MAX:
+        return (f"a docker tag is at most {TAG_MAX} characters; {name!r} becomes {made!r} ({len(made)}) "
+                f"and would be cut where the timestamp is")
+    return None
+
+
+def repository_name(value: str) -> str:
+    """A valid repository name derived from ``value``: lowercase, what it
+    cannot keep becomes ``-``, separators never doubled or leading."""
+    v = _REPO_BAD.sub("-", str(value).lower())
+    v = re.sub(r"[._-]{2,}", "-", v).strip("._-/")
+    return v or "csis"
+
+
+def label_key_problem(key: str) -> str | None:
+    """Why ``key`` cannot be a docker label key, or None."""
+    k = str(key)
+    if not k.strip():
+        return "a docker label key cannot be empty"
+    if any(c.isspace() for c in k):
+        return f"a docker label key carries no whitespace; {key!r} does"
+    if "=" in k:
+        return f"a docker label key carries no '='; {key!r} does"
+    return None
+
+
+def is_image_id(value: str) -> bool:
+    return bool(_IMAGE_ID.match(str(value).strip()))
+
+
+def is_digest_reference(value: str) -> bool:
+    """``<repository>@sha256:<digest>``: the form ``image_id`` pins."""
+    return bool(_DIGEST_REF.match(str(value).strip()))
+
+
+#: The registry a daemon may put in front of a repository it was given
+#: unqualified: Podman's API spells ``csis/x:t`` as ``docker.io/csis/x:t``
+#: (or ``localhost/csis/x:t``) in ``RepoTags``, where Docker keeps it as
+#: written. Found by the Podman leg (stage 103, 2026-11-01).
+IMPLIED_REGISTRIES = ("docker.io/", "index.docker.io/", "localhost/")
+
+
+def same_repository(reported: str, repository: str) -> bool:
+    """Whether a ``RepoTags`` entry's repository part IS the runtime's
+    repository, however the daemon spells the registry it implied."""
+    if reported == repository:
+        return True
+    return any(reported.startswith(p) and reported[len(p):] == repository for p in IMPLIED_REGISTRIES)
+
+
+def short_id(image_id: str) -> str:
+    """The twelve hex characters the CLI shows for an image id."""
+    v = str(image_id).strip()
+    v = v.split(":", 1)[1] if v.startswith("sha256:") else v
+    return v[:12]
+
+
+def full_id(image_id: str) -> str:
+    """The ``sha256:``-prefixed form of an image id the CLI printed."""
+    v = str(image_id).strip()
+    return v if v.startswith("sha256:") else f"sha256:{v}"
+
+
+# tags that carry what a label cannot change after the build (stage 103,
+# decision 4: labels are fixed when an image is built, so release and
+# relabel MOVE TAGS): `<repository>:<short id>--<key>--<value as tag>`
+MOVABLE_SEP = "--"
+
+
+def movable_tag(image_id: str, key: str, value: str) -> str:
+    return f"{short_id(image_id)}{MOVABLE_SEP}{tag_name(key)}{MOVABLE_SEP}{tag_name(value)}"
+
+
+_ID_AS_TAG = re.compile(r"^sha256-([0-9a-f]{64})$")
+
+
+def movable_value_decoded(value: str) -> str:
+    """A movable tag's value as it was given: an image id written as a tag
+    lost its colon (``sha256-<hex>``), and gets it back; anything else is
+    returned as it stands (found live: the state query compared the
+    lineage's ``sha256:...`` parent with the tag's ``sha256-...``)."""
+    m = _ID_AS_TAG.match(str(value))
+    return f"sha256:{m.group(1)}" if m else str(value)
+
+
+def parse_movable_tag(tag: str) -> tuple[str, str, str] | None:
+    """``(short id, key, value)`` of a movable tag, or None for any other;
+    the value is decoded (``movable_value_decoded``)."""
+    parts = str(tag).split(MOVABLE_SEP, 2)
+    if len(parts) != 3 or not re.fullmatch(r"[0-9a-f]{12}", parts[0]) or not parts[1] or not parts[2]:
+        return None
+    return parts[0], parts[1], movable_value_decoded(parts[2])

cs_image_system/docker_runtime/docker_packer_source.py

@@ -0,0 +1,140 @@
+# SPDX-FileCopyrightText: 2026 Mykel Alvis <mykelalvis@infrastructurebuilder.org>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""The ``docker`` packer source for an image baked on a docker runtime
+(stage 103), from HashiCorp's docker plugin.
+
+A bake starts a container from the parent image, provisions it through the
+daemon (no SSH: the plugin's docker communicator runs ``docker exec`` and
+``docker cp``) and COMMITS it. The committed image carries the lineage
+labels and the keepalive command as Dockerfile instructions (``changes``);
+the build's names are tags, put on by the ``docker-tag`` post-processor the
+runtime adds to the build block: the final name and the series' floating
+tag, which a child image bakes from when its parent is deferred.
+"""
+from __future__ import annotations
+
+import logging
+import shlex
+from typing import Any
+
+import hcl2
+from hcl2 import Builder
+
+from cs_image_system.contract.constants import OOPS_DEFAULTS, SELF
+from cs_image_system.hashicorp_utils.hashicorp import FO
+
+from .docker_names import is_image_id, tag_name
+
+log = logging.getLogger(__name__)
+
+DOCKER_SOURCE = "docker"
+#: PID 1's command in every image this runtime bakes (decision 2: no init
+#: system; the launcher runs it under ``--init``)
+KEEPALIVE_CMD = ["sleep", "infinity"]
+#: where the bake writes what must not land in the image (the step runner)
+BAKE_TMPFS = ["/run"]
+
+_ARCH_PLATFORM = {"x86_64": "linux/amd64", "amd64": "linux/amd64", "arm64": "linux/arm64", "aarch64": "linux/arm64"}
+
+
+def bake_container_name(image_name: str, runtime: str) -> str:
+    """The build container's name: what ``ansible_host`` names for the
+    docker connection, so one per image and runtime."""
+    return tag_name(f"csis-bake-{runtime}-{image_name}").lower()
+
+
+def _label_change(key: str, value: str) -> str:
+    v = str(value).replace("\\", "\\\\").replace('"', '\\"')
+    return f'LABEL {key}="{v}"'
+
+
+def docker_source(model: Any, image: Any, *, runtime: str, source_type: str, subconfig: Any,
+                  self_subconfig: Any, psi: Any, tags: dict[str, str], final_name: str,
+                  pinned: str | None) -> list[str]:
+    c: dict[str, Any] = {}
+    # --- the bake's parent image
+    if pinned:
+        c["image"] = pinned if is_image_id(pinned) else str(pinned)
+    elif psi.is_resolved():
+        c["image"] = str(psi.identifier)
+    else:
+        # deferred: the parent series' floating tag, moved by every bake of
+        # the series (the daemon's own "newest of the family")
+        tag = psi.floating_tag() if hasattr(psi, "floating_tag") else None
+        if not tag:
+            raise ValueError(f"image {image.get_name()} on runtime {runtime}: no floating tag for its deferred "
+                             f"parent {psi.source_name!r}")
+        c["image"] = tag
+    # the query pulled every vendor image it resolved; our own builds are
+    # local and no registry has them
+    c["pull"] = False
+    c["commit"] = True
+    arch = getattr(image, "architecture", None) or getattr(psi, "architecture", None)
+    if arch and str(arch) not in OOPS_DEFAULTS and str(arch) in _ARCH_PLATFORM:
+        c["platform"] = _ARCH_PLATFORM[str(arch)]
+    # --- the build container: named (ansible reaches it by name), under an
+    # init, on the runtime's network, with its machine type's limits
+    run: list[str] = ["-d", "-i", "-t", "--init", "--name", bake_container_name(image.get_name(), runtime)]
+    networking = getattr(model, "networking", None)
+    network = getattr(networking, "network", None) if networking is not None else None
+    if network and network not in OOPS_DEFAULTS:
+        run += ["--network", str(network)]
+    mt_name = None
+    for cand in (getattr(subconfig, "machine_type", None) if subconfig else None,
+                 getattr(subconfig, "default_machine_type", None) if subconfig else None,
+                 model.get_default_machine_type()):
+        if cand and cand not in OOPS_DEFAULTS:
+            mt_name = str(cand)
+            break
+    mt = (model.get_machine_types() or {}).get(mt_name) if mt_name else None
+    if mt is not None:
+        if getattr(mt, "cpus", None):
+            run += ["--cpus", str(mt.cpus)]
+        if getattr(mt, "memory", None):
+            run += ["--memory", str(mt.memory)]
+    # the shell the bake provisions through is the CONTAINER's command, not an
+    # entrypoint: packer's default `--entrypoint=/bin/sh` becomes the committed
+    # image's entrypoint, and `ENTRYPOINT []` in `changes` does not clear it
+    # (found live: every later `docker run <image> <cmd>` ran `/bin/sh <cmd>`)
+    run += ["--", "{{.Image}}", "/bin/sh"]
+    c["run_command"] = [f'"{a}"' for a in run]
+    c["tmpfs"] = [f'"{t}"' for t in BAKE_TMPFS]
+    # --- what the committed image carries
+    changes = [_label_change(k, v) for k, v in sorted(tags.items())]
+    changes.append("CMD " + "[" + ", ".join(f'"{a}"' for a in KEEPALIVE_CMD) + "]")
+    c["changes"] = [f'"{ch.replace(chr(92), chr(92) * 2).replace(chr(34), chr(92) + chr(34))}"' for ch in changes]
+    for k, v in c.items():
+        if isinstance(v, str):
+            c[k] = f'"{v}"'
+    doc = Builder()
+    doc.block("source", labels=[f'"{source_type}"', f'"{image.get_name()}"'], **c)
+    return hcl2.dumps(doc.build(), formatter_options=FO).splitlines()
+
+
+def docker_tag_post_processor(image: Any, *, repository: str, source_type: str, final_name: str,
+                              prefix: str | None) -> list[str]:
+    """The ``docker-tag`` post-processor of one image's build: the final name
+    and the series' floating tag, in the runtime's repository."""
+    names = [tag_name(final_name)] if final_name else []
+    if prefix and tag_name(prefix) not in names:
+        names.append(tag_name(prefix))
+    if not names:
+        return []
+    return [
+        f"  # stage 103: the build's names are tags ({image.get_name()}); the floating tag is the series' newest",
+        '  post-processor "docker-tag" {',
+        f'    only       = ["{source_type}.{image.get_name()}"]',
+        f'    repository = "{repository}"',
+        "    tags       = [" + ", ".join(f'"{n}"' for n in names) + "]",
+        "  }",
+    ]
+
+
+def quoted(parts: list[str]) -> str:
+    return " ".join(shlex.quote(p) for p in parts)
+
+
+__all__ = ["DOCKER_SOURCE", "KEEPALIVE_CMD", "SELF", "bake_container_name", "docker_source",
+           "docker_tag_post_processor"]

cs_image_system/docker_runtime/docker_provider_specific_image.py

@@ -0,0 +1,40 @@
+# SPDX-FileCopyrightText: 2026 Mykel Alvis <mykelalvis@infrastructurebuilder.org>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import logging
+from typing import Any
+
+from cs_image_system.base.models.provider_specific_image import ProviderSpecificImage
+
+log = logging.getLogger(__name__)
+
+
+class DockerProviderSpecificImage(ProviderSpecificImage):
+    """An image as a container daemon knows it. Resolved: a vendor image by
+    digest (``<repository>@sha256:...``, what the query recorded) or one of
+    our own builds by image id (``sha256:...``). Deferred: the series'
+    floating tag ``<repository>:<prefix>``, which every bake of the series
+    moves to its newest build -- the daemon has no "newest image matching a
+    name pattern" query, so the tag IS that query."""
+
+    @classmethod
+    def csis_name(cls) -> str:
+        return "docker"
+
+    def floating_tag(self) -> str | None:
+        """``<repository>:<prefix as a tag>`` for a deferred image."""
+        if not self.deferred_name_pattern:
+            return None
+        from cs_image_system.base.global_context import GlobalTypeContext
+        from .docker_names import tag_name
+        rtb = GlobalTypeContext().runtime_builders.get(self.runtime)
+        model = getattr(rtb, "model", None)
+        repo = model.get_repository() if model is not None and hasattr(model, "get_repository") else "csis"
+        return f"{repo}:{tag_name(self.deferred_name_pattern)}"
+
+    def get_query_assets(self) -> dict[str, Any] | None:
+        if self.is_resolved():
+            return {"image": str(self.identifier)}
+        tag = self.floating_tag()
+        return {"image": tag} if tag else None