Skip to content

Commit e721884

Browse files
committed
docs(gpu): define the class admission and licensing contract
The admission webhooks, license copier and budget checks depend on the same class annotations, names and ownership rules. Keep their contract next to the shared constants, including where name acknowledgement ends and capacity scheduling begins. Assisted-by: LLM Signed-off-by: Aleksei Sviridkin <[email protected]>
1 parent 13fa6bc commit e721884

1 file changed

Lines changed: 102 additions & 0 deletions

File tree

‎internal/gpu/doc.go‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
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 lacks unique
40+
// ownership of its exact requested resource name;
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+
// Catalog-name ownership is acknowledged in status.ownedResourceName for
50+
// the object's UID, independently of Ready, license state and generation.
51+
// A serialized status writer retains that name until a successful
52+
// resource-version-checked status transition acquires another name; an
53+
// unacknowledged rename does not release the old name. This reserves a
54+
// catalog name, not GPU capacity. Creation time and name select candidates
55+
// only for unreserved names (model.ResourceNameCandidates).
56+
//
57+
// Admission requires requested and owned names to match uniquely in one
58+
// fresh class snapshot (model.ConfirmedResourceNames). Missing ownership
59+
// is pending; duplicate reservations fail closed without clearing the
60+
// acknowledgements or choosing a creation-time winner. Conditions are not
61+
// ownership evidence. This check is not atomic with future status writes:
62+
// leader election is not fencing, and overlapping writers can produce
63+
// duplicate ownership that the next fresh read must refuse.
64+
//
65+
// The webhook also refuses a labelled VMI that carries GPU entries of its own. It
66+
// reads classes and the KubeVirt CR from the API server, not from a cache,
67+
// writes no object besides its patch, and checks no capacity: a VM short
68+
// of a free unit waits in Scheduling like a VM short of CPU.
69+
//
70+
// A second mutating webhook adds the classes' tolerations to the
71+
// virt-launcher pod at creation, and to the temporary pod KubeVirt creates
72+
// to bind WaitForFirstConsumer volumes. They go on the pod and not on the
73+
// VMI, because under vmRolloutStrategy LiveUpdate KubeVirt resets a VMI's
74+
// tolerations to the VM template's on every sync. Both webhooks select on
75+
// LabelGPUReference and fail closed.
76+
//
77+
// # Licenses
78+
//
79+
// For each vGPU class with a license, the controller copies the hoster's
80+
// Secret from LicenseSecretNamespace into every namespace whose
81+
// LabelNamespaceVGPU is LabelValueTrue, named by LicenseSecretName and
82+
// labelled LabelGPUClass, with the keys LicenseTokenKey and
83+
// LicenseGriddConfKey. It deletes a namespace's copies when the label
84+
// stops being LabelValueTrue, and a class's copies when the class or its
85+
// license goes. While the hoster's Secret is missing or lacks
86+
// LicenseTokenKey, it keeps the copies it has, writes no new ones and sets
87+
// LicenseSecretMissing on the class. It touches no Secret without
88+
// LabelGPUClass.
89+
//
90+
// The VMI webhook adds a secret volume for the copy of the VMI's licensed
91+
// vGPU class, with LicenseVolumeLabel, and a disk for it after the VMI's
92+
// other disks with no bootOrder. A missing copy is not refused: kubelet
93+
// keeps the launcher pod from starting until the copy exists.
94+
//
95+
// # Budgets
96+
//
97+
// A tenant declares GPU budgets in resourceQuotas under model.ClassQuotaKey
98+
// per class and QuotaKeyTotal over every class. They are not resource
99+
// names a pod requests, so the tenant chart keeps them out of the
100+
// namespace ResourceQuota, and they are checked when a VM or a pool is
101+
// written, against the class entries it declares.
102+
package gpu

0 commit comments

Comments
 (0)