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