菜单
Use when you need a guided tour of the GPUStack Operator codebase — its architecture, where things live (key directories), and naming conventions. Examples: "Give me an overview of this repo", "How is this project structured?", "Where does X live?", onboarding to the scheduling chain.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | gpustack-operator-overview |
| description | Use when you need a guided tour of the GPUStack Operator codebase — its architecture, where things live (key directories), and naming conventions. Examples: "Give me an overview of this repo", "How is this project structured?", "Where does X live?", onboarding to the scheduling chain. |
| model | haiku |
A Kubernetes operator that turns raw node hardware into a Kueue-based scheduling chain for accelerators (GPU/NPU/TPU), built on Node Feature Discovery (NFD) + Kueue.
One gpustack-operator binary, three subcommands; the scheduling chain builds in four stages:
worker installs NFD and per-manufacturer Device Manager DaemonSets.acceleratable.feature.gpustack.ai/* labels.NodeFeatureReconciler stamps the gpustack.ai/managed marker and NodeCapacityReconciler derives general./acceleratable. per-card capacity labels (CPU cores + the four .sliced.* accelerator capacities). The general(CPU) key defaults to generic and does not encode os/arch.ResourceFlavor → ClusterQueue (one isolated queue per pool, no Cohort) plus a materialized InstanceType CRD, fronted by a per-namespace LocalQueue and gated per-card by a gpustack-node-devices AdmissionCheck.pkg/nodefeature is the heart of the label algebra (construct/extract of node keys, flavors,
queues, credits). Full stage-by-stage detail and a worked example live in
architecture.md.
cmd/gpustack-operator/ single binary entrypoint (3 cobra subcommands)
pkg/
worker/ control-plane process (worker subcommand)
worker.go Prepare → Start lifecycle (startup ordering)
controllers/worker/ the scheduling-chain reconcilers
extensionapis/ aggregated extension-API handlers (Instance, Devices, InstanceType, …)
webhooks/worker/ admission webhooks (generated + hand-written)
kuberess/ installs NFD / Kueue / Device-Manager / CSI apps
workergateway/ worker-gateway subcommand (upstream aggregation)
devicemanager/ device-manager subcommand (per-node DaemonSet)
detector/<mfr>/ per-manufacturer accelerator detection
allocator/<mfr>/ per-manufacturer device-plugin allocation
nodefeature/ label algebra (node keys, flavors, queues, credits)
extensionapi/ generic aggregated-apiserver storage plumbing
api/
v1/ gpustack.ai/v1 extension API (settings, status)
worker/v1/ worker.gpustack.ai/v1 extension API
worker/v1alpha1/ worker.gpustack.ai/v1alpha1 CRDs (Instance, Devices, InstanceType)
binding/<runtime>/ generated CGO bindings (nvml, rsmi, cndev, dcmi, …)
gen/
api/generator/ custom code generators (apireg-gen, crd-gen, webhook-gen)
binding/<runtime>/config.yaml c-for-go config per GPU runtime
hack/ build/lint/test/deps/generate scripts behind the Makefile
staging/ patched k8s modules (managed by make deps)
Manufacturers: nvidia, amd, ascend, cambricon, hygon, iluvatar, metax, mthreads, thead.
Reconcilers under controllers/worker/ are unit-tested with the controller-runtime fake client
(sigs.k8s.io/controller-runtime/pkg/client/fake), registering the same field indexers the
controller uses via WithIndex — see the *_test.go beside each reconciler.
gpustack-${key}-${os}-${arch}-${count}{c|d} for a ResourceFlavor (c = CPU cores, d = devices); gpustack-${key}-${os}-${arch} for the ClusterQueue / InstanceType — single dash, CPU and device pools split (not composite), os/arch in full.gpustack-fnv64-<fnv64a-hash> — always 31 chars (the full ClusterQueue name goes in the schedule.gpustack.ai/cluster-queue annotation).feature.gpustack.ai/ (CPU/PCI facts), acceleratable.feature.gpustack.ai/ (device models + .sliced.* capacities), general.feature.gpustack.ai/ (CPU-only capacity), credits.gpustack.ai/<mfr> (Kueue quota resource), schedule.gpustack.ai/ + note.gpustack.ai/ (long names / unit-spec annotations); gpustack.ai/managed and gpustack.ai/controlled mark node onboarding and queue teardown._linux.go / _other.go split platform-specific code.zz_generated.*, generated.pb.go, generated.proto is generated — never hand-edit; edit the source types and run the gpustack-operator-generate skill.GPUSTACK_* configuration knobs → settings.mdRun a local end-to-end (E2E) verification of the GPUStack Operator on a reachable local cluster (k3s / docker-desktop): build & load the dev image, deploy via the Helm chart, then assert the NFD → Worker → Kueue scheduling chain materializes. Proactively offer this when a branch ahead of main changes controller reconcile, admission webhook, extension-apiserver, or in-cluster app-installation code. Examples: "run the e2e test", "verify my reconcile change on a real cluster", "deploy the operator to my local k3s and check the Kueue objects", "does this drain change actually work end to end?".
Run `make generate` to regenerate code after editing API types or webhooks. Invoke after changing files under api/ (api/v1, api/worker/v1, api/worker/v1alpha1) or webhook sources under pkg/*/webhooks/*/ — it regenerates deepcopy, register, apiservice, CRD, conversion, protobuf, and webhook code. Examples: "regenerate the API", "I added a field to the Instance type", "update the generated code".
Cut a GPUStack Operator release end to end: sync & verify the target branch (any branch, default `main`), pick and confirm the release commit, draft highlight-focused release notes from the Conventional-Commit history, cut & push the `vX.Y.Z` git tag, watch every tag-triggered pipeline (`ci.yml` image/Release + `ci-chart.yml` Helm chart) go green, then promote the CI-published pre-release to the official/latest release. Releases are published as **pre-releases first** and promoted only after CI is green and the user confirms. Also supports **overwrite (re-publish)** — re-cutting an existing `vX.Y.Z` under the same version via delete+recreate, interactive-only and confirm-gated. Proactively offer this when the user wants to ship/tag/publish a new version. Examples: "release v0.7.0", "cut the next release", "tag and publish v0.7.0", "do an rc pre-release", "ship v0.7.0 and watch CI", "overwrite v0.7.0", "re-release v0.7.0", "redo the release", "覆盖发布 v0.7.0", "重新发布 v0.7.0".
Verify the GPUStack Operator **Helm chart** end to end on a reachable local cluster (k3s / docker-desktop): build & load the dev image, `helm install` the chart, assert the worker/device-manager roll out, the versions are consistent (image tag ↔ bundled chart tgz ↔ `gpustack-operator --version`), then `helm uninstall` and assert zero leftovers. SCOPE: this validates the **chart contract** — chart changes, install/startup, image build, and version consistency — and is **NOT a feature/behavioral e2e**; for deep scheduling-chain behavior use `gpustack-operator-e2e` instead. Proactively offer this when a branch ahead of main changes the chart, the in-cluster app-installation code, or the image build. Examples: "verify the chart installs and uninstalls cleanly", "does helm install of the operator work", "check the chart version is right", "test my chart change end to end", "did my kuberess change break the runtime install".
Build and verify the GPUStack Operator's accelerator soft-slicing **builder stages** (`xbuild-ascend-cann-*` and `xbuild-nvidia-cuda-*` in `pack/gpustack-operator/Dockerfile`) end to end, either on the local docker host or on a remote accelerator host over ssh. Builds one stage via buildx `--target`, then runs numbered cases against the produced runtime. SCOPE — two backends: **Ascend (vcann-rt: `libvruntime.so` + `enpu-monitor`)** and **NVIDIA (HAMi-core: `libvgpu.so`)**. Ascend cases: (1) artifacts+linking [no NPU], (2) inject + `enpu-monitor`, (3) memory-quota enforcement. NVIDIA cases: (1) artifacts+linking [no GPU], (2) single-card inject + `nvidia-smi`/SM-limit, (3) multi-card per-device limits. The hardware cases need a real accelerator. Proactively offer this whenever a branch changes the Docker build flow — `pack/gpustack-operator/Dockerfile` or `pack/gpustack-operator/external/(ascend|nvidia)/**`. Examples: "verify my Dockerfile build-stage change", "did the vcann-rt / HAMi-core build still link", "