gpustack-runtime 0.2.5.post3__tar.gz → 0.2.6__tar.gz

gpustack_runtime-0.2.6/.agents/skills/runtime-release/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: runtime-release
+description: Cut a gpustack-runtime package release end to end (select and push the tag, monitor the release workflow, curate the GitHub Release notes).
+---
+
+# Runtime release
+
+One maintainer duty: cut a package release. Push a version tag; `release.yml` builds and publishes
+it. Then write the GitHub Release notes.
+
+## Cut a package release
+
+The git tag is the single source of truth: hatch-vcs derives the package version from it at build
+time, and there is no version file to bump. Pushing a `v*.*.*` tag runs
+`.github/workflows/release.yml`: build the distributions, create the GitHub Release with the
+wheel/sdist assets, publish to PyPI, then verify an isolated install. Branch pushes to `main` or
+`v*-dev` run the same job against TestPyPI and create no release.
+
+Two workflow facts shape the procedure:
+
+- The GitHub Release is a pre-release only when the tag contains `rc`. A final tag goes public and
+  becomes `latest` immediately. There is no promotion gate.
+- The workflow generates no baseline notes. The release body starts empty, so curating the notes is
+  not polish; it is the entire text the reader gets.
+
+PyPI is the irreversible step: a version once published there cannot be re-uploaded or edited.
+
+### Hard rules
+
+- Tag shapes: `vX.Y.Z` final, `vX.Y.ZrcN` pre-release, `vX.Y.Z.postN` post-release. PEP 440
+  canonical spellings only; history contains the non-dotted `v0.2.5postN` — do not repeat it.
+- A tag whose PyPI publish succeeded is burned. NEVER delete or move it; fix forward with a new
+  version. Delete-and-recreate is limited to a tag that never reached PyPI and is interactive-only.
+- An `rc` tag stays a pre-release; never mark it latest.
+- Release from `origin/main` HEAD by default. A maintenance line (`v*-dev` branch) targets that
+  branch's HEAD; flag the choice in the summary.
+- Interactive mode confirms every mutating step (tag push, note replacement). Auto mode runs
+  unattended through note curation and reports the release URL.
+
+### 1. Preflight (read-only)
+
+```sh
+gh auth status
+git fetch origin --tags --prune
+git status --porcelain                            # must be empty
+git tag -l 'v*' --sort=-v:refname | head -5
+```
+
+### 2. Version and commit (confirm)
+
+- Pick the target ref: `origin/main` by default, or the `v*-dev` branch for a maintenance line. The
+  steps below call it `$TARGET`; `$SHA` is its HEAD (`git rev-parse "$TARGET"`).
+- Read the range since the previous tag: `git log --no-merges --oneline <last>..$TARGET`.
+- Propose the bump from the Conventional Commits in range: any `feat` → minor; fixes, docs, and
+  chores → patch. Use `.postN` only to re-issue the same version line (packaging metadata or a
+  docs-only rebuild of unchanged content).
+- Confirm the (version, commit) pair before tagging. A final tag publishes immediately, so this
+  confirmation is the only gate.
+
+### 3. Draft notes
+
+Group the range by type: Features / Fixes / Docs / Other; omit empty sections. Keep highlights and
+fold noisy `chore`/`ci`/`test` entries. Link PRs from `(#NNN)` subjects. Do not open the body with
+a heading that repeats the tag. End with the Full Changelog compare URL
+(`https://github.com/gpustack/runtime/compare/<last>...<VER>`). Write the draft to `notes.md`;
+step 5 publishes that file.
+
+### 4. Tag and monitor (confirm, then read-only)
+
+```sh
+git tag -a "$VER" "$SHA" -m "Release $VER"
+git push origin "$VER"
+gh run list --branch "$VER" --limit 5     # the release.yml run for the tag
+gh run watch <run-id> --exit-status       # background it; wait for the completion notification
+```
+
+The job's own verify step installs the package from PyPI in an isolated env, but it is unpinned and
+only prints the installed version. A green run proves the upload succeeded, not that PyPI already
+serves the new version; read the verify log's `version =` line and confirm it equals `$VER`. On
+failure read `gh run view <run-id> --log-failed`; retry the same run on transient errors. If the
+failure is real and PyPI already holds the version, cut the next version instead — never re-tag.
+
+### 5. Curate notes (confirm)
+
+```sh
+gh release view "$VER" --json body,isPrerelease     # the body starts empty
+gh release edit "$VER" --notes-file notes.md
+```
+
+A maintenance-line final keeps `--latest=false` when a newer stable tag exists. Verify the badge
+with `gh api repos/gpustack/runtime/releases/latest --jq .tag_name`. An `rc` release stays a
+pre-release and needs no further action.
+
+## Scope
+
+Package releases and their notes run here. No other repository document changes with a release:
+the version comes from the tag, and no README or docs table tracks it. Container image builds are
+`make package` (`pack/`) and deployment manifests live in `deploy/`; both are outside this skill.
+Docs-only changes never trigger a release: the release workflow ignores docs paths on branch
+pushes, so docs updates need no tag.

{gpustack_runtime-0.2.5.post3 → gpustack_runtime-0.2.6}/.gitignore

@@ -3,7 +3,10 @@
 .vscode/
 .DS_Store
 *.swp
-.claude/
+**/.claude/*
+!/.claude/skills
+/.claude/skills/*
+!/.claude/skills/runtime-release
 
 # Python-generated files
 _version.py

gpustack_runtime-0.2.6/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.6/AGENTS.md

@@ -0,0 +1,87 @@
+# 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.
+
+Cut package releases with the [runtime-release](.agents/skills/runtime-release/SKILL.md) skill.
+
+### 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.6/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.6}/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.6/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.5
+Name: gpustack-runtime
+Version: 0.2.6
+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.31
+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.6/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.6}/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.6'
+__version_tuple__ = version_tuple = (0, 2, 6)
 try:
     from ._version_appendix import git_commit
     __commit_id__ = commit_id = git_commit

gpustack_runtime-0.2.6/gpustack_runtime/_version_appendix.py

@@ -0,0 +1 @@
+git_commit = "66c3e8f"

{gpustack_runtime-0.2.5.post3 → gpustack_runtime-0.2.6}/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.6}/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",