oc-gpu

A kubectl/oc plugin that fills a gap in OpenShift/Kubernetes tooling: there's no oc get gpus. This plugin surfaces GPU resource requests per pod and GPU capacity/allocation per node, using only the standard Kubernetes API (no Prometheus or extra RBAC required).

Examples below use oc, but since oc is a superset of kubectl and both use the same plugin mechanism, every command works identically with kubectl too — swap one for the other freely.

Install

Preferred: via krew, kubectl's plugin manager, using this repo as a self-hosted plugin index:

oc krew index add oc-gpu https://github.com/gavinsan33/oc-gpu.git
oc krew install oc-gpu/gpu

Or build from source (requires Go 1.22+):

make install   # builds and installs to /usr/local/bin (override with INSTALL_DIR=...)

Either way, invoke it as a plugin:

oc gpu pods
oc gpu nodes

Usage

oc gpu pods

Lists pods with non-zero GPU requests/limits (any resource name containing gpu, so it works across nvidia.com/gpu, amd.com/gpu, gpu.intel.com/i915, etc. without vendor-specific config).

oc gpu pods -n my-namespace
oc gpu pods -A               # all namespaces
oc gpu pods -A --running-only  # exclude Succeeded/Failed pods

Output columns: namespace, pod, container, node, resource name, requested, limit, GPU model (from node labels), phase.

oc gpu nodes

Summarizes GPU capacity/allocatable per node alongside the sum of GPU requests from pods currently scheduled there, so you can spot GPUs that are claimed (allocatable is reduced) but idle.

oc gpu nodes

Output columns: node, GPU model, resource name, capacity, allocatable, requested, idle (allocatable - requested).

GPU model is read from common device-plugin/operator node labels (nvidia.com/gpu.product, amd.com/gpu.device.id, gpu.intel.com/device-id); falls back to unknown if none are present.

Standard flags

Built with k8s.io/cli-runtime's genericclioptions, so it accepts the same connection flags oc/kubectl themselves do: --kubeconfig, --context, --namespace/-n, --server, --token, etc. — no plugin-specific config needed.

Releasing (krew)

Pushing a v* tag runs .github/workflows/release.yaml, which builds cross-platform archives with make dist and publishes them as a GitHub release. plugins/gpu.yaml is the krew manifest for this repo's index; its Go-template functions (.TagName, addURIAndSha) are resolved by the kubectl krew client itself at install time, so no CI rendering step is needed.

To test the manifest locally before/without a release:

make dist VERSION=v0.0.0-dev
kubectl krew install --manifest=plugins/gpu.yaml --archive=dist/kubectl-gpu_v0.0.0-dev_linux_amd64.tar.gz

Makefile targets

• make build — build ./kubectl-gpu
• make install — build and install to /usr/local/bin (or INSTALL_DIR)
• make uninstall — remove the installed binary from INSTALL_DIR
• make dist — cross-compile release tarballs + checksums.txt into dist/ for krew
• make test — run unit tests
• make vet — run go vet
• make check — vet + test
• make fmt — gofmt the repo
• make tidy — go mod tidy
• make clean — remove the built binary and dist/

Roadmap

• Prometheus-backed utilization percentage (requires access to the cluster's monitoring stack) to distinguish "claimed but idle" from "claimed and actively computing," beyond the allocatable/requested delta this version already reports.

Project structure

cmd/kubectl-gpu/    CLI entrypoint (cobra commands, table output)
internal/gpu/       Kubernetes API queries and GPU resource/node logic