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