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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gpustack-runtime
-Version: 0.2.2.post7
+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.post7 → 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.post7 → 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.post7'
-__version_tuple__ = version_tuple = (0, 2, 2, 'post7')
+__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.post7 → gpustack_runtime-0.2.2.post8}/gpustack_runtime/deployer/kuberentes.py

@@ -338,6 +338,96 @@ def _is_device_plugin_resource(resource_key: str) -> bool:
     )
 
 
+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.
@@ -1297,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.post7 → 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_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.post7/gpustack_runtime/_version_appendix.py

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