1 /* 2 Copyright 2016 The Kubernetes 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 batch 18 19 import ( 20 metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" 21 "k8s.io/apimachinery/pkg/types" 22 api "k8s.io/kubernetes/pkg/apis/core" 23 ) 24 25 const ( 26 // Unprefixed labels are reserved for end-users 27 // so we will add a batch.kubernetes.io to designate these labels as official Kubernetes labels. 28 // See https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#label-selector-and-annotation-conventions 29 labelPrefix = "batch.kubernetes.io/" 30 // JobTrackingFinalizer is a finalizer for Job's pods. It prevents them from 31 // being deleted before being accounted in the Job status. 32 // 33 // Additionally, the apiserver and job controller use this string as a Job 34 // annotation, to mark Jobs that are being tracked using pod finalizers. 35 // However, this behavior is deprecated in kubernetes 1.26. This means that, in 36 // 1.27+, one release after JobTrackingWithFinalizers graduates to GA, the 37 // apiserver and job controller will ignore this annotation and they will 38 // always track jobs using finalizers. 39 JobTrackingFinalizer = labelPrefix + "job-tracking" 40 // LegacyJobName and LegacyControllerUid are legacy labels that were set using unprefixed labels. 41 LegacyJobNameLabel = "job-name" 42 LegacyControllerUidLabel = "controller-uid" 43 // JobName is a user friendly way to refer to jobs and is set in the labels for jobs. 44 JobNameLabel = labelPrefix + LegacyJobNameLabel 45 // Controller UID is used for selectors and labels for jobs 46 ControllerUidLabel = labelPrefix + LegacyControllerUidLabel 47 // Annotation indicating the number of failures for the index corresponding 48 // to the pod, which are counted towards the backoff limit. 49 JobIndexFailureCountAnnotation = labelPrefix + "job-index-failure-count" 50 // Annotation indicating the number of failures for the index corresponding 51 // to the pod, which don't count towards the backoff limit, according to the 52 // pod failure policy. When the annotation is absent zero is implied. 53 JobIndexIgnoredFailureCountAnnotation = labelPrefix + "job-index-ignored-failure-count" 54 // JobControllerName reserved value for the managedBy field for the built-in 55 // Job controller. 56 JobControllerName = "kubernetes.io/job-controller" 57 ) 58 59 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object 60 61 // Job represents the configuration of a single job. 62 type Job struct { 63 metav1.TypeMeta 64 // Standard object's metadata. 65 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata 66 // +optional 67 metav1.ObjectMeta 68 69 // Specification of the desired behavior of a job. 70 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status 71 // +optional 72 Spec JobSpec 73 74 // Current status of a job. 75 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status 76 // +optional 77 Status JobStatus 78 } 79 80 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object 81 82 // JobList is a collection of jobs. 83 type JobList struct { 84 metav1.TypeMeta 85 // Standard list metadata. 86 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata 87 // +optional 88 metav1.ListMeta 89 90 // items is the list of Jobs. 91 Items []Job 92 } 93 94 // JobTemplateSpec describes the data a Job should have when created from a template 95 type JobTemplateSpec struct { 96 // Standard object's metadata of the jobs created from this template. 97 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata 98 // +optional 99 metav1.ObjectMeta 100 101 // Specification of the desired behavior of the job. 102 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status 103 // +optional 104 Spec JobSpec 105 } 106 107 // CompletionMode specifies how Pod completions of a Job are tracked. 108 type CompletionMode string 109 110 const ( 111 // NonIndexedCompletion is a Job completion mode. In this mode, the Job is 112 // considered complete when there have been .spec.completions 113 // successfully completed Pods. Pod completions are homologous to each other. 114 NonIndexedCompletion CompletionMode = "NonIndexed" 115 116 // IndexedCompletion is a Job completion mode. In this mode, the Pods of a 117 // Job get an associated completion index from 0 to (.spec.completions - 1). 118 // The Job is considered complete when a Pod completes for each completion 119 // index. 120 IndexedCompletion CompletionMode = "Indexed" 121 ) 122 123 // PodFailurePolicyAction specifies how a Pod failure is handled. 124 // +enum 125 type PodFailurePolicyAction string 126 127 const ( 128 // This is an action which might be taken on a pod failure - mark the 129 // pod's job as Failed and terminate all running pods. 130 PodFailurePolicyActionFailJob PodFailurePolicyAction = "FailJob" 131 132 // This is an action which might be taken on a pod failure - mark the 133 // Job's index as failed to avoid restarts within this index. This action 134 // can only be used when backoffLimitPerIndex is set. 135 // This value is beta-level. 136 PodFailurePolicyActionFailIndex PodFailurePolicyAction = "FailIndex" 137 138 // This is an action which might be taken on a pod failure - the counter towards 139 // .backoffLimit, represented by the job's .status.failed field, is not 140 // incremented and a replacement pod is created. 141 PodFailurePolicyActionIgnore PodFailurePolicyAction = "Ignore" 142 143 // This is an action which might be taken on a pod failure - the pod failure 144 // is handled in the default way - the counter towards .backoffLimit, 145 // represented by the job's .status.failed field, is incremented. 146 PodFailurePolicyActionCount PodFailurePolicyAction = "Count" 147 ) 148 149 // +enum 150 type PodFailurePolicyOnExitCodesOperator string 151 152 const ( 153 PodFailurePolicyOnExitCodesOpIn PodFailurePolicyOnExitCodesOperator = "In" 154 PodFailurePolicyOnExitCodesOpNotIn PodFailurePolicyOnExitCodesOperator = "NotIn" 155 ) 156 157 // PodReplacementPolicy specifies the policy for creating pod replacements. 158 // +enum 159 type PodReplacementPolicy string 160 161 const ( 162 // TerminatingOrFailed means that we recreate pods 163 // when they are terminating (has a metadata.deletionTimestamp) or failed. 164 TerminatingOrFailed PodReplacementPolicy = "TerminatingOrFailed" 165 //Failed means to wait until a previously created Pod is fully terminated (has phase 166 //Failed or Succeeded) before creating a replacement Pod. 167 Failed PodReplacementPolicy = "Failed" 168 ) 169 170 // PodFailurePolicyOnExitCodesRequirement describes the requirement for handling 171 // a failed pod based on its container exit codes. In particular, it lookups the 172 // .state.terminated.exitCode for each app container and init container status, 173 // represented by the .status.containerStatuses and .status.initContainerStatuses 174 // fields in the Pod status, respectively. Containers completed with success 175 // (exit code 0) are excluded from the requirement check. 176 type PodFailurePolicyOnExitCodesRequirement struct { 177 // Restricts the check for exit codes to the container with the 178 // specified name. When null, the rule applies to all containers. 179 // When specified, it should match one the container or initContainer 180 // names in the pod template. 181 // +optional 182 ContainerName *string 183 184 // Represents the relationship between the container exit code(s) and the 185 // specified values. Containers completed with success (exit code 0) are 186 // excluded from the requirement check. Possible values are: 187 // 188 // - In: the requirement is satisfied if at least one container exit code 189 // (might be multiple if there are multiple containers not restricted 190 // by the 'containerName' field) is in the set of specified values. 191 // - NotIn: the requirement is satisfied if at least one container exit code 192 // (might be multiple if there are multiple containers not restricted 193 // by the 'containerName' field) is not in the set of specified values. 194 // Additional values are considered to be added in the future. Clients should 195 // react to an unknown operator by assuming the requirement is not satisfied. 196 Operator PodFailurePolicyOnExitCodesOperator 197 198 // Specifies the set of values. Each returned container exit code (might be 199 // multiple in case of multiple containers) is checked against this set of 200 // values with respect to the operator. The list of values must be ordered 201 // and must not contain duplicates. Value '0' cannot be used for the In operator. 202 // At least one element is required. At most 255 elements are allowed. 203 // +listType=set 204 Values []int32 205 } 206 207 // PodFailurePolicyOnPodConditionsPattern describes a pattern for matching 208 // an actual pod condition type. 209 type PodFailurePolicyOnPodConditionsPattern struct { 210 // Specifies the required Pod condition type. To match a pod condition 211 // it is required that specified type equals the pod condition type. 212 Type api.PodConditionType 213 // Specifies the required Pod condition status. To match a pod condition 214 // it is required that the specified status equals the pod condition status. 215 // Defaults to True. 216 Status api.ConditionStatus 217 } 218 219 // PodFailurePolicyRule describes how a pod failure is handled when the requirements are met. 220 // One of OnExitCodes and onPodConditions, but not both, can be used in each rule. 221 type PodFailurePolicyRule struct { 222 // Specifies the action taken on a pod failure when the requirements are satisfied. 223 // Possible values are: 224 // 225 // - FailJob: indicates that the pod's job is marked as Failed and all 226 // running pods are terminated. 227 // - FailIndex: indicates that the pod's index is marked as Failed and will 228 // not be restarted. 229 // This value is alpha-level. It can be used when the 230 // `JobBackoffLimitPerIndex` feature gate is enabled (disabled by default). 231 // - Ignore: indicates that the counter towards the .backoffLimit is not 232 // incremented and a replacement pod is created. 233 // - Count: indicates that the pod is handled in the default way - the 234 // counter towards the .backoffLimit is incremented. 235 // Additional values are considered to be added in the future. Clients should 236 // react to an unknown action by skipping the rule. 237 Action PodFailurePolicyAction 238 239 // Represents the requirement on the container exit codes. 240 // +optional 241 OnExitCodes *PodFailurePolicyOnExitCodesRequirement 242 243 // Represents the requirement on the pod conditions. The requirement is represented 244 // as a list of pod condition patterns. The requirement is satisfied if at 245 // least one pattern matches an actual pod condition. At most 20 elements are allowed. 246 // +listType=atomic 247 // +optional 248 OnPodConditions []PodFailurePolicyOnPodConditionsPattern 249 } 250 251 // PodFailurePolicy describes how failed pods influence the backoffLimit. 252 type PodFailurePolicy struct { 253 // A list of pod failure policy rules. The rules are evaluated in order. 254 // Once a rule matches a Pod failure, the remaining of the rules are ignored. 255 // When no rule matches the Pod failure, the default handling applies - the 256 // counter of pod failures is incremented and it is checked against 257 // the backoffLimit. At most 20 elements are allowed. 258 // +listType=atomic 259 Rules []PodFailurePolicyRule 260 } 261 262 // SuccessPolicy describes when a Job can be declared as succeeded based on the success of some indexes. 263 type SuccessPolicy struct { 264 // rules represents the list of alternative rules for the declaring the Jobs 265 // as successful before `.status.succeeded >= .spec.completions`. Once any of the rules are met, 266 // the "SucceededCriteriaMet" condition is added, and the lingering pods are removed. 267 // The terminal state for such a Job has the "Complete" condition. 268 // Additionally, these rules are evaluated in order; Once the Job meets one of the rules, 269 // other rules are ignored. At most 20 elements are allowed. 270 // +listType=atomic 271 Rules []SuccessPolicyRule 272 } 273 274 // SuccessPolicyRule describes rule for declaring a Job as succeeded. 275 // Each rule must have at least one of the "succeededIndexes" or "succeededCount" specified. 276 type SuccessPolicyRule struct { 277 // succeededIndexes specifies the set of indexes 278 // which need to be contained in the actual set of the succeeded indexes for the Job. 279 // The list of indexes must be within 0 to ".spec.completions-1" and 280 // must not contain duplicates. At least one element is required. 281 // The indexes are represented as intervals separated by commas. 282 // The intervals can be a decimal integer or a pair of decimal integers separated by a hyphen. 283 // The number are listed in represented by the first and last element of the series, 284 // separated by a hyphen. 285 // For example, if the completed indexes are 1, 3, 4, 5 and 7, they are 286 // represented as "1,3-5,7". 287 // When this field is null, this field doesn't default to any value 288 // and is never evaluated at any time. 289 // 290 // +optional 291 SucceededIndexes *string 292 293 // succeededCount specifies the minimal required size of the actual set of the succeeded indexes 294 // for the Job. When succeededCount is used along with succeededIndexes, the check is 295 // constrained only to the set of indexes specified by succeededIndexes. 296 // For example, given that succeededIndexes is "1-4", succeededCount is "3", 297 // and completed indexes are "1", "3", and "5", the Job isn't declared as succeeded 298 // because only "1" and "3" indexes are considered in that rules. 299 // When this field is null, this doesn't default to any value and 300 // is never evaluated at any time. 301 // When specified it needs to be a positive integer. 302 // 303 // +optional 304 SucceededCount *int32 305 } 306 307 // JobSpec describes how the job execution will look like. 308 type JobSpec struct { 309 310 // Specifies the maximum desired number of pods the job should 311 // run at any given time. The actual number of pods running in steady state will 312 // be less than this number when ((.spec.completions - .status.successful) < .spec.parallelism), 313 // i.e. when the work left to do is less than max parallelism. 314 // +optional 315 Parallelism *int32 316 317 // Specifies the desired number of successfully finished pods the 318 // job should be run with. Setting to null means that the success of any 319 // pod signals the success of all pods, and allows parallelism to have any positive 320 // value. Setting to 1 means that parallelism is limited to 1 and the success of that 321 // pod signals the success of the job. 322 // +optional 323 Completions *int32 324 325 // Specifies the policy of handling failed pods. In particular, it allows to 326 // specify the set of actions and conditions which need to be 327 // satisfied to take the associated action. 328 // If empty, the default behaviour applies - the counter of failed pods, 329 // represented by the jobs's .status.failed field, is incremented and it is 330 // checked against the backoffLimit. This field cannot be used in combination 331 // with .spec.podTemplate.spec.restartPolicy=OnFailure. 332 // 333 // This field is beta-level. It can be used when the `JobPodFailurePolicy` 334 // feature gate is enabled (enabled by default). 335 // +optional 336 PodFailurePolicy *PodFailurePolicy 337 338 // successPolicy specifies the policy when the Job can be declared as succeeded. 339 // If empty, the default behavior applies - the Job is declared as succeeded 340 // only when the number of succeeded pods equals to the completions. 341 // When the field is specified, it must be immutable and works only for the Indexed Jobs. 342 // Once the Job meets the SuccessPolicy, the lingering pods are terminated. 343 // 344 // This field is alpha-level. To use this field, you must enable the 345 // `JobSuccessPolicy` feature gate (disabled by default). 346 // +optional 347 SuccessPolicy *SuccessPolicy 348 349 // Specifies the duration in seconds relative to the startTime that the job 350 // may be continuously active before the system tries to terminate it; value 351 // must be positive integer. If a Job is suspended (at creation or through an 352 // update), this timer will effectively be stopped and reset when the Job is 353 // resumed again. 354 // +optional 355 ActiveDeadlineSeconds *int64 356 357 // Optional number of retries before marking this job failed. 358 // Defaults to 6 359 // +optional 360 BackoffLimit *int32 361 362 // Specifies the limit for the number of retries within an 363 // index before marking this index as failed. When enabled the number of 364 // failures per index is kept in the pod's 365 // batch.kubernetes.io/job-index-failure-count annotation. It can only 366 // be set when Job's completionMode=Indexed, and the Pod's restart 367 // policy is Never. The field is immutable. 368 // This field is beta-level. It can be used when the `JobBackoffLimitPerIndex` 369 // feature gate is enabled (enabled by default). 370 // +optional 371 BackoffLimitPerIndex *int32 372 373 // Specifies the maximal number of failed indexes before marking the Job as 374 // failed, when backoffLimitPerIndex is set. Once the number of failed 375 // indexes exceeds this number the entire Job is marked as Failed and its 376 // execution is terminated. When left as null the job continues execution of 377 // all of its indexes and is marked with the `Complete` Job condition. 378 // It can only be specified when backoffLimitPerIndex is set. 379 // It can be null or up to completions. It is required and must be 380 // less than or equal to 10^4 when is completions greater than 10^5. 381 // This field is beta-level. It can be used when the `JobBackoffLimitPerIndex` 382 // feature gate is enabled (enabled by default). 383 // +optional 384 MaxFailedIndexes *int32 385 386 // TODO enabled it when https://github.com/kubernetes/kubernetes/issues/28486 has been fixed 387 // Optional number of failed pods to retain. 388 // +optional 389 // FailedPodsLimit *int32 390 391 // A label query over pods that should match the pod count. 392 // Normally, the system sets this field for you. 393 // +optional 394 Selector *metav1.LabelSelector 395 396 // manualSelector controls generation of pod labels and pod selectors. 397 // Leave `manualSelector` unset unless you are certain what you are doing. 398 // When false or unset, the system pick labels unique to this job 399 // and appends those labels to the pod template. When true, 400 // the user is responsible for picking unique labels and specifying 401 // the selector. Failure to pick a unique label may cause this 402 // and other jobs to not function correctly. However, You may see 403 // `manualSelector=true` in jobs that were created with the old `extensions/v1beta1` 404 // API. 405 // +optional 406 ManualSelector *bool 407 408 // Describes the pod that will be created when executing a job. 409 // The only allowed template.spec.restartPolicy values are "Never" or "OnFailure". 410 Template api.PodTemplateSpec 411 412 // ttlSecondsAfterFinished limits the lifetime of a Job that has finished 413 // execution (either Complete or Failed). If this field is set, 414 // ttlSecondsAfterFinished after the Job finishes, it is eligible to be 415 // automatically deleted. When the Job is being deleted, its lifecycle 416 // guarantees (e.g. finalizers) will be honored. If this field is unset, 417 // the Job won't be automatically deleted. If this field is set to zero, 418 // the Job becomes eligible to be deleted immediately after it finishes. 419 // +optional 420 TTLSecondsAfterFinished *int32 421 422 // completionMode specifies how Pod completions are tracked. It can be 423 // `NonIndexed` (default) or `Indexed`. 424 // 425 // `NonIndexed` means that the Job is considered complete when there have 426 // been .spec.completions successfully completed Pods. Each Pod completion is 427 // homologous to each other. 428 // 429 // `Indexed` means that the Pods of a 430 // Job get an associated completion index from 0 to (.spec.completions - 1), 431 // available in the annotation batch.kubernetes.io/job-completion-index. 432 // The Job is considered complete when there is one successfully completed Pod 433 // for each index. 434 // When value is `Indexed`, .spec.completions must be specified and 435 // `.spec.parallelism` must be less than or equal to 10^5. 436 // In addition, The Pod name takes the form 437 // `$(job-name)-$(index)-$(random-string)`, 438 // the Pod hostname takes the form `$(job-name)-$(index)`. 439 // 440 // More completion modes can be added in the future. 441 // If the Job controller observes a mode that it doesn't recognize, which 442 // is possible during upgrades due to version skew, the controller 443 // skips updates for the Job. 444 // +optional 445 CompletionMode *CompletionMode 446 447 // suspend specifies whether the Job controller should create Pods or not. If 448 // a Job is created with suspend set to true, no Pods are created by the Job 449 // controller. If a Job is suspended after creation (i.e. the flag goes from 450 // false to true), the Job controller will delete all active Pods associated 451 // with this Job. Users must design their workload to gracefully handle this. 452 // Suspending a Job will reset the StartTime field of the Job, effectively 453 // resetting the ActiveDeadlineSeconds timer too. Defaults to false. 454 // 455 // +optional 456 Suspend *bool 457 458 // podReplacementPolicy specifies when to create replacement Pods. 459 // Possible values are: 460 // - TerminatingOrFailed means that we recreate pods 461 // when they are terminating (has a metadata.deletionTimestamp) or failed. 462 // - Failed means to wait until a previously created Pod is fully terminated (has phase 463 // Failed or Succeeded) before creating a replacement Pod. 464 // 465 // When using podFailurePolicy, Failed is the the only allowed value. 466 // TerminatingOrFailed and Failed are allowed values when podFailurePolicy is not in use. 467 // This is an beta field. To use this, enable the JobPodReplacementPolicy feature toggle. 468 // This is on by default. 469 // +optional 470 PodReplacementPolicy *PodReplacementPolicy 471 472 // ManagedBy field indicates the controller that manages a Job. The k8s Job 473 // controller reconciles jobs which don't have this field at all or the field 474 // value is the reserved string `kubernetes.io/job-controller`, but skips 475 // reconciling Jobs with a custom value for this field. 476 // The value must be a valid domain-prefixed path (e.g. acme.io/foo) - 477 // all characters before the first "/" must be a valid subdomain as defined 478 // by RFC 1123. All characters trailing the first "/" must be valid HTTP Path 479 // characters as defined by RFC 3986. The value cannot exceed 64 characters. 480 // 481 // This field is alpha-level. The job controller accepts setting the field 482 // when the feature gate JobManagedBy is enabled (disabled by default). 483 // +optional 484 ManagedBy *string 485 } 486 487 // JobStatus represents the current state of a Job. 488 type JobStatus struct { 489 490 // The latest available observations of an object's current state. When a Job 491 // fails, one of the conditions will have type "Failed" and status true. When 492 // a Job is suspended, one of the conditions will have type "Suspended" and 493 // status true; when the Job is resumed, the status of this condition will 494 // become false. When a Job is completed, one of the conditions will have 495 // type "Complete" and status true. 496 // 497 // A job is considered finished when it is in a terminal condition, either 498 // "Complete" or "Failed". A Job cannot have both the "Complete" and "Failed" conditions. 499 // Additionally, it cannot be in the "Complete" and "FailureTarget" conditions. 500 // The "Complete", "Failed" and "FailureTarget" conditions cannot be disabled. 501 // 502 // +optional 503 Conditions []JobCondition 504 505 // Represents time when the job controller started processing a job. When a 506 // Job is created in the suspended state, this field is not set until the 507 // first time it is resumed. This field is reset every time a Job is resumed 508 // from suspension. It is represented in RFC3339 form and is in UTC. 509 // 510 // Once set, the field can only be removed when the job is suspended. 511 // The field cannot be modified while the job is unsuspended or finished. 512 // 513 // +optional 514 StartTime *metav1.Time 515 516 // Represents time when the job was completed. It is not guaranteed to 517 // be set in happens-before order across separate operations. 518 // It is represented in RFC3339 form and is in UTC. 519 // The completion time is set when the job finishes successfully, and only then. 520 // The value cannot be updated or removed. The value indicates the same or 521 // later point in time as the startTime field. 522 // +optional 523 CompletionTime *metav1.Time 524 525 // The number of pending and running pods which are not terminating (without 526 // a deletionTimestamp). 527 // The value is zero for finished jobs. 528 // +optional 529 Active int32 530 531 // The number of pods which are terminating (in phase Pending or Running 532 // and have a deletionTimestamp). 533 // 534 // This field is beta-level. The job controller populates the field when 535 // the feature gate JobPodReplacementPolicy is enabled (enabled by default). 536 // +optional 537 Terminating *int32 538 539 // The number of active pods which have a Ready condition. 540 // +optional 541 Ready *int32 542 543 // The number of pods which reached phase Succeeded. 544 // The value increases monotonically for a given spec. However, it may 545 // decrease in reaction to scale down of elastic indexed jobs. 546 // +optional 547 Succeeded int32 548 549 // The number of pods which reached phase Failed. 550 // The value increases monotonically. 551 // +optional 552 Failed int32 553 554 // completedIndexes holds the completed indexes when .spec.completionMode = 555 // "Indexed" in a text format. The indexes are represented as decimal integers 556 // separated by commas. The numbers are listed in increasing order. Three or 557 // more consecutive numbers are compressed and represented by the first and 558 // last element of the series, separated by a hyphen. 559 // For example, if the completed indexes are 1, 3, 4, 5 and 7, they are 560 // represented as "1,3-5,7". 561 // +optional 562 CompletedIndexes string 563 564 // FailedIndexes holds the failed indexes when spec.backoffLimitPerIndex is set. 565 // The indexes are represented in the text format analogous as for the 566 // `completedIndexes` field, ie. they are kept as decimal integers 567 // separated by commas. The numbers are listed in increasing order. Three or 568 // more consecutive numbers are compressed and represented by the first and 569 // last element of the series, separated by a hyphen. 570 // For example, if the failed indexes are 1, 3, 4, 5 and 7, they are 571 // represented as "1,3-5,7". 572 // The set of failed indexes cannot overlap with the set of completed indexes. 573 // 574 // This field is beta-level. It can be used when the `JobBackoffLimitPerIndex` 575 // feature gate is enabled (enabled by default). 576 // +optional 577 FailedIndexes *string 578 579 // uncountedTerminatedPods holds the UIDs of Pods that have terminated but 580 // the job controller hasn't yet accounted for in the status counters. 581 // 582 // The job controller creates pods with a finalizer. When a pod terminates 583 // (succeeded or failed), the controller does three steps to account for it 584 // in the job status: 585 // 586 // 1. Add the pod UID to the corresponding array in this field. 587 // 2. Remove the pod finalizer. 588 // 3. Remove the pod UID from the array while increasing the corresponding 589 // counter. 590 // 591 // Old jobs might not be tracked using this field, in which case the field 592 // remains null. 593 // The structure is empty for finished jobs. 594 // +optional 595 UncountedTerminatedPods *UncountedTerminatedPods 596 } 597 598 // UncountedTerminatedPods holds UIDs of Pods that have terminated but haven't 599 // been accounted in Job status counters. 600 type UncountedTerminatedPods struct { 601 // succeeded holds UIDs of succeeded Pods. 602 // +listType=set 603 // +optional 604 Succeeded []types.UID 605 606 // failed holds UIDs of failed Pods. 607 // +listType=set 608 // +optional 609 Failed []types.UID 610 } 611 612 // JobConditionType is a valid value for JobCondition.Type 613 type JobConditionType string 614 615 // These are valid conditions of a job. 616 const ( 617 // JobSuspended means the job has been suspended. 618 JobSuspended JobConditionType = "Suspended" 619 // JobComplete means the job has completed its execution. 620 JobComplete JobConditionType = "Complete" 621 // JobFailed means the job has failed its execution. 622 JobFailed JobConditionType = "Failed" 623 // FailureTarget means the job is about to fail its execution. 624 JobFailureTarget JobConditionType = "FailureTarget" 625 // JobSuccessCriteriaMet means the Job has reached a success state and will be marked as Completed 626 JobSuccessCriteriaMet JobConditionType = "SuccessCriteriaMet" 627 ) 628 629 // JobCondition describes current state of a job. 630 type JobCondition struct { 631 // Type of job condition. 632 Type JobConditionType 633 // Status of the condition, one of True, False, Unknown. 634 Status api.ConditionStatus 635 // Last time the condition was checked. 636 // +optional 637 LastProbeTime metav1.Time 638 // Last time the condition transit from one status to another. 639 // +optional 640 LastTransitionTime metav1.Time 641 // (brief) reason for the condition's last transition. 642 // +optional 643 Reason string 644 // Human readable message indicating details about last transition. 645 // +optional 646 Message string 647 } 648 649 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object 650 651 // CronJob represents the configuration of a single cron job. 652 type CronJob struct { 653 metav1.TypeMeta 654 // Standard object's metadata. 655 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata 656 // +optional 657 metav1.ObjectMeta 658 659 // Specification of the desired behavior of a cron job, including the schedule. 660 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status 661 // +optional 662 Spec CronJobSpec 663 664 // Current status of a cron job. 665 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status 666 // +optional 667 Status CronJobStatus 668 } 669 670 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object 671 672 // CronJobList is a collection of cron jobs. 673 type CronJobList struct { 674 metav1.TypeMeta 675 // Standard list metadata. 676 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata 677 // +optional 678 metav1.ListMeta 679 680 // items is the list of CronJobs. 681 Items []CronJob 682 } 683 684 // CronJobSpec describes how the job execution will look like and when it will actually run. 685 type CronJobSpec struct { 686 687 // The schedule in Cron format, see https://en.wikipedia.org/wiki/Cron. 688 Schedule string 689 690 // The time zone name for the given schedule, see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones. 691 // If not specified, this will default to the time zone of the kube-controller-manager process. 692 // The set of valid time zone names and the time zone offset is loaded from the system-wide time zone 693 // database by the API server during CronJob validation and the controller manager during execution. 694 // If no system-wide time zone database can be found a bundled version of the database is used instead. 695 // If the time zone name becomes invalid during the lifetime of a CronJob or due to a change in host 696 // configuration, the controller will stop creating new new Jobs and will create a system event with the 697 // reason UnknownTimeZone. 698 // More information can be found in https://kubernetes.io/docs/concepts/workloads/controllers/cron-jobs/#time-zones 699 // +optional 700 TimeZone *string 701 702 // Optional deadline in seconds for starting the job if it misses scheduled 703 // time for any reason. Missed jobs executions will be counted as failed ones. 704 // +optional 705 StartingDeadlineSeconds *int64 706 707 // Specifies how to treat concurrent executions of a Job. 708 // Valid values are: 709 // 710 // - "Allow" (default): allows CronJobs to run concurrently; 711 // - "Forbid": forbids concurrent runs, skipping next run if previous run hasn't finished yet; 712 // - "Replace": cancels currently running job and replaces it with a new one 713 // +optional 714 ConcurrencyPolicy ConcurrencyPolicy 715 716 // This flag tells the controller to suspend subsequent executions, it does 717 // not apply to already started executions. Defaults to false. 718 // +optional 719 Suspend *bool 720 721 // Specifies the job that will be created when executing a CronJob. 722 JobTemplate JobTemplateSpec 723 724 // The number of successful finished jobs to retain. 725 // This is a pointer to distinguish between explicit zero and not specified. 726 // +optional 727 SuccessfulJobsHistoryLimit *int32 728 729 // The number of failed finished jobs to retain. 730 // This is a pointer to distinguish between explicit zero and not specified. 731 // +optional 732 FailedJobsHistoryLimit *int32 733 } 734 735 // ConcurrencyPolicy describes how the job will be handled. 736 // Only one of the following concurrent policies may be specified. 737 // If none of the following policies is specified, the default one 738 // is AllowConcurrent. 739 type ConcurrencyPolicy string 740 741 const ( 742 // AllowConcurrent allows CronJobs to run concurrently. 743 AllowConcurrent ConcurrencyPolicy = "Allow" 744 745 // ForbidConcurrent forbids concurrent runs, skipping next run if previous 746 // hasn't finished yet. 747 ForbidConcurrent ConcurrencyPolicy = "Forbid" 748 749 // ReplaceConcurrent cancels currently running job and replaces it with a new one. 750 ReplaceConcurrent ConcurrencyPolicy = "Replace" 751 ) 752 753 // CronJobStatus represents the current state of a cron job. 754 type CronJobStatus struct { 755 // A list of pointers to currently running jobs. 756 // +optional 757 Active []api.ObjectReference 758 759 // Information when was the last time the job was successfully scheduled. 760 // +optional 761 LastScheduleTime *metav1.Time 762 763 // Information when was the last time the job successfully completed. 764 // +optional 765 LastSuccessfulTime *metav1.Time 766 } 767