Job

staging/src/k8s.io/api/batch/v1/types.go

kubectl create job pi \
	--image=registry.cn-hangzhou.aliyuncs.com/kube-image-repo/busybox:1.35.0 \
	--dry-run=client \
	-o yaml \
	-- /bin/sh -c "echo helllo; sleep 5; echo world"

apiVersion: batch/v1
kind: Job
metadata:
  creationTimestamp: null
  name: pi
spec:
  template:
    metadata:
      creationTimestamp: null
    spec:
      containers:
      - command:
        - /bin/sh
        - -c
        - echo helllo; sleep 5; echo world
        image: registry.cn-hangzhou.aliyuncs.com/kube-image-repo/busybox:1.35.0
        name: pi
        resources: {}
      restartPolicy: Never
status: {}

// Job represents the configuration of a single job.
type Job struct {
    metav1.TypeMeta `json:",inline"`
    // Standard object's metadata.
    // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata
    // +optional
    metav1.ObjectMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"`

    // Specification of the desired behavior of a job.
    // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status
    // +optional
    Spec JobSpec `json:"spec,omitempty" protobuf:"bytes,2,opt,name=spec"`

    // Current status of a job.
    // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status
    // +optional
    Status JobStatus `json:"status,omitempty" protobuf:"bytes,3,opt,name=status"`
}

// JobSpec describes how the job execution will look like.
type JobSpec struct {

    // Specifies the maximum desired number of pods the job should
    // run at any given time. The actual number of pods running in steady state will
    // be less than this number when ((.spec.completions - .status.successful) < .spec.parallelism),
    // i.e. when the work left to do is less than max parallelism.
    // More info: https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/
    // +optional
    Parallelism *int32 `json:"parallelism,omitempty" protobuf:"varint,1,opt,name=parallelism"`

    // Specifies the desired number of successfully finished pods the
    // job should be run with.  Setting to nil means that the success of any
    // pod signals the success of all pods, and allows parallelism to have any positive
    // value.  Setting to 1 means that parallelism is limited to 1 and the success of that
    // pod signals the success of the job.
    // More info: https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/
    // +optional
    Completions *int32 `json:"completions,omitempty" protobuf:"varint,2,opt,name=completions"`

    // Specifies the duration in seconds relative to the startTime that the job
    // may be continuously active before the system tries to terminate it; value
    // must be positive integer. If a Job is suspended (at creation or through an
    // update), this timer will effectively be stopped and reset when the Job is
    // resumed again.
    // +optional
    ActiveDeadlineSeconds *int64 `json:"activeDeadlineSeconds,omitempty" protobuf:"varint,3,opt,name=activeDeadlineSeconds"`

    // Specifies the number of retries before marking this job failed.
    // Defaults to 6
    // +optional
    BackoffLimit *int32 `json:"backoffLimit,omitempty" protobuf:"varint,7,opt,name=backoffLimit"`

    // TODO enabled it when https://github.com/kubernetes/kubernetes/issues/28486 has been fixed
    // Optional number of failed pods to retain.
    // +optional
    // FailedPodsLimit *int32 `json:"failedPodsLimit,omitempty" protobuf:"varint,9,opt,name=failedPodsLimit"`

    // A label query over pods that should match the pod count.
    // Normally, the system sets this field for you.
    // More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors
    // +optional
    Selector *metav1.LabelSelector `json:"selector,omitempty" protobuf:"bytes,4,opt,name=selector"`

    // manualSelector controls generation of pod labels and pod selectors.
    // Leave `manualSelector` unset unless you are certain what you are doing.
    // When false or unset, the system pick labels unique to this job
    // and appends those labels to the pod template.  When true,
    // the user is responsible for picking unique labels and specifying
    // the selector.  Failure to pick a unique label may cause this
    // and other jobs to not function correctly.  However, You may see
    // `manualSelector=true` in jobs that were created with the old `extensions/v1beta1`
    // API.
    // More info: https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/#specifying-your-own-pod-selector
    // +optional
    ManualSelector *bool `json:"manualSelector,omitempty" protobuf:"varint,5,opt,name=manualSelector"`

    // Describes the pod that will be created when executing a job.
    // More info: https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/
    Template v1.PodTemplateSpec `json:"template" protobuf:"bytes,6,opt,name=template"`

    // ttlSecondsAfterFinished limits the lifetime of a Job that has finished
    // execution (either Complete or Failed). If this field is set,
    // ttlSecondsAfterFinished after the Job finishes, it is eligible to be
    // automatically deleted. When the Job is being deleted, its lifecycle
    // guarantees (e.g. finalizers) will be honored. If this field is unset,
    // the Job won't be automatically deleted. If this field is set to zero,
    // the Job becomes eligible to be deleted immediately after it finishes.
    // This field is alpha-level and is only honored by servers that enable the
    // TTLAfterFinished feature.
    // +optional
    TTLSecondsAfterFinished *int32 `json:"ttlSecondsAfterFinished,omitempty" protobuf:"varint,8,opt,name=ttlSecondsAfterFinished"`

    // CompletionMode specifies how Pod completions are tracked. It can be
    // `NonIndexed` (default) or `Indexed`.
    //
    // `NonIndexed` means that the Job is considered complete when there have
    // been .spec.completions successfully completed Pods. Each Pod completion is
    // homologous to each other.
    //
    // `Indexed` means that the Pods of a
    // Job get an associated completion index from 0 to (.spec.completions - 1),
    // available in the annotation batch.kubernetes.io/job-completion-index.
    // The Job is considered complete when there is one successfully completed Pod
    // for each index.
    // When value is `Indexed`, .spec.completions must be specified and
    // `.spec.parallelism` must be less than or equal to 10^5.
    // In addition, The Pod name takes the form
    // `$(job-name)-$(index)-$(random-string)`,
    // the Pod hostname takes the form `$(job-name)-$(index)`.
    //
    // This field is beta-level. More completion modes can be added in the future.
    // If the Job controller observes a mode that it doesn't recognize, the
    // controller skips updates for the Job.
    // +optional
    CompletionMode *CompletionMode `json:"completionMode,omitempty" protobuf:"bytes,9,opt,name=completionMode,casttype=CompletionMode"`

    // Suspend specifies whether the Job controller should create Pods or not. If
    // a Job is created with suspend set to true, no Pods are created by the Job
    // controller. If a Job is suspended after creation (i.e. the flag goes from
    // false to true), the Job controller will delete all active Pods associated
    // with this Job. Users must design their workload to gracefully handle this.
    // Suspending a Job will reset the StartTime field of the Job, effectively
    // resetting the ActiveDeadlineSeconds timer too. Defaults to false.
    //
    // This field is beta-level, gated by SuspendJob feature flag (enabled by
    // default).
    //
    // +optional
    Suspend *bool `json:"suspend,omitempty" protobuf:"varint,10,opt,name=suspend"`
}

// CompletionMode specifies how Pod completions of a Job are tracked.
type CompletionMode string

const (
    // NonIndexedCompletion is a Job completion mode. In this mode, the Job is
    // considered complete when there have been .spec.completions
    // successfully completed Pods. Pod completions are homologous to each other.
    NonIndexedCompletion CompletionMode = "NonIndexed"

    // IndexedCompletion is a Job completion mode. In this mode, the Pods of a
    // Job get an associated completion index from 0 to (.spec.completions - 1).
    // The Job is  considered complete when a Pod completes for each completion
    // index.
    IndexedCompletion CompletionMode = "Indexed"
)

// JobStatus represents the current state of a Job.
type JobStatus struct {
    // The latest available observations of an object's current state. When a Job
    // fails, one of the conditions will have type "Failed" and status true. When
    // a Job is suspended, one of the conditions will have type "Suspended" and
    // status true; when the Job is resumed, the status of this condition will
    // become false. When a Job is completed, one of the conditions will have
    // type "Complete" and status true.
    // More info: https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/
    // +optional
    // +patchMergeKey=type
    // +patchStrategy=merge
    // +listType=atomic
    Conditions []JobCondition `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type" protobuf:"bytes,1,rep,name=conditions"`

    // Represents time when the job controller started processing a job. When a
    // Job is created in the suspended state, this field is not set until the
    // first time it is resumed. This field is reset every time a Job is resumed
    // from suspension. It is represented in RFC3339 form and is in UTC.
    // +optional
    StartTime *metav1.Time `json:"startTime,omitempty" protobuf:"bytes,2,opt,name=startTime"`

    // Represents time when the job was completed. It is not guaranteed to
    // be set in happens-before order across separate operations.
    // It is represented in RFC3339 form and is in UTC.
    // The completion time is only set when the job finishes successfully.
    // +optional
    CompletionTime *metav1.Time `json:"completionTime,omitempty" protobuf:"bytes,3,opt,name=completionTime"`

    // The number of actively running pods.
    // +optional
    Active int32 `json:"active,omitempty" protobuf:"varint,4,opt,name=active"`

    // The number of pods which reached phase Succeeded.
    // +optional
    Succeeded int32 `json:"succeeded,omitempty" protobuf:"varint,5,opt,name=succeeded"`

    // The number of pods which reached phase Failed.
    // +optional
    Failed int32 `json:"failed,omitempty" protobuf:"varint,6,opt,name=failed"`

    // CompletedIndexes holds the completed indexes when .spec.completionMode =
    // "Indexed" in a text format. The indexes are represented as decimal integers
    // separated by commas. The numbers are listed in increasing order. Three or
    // more consecutive numbers are compressed and represented by the first and
    // last element of the series, separated by a hyphen.
    // For example, if the completed indexes are 1, 3, 4, 5 and 7, they are
    // represented as "1,3-5,7".
    // +optional
    CompletedIndexes string `json:"completedIndexes,omitempty" protobuf:"bytes,7,opt,name=completedIndexes"`

    // UncountedTerminatedPods holds the UIDs of Pods that have terminated but
    // the job controller hasn't yet accounted for in the status counters.
    //
    // The job controller creates pods with a finalizer. When a pod terminates
    // (succeeded or failed), the controller does three steps to account for it
    // in the job status:
    // (1) Add the pod UID to the arrays in this field.
    // (2) Remove the pod finalizer.
    // (3) Remove the pod UID from the arrays while increasing the corresponding
    //     counter.
    //
    // This field is alpha-level. The job controller only makes use of this field
    // when the feature gate PodTrackingWithFinalizers is enabled.
    // Old jobs might not be tracked using this field, in which case the field
    // remains null.
    // +optional
    UncountedTerminatedPods *UncountedTerminatedPods `json:"uncountedTerminatedPods,omitempty" protobuf:"bytes,8,opt,name=uncountedTerminatedPods"`
}

type JobConditionType string

// These are valid conditions of a job.
const (
    // JobSuspended means the job has been suspended.
    JobSuspended JobConditionType = "Suspended"
    // JobComplete means the job has completed its execution.
    JobComplete JobConditionType = "Complete"
    // JobFailed means the job has failed its execution.
    JobFailed JobConditionType = "Failed"
)

// JobCondition describes current state of a job.
type JobCondition struct {
    // Type of job condition, Complete or Failed.
    Type JobConditionType `json:"type" protobuf:"bytes,1,opt,name=type,casttype=JobConditionType"`
    // Status of the condition, one of True, False, Unknown.
    Status v1.ConditionStatus `json:"status" protobuf:"bytes,2,opt,name=status,casttype=k8s.io/api/core/v1.ConditionStatus"`
    // Last time the condition was checked.
    // +optional
    LastProbeTime metav1.Time `json:"lastProbeTime,omitempty" protobuf:"bytes,3,opt,name=lastProbeTime"`
    // Last time the condition transit from one status to another.
    // +optional
    LastTransitionTime metav1.Time `json:"lastTransitionTime,omitempty" protobuf:"bytes,4,opt,name=lastTransitionTime"`
    // (brief) reason for the condition's last transition.
    // +optional
    Reason string `json:"reason,omitempty" protobuf:"bytes,5,opt,name=reason"`
    // Human readable message indicating details about last transition.
    // +optional
    Message string `json:"message,omitempty" protobuf:"bytes,6,opt,name=message"`
}

// UncountedTerminatedPods holds UIDs of Pods that have terminated but haven't
// been accounted in Job status counters.
type UncountedTerminatedPods struct {
    // Succeeded holds UIDs of succeeded Pods.
    // +listType=set
    // +optional
    Succeeded []types.UID `json:"succeeded,omitempty" protobuf:"bytes,1,rep,name=succeeded,casttype=k8s.io/apimachinery/pkg/types.UID"`

    // Failed holds UIDs of failed Pods.
    // +listType=set
    // +optional
    Failed []types.UID `json:"failed,omitempty" protobuf:"bytes,2,rep,name=failed,casttype=k8s.io/apimachinery/pkg/types.UID"`
}