Skip to content

Commit 9f607f0

Browse files
committed
docs(gpu): describe the step 1 GPU class contract
The VMI webhook, the launcher pod webhook, the license copier and the budget check land separately, yet each depends on what the others write: the template annotation and label, the gpus entry names, the license copy's name, label and keys, and the volume label guest images look for. The package comment states that contract next to the names it uses, so each later piece is written and reviewed against one description rather than against the design document. Assisted-by: LLM Signed-off-by: Aleksei Sviridkin <[email protected]>
1 parent 612ff85 commit 9f607f0

1 file changed

Lines changed: 91 additions & 0 deletions

File tree

‎internal/gpu/doc.go‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
/*
2+
Copyright 2026 The Cozystack Authors.
3+
4+
Licensed under the Apache License, Version 2.0 (the "License");
5+
you may not use this file except in compliance with the License.
6+
You may obtain a copy of the License at
7+
8+
http://www.apache.org/licenses/LICENSE-2.0
9+
10+
Unless required by applicable law or agreed to in writing, software
11+
distributed under the License is distributed on an "AS IS" BASIS,
12+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
See the License for the specific language governing permissions and
14+
limitations under the License.
15+
*/
16+
17+
// Package gpu holds the names the GPU components of cozystack-controller
18+
// and cozystack-api share. The pure capacity, budget and tenant logic
19+
// lives in package model.
20+
//
21+
// # Class entries
22+
//
23+
// A VM or a worker pool names a GPUClass and a count in its gpus list.
24+
// The chart renders the entries onto the VMI template as AnnotationGPUs,
25+
// next to LabelGPUReference, which KubeVirt copies to the VMI and its
26+
// virt-launcher pod:
27+
//
28+
// cozystack.io/gpus: '[{"className":"l40s-24c","count":2}]'
29+
//
30+
// # Starting a VMI
31+
//
32+
// A mutating webhook on VMI creation resolves each entry to its class and
33+
// writes one gpus entry per unit, named with VMIGPUNamePrefix and
34+
// requesting the class's resource name. The entries have to be complete
35+
// at admission, since KubeVirt renders the launcher pod's requests from
36+
// the VMI spec and nothing else can change that spec afterwards. The
37+
// webhook refuses the VMI, naming the class, when an entry:
38+
//
39+
// - names a class that does not exist, is being deleted, or has a
40+
// ResourceNameConflict condition;
41+
// - is a vGPU class next to another vGPU class, or takes the VMI's units
42+
// of its class above model.EffectiveMaxCount;
43+
// - names a vGPU class in a namespace without the vGPU entitlement
44+
// (model.Entitled);
45+
// - names a class whose resource name the KubeVirt permittedHostDevices
46+
// table leaves out, when the table is set (model.PermittedResourceNames),
47+
// since KubeVirt would accept the VMI and leave it Pending with no pod.
48+
//
49+
// A class has ResourceNameConflict when an older class has its resource
50+
// name (model.Conflicts), so the class tenants already run on keeps it.
51+
// Age is the creation time: a class whose resource name is edited later
52+
// is judged by when it was created, not by when it took the name.
53+
//
54+
// The webhook also refuses a labelled VMI that carries GPU entries of its own. It
55+
// reads classes and the KubeVirt CR from the API server, not from a cache,
56+
// writes no object besides its patch, and checks no capacity: a VM short
57+
// of a free unit waits in Scheduling like a VM short of CPU.
58+
//
59+
// A second mutating webhook adds the classes' tolerations to the
60+
// virt-launcher pod at creation, and to the temporary pod KubeVirt creates
61+
// to bind WaitForFirstConsumer volumes. They go on the pod and not on the
62+
// VMI, because under vmRolloutStrategy LiveUpdate KubeVirt resets a VMI's
63+
// tolerations to the VM template's on every sync. Both webhooks select on
64+
// LabelGPUReference and fail closed.
65+
//
66+
// # Licenses
67+
//
68+
// For each vGPU class with a license, the controller copies the hoster's
69+
// Secret from LicenseSecretNamespace into every namespace whose
70+
// LabelNamespaceVGPU is LabelValueTrue, named by LicenseSecretName and
71+
// labelled LabelGPUClass, with the keys LicenseTokenKey and
72+
// LicenseGriddConfKey. It deletes a namespace's copies when the label
73+
// stops being LabelValueTrue, and a class's copies when the class or its
74+
// license goes. While the hoster's Secret is missing or lacks
75+
// LicenseTokenKey, it keeps the copies it has, writes no new ones and sets
76+
// LicenseSecretMissing on the class. It touches no Secret without
77+
// LabelGPUClass.
78+
//
79+
// The VMI webhook adds a secret volume for the copy of the VMI's licensed
80+
// vGPU class, with LicenseVolumeLabel, and a disk for it after the VMI's
81+
// other disks with no bootOrder. A missing copy is not refused: kubelet
82+
// keeps the launcher pod from starting until the copy exists.
83+
//
84+
// # Budgets
85+
//
86+
// A tenant declares GPU budgets in resourceQuotas under model.ClassQuotaKey
87+
// per class and QuotaKeyTotal over every class. They are not resource
88+
// names a pod requests, so the tenant chart keeps them out of the
89+
// namespace ResourceQuota, and they are checked when a VM or a pool is
90+
// written, against the class entries it declares.
91+
package gpu

0 commit comments

Comments
 (0)