docker-devkit 0.3.0.dev113__py3-none-any.whl → 0.4.0__py3-none-any.whl

docker_devkit/build_docker.py

@@ -14,6 +14,7 @@ import typer
 from bashrun.bash import bash, bash_output
 from build_artifact_registry.builds import push_build
 from build_artifact_registry.setup_oras import install_oras
+from .config import MirrorConfig
 from .detect_gpu import GPU_TYPES, Gpu, detect_gpu
 from .documents import BakeDocument, digest_pinned, parse_bake
 from pydantic_settings import BaseSettings
@@ -21,7 +22,7 @@ from .context_sha import compute_service_shas
 
 from .image_refs import bake_base_image_refs, resolve_remote_digest
 from .lifecycle import require_manifest, resolve_lock
-from .mirror import is_mirrored, load_mirror_config, upstream_ref
+from .mirror import load_mirror_config, mirrored_ref
 from .modes import parse_env_file
 
 
@@ -85,11 +86,10 @@ def run_build(
     lock_only: bool = False,
     gpu_only: bool = False,
     no_cache: bool = False,
-    env_overlay: dict[str, str] | None = None,
 ) -> None:
     root = Path.cwd()
     manifest = require_manifest(root)
-    lock_file = resolve_lock(root, manifest)
+    lock_file = resolve_lock(root)
     mirror_config = load_mirror_config(root)
 
     bake = parse_bake(manifest)
@@ -117,24 +117,7 @@ def run_build(
     if gpu == "auto" and not lock_only:
         gpu = detect_gpu()
 
-    # One lock entry per declared third-party image: NAME=path:tag@sha256:…
-    # Mirror-prefixed declarations resolve their digest against upstream (crane copies
-    # are byte-identical, so the digest is valid under both names) and record it under
-    # the mirror name — declaring and re-locking works before CI has mirrored anything.
-    for occurrence in bake_base_image_refs(bake):
-        if digest_pinned(occurrence.reference):
-            lock_data[occurrence.name] = occurrence.reference
-            continue
-        if (
-            not upgrade
-            and occurrence.name in lock_data
-            and lock_data[occurrence.name].startswith(occurrence.reference + "@")
-        ):
-            continue
-        inspect_target = occurrence.reference
-        if mirror_config is not None and is_mirrored(occurrence.reference, mirror_config.prefix):
-            inspect_target = upstream_ref(occurrence.reference, mirror_config.prefix)
-        lock_data[occurrence.name] = f"{occurrence.reference}@{resolve_remote_digest(inspect_target)}"
+    update_lock_entries(bake, mirror_config, lock_data, upgrade=upgrade)
 
     # Update main lock file
     lock_file.write_text(
@@ -147,8 +130,6 @@ def run_build(
 
     # Update environment with external dependency image digests
     os.environ.update(lock_data)
-    if env_overlay:
-        os.environ.update(env_overlay)
 
     # Build command arguments
     command_arguments: list[str] = []
@@ -226,6 +207,31 @@ def run_build(
         push_image_digests(shelf, sha, baked_images, targets)
 
 
+# One lock entry per declared third-party image: NAME={prefix}/{ref}@sha256:… — the
+# mirror-prefixed form is derived from the mirror prefix, the digest resolves against
+# the upstream reference (crane copies are byte-identical, so the digest is valid
+# under both names) and records under the mirror name.
+def update_lock_entries(
+    bake: BakeDocument,
+    mirror_config: MirrorConfig | None,
+    lock_data: dict[str, str],
+    *,
+    upgrade: bool,
+) -> None:
+    if not bake.base_images:
+        return
+    if mirror_config is None:
+        raise RuntimeError("x-base-images declared without a mirror section in docker-devkit.yaml")
+    for occurrence in bake_base_image_refs(bake):
+        lock_base = mirrored_ref(occurrence.reference, mirror_config.prefix)
+        if digest_pinned(occurrence.reference):
+            lock_data[occurrence.name] = lock_base
+            continue
+        if not upgrade and occurrence.name in lock_data and lock_data[occurrence.name].startswith(lock_base + "@"):
+            continue
+        lock_data[occurrence.name] = f"{lock_base}@{resolve_remote_digest(occurrence.reference)}"
+
+
 def leg_key(targets: list[str]) -> str:
     return hashlib.sha256(",".join(sorted(targets)).encode("utf-8")).hexdigest()[:8]
 

docker_devkit/down.py

@@ -31,7 +31,7 @@ def down(
     config = load_lifecycle_config(root)
     enforce_bake_declaration(root, config)
     manifest = resolve_manifest(root)
-    lock_file = resolve_lock(root, manifest)
+    lock_file = resolve_lock(root)
 
     if not ENV_FILE.exists():
         raise RuntimeError("No .env file found")

docker_devkit/image_refs.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-import datetime
+import datetime as dt
 import re
 import shlex
 import tomllib
@@ -12,6 +12,7 @@ from bashrun.bash import bash_output
 from pydantic import RootModel
 
 from .documents import BakeDocument, parse_bake
+from .lifecycle import MANIFEST_PATH
 
 BUILD_ARG_PATTERN = re.compile(r"\$\{[A-Za-z0-9_]+\}")
 FROM_PATTERN = re.compile(r"^FROM\s+(?:--platform=\S+\s+)?(\S+)", re.MULTILINE)
@@ -21,17 +22,7 @@ DIGEST_PATTERN = re.compile(r"^Digest:\s+(sha256:[a-f0-9]+)", re.MULTILINE)
 MISSING_VERSION = "<missing>"
 
 
-type TomlValue = (
-    str
-    | int
-    | float
-    | bool
-    | datetime.datetime
-    | datetime.date
-    | datetime.time
-    | list[TomlValue]
-    | dict[str, TomlValue]
-)
+type TomlValue = str | int | float | bool | dt.datetime | dt.date | dt.time | list[TomlValue] | dict[str, TomlValue]
 
 
 class TomlDocument(RootModel[TomlValue]):
@@ -70,15 +61,11 @@ def unpinned_references(root: Path) -> list[str]:
     ]
 
 
-def declared_references(
-    root: Path, bake_globs: tuple[str, ...] = ("workloads/images.yml", "compose*.bake.yml")
-) -> list[ImageReference]:
-    return [
-        reference
-        for bake_glob in bake_globs
-        for path in sorted(root.glob(bake_glob))
-        for reference in bake_base_image_refs(parse_bake(path))
-    ]
+def declared_references(root: Path) -> list[ImageReference]:
+    manifest = root / MANIFEST_PATH
+    if not manifest.exists():
+        return []
+    return bake_base_image_refs(parse_bake(manifest))
 
 
 def stray_references(

docker_devkit/lifecycle.py

@@ -8,11 +8,9 @@ from .detect_gpu import Gpu
 DEFAULT_COMPOSE_FILE = Path("compose.yml")
 GPU_PLACEHOLDER = "{gpu}"
 
-# The image manifest and its lock are a named pair living in the same directory. The
-# legacy names keep resolving so a repo can upgrade the devkit before moving its files.
-MANIFEST_CANDIDATES = (Path("workloads/images.yml"), Path("compose.bake.yml"))
-MANIFEST_LOCK_PAIR = {"images.yml": "images.lock", "compose.bake.yml": ".env.lock"}
-LOCK_CANDIDATES = (Path("workloads/images.lock"), Path(".env.lock"))
+# The image manifest and its lock are a named pair living in the same directory.
+MANIFEST_PATH = Path("workloads/images.yml")
+LOCK_PATH = Path("workloads/images.lock")
 
 
 def load_lifecycle_config(root: Path) -> LifecycleConfig | None:
@@ -21,27 +19,25 @@ def load_lifecycle_config(root: Path) -> LifecycleConfig | None:
 
 
 def resolve_manifest(root: Path) -> Path | None:
-    return next((root / candidate for candidate in MANIFEST_CANDIDATES if (root / candidate).exists()), None)
+    manifest = root / MANIFEST_PATH
+    return manifest if manifest.exists() else None
 
 
 def require_manifest(root: Path) -> Path:
     manifest = resolve_manifest(root)
     if manifest is None:
-        raise RuntimeError(f"No image manifest found; {MANIFEST_CANDIDATES[0]} is the canonical name")
+        raise RuntimeError(f"No image manifest at {MANIFEST_PATH}")
     return manifest
 
 
-def resolve_lock(root: Path, manifest: Path | None) -> Path:
-    if manifest is not None:
-        return manifest.parent / MANIFEST_LOCK_PAIR[manifest.name]
-    existing = next((root / candidate for candidate in LOCK_CANDIDATES if (root / candidate).exists()), None)
-    return existing if existing is not None else root / LOCK_CANDIDATES[0]
+def resolve_lock(root: Path) -> Path:
+    return root / LOCK_PATH
 
 
 def enforce_bake_declaration(root: Path, config: LifecycleConfig | None) -> None:
-    if config is None and any((root / candidate).exists() for candidate in MANIFEST_CANDIDATES):
+    if config is None and (root / MANIFEST_PATH).exists():
         raise RuntimeError(
-            "image manifest present without a lifecycle section in docker-devkit.yaml; declare the section or rename the file"
+            "image manifest present without a lifecycle section in docker-devkit.yaml; declare the section"
         )
 
 

docker_devkit/mirror.py

@@ -2,14 +2,13 @@ from __future__ import annotations
 
 import os
 import shlex
-import tempfile
 from pathlib import Path
 
 import typer
 from bashrun.bash import bash, bash_check
 
 from .config import MirrorConfig, load_config
-from .image_refs import ImageReference, declared_references
+from .image_refs import declared_references
 
 app = typer.Typer(add_completion=False, pretty_exceptions_show_locals=False)
 
@@ -23,7 +22,7 @@ def mirror() -> None:
     if config is None:
         raise RuntimeError("a mirror section with 'prefix' is required in docker-devkit.yaml to mirror")
 
-    targets = mirror_targets(root, config.prefix)
+    targets = sorted(declared_references(root), key=lambda occurrence: occurrence.reference)
     print(f"Install crane {CRANE_VERSION}")
     sudo = "sudo " if os.geteuid() != 0 else ""
     archive = "go-containerregistry_Linux_x86_64.tar.gz"
@@ -31,9 +30,9 @@ def mirror() -> None:
     bash(f"{sudo}tar -xzf {archive} -C /usr/local/bin crane")
     Path(archive).unlink()
     for target in targets:
-        upstream = upstream_ref(target.reference, config.prefix)
-        print(f"Mirror {upstream} -> {target.reference}")
-        bash(f"crane copy {upstream} {target.reference}")
+        destination = mirrored_ref(target.reference, config.prefix)
+        print(f"Mirror {target.reference} -> {destination}")
+        bash(f"crane copy {target.reference} {destination}")
     print(f"Mirrored images: {len(targets)}")
 
 
@@ -42,49 +41,27 @@ def load_mirror_config(root: Path) -> MirrorConfig | None:
     return config.mirror if config is not None else None
 
 
-def is_mirrored(reference: str, prefix: str) -> bool:
-    return reference.startswith(f"{prefix}/")
-
-
-def upstream_ref(reference: str, prefix: str) -> str:
-    return reference[len(prefix) + 1 :]
+def mirrored_ref(reference: str, prefix: str) -> str:
+    if reference.startswith(f"{prefix}/"):
+        raise RuntimeError(
+            f"x-base-images values are upstream-native; {reference} already carries the mirror prefix {prefix}"
+        )
+    return f"{prefix}/{reference}"
 
 
 def reference_exists(reference: str) -> bool:
     return bash_check(f"docker buildx imagetools inspect {shlex.quote(reference)}")
 
 
-def mirror_targets(root: Path, prefix: str) -> list[ImageReference]:
-    return sorted(
-        (occurrence for occurrence in declared_references(root) if is_mirrored(occurrence.reference, prefix)),
-        key=lambda occurrence: occurrence.reference,
-    )
-
-
-def upstream_fallback(lock_data: dict[str, str], prefix: str, *, allow_upstream_fallback: bool) -> dict[str, str]:
-    missing = {
-        name: value for name, value in lock_data.items() if is_mirrored(value, prefix) and not reference_exists(value)
-    }
-    if not missing:
-        return {}
-    if not allow_upstream_fallback:
-        value = next(iter(missing.values()))
+def enforce_mirrored(lock_data: dict[str, str]) -> None:
+    for value in sorted(lock_data.values()):
+        if reference_exists(value):
+            continue
         reference, _, digest = value.rpartition("@")
         raise RuntimeError(
-            f"Image {reference or value} (digest {digest or 'unknown'}) is not mirrored yet. "
-            "If this is a new upstream dependency that has not been through CI, pass --allow-upstream-fallback "
-            "to pull the same digest from upstream for this run."
+            f"Image {reference or value} (digest {digest or 'unknown'}) is not mirrored yet; "
+            "the CI mirror job populates it when the declaring change runs"
         )
-    return {name: upstream_ref(value, prefix) for name, value in missing.items()}
-
-
-def write_fallback_overlay(substitutions: dict[str, str]) -> Path:
-    overlay = Path(tempfile.gettempdir()) / f"docker-devkit-upstream-fallback-{os.getpid()}.env"
-    overlay.write_text(
-        "\n".join(f"{name}={value}" for name, value in sorted(substitutions.items())) + "\n",
-        encoding="utf-8",
-    )
-    return overlay
 
 
 def main() -> None:

docker_devkit/up.py

@@ -16,7 +16,7 @@ from .lifecycle import (
     resolve_lock,
     resolve_manifest,
 )
-from .mirror import load_mirror_config, upstream_fallback, write_fallback_overlay
+from .mirror import enforce_mirrored, load_mirror_config
 from .modes import parse_env_file, resolve_auth_mode
 
 ENV_FILE = Path(".env")
@@ -42,19 +42,12 @@ def up(
         "--dev",
         help="Layer the declared dev overlay (compose.dev.yml shape) over the production stack for bind-mount/debug bring-up.",
     ),
-    allow_upstream_fallback: Annotated[
-        bool,
-        typer.Option(
-            "--allow-upstream-fallback",
-            help="Pull unmirrored lock entries from upstream at the same digest instead of failing closed.",
-        ),
-    ] = False,
 ) -> None:
     root = Path.cwd()
     config = load_lifecycle_config(root)
     enforce_bake_declaration(root, config)
     manifest = resolve_manifest(root)
-    lock_file = resolve_lock(root, manifest)
+    lock_file = resolve_lock(root)
 
     if dev and (config is None or config.dev_file is None):
         raise RuntimeError("--dev requires a dev_file in the lifecycle section of docker-devkit.yaml")
@@ -75,21 +68,12 @@ def up(
 
     auth_mode = resolve_auth_mode(ENV_FILE)
 
-    substitutions: dict[str, str] = {}
-    fallback_overlay: Path | None = None
     mirror_config = load_mirror_config(root)
     if mirror_config is not None:
-        substitutions = upstream_fallback(
-            parse_env_file(lock_file), mirror_config.prefix, allow_upstream_fallback=allow_upstream_fallback
-        )
-        if substitutions:
-            for name, upstream in sorted(substitutions.items()):
-                print(f"Falling back to upstream for {name}: {upstream}", flush=True)
-            os.environ.update(substitutions)
-            fallback_overlay = write_fallback_overlay(substitutions)
+        enforce_mirrored(parse_env_file(lock_file))
 
     if build:
-        run_build(gpu=gpu, env_overlay=substitutions)
+        run_build(gpu=gpu)
 
     if manifest is not None:
         os.environ.update(compute_service_shas(root, parse_bake(manifest)))
@@ -101,8 +85,6 @@ def up(
     files_args = " ".join(f"-f {compose_file}" for compose_file in compose_files)
     profile_flag = "--profile keycloak " if auth_mode == "keycloak" else ""
     compose_args = f"{files_args} {profile_flag}--project-directory {root} --env-file .env --env-file {lock_file}"
-    if fallback_overlay is not None:
-        compose_args += f" --env-file {fallback_overlay}"
 
     up_command = f"docker compose {compose_args} up"
     if not build:

{docker_devkit-0.3.0.dev113.dist-info → docker_devkit-0.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: docker-devkit
-Version: 0.3.0.dev113
+Version: 0.4.0
 Summary: Docker-stack lifecycle commands (up/down/build) driven by a pyproject-declared compose assembly
 License-File: LICENSE
 License-File: NOTICE

docker_devkit-0.4.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+docker_devkit/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+docker_devkit/build_docker.py,sha256=-oH0RPIDm1EZOh6UP2MMEDSX0G6W6zM4YgZSHw6_8u0,12978
+docker_devkit/config.py,sha256=UMAS6yF1E9PIbsRs2TVig9XwSNCvQe5w9eTLUHOPKq0,3112
+docker_devkit/context_sha.py,sha256=lhCxUcYM98xCdDum3hsFRFw5WYrjvZUSMbOu_7ZmQjE,3041
+docker_devkit/detect_gpu.py,sha256=C4e3vixvSSJS6xQiMVWp2IdWSAgMr551KrBTuIrkTk4,456
+docker_devkit/documents.py,sha256=c6jqbBNUKyJOltex-8u536_niWhEL7ScOab_MwZmM9k,2195
+docker_devkit/down.py,sha256=WDlq_RBpP84E1-5sp7MtKEhRB9wBOz8Ib59RoviZ8uQ,2179
+docker_devkit/image_refs.py,sha256=dyngpklq8mz4rGzb7gZGg3o3i9q5YO6_DRAC9fBNRfw,5148
+docker_devkit/lifecycle.py,sha256=_2ZTn2xpjhDFzdVacA2oog2CvsDujaoc8oqnRnpHtC8,1631
+docker_devkit/matrix.py,sha256=6NyGL4Ol849dYlcMRzAL2yjFoN6sGkGwVaaxcDm3bG4,4530
+docker_devkit/mirror.py,sha256=AGL_oQUv68DKXjEFVdD-NQoLbC6w3DZJ7h-lzzvdKwM,2334
+docker_devkit/modes.py,sha256=Lwhblzu5Kn7qhfy_QMqE28XuflSIJtCRBYNX7Iq8Qfo,1510
+docker_devkit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+docker_devkit/score_generate.py,sha256=psbQm-MWf9A5YP0ov0rLPUiuVAQbUWn6yfUmB-CXurU,9434
+docker_devkit/up.py,sha256=9h5fNuEfUQbQozae8yrueiSfS_Be_ne0SuR1j6tadbU,3394
+docker_devkit-0.4.0.dist-info/METADATA,sha256=_RO7Dz5QqwAHku7kcbtB9VvCvRID1hpXCrLzsrHAyCM,533
+docker_devkit-0.4.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+docker_devkit-0.4.0.dist-info/entry_points.txt,sha256=6cAHqlMvuXI00uTJLf73MTqWnLd1-m5sDgJrSyHWv4U,244
+docker_devkit-0.4.0.dist-info/licenses/LICENSE,sha256=RFhQPdSOiMTguUX7JSoIuTxA7HVzCbj_p8WU36HjUQQ,10947
+docker_devkit-0.4.0.dist-info/licenses/NOTICE,sha256=jvglZza3GCdN7v4_TLuXUqX9C_uABlwAKUkcIeKwk_8,26
+docker_devkit-0.4.0.dist-info/RECORD,,

docker_devkit-0.3.0.dev113.dist-info/RECORD

@@ -1,21 +0,0 @@
-docker_devkit/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-docker_devkit/build_docker.py,sha256=DtvTUTGHdQAkpBVelGObWyYD5Ldc05iPWXkNpCMQt-E,12927
-docker_devkit/config.py,sha256=UMAS6yF1E9PIbsRs2TVig9XwSNCvQe5w9eTLUHOPKq0,3112
-docker_devkit/context_sha.py,sha256=lhCxUcYM98xCdDum3hsFRFw5WYrjvZUSMbOu_7ZmQjE,3041
-docker_devkit/detect_gpu.py,sha256=C4e3vixvSSJS6xQiMVWp2IdWSAgMr551KrBTuIrkTk4,456
-docker_devkit/documents.py,sha256=c6jqbBNUKyJOltex-8u536_niWhEL7ScOab_MwZmM9k,2195
-docker_devkit/down.py,sha256=9OMXPZQ3SIdaSELc46hzkqNpLSwOJ1athCD8Bmlz2BI,2189
-docker_devkit/image_refs.py,sha256=6pHYPWh4lL6qMqHtQBHBbeWijVsT0PhsMS6CMDho5nY,5294
-docker_devkit/lifecycle.py,sha256=FuwaCSRK7qVx_qj-HmIFqMm8Ak4cpAQEqqXRPDNCLmo,2259
-docker_devkit/matrix.py,sha256=6NyGL4Ol849dYlcMRzAL2yjFoN6sGkGwVaaxcDm3bG4,4530
-docker_devkit/mirror.py,sha256=tissqnoqMwRA6s0ykwXZOEgy6F1d3AAebPKGEkSpJRg,3224
-docker_devkit/modes.py,sha256=Lwhblzu5Kn7qhfy_QMqE28XuflSIJtCRBYNX7Iq8Qfo,1510
-docker_devkit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-docker_devkit/score_generate.py,sha256=psbQm-MWf9A5YP0ov0rLPUiuVAQbUWn6yfUmB-CXurU,9434
-docker_devkit/up.py,sha256=32A2_6mxAF00XILecxYTzCQw0QvSjevBWCnayF5X1Xs,4284
-docker_devkit-0.3.0.dev113.dist-info/METADATA,sha256=0NT3OLGPZKW3hL5cvP-avLSORfSbo57cbDvwrZV2aOs,540
-docker_devkit-0.3.0.dev113.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-docker_devkit-0.3.0.dev113.dist-info/entry_points.txt,sha256=6cAHqlMvuXI00uTJLf73MTqWnLd1-m5sDgJrSyHWv4U,244
-docker_devkit-0.3.0.dev113.dist-info/licenses/LICENSE,sha256=RFhQPdSOiMTguUX7JSoIuTxA7HVzCbj_p8WU36HjUQQ,10947
-docker_devkit-0.3.0.dev113.dist-info/licenses/NOTICE,sha256=jvglZza3GCdN7v4_TLuXUqX9C_uABlwAKUkcIeKwk_8,26
-docker_devkit-0.3.0.dev113.dist-info/RECORD,,