gpustack-runtime 0.2.2.post6__tar.gz → 0.2.2.post8__tar.gz

{gpustack_runtime-0.2.2.post6 → gpustack_runtime-0.2.2.post8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gpustack-runtime
-Version: 0.2.2.post6
+Version: 0.2.2.post8
 Summary: GPUStack Runtime is library for detecting GPU resources and launching GPU workloads.
 Project-URL: Homepage, https://github.com/gpustack/runtime
 Project-URL: Bug Tracker, https://github.com/gpustack/gpustack/issues

{gpustack_runtime-0.2.2.post6 → gpustack_runtime-0.2.2.post8}/deploy/manifests/kubernetes.yaml

@@ -25,6 +25,14 @@ rules:
       - "pods/exec"
     verbs:
       - "*"
+  # Allow resolving the vendor RuntimeClass (e.g. "ascend", "nvidia") for
+  # accelerated workload Pods, see GPUSTACK_RUNTIME_DEPLOY_RESOURCE_KEY_MAP_RUNTIME_CLASS.
+  - apiGroups:
+      - "node.k8s.io"
+    resources:
+      - "runtimeclasses"
+    verbs:
+      - "get"
 ---
 apiVersion: rbac.authorization.k8s.io/v1
 kind: RoleBinding
@@ -76,6 +84,11 @@ spec:
         "app.kubernetes.io/name": "gpustack-runtime"
     spec:
     # Provide GPU resource request for gpustack-runtime if not using default runtime.
+    # The runtimeClassName set here is mirrored to every deployed workload Pod
+    # that does not resolve one itself. Usually this is unnecessary: workload
+    # Pods requesting device plugin resources automatically adopt the mapped
+    # vendor RuntimeClass when it exists in the cluster,
+    # see GPUSTACK_RUNTIME_DEPLOY_RESOURCE_KEY_MAP_RUNTIME_CLASS.
     #
     # runtimeClassName: nvidia
 

{gpustack_runtime-0.2.2.post6 → gpustack_runtime-0.2.2.post8}/gpustack_runtime/_version.py

@@ -27,8 +27,8 @@ version_tuple: VERSION_TUPLE
 __commit_id__: COMMIT_ID
 commit_id: COMMIT_ID
 
-__version__ = version = '0.2.2.post6'
-__version_tuple__ = version_tuple = (0, 2, 2, 'post6')
+__version__ = version = '0.2.2.post8'
+__version_tuple__ = version_tuple = (0, 2, 2, 'post8')
 try:
     from ._version_appendix import git_commit
     __commit_id__ = commit_id = git_commit

gpustack_runtime-0.2.2.post8/gpustack_runtime/_version_appendix.py

@@ -0,0 +1 @@
+git_commit = "cad3f1b"

{gpustack_runtime-0.2.2.post6 → gpustack_runtime-0.2.2.post8}/gpustack_runtime/deployer/kuberentes.py

@@ -325,6 +325,151 @@ def _pin_pod_for_kueue(
     }
 
 
+def _is_device_plugin_resource(resource_key: str) -> bool:
+    """
+    Report whether a resource key belongs to a device plugin resource family,
+    which is either a CDI kind ("nvidia.com/gpu") or one of its suffixed
+    variants ("nvidia.com/gpu.shared", "nvidia.com/gpu.sliced.units",
+    "nvidia.com/gpu.partitioned.mig-1g.20gb").
+    """
+    return any(
+        resource_key == cdi or resource_key.startswith(f"{cdi}.")
+        for cdi in envs.GPUSTACK_RUNTIME_DEPLOY_RESOURCE_KEY_MAP_CDI.values()
+    )
+
+
+def _match_runtime_class(resource_key: str) -> str:
+    """
+    Return the RuntimeClass name mapped to the device plugin resource family
+    of the given resource key, which matches either a mapped base key
+    ("huawei.com/npu") or one of its suffixed variants
+    ("huawei.com/npu.sliced", "huawei.com/npu.sliced.units").
+    Return an empty string if the key belongs to no mapped family.
+    """
+    for base_key, runtime_class_name in (
+        envs.GPUSTACK_RUNTIME_DEPLOY_RESOURCE_KEY_MAP_RUNTIME_CLASS or {}
+    ).items():
+        if resource_key == base_key or resource_key.startswith(f"{base_key}."):
+            return runtime_class_name
+    return ""
+
+
+def _resolve_runtime_class_name(
+    pod: kubernetes.client.V1Pod,
+    client: kubernetes.client.ApiClient,
+):
+    """
+    Resolve the RuntimeClass for the Pod from the device plugin resources
+    requested by its containers, and set `pod.spec.runtime_class_name`
+    when the mapped RuntimeClass object exists in the cluster.
+
+    A Pod that already names a runtime class is left untouched, and the
+    mirrored deployment fill stays the fallback for Pods without any
+    mapped device request, so the precedence is:
+    explicit > discovered > mirrored.
+    """
+    if pod.spec.runtime_class_name:
+        return
+
+    # Find the RuntimeClass mapped to the requested device resources,
+    # keeping the first match on multi-vendor conflicts.
+    runtime_class_name = ""
+    for container in (pod.spec.containers or []) + (pod.spec.init_containers or []):
+        resources = container.resources
+        if not resources or not resources.requests:
+            continue
+        for r_k in resources.requests:
+            matched = _match_runtime_class(r_k)
+            if not matched:
+                continue
+            if runtime_class_name and runtime_class_name != matched:
+                logger.warning(
+                    "Container '%s' requests resource '%s' mapped to RuntimeClass '%s', "
+                    "but keeping the first matched RuntimeClass '%s'",
+                    container.name,
+                    r_k,
+                    matched,
+                    runtime_class_name,
+                )
+                continue
+            runtime_class_name = matched
+    if not runtime_class_name:
+        return
+
+    # Set the RuntimeClass only if the object exists in the cluster,
+    # as naming a missing class makes the kubelet reject the Pod.
+    node_api = kubernetes.client.NodeV1Api(client)
+    try:
+        node_api.read_runtime_class(name=runtime_class_name)
+    except kubernetes.client.exceptions.ApiException as e:
+        if e.status == 403:
+            logger.warning(
+                "Workload requests device resources mapped to RuntimeClass '%s', "
+                "but the deployer has no permission to read RuntimeClasses, "
+                "leaving the Pod runtimeClassName empty",
+                runtime_class_name,
+            )
+            return
+        if e.status == 404:
+            logger.warning(
+                "Workload requests device resources mapped to RuntimeClass '%s', "
+                "but that RuntimeClass is not available in the cluster, "
+                "leaving the Pod runtimeClassName empty",
+                runtime_class_name,
+            )
+            return
+        raise
+
+    logger.info(
+        "Setting Pod runtimeClassName to '%s', "
+        "resolved from the requested device resources",
+        runtime_class_name,
+    )
+    pod.spec.runtime_class_name = runtime_class_name
+
+
+def _resolve_privileged(container: Container) -> bool:
+    """
+    Resolve whether a container runs privileged.
+
+    Privilege is dropped when the container's devices are handed out by a
+    device plugin, which is the case for every device plugin resource family
+    and, under the KDP injection policy, for every mapped device request.
+
+    A privileged container receives all device nodes of the host, so it
+    enumerates -- and can use -- every accelerator on the node, no matter
+    which one the device plugin allocated to it. That silently undoes
+    slicing: a workload holding a single MIG device or a single memory slice
+    still sees the untouched cards next to it, and a soft-slicing limit
+    lands on whichever device comes first instead of the allocated one.
+    """
+    if not container.execution or not container.execution.privileged:
+        return False
+    if not container.resources:
+        return True
+
+    kdp = get_resource_injection_policy() == "kdp"
+    for r_k in container.resources:
+        if r_k in ("cpu", "memory"):
+            continue
+        if _is_device_plugin_resource(r_k) or (
+            kdp
+            and (
+                r_k
+                in envs.GPUSTACK_RUNTIME_DEPLOY_RESOURCE_KEY_MAP_RUNTIME_VISIBLE_DEVICES
+                or r_k == envs.GPUSTACK_RUNTIME_DEPLOY_AUTOMAP_RESOURCE_KEY
+            )
+        ):
+            clogger.info(
+                "Dropping privilege of container '%s', "
+                "as its device request '%s' is allocated by a device plugin",
+                container.name,
+                r_k,
+            )
+            return False
+    return True
+
+
 class KubernetesDeployer(EndoscopicDeployer):
     """
     Deployer implementation for Kubernetes.
@@ -1048,7 +1193,7 @@ class KubernetesDeployer(EndoscopicDeployer):
                     run_as_user=c.execution.run_as_user,
                     run_as_group=c.execution.run_as_group,
                     read_only_root_filesystem=c.execution.readonly_rootfs,
-                    privileged=c.execution.privileged,
+                    privileged=_resolve_privileged(c),
                     capabilities=(
                         kubernetes.client.V1Capabilities(
                             add=c.execution.capabilities.add,
@@ -1242,6 +1387,7 @@ class KubernetesDeployer(EndoscopicDeployer):
             _apply_instance_type_admission(pod, workload.instance_type)
             _pin_pod_for_kueue(pod, self._node_name)
 
+            _resolve_runtime_class_name(pod, self._client)
             pod = self._mutate_create_pod(pod)
             if envs.GPUSTACK_RUNTIME_DEPLOY_PRINT_CONVERSION:
                 clogger.info(

{gpustack_runtime-0.2.2.post6 → gpustack_runtime-0.2.2.post8}/gpustack_runtime/envs.py

@@ -185,6 +185,17 @@ if TYPE_CHECKING:
     e.g., `{"nvidia.com/devices": ["CUDA_VISIBLE_DEVICES"], "amd.com/devices": ["ROCR_VISIBLE_DEVICES"]}`.
     The key is the resource key, and the value is a list of environment variable names.
     """
+    GPUSTACK_RUNTIME_DEPLOY_RESOURCE_KEY_MAP_RUNTIME_CLASS: dict[str, str] | None = None
+    """
+    Manual mapping of Kubernetes RuntimeClass names,
+    which is used to tell the Kubernetes Deployer which RuntimeClass to run the workload Pod with,
+    e.g., `{"nvidia.com/gpu": "nvidia", "huawei.com/npu": "ascend"}`.
+    The key is the device plugin base resource key, and the value is the RuntimeClass name.
+    During deployment, if any container requests a resource of a mapped family
+    (the base key or one of its suffixed variants, e.g., "huawei.com/npu.sliced"),
+    and a RuntimeClass object with the mapped name exists in the cluster,
+    the workload Pod carries that RuntimeClass name.
+    """
     GPUSTACK_RUNTIME_DEPLOY_RUNTIME_VISIBLE_DEVICES_VALUE_UUID: set[str] | None = None
     """
     Apply UUIDs for the given runtime visible devices environment variables.
@@ -538,6 +549,17 @@ variables: dict[str, Callable[[], Any]] = {
             "alibabacloud.com/devices=alibabacloud.com/ppu;",
         ),
     ),
+    "GPUSTACK_RUNTIME_DEPLOY_RESOURCE_KEY_MAP_RUNTIME_CLASS": lambda: to_dict(
+        getenv(
+            "GPUSTACK_RUNTIME_DEPLOY_RESOURCE_KEY_MAP_RUNTIME_CLASS",
+            "amd.com/gpu=amd;"
+            "huawei.com/npu=ascend;"
+            "cambricon.com/mlu=cambricon;"
+            "iluvatar.com/gpu=iluvatar;"
+            "mthreads.com/gpu=mthreads;"
+            "nvidia.com/gpu=nvidia;",
+        ),
+    ),
     "GPUSTACK_RUNTIME_DEPLOY_RESOURCE_KEY_MAP_RUNTIME_VISIBLE_DEVICES": lambda: to_dict(
         getenv(
             "GPUSTACK_RUNTIME_DEPLOY_RESOURCE_KEY_MAP_RUNTIME_VISIBLE_DEVICES",

gpustack_runtime-0.2.2.post8/tests/gpustack_runtime/deployer/test_privileged.py

@@ -0,0 +1,137 @@
+import pytest
+
+from gpustack_runtime.deployer.__types__ import (
+    Container,
+    ContainerExecution,
+    ContainerResources,
+)
+from gpustack_runtime.deployer.kuberentes import _resolve_privileged
+
+
+def _container(privileged: bool | None, resources: dict | None = None) -> Container:
+    container_resources = None
+    if resources is not None:
+        container_resources = ContainerResources()
+        container_resources.update(resources)
+    return Container(
+        name="default",
+        image="gpustack/runner:latest",
+        execution=(
+            ContainerExecution(privileged=privileged)
+            if privileged is not None
+            else None
+        ),
+        resources=container_resources,
+    )
+
+
+@pytest.mark.parametrize(
+    "name, privileged, resources, policy, expected",
+    [
+        (
+            "no execution",
+            None,
+            None,
+            "env",
+            False,
+        ),
+        (
+            "not requested",
+            False,
+            {"nvidia.com/devices": "0"},
+            "env",
+            False,
+        ),
+        (
+            "no resources",
+            True,
+            None,
+            "env",
+            True,
+        ),
+        (
+            "non-device resources only",
+            True,
+            {"cpu": "2", "memory": "4Gi"},
+            "env",
+            True,
+        ),
+        (
+            "specific whole cards, env injection",
+            True,
+            {"cpu": "2", "nvidia.com/devices": "0,1"},
+            "env",
+            True,
+        ),
+        (
+            "all devices, env injection",
+            True,
+            {"nvidia.com/devices": "all"},
+            "env",
+            True,
+        ),
+        (
+            "specific whole cards, kdp injection",
+            True,
+            {"nvidia.com/devices": "0,1"},
+            "kdp",
+            False,
+        ),
+        (
+            "auto-mapped devices, kdp injection",
+            True,
+            {"gpustack.ai/devices": "0"},
+            "kdp",
+            False,
+        ),
+        (
+            "exclusive whole card",
+            True,
+            {"nvidia.com/gpu": "1"},
+            "env",
+            False,
+        ),
+        (
+            "soft slice",
+            True,
+            {
+                "nvidia.com/gpu.sliced": "1",
+                "nvidia.com/gpu.sliced.memory-percentage": "50",
+                "nvidia.com/gpu.sliced.cores-percentage": "50",
+            },
+            "env",
+            False,
+        ),
+        (
+            "hard partition",
+            True,
+            {
+                "nvidia.com/gpu.partitioned": "1",
+                "nvidia.com/gpu.partitioned.mig-1g.20gb": "1",
+            },
+            "env",
+            False,
+        ),
+        (
+            "non-NVIDIA soft slice",
+            True,
+            {"amd.com/gpu.sliced": "1"},
+            "env",
+            False,
+        ),
+        (
+            "resource key merely prefixed by a CDI kind",
+            True,
+            {"nvidia.com/gpu-alike": "1"},
+            "env",
+            True,
+        ),
+    ],
+)
+def test_resolve_privileged(name, privileged, resources, policy, expected, monkeypatch):
+    monkeypatch.setattr(
+        "gpustack_runtime.deployer.kuberentes.get_resource_injection_policy",
+        lambda: policy,
+    )
+    actual = _resolve_privileged(_container(privileged, resources))
+    assert actual == expected, f"case {name} expected {expected}, but got {actual}"

gpustack_runtime-0.2.2.post8/tests/gpustack_runtime/deployer/test_runtime_class.py

@@ -0,0 +1,183 @@
+import logging
+
+import kubernetes
+import pytest
+
+from gpustack_runtime import envs
+from gpustack_runtime.deployer.kuberentes import (
+    _match_runtime_class,
+    _resolve_runtime_class_name,
+)
+
+
+@pytest.mark.parametrize(
+    "name, resource_key, expected",
+    [
+        ("base key", "huawei.com/npu", "ascend"),
+        ("sliced variant", "huawei.com/npu.sliced", "ascend"),
+        ("sliced units variant", "huawei.com/npu.sliced.units", "ascend"),
+        ("shared variant", "nvidia.com/gpu.shared", "nvidia"),
+        (
+            "partitioned variant",
+            "nvidia.com/gpu.partitioned.mig-1g.20gb",
+            "nvidia",
+        ),
+        ("unmapped base key", "hygon.com/dcu", ""),
+        ("unrelated resource", "cpu", ""),
+        ("gpustack automap key", "gpustack.ai/devices", ""),
+        ("key merely prefixed by a base key", "nvidia.com/gpu-alike", ""),
+    ],
+)
+def test_match_runtime_class(name, resource_key, expected):
+    actual = _match_runtime_class(resource_key)
+    assert actual == expected, f"case {name} expected {expected}, but got {actual}"
+
+
+def _pod(
+    containers_requests: list[dict | None],
+    runtime_class_name: str | None = None,
+) -> kubernetes.client.V1Pod:
+    containers = []
+    for i, requests in enumerate(containers_requests):
+        container = kubernetes.client.V1Container(name=f"container-{i}")
+        if requests is not None:
+            container.resources = kubernetes.client.V1ResourceRequirements(
+                requests=requests,
+                limits=requests,
+            )
+        containers.append(container)
+    return kubernetes.client.V1Pod(
+        spec=kubernetes.client.V1PodSpec(
+            containers=containers,
+            runtime_class_name=runtime_class_name,
+        ),
+    )
+
+
+def _fake_node_api(monkeypatch, existing: set[str], forbidden: bool = False):
+    """
+    Patch NodeV1Api so that reading a RuntimeClass succeeds for names in
+    `existing`, raises 403 when `forbidden`, and 404 otherwise.
+    """
+    calls = []
+
+    class FakeNodeV1Api:
+        def __init__(self, client):
+            pass
+
+        def read_runtime_class(self, name):
+            calls.append(name)
+            if forbidden:
+                raise kubernetes.client.exceptions.ApiException(
+                    status=403,
+                    reason="Forbidden",
+                )
+            if name not in existing:
+                raise kubernetes.client.exceptions.ApiException(
+                    status=404,
+                    reason="Not Found",
+                )
+            return kubernetes.client.V1RuntimeClass(
+                metadata=kubernetes.client.V1ObjectMeta(name=name),
+                handler=name,
+            )
+
+    monkeypatch.setattr(kubernetes.client, "NodeV1Api", FakeNodeV1Api)
+    return calls
+
+
+def test_resolve_runtime_class_name_base_key(monkeypatch):
+    _fake_node_api(monkeypatch, existing={"nvidia"})
+    pod = _pod([{"nvidia.com/gpu": "1"}])
+
+    _resolve_runtime_class_name(pod, None)
+
+    assert pod.spec.runtime_class_name == "nvidia"
+
+
+def test_resolve_runtime_class_name_suffixed_family(monkeypatch):
+    _fake_node_api(monkeypatch, existing={"ascend"})
+    pod = _pod(
+        [
+            {
+                "huawei.com/npu.sliced": "1",
+                "huawei.com/npu.sliced.cores-percentage": "30",
+                "huawei.com/npu.sliced.memory-percentage": "20",
+            },
+        ],
+    )
+
+    _resolve_runtime_class_name(pod, None)
+
+    assert pod.spec.runtime_class_name == "ascend"
+
+
+def test_resolve_runtime_class_name_missing_class(monkeypatch, caplog):
+    _fake_node_api(monkeypatch, existing=set())
+    pod = _pod([{"huawei.com/npu.sliced": "1"}])
+
+    with caplog.at_level(logging.WARNING):
+        _resolve_runtime_class_name(pod, None)
+
+    assert pod.spec.runtime_class_name is None
+    assert "ascend" in caplog.text
+
+
+def test_resolve_runtime_class_name_forbidden(monkeypatch, caplog):
+    _fake_node_api(monkeypatch, existing={"ascend"}, forbidden=True)
+    pod = _pod([{"huawei.com/npu.sliced": "1"}])
+
+    with caplog.at_level(logging.WARNING):
+        _resolve_runtime_class_name(pod, None)
+
+    assert pod.spec.runtime_class_name is None
+    assert "ascend" in caplog.text
+    assert "permission" in caplog.text
+
+
+def test_resolve_runtime_class_name_never_overwritten(monkeypatch):
+    calls = _fake_node_api(monkeypatch, existing={"ascend"})
+    pod = _pod([{"huawei.com/npu.sliced": "1"}], runtime_class_name="custom")
+
+    _resolve_runtime_class_name(pod, None)
+
+    assert pod.spec.runtime_class_name == "custom"
+    assert not calls
+
+
+def test_resolve_runtime_class_name_conflict_keeps_first(monkeypatch, caplog):
+    _fake_node_api(monkeypatch, existing={"nvidia", "ascend"})
+    pod = _pod(
+        [
+            {"nvidia.com/gpu": "1"},
+            {"huawei.com/npu.sliced": "1"},
+        ],
+    )
+
+    with caplog.at_level(logging.WARNING):
+        _resolve_runtime_class_name(pod, None)
+
+    assert pod.spec.runtime_class_name == "nvidia"
+    assert "ascend" in caplog.text
+
+
+def test_resolve_runtime_class_name_no_mapped_resources(monkeypatch):
+    calls = _fake_node_api(monkeypatch, existing={"nvidia"})
+    pod = _pod([{"cpu": "2", "memory": "4Gi"}, None])
+
+    _resolve_runtime_class_name(pod, None)
+
+    assert pod.spec.runtime_class_name is None
+    assert not calls
+
+
+def test_default_runtime_class_map():
+    mapping = envs.GPUSTACK_RUNTIME_DEPLOY_RESOURCE_KEY_MAP_RUNTIME_CLASS
+    assert mapping == {
+        "amd.com/gpu": "amd",
+        "huawei.com/npu": "ascend",
+        "cambricon.com/mlu": "cambricon",
+        "iluvatar.com/gpu": "iluvatar",
+        "mthreads.com/gpu": "mthreads",
+        "nvidia.com/gpu": "nvidia",
+    }

gpustack_runtime-0.2.2.post6/gpustack_runtime/_version_appendix.py

@@ -1 +0,0 @@
-git_commit = "79ee112"