gpustack-runner 0.1.23.post5__py3-none-any.whl → 0.1.24__py3-none-any.whl

gpustack_runner/__init__.py

@@ -1,5 +1,11 @@
 from __future__ import annotations
 
+from .__utils__ import (
+    merge_image,
+    parse_image,
+    replace_image_with,
+    split_image,
+)
 from ._version import commit_id, version, version_tuple
 from .runner import (
     BackendRunners,
@@ -21,7 +27,11 @@ __all__ = [
     "list_backend_runners",
     "list_runners",
     "list_service_runners",
+    "merge_image",
+    "parse_image",
+    "replace_image_with",
     "set_re_docker_image",
+    "split_image",
     "version",
     "version_tuple",
 ]

gpustack_runner/__main__.py

@@ -11,6 +11,7 @@ from .cmds import (
     CompareImagesSubCommand,
     CopyImagesSubCommand,
     ListImagesSubCommand,
+    LoadImagesSubCommand,
     SaveImagesSubCommand,
 )
 
@@ -35,6 +36,7 @@ def main():
     SaveImagesSubCommand.register(subcommand_parser)
     CopyImagesSubCommand.register(subcommand_parser)
     CompareImagesSubCommand.register(subcommand_parser)
+    LoadImagesSubCommand.register(subcommand_parser)
 
     # Autocomplete
     argcomplete.autocomplete(parser)

gpustack_runner/__utils__.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+
+_BLANK_TAG = "latest"
+
+
+def split_image(image: str, fill_blank_tag: bool = False) -> tuple:
+    """
+    Split the Docker completed image string into its image_name([registry/][namespace/]repository) and image_tag.
+
+    Args:
+        image:
+            The Docker completed image string to split.
+        fill_blank_tag:
+            If True, fill the blank tag with `latest`.
+
+    Returns:
+        A tuple of (image_name, image_tag).
+
+    """
+    parts = image.rsplit("@", maxsplit=1)
+    if len(parts) == 2:
+        return tuple(parts)
+    parts = image.rsplit(":", maxsplit=1)
+    if len(parts) == 2 and "/" not in parts[1]:
+        if fill_blank_tag:
+            parts[1] = parts[1] or _BLANK_TAG
+        return tuple(parts)
+    return image, _BLANK_TAG if fill_blank_tag else None
+
+
+def merge_image(image_name: str, image_tag: str | None = None) -> str:
+    """
+    Merge the Docker image and image_tag into a single string.
+
+    Args:
+        image_name:
+            The Docker image name, in form of [registry/][namespace/]repository.
+        image_tag:
+            The Docker image tag.
+
+    Returns:
+        The completed Docker image string.
+
+    """
+    if not image_tag:
+        return image_name
+    if image_tag.startswith("sha256:"):
+        return f"{image_name}@{image_tag}"
+    return f"{image_name}:{image_tag}"
+
+
+def parse_image(
+    image: str,
+    fill_blank_tag: bool = False,
+) -> tuple[str | None, str | None, str, str | None] | None:
+    """
+    Parse the Docker image string into its components:
+    registry, namespace, repository, and tag.
+
+    Args:
+        image:
+            The Docker image string to parse.
+        fill_blank_tag:
+            If True, fill the blank tag with `latest`.
+
+    Returns:
+        A tuple of (registry, namespace, repository, tag).
+        Registry, namespace, and tag can be None if not present.
+        If the image string is invalid, return None.
+
+    """
+    image_reg, image_ns, image_repo, image_tag = (
+        None,
+        None,
+        None,
+        None,
+    )
+    image_rest = image.strip()
+
+    # Get tag.
+    image_rest, image_tag = split_image(image_rest, fill_blank_tag=fill_blank_tag)
+    if not image_rest:
+        return None
+
+    # Get repository.
+    parts = image_rest.rsplit("/", maxsplit=1)
+    if len(parts) == 2:
+        image_rest, image_repo = parts
+    else:
+        image_rest, image_repo = None, image_rest
+
+    # Get namespace.
+    if image_rest:
+        parts = image_rest.rsplit("/", maxsplit=1)
+        if len(parts) == 2:
+            image_reg, image_ns = parts
+        else:
+            image_reg, image_ns = None, image_rest
+
+    return image_reg, image_ns, image_repo, image_tag
+
+
+def replace_image_with(
+    image: str,
+    registry: str | None = None,
+    namespace: str | None = None,
+    repository: str | None = None,
+) -> str:
+    """
+    Replace the registry, namespace, and repository of a Docker image string.
+
+    The given image string is parsed into its components (registry, namespace, repository, tag),
+    and the specified components are replaced with the provided values.
+
+    The format of a Docker image string is:
+    [registry/][namespace/]repository[:tag|@digest]
+
+    Args:
+        image:
+            The original Docker image string.
+        registry:
+            The new registry to use. If None, keep the original registry.
+        namespace:
+            The new namespace to use. If None, keep the original namespace.
+        repository:
+            The new repository to use. If None, keep the original repository.
+
+    Returns:
+        The modified Docker image string.
+
+    """
+    if not image or (not registry and not namespace and not repository):
+        return image
+
+    registry = registry.strip() if registry else None
+    namespace = namespace.strip() if namespace else None
+    repository = repository.strip() if repository else None
+
+    image_reg, image_ns, image_repo, image_tag = parse_image(image)
+
+    registry = registry or image_reg
+    namespace = namespace or image_ns
+    repository = repository or image_repo
+
+    image_name = ""
+    if registry:
+        image_name += f"{registry}/"
+    if namespace:
+        image_name += f"{namespace}/"
+    elif registry:
+        image_name += "library/"
+    image_name += repository
+
+    image = merge_image(image_name, image_tag)
+    return image

gpustack_runner/_version.py

@@ -27,8 +27,8 @@ version_tuple: VERSION_TUPLE
 __commit_id__: COMMIT_ID
 commit_id: COMMIT_ID
 
-__version__ = version = '0.1.23.post5'
-__version_tuple__ = version_tuple = (0, 1, 23, 'post5')
+__version__ = version = '0.1.24'
+__version_tuple__ = version_tuple = (0, 1, 24)
 try:
     from ._version_appendix import git_commit
     __commit_id__ = commit_id = git_commit

gpustack_runner/_version_appendix.py

@@ -1 +1 @@
-git_commit = "d297d69"
+git_commit = "c2b7172"

gpustack_runner/cmds/__init__.py

@@ -4,6 +4,7 @@ from .images import (
     CompareImagesSubCommand,
     CopyImagesSubCommand,
     ListImagesSubCommand,
+    LoadImagesSubCommand,
     PlatformedImage,
     SaveImagesSubCommand,
     append_images,
@@ -14,6 +15,7 @@ __all__ = [
     "CompareImagesSubCommand",
     "CopyImagesSubCommand",
     "ListImagesSubCommand",
+    "LoadImagesSubCommand",
     "PlatformedImage",
     "SaveImagesSubCommand",
     "append_images",

gpustack_runner/cmds/images.py

@@ -9,7 +9,7 @@ import sys
 import tempfile
 import time
 from argparse import OPTIONAL
-from concurrent.futures import CancelledError, ThreadPoolExecutor, as_completed
+from concurrent.futures import CancelledError, Future, ThreadPoolExecutor, as_completed
 from dataclasses import dataclass
 from pathlib import Path
 from typing import TYPE_CHECKING
@@ -17,7 +17,14 @@ from typing import TYPE_CHECKING
 import requests
 from dataclasses_json import dataclass_json
 
-from gpustack_runner import BackendRunners, envs, list_backend_runners
+from gpustack_runner import (
+    BackendRunners,
+    envs,
+    list_backend_runners,
+    merge_image,
+    replace_image_with,
+    split_image,
+)
 
 from .__types__ import SubCommand
 
@@ -29,6 +36,7 @@ _AVAILABLE_BACKENDS = [
     "corex",
     "cuda",
     "dtk",
+    "hggc",
     "maca",
     "musa",
     "neuware",
@@ -46,10 +54,6 @@ _AVAILABLE_PLATFORMS = [
 ]
 
 
-# Disable overriding default namespace at images operations.
-os.environ["GPUSTACK_RUNNER_DEFAULT_NAMESPACE"] = "gpustack"
-
-
 class ListImagesSubCommand(SubCommand):
     """
     Command to list images.
@@ -187,7 +191,7 @@ class ListImagesSubCommand(SubCommand):
 
 class SaveImagesSubCommand(SubCommand):
     """
-    Command to save images to local that matched Docker Archive.
+    Command to save images to local that matched Docker/OCI archive.
     """
 
     backend: str
@@ -206,13 +210,14 @@ class SaveImagesSubCommand(SubCommand):
     source_namespace: str
     source_username: str
     source_password: str
+    archive_format: str
     output: Path
 
     @staticmethod
     def register(parser: _SubParsersAction):
         save_parser = parser.add_parser(
             "save-images",
-            help="Save images as Docker Archive to local path, "
+            help="Save images as OCI/Docker Archive to local path, "
             "powered by https://github.com/containers/skopeo",
         )
 
@@ -305,10 +310,7 @@ class SaveImagesSubCommand(SubCommand):
             "--source-namespace",
             "--src-namespace",
             type=str,
-            help="Source namespace in the source registry, "
-            "if the namespace has multiple levels, "
-            "please specify the parent levels to --source, "
-            "e.g --source my.registry.com/a/b --source-namespace c",
+            help="Namespace in the source registry",
         )
 
         save_parser.add_argument(
@@ -322,7 +324,16 @@ class SaveImagesSubCommand(SubCommand):
             "--source-password",
             "--src-passwd",
             type=str,
-            help="Password/Token for source registry authentication (env: SOURCE_PASSWORD)",
+            help="Password/Token for source registry authentication "
+            "(env: SOURCE_PASSWORD)",
+        )
+
+        save_parser.add_argument(
+            "--archive-format",
+            type=str,
+            choices=["oci", "docker"],
+            default="oci",
+            help="Archive format to save (default: oci)",
         )
 
         save_parser.add_argument(
@@ -352,16 +363,21 @@ class SaveImagesSubCommand(SubCommand):
         self.source_namespace = args.source_namespace
         self.source_username = args.source_username or os.getenv("SOURCE_USERNAME")
         self.source_password = args.source_password or os.getenv("SOURCE_PASSWORD")
+        self.archive_format = args.archive_format
         self.output = Path(args.output or Path.cwd())
 
         try:
             if not self.output.exists():
                 self.output.mkdir(parents=True, exist_ok=True)
         except OSError as e:
-            msg = f"Failed to create output directory '{self.output}'"
-            raise RuntimeError(
-                msg,
-            ) from e
+            msg = (
+                f"Failed to prepare output directory '{self.output}' for saving images"
+            )
+            raise RuntimeError(msg) from e
+
+        if not self.output.is_dir():
+            msg = f"Output path '{self.output}' is not a directory"
+            raise RuntimeError(msg)
 
     def run(self):
         images = list_images(
@@ -389,11 +405,23 @@ class SaveImagesSubCommand(SubCommand):
 
         print("\033[2J\033[H", end="")
 
-        print(f"Output Directory: {self.output}")
-        print(f"Image Platform: {self.platform} ")
-        print(f"Total Images ({len(images)}): ")
-        for img in images:
-            print("  -", img.name)
+        saving_tasks: list[tuple[str, str, Path, Path]] = []
+        print(
+            f"Output: {self.output} | Archive: {self.archive_format} | Platform: {self.platform}",
+        )
+        print(f"Saving Images ({len(images)}):")
+        for task_idx, img in enumerate(images):
+            task_name = f"task-{task_idx:0>2d}"
+            src_img = f"{self.source}/{img.name}"
+            img_name, img_tag = split_image(src_img, fill_blank_tag=True)
+            dst_file = self.output / img_name / f"{img_tag}.tar"
+            dst_file_relative = dst_file.relative_to(self.output)
+            saving_tasks.append(
+                (task_name, src_img, dst_file, dst_file_relative),
+            )
+            print(
+                f"  - [{task_name}]: {src_img} -> {dst_file_relative}",
+            )
         print()
 
         for i in range(5, 0, -1):
@@ -410,37 +438,35 @@ class SaveImagesSubCommand(SubCommand):
             max_workers=self.max_workers,
             thread_name_prefix="gpustack-saving-image",
         ) as executor:
-            futures = {}
-            failures = []
+            futures: dict[Future, tuple[str, str, Path, Path]] = {}
+            failures: list[tuple[str, str, Path, str]] = []
 
             def check_result(f):
-                img_name, img_output = futures[f]
+                _task_name, _src_img, _dst_file, _dst_file_relative = futures[f]
                 try:
                     result = f.result()
                     if result.returncode == 0:
-                        print(f"✅ Downloaded image '{img_name}'")
+                        print(f"✅ Saved {_src_img} -> {_dst_file_relative}")
                         return
-                    img_err = result.stderr
+                    _save_err = result.stderr
                 except subprocess.CalledProcessError as cpe:
-                    img_err = cpe.stderr if cpe.stderr else str(cpe)
+                    _save_err = cpe.stderr if cpe.stderr else str(cpe)
                 except CancelledError:
                     return
                 except Exception as e:
-                    img_err = str(e)
-                print(f"❌ Error downloading image '{img_name}'")
-                failures.append((img_name, img_err))
-                img_output.unlink(missing_ok=True)
+                    _save_err = str(e)
+                print(f"❌ Error saving {_src_img} -> {_dst_file_relative}")
+                _dst_file.unlink(missing_ok=True)
+                failures.append((_task_name, _src_img, _dst_file_relative, _save_err))
 
             override_os, override_arch = self.platform.split("/", maxsplit=1)
 
             # Submit tasks
-            for img in images:
-                output_path = (
-                    self.output / f"{img.name.replace('/', '-').replace(':', '_')}.tar"
-                )
-                if output_path.exists():
-                    print(f"Image {img.name} already exists, skipping download.")
+            for task_name, src_img, dst_file, dst_file_relative in saving_tasks:
+                if dst_file.exists():
+                    print(f"{dst_file.name} already exists, skipping save {src_img}.")
                     continue
+                dst_file.parent.mkdir(parents=True, exist_ok=True, mode=0o744)
 
                 command = [
                     "skopeo",
@@ -462,19 +488,19 @@ class SaveImagesSubCommand(SubCommand):
                     )
                 command.extend(
                     [
-                        f"docker://{self.source}/{img.name}",
-                        f"docker-archive:{output_path}",
+                        f"docker://{src_img}",
+                        f"{self.archive_format}-archive:{dst_file}:{src_img}",
                     ],
                 )
 
                 future = executor.submit(
                     _execute_command,
-                    title=img.name,
-                    description=f"⏳ Downloading image '{img.name}'...",
+                    title=task_name,
+                    description=f"⏳ Saving {src_img} -> {dst_file_relative}...",
                     command=command,
                 )
                 future.add_done_callback(check_result)
-                futures[future] = (img.name, output_path)
+                futures[future] = (task_name, src_img, dst_file, dst_file_relative)
 
             # Wait
             try:
@@ -488,11 +514,11 @@ class SaveImagesSubCommand(SubCommand):
             # Review
             print()
             if failures:
-                print(f"⚠️ Error downloading {len(failures)} images:")
-                for name, err in failures:
-                    print(f"  - {name}:")
-                    if err:
-                        for line in err.splitlines():
+                print(f"⚠️ Error saving {len(failures)} images:")
+                for task_name, src_img, dst_file_relative, save_err in failures:
+                    print(f"  - [{task_name}]: {src_img} -> {dst_file_relative}")
+                    if save_err:
+                        for line in save_err.splitlines():
                             print(f"      {line}")
                     else:
                         print("      (no error message)")
@@ -622,10 +648,7 @@ class CopyImagesSubCommand(SubCommand):
             "--source-namespace",
             "--src-namespace",
             type=str,
-            help="Source namespace in the source registry, "
-            "if the namespace has multiple levels, "
-            "please specify the parent levels to --source, "
-            "e.g --source my.registry.com/a/b --source-namespace c",
+            help="Namespace in the source registry",
         )
 
         copy_parser.add_argument(
@@ -639,39 +662,40 @@ class CopyImagesSubCommand(SubCommand):
             "--source-password",
             "--src-passwd",
             type=str,
-            help="Password/Token for source registry authentication (env: SOURCE_PASSWORD)",
+            help="Password/Token for source registry authentication "
+            "(env: SOURCE_PASSWORD)",
         )
 
         copy_parser.add_argument(
             "--destination",
             "--dest",
             type=str,
-            default="docker.io",
-            help="Destination registry (default: docker.io)",
+            help="Destination registry (default: docker.io) "
+            "(env: GPUSTACK_RUNNER_DEFAULT_CONTAINER_REGISTRY, GPUSTACK_RUNTIME_DEPLOY_DEFAULT_CONTAINER_REGISTRY, GPUSTACK_SYSTEM_DEFAULT_CONTAINER_REGISTRY)",
         )
 
         copy_parser.add_argument(
             "--destination-namespace",
             "--dest-namespace",
             type=str,
-            help="Source namespace in the destination registry, "
-            "if the namespace has multiple levels, "
-            "please specify the parent levels to --destination, "
-            "e.g --destination my.registry.com/a/b --destination-namespace c",
+            help="Namespace in the destination registry "
+            "(env: GPUSTACK_RUNNER_DEFAULT_CONTAINER_NAMESPACE, GPUSTACK_RUNTIME_DEPLOY_DEFAULT_CONTAINER_NAMESPACE)",
         )
 
         copy_parser.add_argument(
             "--destination-username",
             "--dest-user",
             type=str,
-            help="Username for destination registry authentication (env: DESTINATION_USERNAME)",
+            help="Username for destination registry authentication "
+            "(env: DESTINATION_USERNAME)",
         )
 
         copy_parser.add_argument(
             "--destination-password",
             "--dest-passwd",
             type=str,
-            help="Password/Token for destination registry authentication (env: DESTINATION_PASSWORD)",
+            help="Password/Token for destination registry authentication "
+            "(env: DESTINATION_PASSWORD)",
         )
 
         copy_parser.set_defaults(func=CopyImagesSubCommand)
@@ -695,8 +719,15 @@ class CopyImagesSubCommand(SubCommand):
         self.source_namespace = args.source_namespace
         self.source_username = args.source_username or os.getenv("SOURCE_USERNAME")
         self.source_password = args.source_password or os.getenv("SOURCE_PASSWORD")
-        self.destination = args.destination
-        self.destination_namespace = args.destination_namespace
+        self.destination = (
+            args.destination
+            or envs.GPUSTACK_RUNNER_DEFAULT_CONTAINER_REGISTRY
+            or "docker.io"
+        )
+        self.destination_namespace = (
+            args.destination_namespace
+            or envs.GPUSTACK_RUNNER_DEFAULT_CONTAINER_NAMESPACE
+        )
         self.destination_username = args.destination_username or os.getenv(
             "DESTINATION_USERNAME",
         )
@@ -730,11 +761,20 @@ class CopyImagesSubCommand(SubCommand):
 
         print("\033[2J\033[H", end="")
 
-        print(f"Destination: {self.destination}")
-        print(f"Source: {self.source} ")
-        print(f"Total Images ({len(images)}): ")
-        for img in images:
-            print("  -", img.name)
+        copying_tasks: list[tuple[str, str, str]] = []
+        print(f"Copying Images ({len(images)}):")
+        for task_idx, img in enumerate(images):
+            task_name = f"task-{task_idx:0>2d}"
+            src_img = f"{self.source}/{img.name}"
+            dst_img_name = img.name
+            if self.destination_namespace:
+                _, suffix = img.name.split("/", maxsplit=1)
+                dst_img_name = f"{self.destination_namespace}/{suffix}"
+            dst_img = f"{self.destination}/{dst_img_name}"
+            copying_tasks.append(
+                (task_name, src_img, dst_img),
+            )
+            print(f"  - [{task_name}]: {src_img} -> {dst_img}")
         print()
 
         for i in range(5, 0, -1):
@@ -751,32 +791,32 @@ class CopyImagesSubCommand(SubCommand):
             max_workers=self.max_workers,
             thread_name_prefix="gpustack-copying-image",
         ) as executor:
-            futures = {}
-            failures = []
+            futures: dict[Future, tuple[str, str, str]] = {}
+            failures: list[tuple[str, str, str, str]] = []
 
             def check_result(f):
-                img_name = futures[f]
+                _task_name, _src_img, _dst_img = futures[f]
                 try:
                     result = f.result()
                     if result.returncode == 0:
-                        print(f"✅ Synced image '{img_name}'")
+                        print(f"✅ Copied {_src_img} -> {_dst_img}")
                         return
-                    img_err = result.stderr
+                    _copy_err = result.stderr
                 except subprocess.CalledProcessError as cpe:
-                    img_err = cpe.stderr if cpe.stderr else str(cpe)
+                    _copy_err = cpe.stderr if cpe.stderr else str(cpe)
                 except CancelledError:
                     return
                 except Exception as e:
-                    img_err = str(e)
-                print(f"❌ Error syncing image '{img_name}'")
-                failures.append((img_name, img_err))
+                    _copy_err = str(e)
+                print(f"❌ Error copying {_src_img} -> {_dst_img}")
+                failures.append((_task_name, _src_img, _dst_img, _copy_err))
 
             override_os, override_arch = None, None
             if self.platform:
                 override_os, override_arch = self.platform.split("/", maxsplit=1)
 
             # Submit tasks
-            for img in images:
+            for task_name, src_img, dst_img in copying_tasks:
                 command = [
                     "skopeo",
                     "copy",
@@ -810,29 +850,21 @@ class CopyImagesSubCommand(SubCommand):
                             f"{self.destination_username}:{self.destination_password}",
                         ],
                     )
-                dest_img_name = img.name
-                if self.destination_namespace:
-                    _, suffix = img.name.split("/", maxsplit=1)
-                    dest_img_name = f"{self.destination_namespace}/{suffix}"
                 command.extend(
                     [
-                        f"docker://{self.source}/{img.name}",
-                        f"docker://{self.destination}/{dest_img_name}",
+                        f"docker://{src_img}",
+                        f"docker://{dst_img}",
                     ],
                 )
 
                 future = executor.submit(
                     _execute_command,
-                    title=img.name,
-                    description=(
-                        f"⏳ Syncing image '{img.name}' to '{dest_img_name}'..."
-                        if img.name != dest_img_name
-                        else f"⏳ Syncing image '{img.name}'..."
-                    ),
+                    title=task_name,
+                    description=f"⏳ Copying {src_img} -> {dst_img}...",
                     command=command,
                 )
                 future.add_done_callback(check_result)
-                futures[future] = img.name
+                futures[future] = (task_name, src_img, dst_img)
 
             # Wait
             try:
@@ -846,11 +878,255 @@ class CopyImagesSubCommand(SubCommand):
             # Review
             print()
             if failures:
-                print(f"⚠️ Error syncing {len(failures)} images:")
-                for name, err in failures:
-                    print(f"  - {name}:")
-                    if err:
-                        for line in err.splitlines():
+                print(f"⚠️ Error copying {len(failures)} images:")
+                for task_name, src_img, dst_img, copy_err in failures:
+                    print(f"  - [{task_name}]: {src_img} -> {dst_img}:")
+                    if copy_err:
+                        for line in copy_err.splitlines():
+                            print(f"      {line}")
+                    else:
+                        print("      (no error message)")
+                sys.exit(1)
+
+
+class LoadImagesSubCommand(SubCommand):
+    """
+    Command to load images to local container image storage that matched Docker/OCI archive.
+
+    """
+
+    repository: str
+    platform: str
+    max_workers: int
+    max_retries: int
+    destination: str
+    destination_namespace: str
+    archive_format: str
+    storage: str
+    input: Path
+    archives: list[Path]
+
+    @staticmethod
+    def register(parser: _SubParsersAction):
+        load_parser = parser.add_parser(
+            "load-images",
+            help="Load images from OCI/Docker Archive to local container image storage, "
+            "powered by https://github.com/containers/skopeo",
+        )
+
+        load_parser.add_argument(
+            "--repository",
+            type=str,
+            help="Filter images by repository name",
+        )
+
+        load_parser.add_argument(
+            "--platform",
+            type=str,
+            help="Filter images by platform (default: current platform)",
+            choices=_AVAILABLE_PLATFORMS,
+        )
+
+        load_parser.add_argument(
+            "--max-workers",
+            type=int,
+            default=1,
+            help="Maximum number of worker threads to use for loading images concurrently (default: 1)",
+        )
+
+        load_parser.add_argument(
+            "--max-retries",
+            type=int,
+            default=1,
+            help="Maximum number of retries for loading an image (default: 1)",
+        )
+
+        load_parser.add_argument(
+            "--destination",
+            "--dest",
+            type=str,
+            help="Override destination registry "
+            "(env: GPUSTACK_RUNNER_DEFAULT_CONTAINER_REGISTRY, GPUSTACK_RUNTIME_DEPLOY_DEFAULT_CONTAINER_REGISTRY, GPUSTACK_SYSTEM_DEFAULT_CONTAINER_REGISTRY)",
+        )
+
+        load_parser.add_argument(
+            "--destination-namespace",
+            "--dest-namespace",
+            type=str,
+            help="Override namespace in the destination registry "
+            "(env: GPUSTACK_RUNNER_DEFAULT_CONTAINER_NAMESPACE, GPUSTACK_RUNTIME_DEPLOY_DEFAULT_CONTAINER_NAMESPACE)",
+        )
+
+        load_parser.add_argument(
+            "--archive-format",
+            type=str,
+            choices=["oci", "docker"],
+            default="oci",
+            help="Archive format to load (default: oci)",
+        )
+
+        load_parser.add_argument(
+            "--storage",
+            type=str,
+            choices=["docker", "podman"],
+            default="docker",
+            help="Container image storage to load images into (default: docker)",
+        )
+
+        load_parser.add_argument(
+            "input",
+            nargs=OPTIONAL,
+            help="Input directory to load images (default: current working directory)",
+        )
+
+        load_parser.set_defaults(func=LoadImagesSubCommand)
+
+    def __init__(self, args: Namespace):
+        _ensure_required_tools()
+
+        self.repository = args.repository
+        self.platform = args.platform or _get_current_platform()
+        self.max_workers = args.max_workers
+        self.max_retries = args.max_retries
+        self.destination = (
+            args.destination or envs.GPUSTACK_RUNNER_DEFAULT_CONTAINER_REGISTRY
+        )
+        self.destination_namespace = (
+            args.destination_namespace
+            or envs.GPUSTACK_RUNNER_DEFAULT_CONTAINER_NAMESPACE
+        )
+        self.archive_format = args.archive_format
+        self.storage = args.storage
+        self.input = Path(args.input)
+        self.archives = []
+
+        if not self.input.exists() or not self.input.is_dir():
+            msg = f"Input path '{self.input}' is not a valid directory"
+            raise RuntimeError(msg)
+
+        if self.input.exists() and self.input.is_dir():
+            for archive_path in self.input.rglob("*.tar"):
+                if not archive_path.is_file():
+                    continue
+                if self.repository and archive_path.parent.name != self.repository:
+                    continue
+                self.archives.append(archive_path)
+
+    def run(self):
+        if not self.archives:
+            print("No matching image archives found.")
+            return
+
+        print("\033[2J\033[H", end="")
+
+        loading_tasks: list[tuple[str, Path, Path, str]] = []
+        print(
+            f"Input: {self.input} | Archive: {self.archive_format} | Storage: {self.storage}",
+        )
+        print(f"Loading Images ({len(self.archives)}):")
+        for task_idx, src_file in enumerate(self.archives):
+            task_name = f"task-{task_idx:0>2d}"
+            src_file_relative = src_file.relative_to(self.input)
+            dst_img_repo = str(src_file.parent.relative_to(self.input))
+            dst_img_tag = src_file.name.removesuffix(src_file.suffix)
+            dst_img = replace_image_with(
+                merge_image(dst_img_repo, dst_img_tag),
+                registry=self.destination,
+                namespace=self.destination_namespace,
+            )
+            loading_tasks.append(
+                (task_name, src_file, src_file_relative, dst_img),
+            )
+            print(f"  - [{task_name}]: {src_file_relative} -> {dst_img}")
+        print()
+
+        for i in range(5, 0, -1):
+            if sys.stdout.isatty():
+                print(f"\rStarting in {i} seconds...   ", end="", flush=True)
+            else:
+                print(f"Starting in {i} seconds...")
+            time.sleep(1)
+        if sys.stdout.isatty():
+            print("\rStarting now...              ", end="", flush=True)
+        print()
+
+        with ThreadPoolExecutor(
+            max_workers=self.max_workers,
+            thread_name_prefix="gpustack-loading-image",
+        ) as executor:
+            futures: dict[Future, tuple[str, Path, str]] = {}
+            failures: list[tuple[str, Path, str, str]] = []
+
+            def check_result(f):
+                _task_name, _src_file_relative, _dst_img = futures[f]
+                try:
+                    result = f.result()
+                    if result.returncode == 0:
+                        print(
+                            f"✅ Loaded {_src_file_relative} -> {_dst_img}",
+                        )
+                        return
+                    _load_err = result.stderr
+                except subprocess.CalledProcessError as cpe:
+                    _load_err = cpe.stderr if cpe.stderr else str(cpe)
+                except CancelledError:
+                    return
+                except Exception as e:
+                    _load_err = str(e)
+                print(f"❌ Error loading {_src_file_relative} -> {_dst_img}")
+                failures.append((_task_name, _src_file_relative, _dst_img, _load_err))
+
+            override_os, override_arch = self.platform.split("/", maxsplit=1)
+
+            # Submit tasks
+            for task_name, src_file, src_file_relative, dst_img in loading_tasks:
+                command = [
+                    "skopeo",
+                    "copy",
+                    "--dest-tls-verify=false",
+                    "--retry-times",
+                    str(self.max_retries),
+                    "--override-os",
+                    override_os,
+                    "--override-arch",
+                    override_arch,
+                    f"{self.archive_format}-archive:{src_file}",
+                ]
+                if self.storage == "docker":
+                    command.append(
+                        f"docker-daemon:{dst_img}",
+                    )
+                else:
+                    command.append(
+                        f"containers-storage:{dst_img}",
+                    )
+
+                future = executor.submit(
+                    _execute_command,
+                    title=task_name,
+                    description=f"⏳ Loading {src_file_relative} -> {dst_img}...",
+                    command=command,
+                )
+                future.add_done_callback(check_result)
+                futures[future] = (task_name, src_file_relative, dst_img)
+
+            # Wait
+            try:
+                for _ in as_completed(futures):
+                    pass
+            except Exception:
+                for future in futures:
+                    future.cancel()
+                raise
+
+            # Review
+            print()
+            if failures:
+                print(f"⚠️ Error loading {len(failures)} images:")
+                for task_name, src_file_relative, dst_img, load_err in failures:
+                    print(f"  - [{task_name}]: {src_file_relative} -> {dst_img}:")
+                    if load_err:
+                        for line in load_err.splitlines():
                             print(f"      {line}")
                     else:
                         print("      (no error message)")
@@ -1072,6 +1348,10 @@ def list_images(**kwargs) -> list[PlatformedImage]:
         A list of platformed images.
 
     """
+    # Reset to default for listing images,
+    # in case the env is set to other value.
+    envs.GPUSTACK_RUNNER_DEFAULT_CONTAINER_NAMESPACE = None
+
     platform = kwargs.pop("platform", None)
     repository = kwargs.pop("repository", None)
 
@@ -1108,9 +1388,6 @@ def list_images(**kwargs) -> list[PlatformedImage]:
             name = img.name
             if not name:
                 continue
-            if namespace := envs.GPUSTACK_RUNNER_DEFAULT_CONTAINER_NAMESPACE:
-                name = name.replace("gpustack/", f"{namespace}/")
-                img.name = name
             if name not in image_names_index:
                 image_names_index[name] = len(images)
                 images.append(img)
@@ -1220,3 +1497,8 @@ def _execute_command(
             args=command,
             returncode=returncode,
         )
+
+
+append_images(
+    "gpustack/runtime:pause",
+)

gpustack_runner/envs.py

@@ -9,6 +9,11 @@ if TYPE_CHECKING:
 
     # Global
 
+    GPUSTACK_RUNNER_DEFAULT_CONTAINER_REGISTRY: str | None = None
+    """
+    Default container registry for copying images.
+    If not set, it should be "docker.io".
+    """
     GPUSTACK_RUNNER_DEFAULT_CONTAINER_NAMESPACE: str | None = None
     """
     Namespace for default runner container images.
@@ -19,13 +24,24 @@ if TYPE_CHECKING:
 
 variables: dict[str, Callable[[], Any]] = {
     # Global
+    "GPUSTACK_RUNNER_DEFAULT_CONTAINER_REGISTRY": lambda: trim_str(
+        getenvs(
+            [
+                "GPUSTACK_RUNNER_DEFAULT_CONTAINER_REGISTRY",
+                # Compatible with gpustack/gpustack_runtime.
+                "GPUSTACK_RUNTIME_DEPLOY_DEFAULT_CONTAINER_REGISTRY",
+                # Compatible with gpustack/gpustack.
+                "GPUSTACK_SYSTEM_DEFAULT_CONTAINER_REGISTRY",
+            ],
+        ),
+    ),
     "GPUSTACK_RUNNER_DEFAULT_CONTAINER_NAMESPACE": lambda: trim_str(
         getenvs(
-            keys=[
+            [
                 "GPUSTACK_RUNNER_DEFAULT_CONTAINER_NAMESPACE",
-                ## Compatible with gpustack/gpustack_runtime.
+                # Compatible with gpustack/gpustack_runtime.
                 "GPUSTACK_RUNTIME_DEPLOY_DEFAULT_CONTAINER_NAMESPACE",
-                ## Legacy compatibility.
+                # Legacy compatibility.
                 "GPUSTACK_RUNNER_DEFAULT_IMAGE_NAMESPACE",
                 "GPUSTACK_RUNTIME_DEPLOY_DEFAULT_IMAGE_NAMESPACE",
             ],

gpustack_runner/runner.py

@@ -13,7 +13,7 @@ from dataclasses_json import dataclass_json
 from . import envs
 
 _RE_DOCKER_IMAGE = re.compile(
-    r"(?:(?P<prefix>[\w\\.\-]+(?:/[\w\\.\-]+)*)/)?runner:(?P<backend>(Host|cann|corex|cuda|dtk|maca|musa|rocm))(?P<backend_version>[XY\d\\.]+)(?:-(?P<backend_variant>\w+))?-(?P<service>(vllm|voxbox|mindie|sglang))(?P<service_version>[\w\\.]+)(?:-(?P<suffix>\w+))?",
+    r"(?:(?P<prefix>[\w\\.\-]+(?:/[\w\\.\-]+)*)/)?runner:(?P<backend>(Host|cann|corex|cuda|dtk|hggc|maca|musa|rocm))(?P<backend_version>[XY\d\\.]+)(?:-(?P<backend_variant>\w+))?-(?P<service>(vllm|voxbox|mindie|sglang))(?P<service_version>[\w\\.]+)(?:-(?P<suffix>\w+))?",
 )
 """
 Regex for Docker image parsing,

gpustack_runner/runner.py.json

@@ -1396,6 +1396,28 @@
     "docker_image": "gpustack/runner:dtk25.04-vllm0.8.5",
     "deprecated": false
   },
+  {
+    "backend": "hggc",
+    "backend_version": "12.3",
+    "original_backend_version": "12.3",
+    "backend_variant": "",
+    "service": "sglang",
+    "service_version": "0.5.5",
+    "platform": "linux/amd64",
+    "docker_image": "gpustack/runner:hggc12.3-sglang0.5.5",
+    "deprecated": false
+  },
+  {
+    "backend": "hggc",
+    "backend_version": "12.3",
+    "original_backend_version": "12.3",
+    "backend_variant": "",
+    "service": "vllm",
+    "service_version": "0.11.1",
+    "platform": "linux/amd64",
+    "docker_image": "gpustack/runner:hggc12.3-vllm0.11.1",
+    "deprecated": false
+  },
   {
     "backend": "maca",
     "backend_version": "3.2",

{gpustack_runner-0.1.23.post5.dist-info → gpustack_runner-0.1.24.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gpustack-runner
-Version: 0.1.23.post5
+Version: 0.1.24
 Summary: GPUStack Runner is library for registering runnable accelerated backends and services in GPUStack.
 Project-URL: Homepage, https://github.com/gpustack/runner
 Project-URL: Bug Tracker, https://github.com/gpustack/gpustack/issues
@@ -101,6 +101,12 @@ The following table lists the supported accelerated backends and their correspon
 |-----------------------------|----------------------------|
 | 25.04                       | `0.11.0`, `0.9.2`, `0.8.5` |
 
+### THead HGGC
+
+| HGGC Version <br/> (Variant) | vLLM     | SGLang  |
+|------------------------------|----------|---------|
+| 12.3                         | `0.11.1` | `0.5.5` |
+
 ### MetaX MACA
 
 | MACA Version <br/> (Variant) | vLLM     |
@@ -251,7 +257,7 @@ To add support for a new accelerated backend:
 
 1. Create a new directory under `pack/` named with the new backend.
 2. Add a `Dockerfile` in the new directory following the [Dockerfile Convention](#dockerfile-convention).
-3. Update [pack.yml](.github/workflows/pack.yml) to include the new backend in the build matrix.
+3. Update [pack.yml](.github/workflows/pack.yml), [discard.yml](.github/workflows/discard.yml) and [prune.yml](.github/workflows/prune.yml) to include the new backend in the build matrix.
 4. Update [matrix.yml](pack/matrix.yaml) to include the new backend and its variants.
 5. Update `_RE_DOCKER_IMAGE` in [runner.py](gpustack_runner/runner.py) to recognize the new backend.
 6. [Optional] Update [tests](tests/gpustack_runner) if necessary.

gpustack_runner-0.1.24.dist-info/RECORD

@@ -0,0 +1,17 @@
+gpustack_runner/__init__.py,sha256=ss8_wsk1oo13qFlP9usrXKX4ypHs1NZb2OVd6uFx5cc,715
+gpustack_runner/__main__.py,sha256=uvpk9GtyJGtHaKM7DyM64N5mwehwpDD3v8ba6Yy8V3A,1364
+gpustack_runner/__utils__.py,sha256=LSo0Iqxd5OjQFncVOYcqC8cncjtywf0qac31UPw7Ou4,4372
+gpustack_runner/_version.py,sha256=PGtcaWdpQHoovDMPesJn_siACNRb_TCcIlFvVB6YEig,777
+gpustack_runner/_version.pyi,sha256=A42NoSgcqEXVy2OeNm4LXC9CbyonbooYrSUBlPm2lGY,156
+gpustack_runner/envs.py,sha256=Wm0GTIiDJIT1zEjLpaPZNLbOs23NNFc2Y6zZuRLlTKQ,3470
+gpustack_runner/runner.py,sha256=WOERxhW2huq_zESGaJ7ntlWFeQJkOs1NWc8XSrlTJTI,26594
+gpustack_runner/runner.py.json,sha256=rQEZrBRAQngUY9z2AntWTnnwjhTzZI_yywMxhjAAcAw,45403
+gpustack_runner/cmds/__init__.py,sha256=zjdv_OC674KAcitjiHrHbXnAwLtw8Ju3psW0IKFqPIg,471
+gpustack_runner/cmds/__types__.py,sha256=7C4kQM0EHPD8WpJpTo6kh9rEdkrYALcLQ-GAzMMsqV8,789
+gpustack_runner/cmds/images.py,sha256=Bd_yoW7MboVNAxtpMlf8JKm9vPGvuIcHcxInA9VCUsI,49223
+gpustack_runner/_version_appendix.py,sha256=ZgtpyK-U9XcDUsfZR8KHFW6SDKmtMp9w4_lXLNiK5YY,23
+gpustack_runner-0.1.24.dist-info/METADATA,sha256=T6nsHWr00ZtYpB8Ri0ADF5aqhTJxc2V54QKzi_B71mw,13559
+gpustack_runner-0.1.24.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+gpustack_runner-0.1.24.dist-info/entry_points.txt,sha256=M1Dxl6cY0kIgf2I4pPsV-_kU6BAtjj93spmsXAdwW3s,66
+gpustack_runner-0.1.24.dist-info/licenses/LICENSE,sha256=OiPibowBvB-NHV3TP_NOj18XNBlXcshXZFMpa3uvKVE,10362
+gpustack_runner-0.1.24.dist-info/RECORD,,

gpustack_runner-0.1.23.post5.dist-info/RECORD

@@ -1,16 +0,0 @@
-gpustack_runner/__init__.py,sha256=0_0jsxo1xjLtHTOIEU0_-A1qFEANzsVw-uXGjcILDwk,530
-gpustack_runner/__main__.py,sha256=wtcp9lwMkaXGbQkuOY08EQhKfIHcTLSjMdnj2W3UGwk,1285
-gpustack_runner/_version.py,sha256=NDbGgX_SVQwK4ytZFVrGe_PzIARK2sZAIaj9J28Xql4,792
-gpustack_runner/_version.pyi,sha256=A42NoSgcqEXVy2OeNm4LXC9CbyonbooYrSUBlPm2lGY,156
-gpustack_runner/envs.py,sha256=EVQvU1bdF5DHSY83X1mHkQWiF4jlLhre1YCArAFe5Wk,2862
-gpustack_runner/runner.py,sha256=PlwYWNj_9kVB-Aoo0dmCHVPiAjKVT3ZoezhAiYtJiJA,26589
-gpustack_runner/runner.py.json,sha256=a6U7utY4wZ2yEGZ2wEGmbDzoVb3GvzbK_1GrIcM9yQA,44801
-gpustack_runner/cmds/__init__.py,sha256=Os8FdvqNjLYiVn_jnDo7rFEtAeVLJJI1odKHEqWF-Fw,417
-gpustack_runner/cmds/__types__.py,sha256=7C4kQM0EHPD8WpJpTo6kh9rEdkrYALcLQ-GAzMMsqV8,789
-gpustack_runner/cmds/images.py,sha256=UM-fO_7lKzfaFep8_kHxy36AkjSw-ZUk3Ty2dCQmvnQ,38909
-gpustack_runner/_version_appendix.py,sha256=YRx5Cq7oDt_x3DaU5ub-D03qpMmWfqMHO-Dr6CBv2fY,23
-gpustack_runner-0.1.23.post5.dist-info/METADATA,sha256=BFlwdr9yVQiF0uYhilCS-GL3EAPhraqf9kf_T5Kcq4g,13295
-gpustack_runner-0.1.23.post5.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-gpustack_runner-0.1.23.post5.dist-info/entry_points.txt,sha256=M1Dxl6cY0kIgf2I4pPsV-_kU6BAtjj93spmsXAdwW3s,66
-gpustack_runner-0.1.23.post5.dist-info/licenses/LICENSE,sha256=OiPibowBvB-NHV3TP_NOj18XNBlXcshXZFMpa3uvKVE,10362
-gpustack_runner-0.1.23.post5.dist-info/RECORD,,