|
| 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