gpustack-runtime 0.2.5.post3__tar.gz → 0.2.5.post4__tar.gz

gpustack_runtime-0.2.5.post4/ADOPTERS.md

@@ -0,0 +1,12 @@
+# Who's using GPUStack Runtime
+
+GPUStack Runtime is used by a growing range of companies and projects to detect accelerator (GPU/NPU) resources and run accelerator workloads on Docker, Kubernetes and Podman.
+
+If you are using GPUStack Runtime and your name is not on this list, please send us a PR!
+
+## Companies/Projects using GPUStack Runtime in production
+
+These companies and projects are using GPUStack Runtime in production. If your company is using GPUStack Runtime, open a PR to add your company or project name and a description of how you are using GPUStack Runtime.
+
+| Company / Project | Use Case |
+| --- | --- |

gpustack_runtime-0.2.5.post4/AGENTS.md

@@ -0,0 +1,85 @@
+# GPUStack Runtime
+
+A Python library with a unified interface for detecting accelerator (GPU/NPU) resources and
+launching and managing GPU workloads on Docker, Kubernetes and Podman.
+
+## Project Structure
+
+- `gpustack_runtime/` — the library.
+  - `detector/` — one detector per vendor (`nvidia.py`, `amd.py`, `ascend.py`, `cambricon.py`,
+    `hygon.py`, `iluvatar.py`, `metax.py`, `mthreads.py`, `thead.py`), plus the `py*` packages,
+    ctypes bindings to vendor management libraries (`pynvml`, `pydcmi`, `pycndev`, ...).
+  - `deployer/` — one deployer per container runtime (`docker.py`, `kubernetes.py`, `podman.py`),
+    `cdi/` for vendor CDI spec handling, `k8s/` for Kubernetes helpers, and `__patches__.py` for
+    the vendored Podman client patch.
+  - `cmds/` — CLI subcommands behind the `gpustack-runtime` entrypoint (`__main__.py`).
+  - `envs.py` — environment variables; `logging.py` — logging helpers.
+- `tests/gpustack_runtime/` — pytest suite mirroring the package; `detector/samples/` holds
+  captured vendor-tool outputs used as fixtures.
+- `docs/` — MkDocs site; `docs/modules/` is API reference rendered from docstrings by
+  mkdocstrings.
+- `specs/` — design records.
+- `pack/` / `deploy/` — container image build and deployment manifests.
+
+## Architecture
+
+Detection: each vendor detector in `gpustack_runtime/detector/` probes its vendor library through
+the matching `py*` binding and reports `Device`s with topology. `detector/__init__.py` owns the
+registry (`_DETECTORS`) and the aggregate entry points (`supported_list()`, `detect_devices()`).
+
+Deployment: `deployer/__init__.py` owns the registry (`_DEPLOYERS`) and picks the first available
+runtime (Docker, Kubernetes, Podman). A `WorkloadPlan` describes the desired containers; the
+deployer injects vendor resources (CDI devices, environment variables, mounts) and returns a
+workload handle for inspect/logs/exec/delete. Shared types live in `deployer/__types__.py`,
+including the `OperationError` / `UnsupportedError` error contract.
+
+## Finding sources
+
+- Confirm the checkout, branch and uncommitted changes before reasoning about behavior. The
+  published wheel or a merged PR may describe a different revision.
+- Docstrings are the usage contract: `make docs` renders them into `site/`. Specs under
+  `specs/` own design rationale; current code establishes what this checkout implements. Report
+  disagreement rather than silently choosing one.
+- For a vendor behavior claim, read the matching `py*` binding and the detector tests under
+  `tests/gpustack_runtime/detector/`; captured outputs live in `detector/samples/`.
+- For a concrete error, search its stable text locally first. When it concerns an upstream
+  dependency (docker, kubernetes, podman clients), check that project's issues and pinned version
+  in `pyproject.toml` / `uv.lock`.
+
+## Development
+
+Setup is `make install` (uv sync plus pre-commit hooks). Day-to-day targets:
+
+- `make lint` — pre-commit on all files: ruff check/format, codespell, commitizen.
+- `make test` — pytest.
+- `make docs` — build the MkDocs site into `site/` (git-ignored).
+- `make build` — build wheel and sdist into `dist/` (git-ignored).
+- `make package` — build the container image with docker buildx; `PACKAGE_PUSH=true` pushes.
+
+`gpustack_runtime/_version.py` is generated by hatch-vcs and `_version_appendix.py` by
+`make prepare`; never hand-edit either.
+
+### Python conventions
+
+- Prefer clarity over cleverness to simplify long-term maintenance.
+- Start every package module with `from __future__ import annotations as __future_annotations__`.
+- Follow the ruff configuration in `ruff.toml`; run `make lint` whenever modifying Python source.
+- Type-annotate public APIs and re-export them from the package `__init__.py` (`__all__`).
+- Write Google-style docstrings; they render into the published API reference.
+- Handle errors explicitly. Deployers raise `OperationError` or `UnsupportedError` from
+  `deployer.__types__` instead of leaking runtime-client exceptions. Detectors degrade to an
+  empty result and log at debug level rather than failing on a host without that vendor.
+- Keep private helpers in double-underscore modules (`__types__.py`, `__utils__.py`); import them
+  through the package, not across subpackages.
+- Keep concurrency simple, safe and justified; minimize mutable shared state.
+- Keep comments plain and short: no emoji, no decorative symbols. State the point in words.
+
+### Testing conventions
+
+- pytest; tests mirror the package layout under `tests/gpustack_runtime/`.
+- Never require real hardware or a real container runtime. Detector tests fake the `py*` vendor
+  binding in the test module; deployer tests fake the runtime client.
+- Reuse captured vendor outputs from `tests/gpustack_runtime/detector/samples/` and shared
+  fixtures from `fixtures/` instead of inventing new sample data.
+- Verify one behavior or contract per test; assert observable state, not implementation details.
+- Keep tests deterministic and repeatable: no wall-clock, ordering or randomness dependence.

gpustack_runtime-0.2.5.post4/DCO

@@ -0,0 +1,34 @@
+Developer Certificate of Origin
+Version 1.1
+
+Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
+
+Everyone is permitted to copy and distribute verbatim copies of this
+license document, but changing it is not allowed.
+
+
+Developer's Certificate of Origin 1.1
+
+By making a contribution to this project, I certify that:
+
+(a) The contribution was created in whole or in part by me and I
+    have the right to submit it under the open source license
+    indicated in the file; or
+
+(b) The contribution is based upon previous work that, to the best
+    of my knowledge, is covered under an appropriate open source
+    license and I have the right under that license to submit that
+    work with modifications, whether created in whole or in part
+    by me, under the same open source license (unless I am
+    permitted to submit under a different license), as indicated
+    in the file; or
+
+(c) The contribution was provided directly to me by some other
+    person who certified (a), (b) or (c) and I have not modified
+    it.
+
+(d) I understand and agree that this project and the contribution
+    are public and that a record of the contribution (including all
+    personal information I submit with it, including my sign-off) is
+    maintained indefinitely and may be redistributed consistent with
+    this project or the open source license(s) involved.

{gpustack_runtime-0.2.5.post3 → gpustack_runtime-0.2.5.post4}/LICENSE

@@ -175,7 +175,7 @@ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
 
 END OF TERMS AND CONDITIONS
 
-Copyright (c) 2025 The GPUStack Authors
+Copyright (c) 2026 The GPUStack Authors
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

gpustack_runtime-0.2.5.post4/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.5
+Name: gpustack-runtime
+Version: 0.2.5.post4
+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
+Author-email: GPUStack Authors <contact@gpustack.ai>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: argcomplete>=3.6.3
+Requires-Dist: cachetools>=5.5.2
+Requires-Dist: docker>=7.1.0
+Requires-Dist: gpustack-runner>=0.1.29
+Requires-Dist: kubernetes>=33.1.0
+Requires-Dist: mthreads-ml-py>=2.2.10
+Requires-Dist: nvidia-ml-py>=13.580.65
+Requires-Dist: podman==5.6.0
+Requires-Dist: pyyaml
+Requires-Dist: tqdm
+Description-Content-Type: text/markdown
+
+# GPUStack Runtime
+
+[![License](https://img.shields.io/github/license/gpustack/runtime?logo=apache&label=License)](./LICENSE)
+[![PyPI](https://img.shields.io/pypi/v/gpustack-runtime?logo=pypi&label=PyPI)](https://pypi.org/project/gpustack-runtime/)
+[![Latest Release](https://img.shields.io/github/v/release/gpustack/runtime?logo=semanticrelease&label=Release&include_prereleases)](https://github.com/gpustack/runtime/releases/latest)
+[![Docker Pulls](https://img.shields.io/docker/pulls/gpustack/runtime?logo=docker&logoColor=fff&label=Docker%20Pulls)](https://hub.docker.com/r/gpustack/runtime)
+[![Ask DeepWiki](https://img.shields.io/badge/Ask_DeepWiki-purple?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAACXBIWXMAAAPoAAAD6AG1e1JrAAACIUlEQVRYw+2XP2gUQRTGv7d3JhYWQawkIBaCVWzETos0gmAnVoKNTSoLK0E7EQQrC20sBVFBtLPQRgTBtBaKjYgIQUSxiJq7fT+LvCGPJZdNLt4dQj5Y3u7sznzfzLw/s9IO/icANiniCujEfWdsQgBLxAbsbraPZcmBfcAt4DNwKQsZNfEUsAB8YRV12LfA6ZHuedg7AO7ed/c+UBcbQhbiu+6wXIM6EnZWkszMJe2Ke0n6I2la0v51hFeSMLN6OwIK6jJwEBdUYb2MAxRSz6sY4geiahFgLe1Hwq6YWe3us8AN4FQQU4QM64SPY69Xyr43fADgNjAPXHb3peSsD4FDQ0VLEjAHvIhBPS6AHvA1bBO9JPAXcHFbIRtJ5yzwIQZ9CZwAusDJENIkLqsG8DpNyIZJwSUk9wLHgakcesC1JCCjiHm1kYDNOEjptCxpSVK/8f73OFLxPLAYM3oCzEX7MXf/lJbc/8kWpA4HgQdpYI9IWAbeh83whi84cHXL+58EPBoQhnmm94EzwE3gZ2p/Dhzdbhg+TaRr01x7ftb4/jBwFzjXrCvDpmLW9crVLNeR9CaapoGemb2TdCERW1tNaBNQ8jktwmozqwtpqRNtdWAjARYk39IS12ZWRX7vmJmA71nQZgi36gN7gCvAj5xc3P0jcH7kx7Ik5IC73wsh14GZsZySow5002l4Jr0b6+m4eSyvpAn8lEzsx2QHo8RfUrlN+uPq4ksAAAAASUVORK5CYII=)](https://deepwiki.com/gpustack/runtime)
+
+GPUStack Runtime offers a unified interface for detecting GPU resources and managing GPU workloads.
+
+## Features
+
+- Detect a wide range of GPU and accelerator resources:
+
+  - AMD GPU
+  - Ascend NPU
+  - Cambricon MLU
+  - Hygon DCU
+  - Iluvatar GPU
+  - MetaX GPU
+  - Moore Threads GPU
+  - NVIDIA GPU
+  - T-Head PPU
+
+- Manage GPU workloads on the following platforms:
+
+  - Docker
+  - Kubernetes
+  - Podman (>=4.9, experimental support via the `CONTAINER_HOST=http+unix:///path/to/podman/socket` environment variable)
+
+Contributions to support additional GPU resources are welcome!
+
+## Installation
+
+```bash
+pip install gpustack-runtime
+```
+
+## Documentation
+
+The API reference renders from docstrings. Build the site locally with `make docs` and open
+`site/index.html`.
+
+## Contributing
+
+Contributions are welcome. Commits must carry a `Signed-off-by` line certifying the
+[Developer Certificate of Origin](./DCO).
+
+Using GPUStack Runtime in production? Add your company or project to [ADOPTERS.md](./ADOPTERS.md)
+via pull request.
+
+## License
+
+Copyright (c) 2026 The GPUStack Authors. Licensed under the
+[Apache License 2.0](./LICENSE).

gpustack_runtime-0.2.5.post4/README.md

@@ -0,0 +1,55 @@
+# GPUStack Runtime
+
+[![License](https://img.shields.io/github/license/gpustack/runtime?logo=apache&label=License)](./LICENSE)
+[![PyPI](https://img.shields.io/pypi/v/gpustack-runtime?logo=pypi&label=PyPI)](https://pypi.org/project/gpustack-runtime/)
+[![Latest Release](https://img.shields.io/github/v/release/gpustack/runtime?logo=semanticrelease&label=Release&include_prereleases)](https://github.com/gpustack/runtime/releases/latest)
+[![Docker Pulls](https://img.shields.io/docker/pulls/gpustack/runtime?logo=docker&logoColor=fff&label=Docker%20Pulls)](https://hub.docker.com/r/gpustack/runtime)
+[![Ask DeepWiki](https://img.shields.io/badge/Ask_DeepWiki-purple?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAACXBIWXMAAAPoAAAD6AG1e1JrAAACIUlEQVRYw+2XP2gUQRTGv7d3JhYWQawkIBaCVWzETos0gmAnVoKNTSoLK0E7EQQrC20sBVFBtLPQRgTBtBaKjYgIQUSxiJq7fT+LvCGPJZdNLt4dQj5Y3u7sznzfzLw/s9IO/icANiniCujEfWdsQgBLxAbsbraPZcmBfcAt4DNwKQsZNfEUsAB8YRV12LfA6ZHuedg7AO7ed/c+UBcbQhbiu+6wXIM6EnZWkszMJe2Ke0n6I2la0v51hFeSMLN6OwIK6jJwEBdUYb2MAxRSz6sY4geiahFgLe1Hwq6YWe3us8AN4FQQU4QM64SPY69Xyr43fADgNjAPXHb3peSsD4FDQ0VLEjAHvIhBPS6AHvA1bBO9JPAXcHFbIRtJ5yzwIQZ9CZwAusDJENIkLqsG8DpNyIZJwSUk9wLHgakcesC1JCCjiHm1kYDNOEjptCxpSVK/8f73OFLxPLAYM3oCzEX7MXf/lJbc/8kWpA4HgQdpYI9IWAbeh83whi84cHXL+58EPBoQhnmm94EzwE3gZ2p/Dhzdbhg+TaRr01x7ftb4/jBwFzjXrCvDpmLW9crVLNeR9CaapoGemb2TdCERW1tNaBNQ8jktwmozqwtpqRNtdWAjARYk39IS12ZWRX7vmJmA71nQZgi36gN7gCvAj5xc3P0jcH7kx7Ik5IC73wsh14GZsZySow5002l4Jr0b6+m4eSyvpAn8lEzsx2QHo8RfUrlN+uPq4ksAAAAASUVORK5CYII=)](https://deepwiki.com/gpustack/runtime)
+
+GPUStack Runtime offers a unified interface for detecting GPU resources and managing GPU workloads.
+
+## Features
+
+- Detect a wide range of GPU and accelerator resources:
+
+  - AMD GPU
+  - Ascend NPU
+  - Cambricon MLU
+  - Hygon DCU
+  - Iluvatar GPU
+  - MetaX GPU
+  - Moore Threads GPU
+  - NVIDIA GPU
+  - T-Head PPU
+
+- Manage GPU workloads on the following platforms:
+
+  - Docker
+  - Kubernetes
+  - Podman (>=4.9, experimental support via the `CONTAINER_HOST=http+unix:///path/to/podman/socket` environment variable)
+
+Contributions to support additional GPU resources are welcome!
+
+## Installation
+
+```bash
+pip install gpustack-runtime
+```
+
+## Documentation
+
+The API reference renders from docstrings. Build the site locally with `make docs` and open
+`site/index.html`.
+
+## Contributing
+
+Contributions are welcome. Commits must carry a `Signed-off-by` line certifying the
+[Developer Certificate of Origin](./DCO).
+
+Using GPUStack Runtime in production? Add your company or project to [ADOPTERS.md](./ADOPTERS.md)
+via pull request.
+
+## License
+
+Copyright (c) 2026 The GPUStack Authors. Licensed under the
+[Apache License 2.0](./LICENSE).

{gpustack_runtime-0.2.5.post3 → gpustack_runtime-0.2.5.post4}/gpustack_runtime/_version.py

@@ -27,8 +27,8 @@ version_tuple: VERSION_TUPLE
 __commit_id__: COMMIT_ID
 commit_id: COMMIT_ID
 
-__version__ = version = '0.2.5.post3'
-__version_tuple__ = version_tuple = (0, 2, 5, 'post3')
+__version__ = version = '0.2.5.post4'
+__version_tuple__ = version_tuple = (0, 2, 5, 'post4')
 try:
     from ._version_appendix import git_commit
     __commit_id__ = commit_id = git_commit

gpustack_runtime-0.2.5.post4/gpustack_runtime/_version_appendix.py

@@ -0,0 +1 @@
+git_commit = "089358e"

{gpustack_runtime-0.2.5.post3 → gpustack_runtime-0.2.5.post4}/gpustack_runtime/deployer/__init__.py

@@ -36,7 +36,8 @@ from .docker import (
     DockerWorkloadPlan,
     DockerWorkloadStatus,
 )
-from .kuberentes import (
+from .k8s.devicemanager import KubernetesResourceInjectionPolicyEnum
+from .kubernetes import (
     KubernetesDeployer,
     KubernetesWorkloadPlan,
     KubernetesWorkloadStatus,
@@ -595,6 +596,7 @@ __all__ = [
     "ContainerSecurity",
     "DockerWorkloadPlan",
     "DockerWorkloadStatus",
+    "KubernetesResourceInjectionPolicyEnum",
     "KubernetesWorkloadPlan",
     "KubernetesWorkloadStatus",
     "OperationError",

{gpustack_runtime-0.2.5.post3 → gpustack_runtime-0.2.5.post4}/gpustack_runtime/deployer/k8s/devicemanager/__init__.py

@@ -1,6 +1,7 @@
 from __future__ import annotations as __future_annotations__
 
 import stat
+from enum import Enum
 from functools import lru_cache
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, Literal
@@ -11,6 +12,36 @@ if TYPE_CHECKING:
     from collections.abc import Callable, Mapping
 
 
+class KubernetesResourceInjectionPolicyEnum(str, Enum):
+    """
+    Device injection policies for Kubernetes workloads.
+    """
+
+    AUTO = "Auto"
+    """
+    Detect the policy from the target node's allocatable resources.
+    """
+    ENV = "Env"
+    """
+    Inject runtime-visible device environment variables without device-plugin requests.
+    """
+    KDP = "KDP"
+    """
+    Request device-plugin resources.
+    """
+
+    @classmethod
+    def _missing_(cls, value: object) -> KubernetesResourceInjectionPolicyEnum | None:
+        if isinstance(value, str):
+            for member in cls:
+                if member.value.lower() == value.lower():
+                    return member
+        return None
+
+    def __str__(self) -> str:
+        return self.value
+
+
 def is_kubelet_socket_accessible(
     kubelet_endpoint: Path | None = None,
 ) -> bool:
@@ -79,13 +110,16 @@ def node_has_device_plugin_resources(
 
 def get_resource_injection_policy(
     probe_node_allocatable: Callable[[], Mapping[str, Any] | None] | None = None,
+    *,
+    policy: KubernetesResourceInjectionPolicyEnum | None = None,
 ) -> Literal["env", "kdp"]:
     """
     Get the resource injection policy (in lowercase) for the deployer.
 
-    An explicit policy always wins. Under "auto" the decision belongs to the
-    cluster, not to the process doing the deploying: the Kubernetes deployer
-    orchestrates remotely, so whether *it* can reach a kubelet socket says
+    A workload policy overrides the environment setting. Under "auto" the
+    decision belongs to the cluster, not to the process doing the deploying:
+    the Kubernetes deployer orchestrates remotely, so whether *it* can reach
+    a kubelet socket says
     nothing about whether the *target* node runs a device plugin. So the probe
     reads that node's allocatable resources and looks for a device-plugin
     resource family there.
@@ -99,14 +133,29 @@ def get_resource_injection_policy(
         probe_node_allocatable:
             Called only under the "auto" policy, to read the target node's
             allocatable resources. Returns None when the node cannot be read.
+        policy:
+            Workload policy override. None inherits the environment setting;
+            Auto probes the node even if the environment selects Env or KDP.
+
+    Raises:
+        ValueError:
+            If the policy is not Auto, Env or KDP.
 
     Returns:
         The resource injection policy.
 
     """
-    policy = envs.GPUSTACK_RUNTIME_KUBERNETES_RESOURCE_INJECTION_POLICY.lower()
-    if policy != "auto":
-        return policy
+    if policy is None:
+        policy = envs.GPUSTACK_RUNTIME_KUBERNETES_RESOURCE_INJECTION_POLICY
+    try:
+        policy = KubernetesResourceInjectionPolicyEnum(policy)
+    except ValueError as e:
+        msg = f"Invalid resource injection policy '{policy}'"
+        raise ValueError(msg) from e
+    if policy == KubernetesResourceInjectionPolicyEnum.ENV:
+        return "env"
+    if policy == KubernetesResourceInjectionPolicyEnum.KDP:
+        return "kdp"
 
     if probe_node_allocatable is None:
         return "kdp"
@@ -142,6 +191,7 @@ def cdi_kind_to_kdp_resource(
 
 
 __all__ = [
+    "KubernetesResourceInjectionPolicyEnum",
     "cdi_kind_to_kdp_resource",
     "get_resource_injection_policy",
     "is_kubelet_socket_accessible",

gpustack_runtime-0.2.5.post3/gpustack_runtime/deployer/kuberentes.py → gpustack_runtime-0.2.5.post4/gpustack_runtime/deployer/kubernetes.py

@@ -7,12 +7,14 @@ import math
 import os
 import re
 import time
+from copy import copy
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
 from decimal import Decimal
 from enum import Enum
 from pathlib import Path
-from typing import TYPE_CHECKING
+from threading import Lock
+from typing import TYPE_CHECKING, Literal
 
 import kubernetes
 import kubernetes.stream.ws_client
@@ -49,11 +51,16 @@ from .__utils__ import (
     sensitive_env_var,
     validate_rfc1123_domain_name,
 )
-from .k8s.devicemanager import get_resource_injection_policy
+from .k8s.devicemanager import (
+    KubernetesResourceInjectionPolicyEnum,
+    get_resource_injection_policy,
+)
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Generator
 
+    from .__types__ import DevicesMaterial
+
 logger = logging.getLogger(__name__)
 clogger = logger.getChild("conversion")
 
@@ -117,6 +124,9 @@ class KubernetesWorkloadPlan(WorkloadPlan):
             Domain suffix for the cluster. Default is "cluster.local".
         service_type (KubernetesWorkloadServiceTypeEnum):
             Service type for the workload. Default is CLUSTER_IP.
+        resource_injection_policy (KubernetesResourceInjectionPolicyEnum | None):
+            Workload override for GPUSTACK_RUNTIME_KUBERNETES_RESOURCE_INJECTION_POLICY.
+            None inherits the environment setting. Auto probes the target node.
         namespace (str | None):
             Namespace of the workload.
         name (str):
@@ -159,6 +169,16 @@ class KubernetesWorkloadPlan(WorkloadPlan):
     Service type for the workload.
     """
 
+    resource_injection_policy: KubernetesResourceInjectionPolicyEnum | None = None
+    """
+    Device injection policy for this workload. None inherits
+    GPUSTACK_RUNTIME_KUBERNETES_RESOURCE_INJECTION_POLICY (default Auto).
+    Env uses runtime-visible device environment variables; KDP requests
+    device-plugin resources; Auto detects the policy from the target node.
+    This setting does not change the environment or other workloads.
+    Env injection of all devices uses the runtime's privileged container path.
+    """
+
     def validate_and_default(self):
         """
         Validate and set defaults for the workload plan.
@@ -168,6 +188,15 @@ class KubernetesWorkloadPlan(WorkloadPlan):
                 If the workload plan is invalid.
 
         """
+        if self.resource_injection_policy is not None:
+            try:
+                self.resource_injection_policy = KubernetesResourceInjectionPolicyEnum(
+                    self.resource_injection_policy,
+                )
+            except ValueError as e:
+                msg = f"Invalid resource injection policy '{self.resource_injection_policy}'"
+                raise ValueError(msg) from e
+
         if self.labels is None:
             self.labels = {}
         if self.containers is None:
@@ -1153,6 +1182,9 @@ class KubernetesDeployer(EndoscopicDeployer):
             self._node_name = node.metadata.name
         return node.status.allocatable or {}
 
+    _resource_injection_policy: Literal["env", "kdp"] | None = None
+    """Resolved policy on the deployment instance dedicated to one workload."""
+
     def _resolve_resource_injection_policy(self) -> str:
         """
         Resolve the resource injection policy for this deployer, probing the
@@ -1162,6 +1194,8 @@ class KubernetesDeployer(EndoscopicDeployer):
             The resource injection policy.
 
         """
+        if self._resource_injection_policy is not None:
+            return self._resource_injection_policy
         return get_resource_injection_policy(self._probe_node_allocatable)
 
     def _get_default_node_name(self) -> str:
@@ -1806,14 +1840,33 @@ class KubernetesDeployer(EndoscopicDeployer):
         self._client = self._get_client()
         self._node_name = envs.GPUSTACK_RUNTIME_KUBERNETES_NODE_NAME
         self._runtime_uuid_values_allowed: bool | None = None
+        self._deployment_lock = Lock()
+        self._materials_cache: dict[str, dict[str, DevicesMaterial]] = {}
+        self._materials_locks = {policy: Lock() for policy in ("env", "kdp")}
+
+    def _prepare(self):
+        """
+        Reuse device materials built for the same resolved injection policy.
+        """
+        if self._materials is not None:
+            return
+        policy = self._resolve_resource_injection_policy()
+        with self._materials_locks[policy]:
+            if policy not in self._materials_cache:
+                self._runtime_uuid_values_allowed = policy != "kdp"
+                try:
+                    super()._prepare()
+                except Exception:
+                    # Incomplete detection must not become a reusable device map.
+                    self._materials = None
+                    raise
+                self._materials_cache[policy] = self._materials
+            self._materials = self._materials_cache[policy]
 
     @property
     def allowed_runtime_uuid_values(self) -> bool:
-        # Resolved once per deployer, unlike the per-Pod resolution the
-        # creation path wants: this gates how `_prepare` builds the device
-        # materials, which are themselves built once, and it is read there once
-        # per manufacturer -- so probing on every read would spend one API call
-        # per manufacturer to answer a question already settled.
+        # Device materials and UUID eligibility belong to the same resolved
+        # policy. Workloads with the same policy reuse the device materials.
         if self._runtime_uuid_values_allowed is None:
             self._runtime_uuid_values_allowed = (
                 self._resolve_resource_injection_policy() != "kdp"
@@ -2143,25 +2196,40 @@ class KubernetesDeployer(EndoscopicDeployer):
             msg = f"Invalid workload plan type: {type(workload)}"
             raise TypeError(msg)
 
-        self._prepare_mirrored_deployment()
-
-        if isinstance(workload, WorkloadPlan):
+        if not isinstance(workload, KubernetesWorkloadPlan):
             workload = KubernetesWorkloadPlan(**workload.__dict__)
         workload.validate_and_default()
+
+        # Node selection and mirrored options belong to the registered deployer,
+        # including the node used by later workload listing operations.
+        with self._deployment_lock:
+            self._prepare_mirrored_deployment()
+            deployer: KubernetesDeployer = copy(self)
+
+        # Each workload resolves its policy independently while sharing cached
+        # device materials only with workloads using the same policy.
+        deployer._materials = None
+        deployer._resource_injection_policy = get_resource_injection_policy(
+            deployer._probe_node_allocatable,
+            policy=workload.resource_injection_policy,
+        )
+        deployer._runtime_uuid_values_allowed = (
+            deployer._resource_injection_policy != "kdp"
+        )
         if logger.isEnabledFor(logging.DEBUG):
             logger.debug("Creating workload:\n%s", workload.to_yaml())
 
         # Create ephemeral file if needed,
         # (container index, configured path): <actual ConfigMap name>
         ephemeral_filename_mapping: dict[tuple[int, str], str] = (
-            self._create_ephemeral_configmaps(workload)
+            deployer._create_ephemeral_configmaps(workload)
         )
 
         # Create Service if needed.
-        self._create_service(workload)
+        deployer._create_service(workload)
 
         # Create Pod.
-        self._create_pod(
+        deployer._create_pod(
             workload,
             ephemeral_filename_mapping,
         )

{gpustack_runtime-0.2.5.post3 → gpustack_runtime-0.2.5.post4}/mkdocs.yml

@@ -41,7 +41,7 @@ markdown_extensions:
 extra:
   generator: false
 
-copyright: Copyright © 2025, GPUStack Contributors
+copyright: Copyright © 2026, GPUStack Contributors
 
 nav:
   - Modules:

{gpustack_runtime-0.2.5.post3 → gpustack_runtime-0.2.5.post4}/specs/2026-08-14-detector-alignment-and-workload-exit-status.md

@@ -425,7 +425,7 @@ gpustack_runtime/
 │   ├── __types__.py         # Container/Workload{Plan,Status}, Deployer ABC, DevicesMaterial
 │   ├── docker.py            # DockerWorkloadStatus.parse_state
 │   ├── podman.py
-│   ├── kuberentes.py        # KubernetesWorkloadStatus.parse_state, Pod/Event reads
+│   ├── kubernetes.py        # KubernetesWorkloadStatus.parse_state, Pod/Event reads
 │   └── cdi/<vendor>.py      # CDI spec generation, consumes Device.index/appendix
 ├── cmds/detector.py         # `detect` / `topology` sub-commands
 └── envs.py                  # GPUSTACK_RUNTIME_* env surface
@@ -769,14 +769,14 @@ implement `detect_info()`.
 - [x] **D1 · Pin the device ordering for containers that see every card**
       Blocked by: None
       Owns: `gpustack_runtime/deployer/__types__.py`, `gpustack_runtime/deployer/docker.py`,
-      `gpustack_runtime/deployer/podman.py`, `gpustack_runtime/deployer/kuberentes.py`,
+      `gpustack_runtime/deployer/podman.py`, `gpustack_runtime/deployer/kubernetes.py`,
       `tests/gpustack_runtime/deployer/test_visible_devices_ordering.py`
       Gate: review
       Scope: add `Deployer.map_visible_devices_ordering(runtime_envs) -> dict[str, str]` beside the
       existing `map_backend_visible_devices` / `map_visible_devices_affinities` — it resolves each
       runtime visible-devices env name to its manufacturer through `get_manufacturer()` and returns
       `{"CUDA_DEVICE_ORDER": "PCI_BUS_ID"}` when NVIDIA is among them, `{}` otherwise. Call it from all
-      three deployers' device-request loops (`docker.py`, `podman.py`, `kuberentes.py`), right beside
+      three deployers' device-request loops (`docker.py`, `podman.py`, `kubernetes.py`), right beside
       the existing `if r_v != "all" and privileged:` backend-visible-devices block, under the
       complementary condition `r_v == "all" or privileged` — the deployers' own resolution of "this
       container sees every card". Never overwrite a value the container already declares (the
@@ -823,7 +823,7 @@ implement `detect_info()`.
 
 - [x] **D5 · Kubernetes: exit status, image-pull failure, Pod Events, RBAC**
       Blocked by: D2
-      Owns: `gpustack_runtime/deployer/kuberentes.py`, `deploy/manifests/kubernetes.yaml`,
+      Owns: `gpustack_runtime/deployer/kubernetes.py`, `deploy/manifests/kubernetes.yaml`,
       `tests/gpustack_runtime/deployer/test_kubernetes_status.py`
       Gate: review
       Scope: fill the exit list from `container_statuses` / `init_container_statuses`, reading

{gpustack_runtime-0.2.5.post3 → gpustack_runtime-0.2.5.post4}/tests/gpustack_runtime/deployer/test_kubernetes_status.py

@@ -9,7 +9,7 @@ import kubernetes.client
 import pytest
 
 from gpustack_runtime.deployer.__types__ import WorkloadStatusStateEnum
-from gpustack_runtime.deployer.kuberentes import KubernetesWorkloadStatus
+from gpustack_runtime.deployer.kubernetes import KubernetesWorkloadStatus
 
 _REGISTRY_MESSAGE = 'Back-off pulling image "does-not-exist.invalid/x:y"'
 _EVENT_MESSAGE = (