1package v1alpha2
2
3import "cue.dev/x/k8s.io/apimachinery/pkg/apis/meta/v1"
4
5// BasicSchedulingPolicy indicates that standard Kubernetes
6// scheduling behavior should be used.
7#BasicSchedulingPolicy: {}
8
9// GangSchedulingPolicy defines the parameters for gang
10// scheduling.
11#GangSchedulingPolicy: {
12 // MinCount is the minimum number of pods that must be schedulable
13 // or scheduled at the same time for the scheduler to admit the
14 // entire group. It must be a positive integer.
15 "minCount"!: int32 & int
16}
17
18// PodGroup represents a runtime instance of pods grouped
19// together. PodGroups are created by workload controllers (Job,
20// LWS, JobSet, etc...) from Workload.podGroupTemplates. PodGroup
21// API enablement is toggled by the GenericWorkload feature gate.
22#PodGroup: {
23 // APIVersion defines the versioned schema of this representation
24 // of an object. Servers should convert recognized schemas to the
25 // latest internal value, and may reject unrecognized values.
26 // More info:
27 // https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
28 "apiVersion": "scheduling.k8s.io/v1alpha2"
29
30 // Kind is a string value representing the REST resource this
31 // object represents. Servers may infer this from the endpoint
32 // the client submits requests to. Cannot be updated. In
33 // CamelCase. More info:
34 // https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
35 "kind": "PodGroup"
36
37 // Standard object's metadata. More info:
38 // https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata
39 "metadata"?: v1.#ObjectMeta
40
41 // Spec defines the desired state of the PodGroup.
42 "spec"!: #PodGroupSpec
43
44 // Status represents the current observed state of the PodGroup.
45 "status"?: #PodGroupStatus
46}
47
48// PodGroupList contains a list of PodGroup resources.
49#PodGroupList: {
50 // APIVersion defines the versioned schema of this representation
51 // of an object. Servers should convert recognized schemas to the
52 // latest internal value, and may reject unrecognized values.
53 // More info:
54 // https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
55 "apiVersion": "scheduling.k8s.io/v1alpha2"
56
57 // Items is the list of PodGroups.
58 "items"!: [...#PodGroup]
59
60 // Kind is a string value representing the REST resource this
61 // object represents. Servers may infer this from the endpoint
62 // the client submits requests to. Cannot be updated. In
63 // CamelCase. More info:
64 // https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
65 "kind": "PodGroupList"
66
67 // Standard list metadata.
68 "metadata"?: v1.#ListMeta
69}
70
71// PodGroupResourceClaim references exactly one ResourceClaim,
72// either directly or by naming a ResourceClaimTemplate which is
73// then turned into a ResourceClaim for the PodGroup.
74//
75// It adds a name to it that uniquely identifies the ResourceClaim
76// inside the PodGroup. Pods that need access to the
77// ResourceClaim define a matching reference in its own
78// Spec.ResourceClaims. The Pod's claim must match all fields of
79// the PodGroup's claim exactly.
80#PodGroupResourceClaim: {
81 // Name uniquely identifies this resource claim inside the
82 // PodGroup. This must be a DNS_LABEL.
83 "name"!: string
84
85 // ResourceClaimName is the name of a ResourceClaim object in the
86 // same namespace as this PodGroup. The ResourceClaim will be
87 // reserved for the PodGroup instead of its individual pods.
88 //
89 // Exactly one of ResourceClaimName and ResourceClaimTemplateName
90 // must be set.
91 "resourceClaimName"?: string
92
93 // ResourceClaimTemplateName is the name of a
94 // ResourceClaimTemplate object in the same namespace as this
95 // PodGroup.
96 //
97 // The template will be used to create a new ResourceClaim, which
98 // will be bound to this PodGroup. When this PodGroup is deleted,
99 // the ResourceClaim will also be deleted. The PodGroup name and
100 // resource name, along with a generated component, will be used
101 // to form a unique name for the ResourceClaim, which will be
102 // recorded in podgroup.status.resourceClaimStatuses.
103 //
104 // This field is immutable and no changes will be made to the
105 // corresponding ResourceClaim by the control plane after
106 // creating the ResourceClaim.
107 //
108 // Exactly one of ResourceClaimName and ResourceClaimTemplateName
109 // must be set.
110 "resourceClaimTemplateName"?: string
111}
112
113// PodGroupResourceClaimStatus is stored in the PodGroupStatus for
114// each PodGroupResourceClaim which references a
115// ResourceClaimTemplate. It stores the generated name for the
116// corresponding ResourceClaim.
117#PodGroupResourceClaimStatus: {
118 // Name uniquely identifies this resource claim inside the
119 // PodGroup. This must match the name of an entry in
120 // podgroup.spec.resourceClaims, which implies that the string
121 // must be a DNS_LABEL.
122 "name"!: string
123
124 // ResourceClaimName is the name of the ResourceClaim that was
125 // generated for the PodGroup in the namespace of the PodGroup.
126 // If this is unset, then generating a ResourceClaim was not
127 // necessary. The podgroup.spec.resourceClaims entry can be
128 // ignored in this case.
129 "resourceClaimName"?: string
130}
131
132// PodGroupSchedulingConstraints defines scheduling constraints
133// (e.g. topology) for a PodGroup.
134#PodGroupSchedulingConstraints: {
135 // Topology defines the topology constraints for the pod group.
136 // Currently only a single topology constraint can be specified.
137 // This may change in the future.
138 "topology"?: [...#TopologyConstraint]
139}
140
141// PodGroupSchedulingPolicy defines the scheduling configuration
142// for a PodGroup. Exactly one policy must be set.
143#PodGroupSchedulingPolicy: {
144 // Basic specifies that the pods in this group should be scheduled
145 // using standard Kubernetes scheduling behavior.
146 "basic"?: #BasicSchedulingPolicy
147
148 // Gang specifies that the pods in this group should be scheduled
149 // using all-or-nothing semantics.
150 "gang"?: #GangSchedulingPolicy
151}
152
153// PodGroupSpec defines the desired state of a PodGroup.
154#PodGroupSpec: {
155 // DisruptionMode defines the mode in which a given PodGroup can
156 // be disrupted. Controllers are expected to fill this field by
157 // copying it from a PodGroupTemplate. One of Pod, PodGroup.
158 // Defaults to Pod if unset. This field is immutable. This field
159 // is available only when the WorkloadAwarePreemption feature
160 // gate is enabled.
161 "disruptionMode"?: string
162
163 // PodGroupTemplateRef references an optional PodGroup template
164 // within other object (e.g. Workload) that was used to create
165 // the PodGroup. This field is immutable.
166 "podGroupTemplateRef"?: #PodGroupTemplateReference
167
168 // Priority is the value of priority of this pod group. Various
169 // system components use this field to find the priority of the
170 // pod group. When Priority Admission Controller is enabled, it
171 // prevents users from setting this field. The admission
172 // controller populates this field from PriorityClassName. The
173 // higher the value, the higher the priority. This field is
174 // immutable. This field is available only when the
175 // WorkloadAwarePreemption feature gate is enabled.
176 "priority"?: int32 & int
177
178 // PriorityClassName defines the priority that should be
179 // considered when scheduling this pod group. Controllers are
180 // expected to fill this field by copying it from a
181 // PodGroupTemplate. Otherwise, it is validated and resolved
182 // similarly to the PriorityClassName on PodGroupTemplate (i.e.
183 // if no priority class is specified, admission control can set
184 // this to the global default priority class if it exists.
185 // Otherwise, the pod group's priority will be zero). This field
186 // is immutable. This field is available only when the
187 // WorkloadAwarePreemption feature gate is enabled.
188 "priorityClassName"?: string
189
190 // ResourceClaims defines which ResourceClaims may be shared among
191 // Pods in the group. Pods consume the devices allocated to a
192 // PodGroup's claim by defining a claim in its own
193 // Spec.ResourceClaims that matches the PodGroup's claim exactly.
194 // The claim must have the same name and refer to the same
195 // ResourceClaim or ResourceClaimTemplate.
196 //
197 // This is an alpha-level field and requires that the
198 // DRAWorkloadResourceClaims feature gate is enabled.
199 //
200 // This field is immutable.
201 "resourceClaims"?: [...#PodGroupResourceClaim]
202
203 // SchedulingConstraints defines optional scheduling constraints
204 // (e.g. topology) for this PodGroup. Controllers are expected to
205 // fill this field by copying it from a PodGroupTemplate. This
206 // field is immutable. This field is only available when the
207 // TopologyAwareWorkloadScheduling feature gate is enabled.
208 "schedulingConstraints"?: #PodGroupSchedulingConstraints
209
210 // SchedulingPolicy defines the scheduling policy for this
211 // instance of the PodGroup. Controllers are expected to fill
212 // this field by copying it from a PodGroupTemplate. This field
213 // is immutable.
214 "schedulingPolicy"!: #PodGroupSchedulingPolicy
215}
216
217// PodGroupStatus represents information about the status of a pod
218// group.
219#PodGroupStatus: {
220 // Conditions represent the latest observations of the PodGroup's
221 // state.
222 //
223 // Known condition types: - "PodGroupScheduled": Indicates whether
224 // the scheduling requirement has been satisfied. -
225 // "DisruptionTarget": Indicates whether the PodGroup is about to
226 // be terminated
227 // due to disruption such as preemption.
228 //
229 // Known reasons for the PodGroupScheduled condition: -
230 // "Unschedulable": The PodGroup cannot be scheduled due to
231 // resource constraints,
232 // affinity/anti-affinity rules, or insufficient capacity for the
233 // gang.
234 // - "SchedulerError": The PodGroup cannot be scheduled due to
235 // some internal error
236 // that happened during scheduling, for example due to
237 // nodeAffinity parsing errors.
238 //
239 // Known reasons for the DisruptionTarget condition: -
240 // "PreemptionByScheduler": The PodGroup was preempted by the
241 // scheduler to make room for
242 // higher-priority PodGroups or Pods.
243 "conditions"?: [...v1.#Condition]
244
245 // Status of resource claims.
246 "resourceClaimStatuses"?: [...#PodGroupResourceClaimStatus]
247}
248
249// PodGroupTemplate represents a template for a set of pods with a
250// scheduling policy.
251#PodGroupTemplate: {
252 // DisruptionMode defines the mode in which a given PodGroup can
253 // be disrupted. One of Pod, PodGroup. This field is available
254 // only when the WorkloadAwarePreemption feature gate is enabled.
255 "disruptionMode"?: string
256
257 // Name is a unique identifier for the PodGroupTemplate within the
258 // Workload. It must be a DNS label. This field is immutable.
259 "name"!: string
260
261 // Priority is the value of priority of pod groups created from
262 // this template. Various system components use this field to
263 // find the priority of the pod group. When Priority Admission
264 // Controller is enabled, it prevents users from setting this
265 // field. The admission controller populates this field from
266 // PriorityClassName. The higher the value, the higher the
267 // priority. This field is available only when the
268 // WorkloadAwarePreemption feature gate is enabled.
269 "priority"?: int32 & int
270
271 // PriorityClassName indicates the priority that should be
272 // considered when scheduling a pod group created from this
273 // template. If no priority class is specified, admission control
274 // can set this to the global default priority class if it
275 // exists. Otherwise, pod groups created from this template will
276 // have the priority set to zero. This field is available only
277 // when the WorkloadAwarePreemption feature gate is enabled.
278 "priorityClassName"?: string
279
280 // ResourceClaims defines which ResourceClaims may be shared among
281 // Pods in the group. Pods consume the devices allocated to a
282 // PodGroup's claim by defining a claim in its own
283 // Spec.ResourceClaims that matches the PodGroup's claim exactly.
284 // The claim must have the same name and refer to the same
285 // ResourceClaim or ResourceClaimTemplate.
286 //
287 // This is an alpha-level field and requires that the
288 // DRAWorkloadResourceClaims feature gate is enabled.
289 //
290 // This field is immutable.
291 "resourceClaims"?: [...#PodGroupResourceClaim]
292
293 // SchedulingConstraints defines optional scheduling constraints
294 // (e.g. topology) for this PodGroupTemplate. This field is only
295 // available when the TopologyAwareWorkloadScheduling feature
296 // gate is enabled.
297 "schedulingConstraints"?: #PodGroupSchedulingConstraints
298
299 // SchedulingPolicy defines the scheduling policy for this
300 // PodGroupTemplate.
301 "schedulingPolicy"!: #PodGroupSchedulingPolicy
302}
303
304// PodGroupTemplateReference references a PodGroup template
305// defined in some object (e.g. Workload). Exactly one reference
306// must be set.
307#PodGroupTemplateReference: {
308 // Workload references the PodGroupTemplate within the Workload
309 // object that was used to create the PodGroup.
310 "workload"?: #WorkloadPodGroupTemplateReference
311}
312
313// TopologyConstraint defines a topology constraint for a
314// PodGroup.
315#TopologyConstraint: {
316 // Key specifies the key of the node label representing the
317 // topology domain. All pods within the PodGroup must be
318 // colocated within the same domain instance. Different PodGroups
319 // can land on different domain instances even if they derive
320 // from the same PodGroupTemplate. Examples:
321 // "topology.kubernetes.io/rack"
322 "key"!: string
323}
324
325// TypedLocalObjectReference allows to reference typed object
326// inside the same namespace.
327#TypedLocalObjectReference: {
328 // APIGroup is the group for the resource being referenced. If
329 // APIGroup is empty, the specified Kind must be in the core API
330 // group. For any other third-party types, setting APIGroup is
331 // required. It must be a DNS subdomain.
332 "apiGroup"?: string
333
334 // Kind is the type of resource being referenced. It must be a
335 // path segment name.
336 "kind"!: string
337
338 // Name is the name of resource being referenced. It must be a
339 // path segment name.
340 "name"!: string
341}
342
343// Workload allows for expressing scheduling constraints that
344// should be used when managing the lifecycle of workloads from
345// the scheduling perspective, including scheduling, preemption,
346// eviction and other phases. Workload API enablement is toggled
347// by the GenericWorkload feature gate.
348#Workload: {
349 // APIVersion defines the versioned schema of this representation
350 // of an object. Servers should convert recognized schemas to the
351 // latest internal value, and may reject unrecognized values.
352 // More info:
353 // https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
354 "apiVersion": "scheduling.k8s.io/v1alpha2"
355
356 // Kind is a string value representing the REST resource this
357 // object represents. Servers may infer this from the endpoint
358 // the client submits requests to. Cannot be updated. In
359 // CamelCase. More info:
360 // https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
361 "kind": "Workload"
362
363 // Standard object's metadata. More info:
364 // https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata
365 "metadata"?: v1.#ObjectMeta
366
367 // Spec defines the desired behavior of a Workload.
368 "spec"!: #WorkloadSpec
369}
370
371// WorkloadList contains a list of Workload resources.
372#WorkloadList: {
373 // APIVersion defines the versioned schema of this representation
374 // of an object. Servers should convert recognized schemas to the
375 // latest internal value, and may reject unrecognized values.
376 // More info:
377 // https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
378 "apiVersion": "scheduling.k8s.io/v1alpha2"
379
380 // Items is the list of Workloads.
381 "items"!: [...#Workload]
382
383 // Kind is a string value representing the REST resource this
384 // object represents. Servers may infer this from the endpoint
385 // the client submits requests to. Cannot be updated. In
386 // CamelCase. More info:
387 // https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
388 "kind": "WorkloadList"
389
390 // Standard list metadata.
391 "metadata"?: v1.#ListMeta
392}
393
394// WorkloadPodGroupTemplateReference references the
395// PodGroupTemplate within the Workload object.
396#WorkloadPodGroupTemplateReference: {
397 // PodGroupTemplateName defines the PodGroupTemplate name within
398 // the Workload object.
399 "podGroupTemplateName"!: string
400
401 // WorkloadName defines the name of the Workload object.
402 "workloadName"!: string
403}
404
405// WorkloadSpec defines the desired state of a Workload.
406#WorkloadSpec: {
407 // ControllerRef is an optional reference to the controlling
408 // object, such as a Deployment or Job. This field is intended
409 // for use by tools like CLIs to provide a link back to the
410 // original workload definition. This field is immutable.
411 "controllerRef"?: #TypedLocalObjectReference
412
413 // PodGroupTemplates is the list of templates that make up the
414 // Workload. The maximum number of templates is 8. This field is
415 // immutable.
416 "podGroupTemplates"!: [...#PodGroupTemplate]
417}