Job

Job 表示单个任务的配置。

apiVersion: batch/v1

import "k8s.io/api/batch/v1"

Job

Job 表示单个任务的配置。


JobSpec

JobSpec 描述了任务执行的情况。


Replicas

Lifecycle

  • completions (int32)

    指定任务应该运行并预期成功完成的 Pod 个数。设置为空意味着任何 Pod 的成功都标识着所有 Pod 的成功, 并允许 parallelism 设置为任何正值。设置为 1 意味着并行性被限制为 1,并且该 Pod 的成功标志着任务的成功。更多信息: https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/

  • completionMode (string)

    completionMode 指定如何跟踪 Pod 完成情况。它可以是 NonIndexed(默认)或者 Indexed

    NonIndexed 表示当有 .spec.completions 个成功完成的 Pod 时,认为 Job 完成。每个 Pod 完成都是彼此同源的。

    Indexed 意味着 Job 的各个 Pod 会获得对应的完成索引值,从 0 到(.spec.completions - 1),可在注解 “batch.kubernetes.io/job-completion-index” 中找到。当每个索引都对应有一个成功完成的 Pod 时, 该任务被认为是完成的。 当值为 Indexed 时,必须指定 .spec.completions 并且 .spec.parallelism 必须小于或等于 10^5。 此外,Pod 名称采用 $(job-name)-$(index)-$(random-string) 的形式,Pod 主机名采用 $(job-name)-$(index) 的形式。

    将来可能添加更多的完成模式。如果 Job 控制器发现它无法识别的模式 (这种情况在升级期间由于版本偏差可能发生),则控制器会跳过 Job 的更新。

  • backoffLimit (int32)

    指定标记此任务失败之前的重试次数。默认值为 6。

  • activeDeadlineSeconds (int64)

    系统尝试终止任务之前任务可以持续活跃的持续时间(秒),时间长度是相对于 startTime 的; 字段值必须为正整数。如果任务被挂起(在创建期间或因更新而挂起), 则当任务再次恢复时,此计时器会被停止并重置。

  • ttlSecondsAfterFinished (int32)

    ttlSecondsAfterFinished 限制已完成执行(完成或失败)的任务的生命周期。如果设置了这个字段, 在 Job 完成 ttlSecondsAfterFinished 秒之后,就可以被自动删除。 当 Job 被删除时,它的生命周期保证(例如终结器)会被考察。 如果未设置此字段,则任务不会被自动删除。如果此字段设置为零,则任务在完成后即可立即删除。

  • suspend (boolean)

    suspend 指定 Job 控制器是否应该创建 Pod。如果创建 Job 时将 suspend 设置为 true,则 Job 控制器不会创建任何 Pod。 如果 Job 在创建后被挂起(即标志从 false 变为 true),则 Job 控制器将删除与该 Job 关联的所有活动 Pod。 用户必须设计他们的工作负载来优雅地处理这个问题。暂停 Job 将重置 Job 的 startTime 字段, 也会重置 ActiveDeadlineSeconds 计时器。默认为 false。

Selector

Beta 级别

  • podFailurePolicy (PodFailurePolicy)

    指定处理失效 Pod 的策略。特别是,它允许指定采取关联操作需要满足的一组操作和状况。 如果为空,则应用默认行为:由该任务的 .status.failed 字段表示的失效 Pod 的计数器将递增, 并针对 backoffLimit 进行检查。此字段不能与 restartPolicy=OnFailure 结合使用。

    PodFailurePolicy 描述失效的 Pod 如何影响 backoffLimit。

    • podFailurePolicy.rules ([]PodFailurePolicyRule),必需

      原子: 将在合并期间被替换

      Pod 失效策略规则的列表。这些规则按顺序进行评估。一旦某规则匹配 Pod 失效,则其余规将被忽略。 当没有规则匹配 Pod 失效时,将应用默认的处理方式: Pod 失效的计数器递增并针对 backoffLimit 进行检查。最多允许 20 个。

      PodFailurePolicyRule 描述当满足要求时如何处理一个 Pod 失效。 在每个规则中可以使用 onExitCodes 和 onPodConditions 之一,但不能同时使用二者。

      • podFailurePolicy.rules.action (string),必需

        指定当要求满足时对 Pod 失效采取的操作。可能的值是:

        • FailJob:表示 Pod 的任务被标记为 Failed 且所有正在运行的 Pod 都被终止。
        • FailIndex:表示 Pod 对应的索引被标记为 Failed 且 Pod 不会被重新启动。 此值是 Beta 级别的。当 JobBackoffLimitPerIndex 特性门控被启用时(默认被启用),可以使用此值。

        • Ignore:表示 .backoffLimit 的计数器没有递增,并创建了一个替代 Pod。

        • Count:表示以默认方式处理该 Pod,计数器朝着 .backoffLimit 的方向递增。

        后续会考虑增加其他值。客户端应通过跳过此规则对未知的操作做出反应。

        • podFailurePolicy.rules.onPodConditions.status (string),必需

          指定必需的 Pod 状况状态。要匹配一个 Pod 状况,指定的状态必须等于该 Pod 状况状态。默认为 True。

        • podFailurePolicy.rules.onPodConditions.type (string),必需

          指定必需的 Pod 状况类型。要匹配一个 Pod 状况,指定的类型必须等于该 Pod 状况类型。

      • podFailurePolicy.rules.onExitCodes (PodFailurePolicyOnExitCodesRequirement)

        表示容器退出码有关的要求。

        PodFailurePolicyOnExitCodesRequirement 描述根据容器退出码处理失效 Pod 的要求。 特别是,它为每个应用容器和 Init 容器状态查找在 Pod 状态中分别用 .status.containerStatuses 和 .status.initContainerStatuses 字段表示的 .state.terminated.exitCode。 成功完成的容器(退出码 0)被排除在此要求检查之外。

        • podFailurePolicy.rules.onExitCodes.operator (string),必需

          表示容器退出码和指定值之间的关系。成功完成的容器(退出码 0)被排除在此要求检查之外。可能的值为:

          • In:如果至少一个容器退出码(如果有多个容器不受 ‘containerName’ 字段限制,则可能是多个退出码) 在一组指定值中,则满足要求。

          • NotIn:如果至少一个容器退出码(如果有多个容器不受 ‘containerName’ 字段限制,则可能是多个退出码) 不在一组指定值中,则满足要求。

          后续会考虑增加其他值。客户端应通过假设不满足要求来对未知操作符做出反应。

        • podFailurePolicy.rules.onExitCodes.values ([]int32),必需

          集合:合并期间保留唯一值

          指定值集。每个返回的容器退出码(在多个容器的情况下可能是多个)将根据该操作符有关的这个值集进行检查。 值的列表必须有序且不得包含重复项。值 ‘0’ 不能用于 In 操作符。至少需要 1 个。最多允许 255 个。

        • podFailurePolicy.rules.onExitCodes.containerName (string)

          将退出码的检查限制为具有指定名称的容器。当为 null 时,该规则适用于所有容器。 当被指定时,它应与 Pod 模板中的容器名称或 initContainer 名称之一匹配。

      • podFailurePolicy.rules.onPodConditions ([]PodFailurePolicyOnPodConditionsPattern),必需

        原子: 将在合并期间被替换

        表示对 Pod 状况的要求。该要求表示为 Pod 状况模式的一个列表。 如果至少一个模式与实际的 Pod 状况匹配,则满足此要求。最多允许 20 个。

        PodFailurePolicyOnPodConditionsPattern 描述与实际 Pod 状况类型匹配的模式。

        1. - **podFailurePolicy.rules.onPodConditions.status** (string),必需

        指定必需的 Pod 状况状态。要匹配一个 Pod 状况,指定的状态必须等于该 Pod 状况状态。默认为 True。

        • podFailurePolicy.rules.onPodConditions.type (string),必需

          指定必需的 Pod 状况类型。要匹配一个 Pod 状况,指定的类型必须等于该 Pod 状况类型。

  • successPolicy (SuccessPolicy)

successPolicy 指定策略,用于判定何时可以声明任务为成功。如果为空,则应用默认行为 —— 仅当成功 Pod 的数量等于完成数量时,任务才会被声明为成功。指定了该字段时,该字段必须是不可变的, 并且仅适用于带索引的任务。一旦任务满足 successPolicy,滞留 Pod 就会被终止。

此字段为 Beta 级。要使用此字段,你必须启用 JobSuccessPolicy 特性门控(默认启用)。

successPolicy 描述何时可以根据某些索引的成功将任务声明为成功。

successPolicy.rules ([]SuccessPolicyRule),必需

原子性:合并期间会被替换

rules 表示在 .status.succeeded >= .spec.completions 之前将任务声明为成功的备选规则列表。 一旦满足任何规则,就会添加 SucceededCriteriaMet 状况,并删除滞留的 Pod。 此类 Pod 的最终状态具有 Complete 状况。此外,这些规则按顺序进行评估; 一旦任务满足其中一条规则,其他规则将被忽略。最多允许 20 个元素。

SuccessPolicyRule 描述了将任务声明为成功的规则。每条规则必须至少指定 succeededIndexessucceededCount 之一。

  • successPolicy.rules.succeededCount (int32)

    succeededCount 指定任务成功索引集所需的最小规模。当 succeededCountsucceededIndexes 一起使用时, 仅检查由 succeededIndexes 指定的索引集合。例如,假定 succeededIndexes 是 “1-4”,succeededCount 是 “3”,而完成的索引是 “1”、”3” 和 “5”,那么该任务不会被视为成功, 因为在该规则下只考虑了 “1” 和 “3” 索引。当该字段为 null 时,不会被视为具有默认值, 并且在任何时候都不会进行评估。当该字段被设置时,所设置的值应是一个正整数。

  • successPolicy.rules.succeededIndexes (string)

    succeededIndexes 指定需要包含在实际完成索引集合中的各个索引。索引列表必须在 0 到 .spec.completions-1 之间,并且不能包含重复项。至少需要一个元素。索引表示为用逗号分隔的区间。 区间可以是一个十进制整数或一对由破折号分隔的十进制整数。数字序列用区间的第一个和最后一个元素来表示, 并用破折号分隔。例如,如果完成的索引是 1、3、4、5 和 7,则表示为 “1,3-5,7”。 当该字段为 null 时,该字段不会默认为任何值,并且在任何时候都不会进行评估。

Alpha 级别

  • backoffLimitPerIndex(int32)

    指定在将特定索引的 Pod 标记为失败之前在对该 Pod 重试次数的限制。 启用后,各索引的失败次数将保存在 Pod 的 batch.kubernetes.io/job-index-failure-count 注解中。 仅当 Job 的 completionMode=Indexed 且 Pod 的重启策略为 Never 时才能设置此字段。 此字段是不可变更的。此字段是 Beta 级别的。 当 JobBackoffLimitPerIndex 特性门控被启用时(默认被启用),可以使用此字段。

  • managedBy (string)

    managedBy 字段标明管理任务的控制器。 Kubernetes 的 Job 控制器会协调那些没有这个字段或字段值为保留字符串 kubernetes.io/job-controller 的任务, 但会跳过协调那些为此字段设置了自定义值的任务。字段值必须是一个包含有效域名前缀的路径(例如 acme.io/foo)—— 第一个 / 之前的全部字符必须符合 RFC 1123 定义的有效子域。第一个 / 后面的所有字符必须是 RFC 3986 定义的有效 HTTP 路径字符。 字段值的长度不能超过 63 个字符。此字段是不可变的。

    此字段处于 Beta 阶段。当启用 JobManagedBy 特性门控时(默认情况下禁用),任务控制器接受设置此字段。

  • maxFailedIndexes(int32)

    指定在 backoffLimitPerIndex 被设置时、标记 Job 为失败之前所允许的最大失败索引数。 一旦失败的索引数超过此数值,整个 Job 将被标记为 Failed 并终止执行。 如果不设置此字段(对应为 null),则作业继续执行其所有索引,且 Job 会被标记 Complete 状况。 此字段只能在设置 backoffLimitPerIndex 时指定。此字段值可以是 null 或完成次数之内的值。 当完成次数大于 10^5 时,此字段是必需的且必须小于等于 10^4。 此字段是 Beta 级别的。当 JobBackoffLimitPerIndex 特性门控被启用时(默认启用),可以使用此字段。

  • podReplacementPolicy(string)

    podReplacementPolicy 指定何时创建替代的 Pod。可能的值包括:

    • TerminatingOrFailed:表示当 Pod 处于终止中(具有 metadata.deletionTimestamp)或失败时,重新创建 Pod。
    • Failed:表示在创建替代的 Pod 之前,等待先前创建的 Pod 完全终止(处于 Failed 或 Succeeded 阶段)。

    当使用 podFailurePolicy 时,Failed 是唯一允许值。 当不使用 podFailurePolicy 时,允许使用 TerminatingOrFailed 和 Failed。 这是一个 Beta 级别的字段。要使用此特性,请启用 JobPodReplacementPolicy 特性门控。 此特性默认处于被启用状态。

JobStatus

JobStatus 表示 Job 的当前状态。


  • startTime (Time)

    表示任务控制器开始处理任务的时间。在挂起状态下创建 Job 时,直到第一次恢复时才会设置此字段。 每次从暂停中恢复任务时都会重置此字段。它表示为 RFC3339 格式的 UTC 时间。

    一旦设置,仅当 Job 被挂起时才可移除该字段。Job 取消挂起或完成时,无法修改该字段。

    Time 是 time.Time 的包装器,支持正确编码为 YAML 和 JSON。time 包提供的许多工厂方法都提供了包装器。

  • completionTime (Time)

    表示 Job 完成的时间。不能保证对多个独立操作按发生的先后顺序设置。此字段表示为 RFC3339 格式的 UTC 时间。 完成时间在且仅在 Job 成功完成时设置。该值无法更新或删除。该值表示与 startTime 字段相同或更晚的时间点。

    Time 是 time.Time 的包装器,支持正确编码为 YAML 和 JSON。time 包提供的许多工厂方法都提供了包装器。

  • active (int32)

    未处于终止进程中(未设置 deletionTimestamp)的待处理和正在运行的 Pod 数量。对于已完成的 Job,该值为零。

  • failed (int32)

    进入 Failed 阶段的 Pod 数量。该值单调增加。

  • succeeded (int32)

    进入 Succeeded 阶段的 Pod 数量。对于给定的规范,该值会单调增加。 但是,由于弹性索引任务的缩减,该值可能会减少。

  • completedIndexes (string)

    completedIndexes 以文本格式保存 .spec.completionMode 设置为 "Indexed" 的 Pod 已完成的索引。 索引用十进制整数表示,用逗号分隔。数字是按递增的顺序排列的。三个或更多的连续数字被压缩, 用系列的第一个和最后一个元素表示,用连字符分开。例如,如果完成的索引是 1、3、4、5 和 7,则表示为 “1、3-5、7”。

  • conditions ([]JobCondition)

    补丁策略:根据 type 键合并

    原子: 将在合并期间被替换

    对象当前状态的最新可用观察结果。当任务失败时,其中一个状况的类型为 “Failed”,状态为 true。 当任务被暂停时,其中一个状况的类型为 “Suspended”,状态为true;当任务被恢复时,该状况的状态将变为 false。 任务完成时,其中一个状况的类型为 “Complete”,状态为 true。

    当任务处于最终状态(即 “Complete” 或 “Failed”)时,即视为任务已完成。任务不能同时处于 “Complete” 和 “Failed” 状态。 此外,任务也不能处于 “Complete” 和 “FailureTarget” 状态。”Complete”、”Failed” 和 “FailureTarget” 状态不能被禁用。

    更多信息:https://kubernetes.io/zh-cn/docs/concepts/workloads/controllers/jobs-run-to-completion/

    JobCondition 描述任务的当前状况。

    • conditions.status (string), 必需

      状况的状态:True、False、Unknown 之一。

    • conditions.type (string), 必需

      任务状况的类型:Completed 或 Failed。

    • conditions.lastProbeTime (Time)

      最后一次探测的时间。

      Time 是对 time.Time 的封装,支持正确编码为 YAML 和 JSON。我们为 time 包提供的许多工厂方法提供了封装器。

    • conditions.lastTransitionTime (Time)

      上一次从一种状况转换到另一种状况的时间。

      Time 是 time.Time 的包装器,支持正确编码为 YAML 和 JSON。time 包提供的许多工厂方法都提供了包装器。

    • conditions.message (string)

      表示上次转换信息的人类可读消息。

    • conditions.reason (string)

      状况最后一次转换的(简要)原因

  • uncountedTerminatedPods (UncountedTerminatedPods)

    UncountedTerminatedPods 保存已终止但尚未被任务控制器纳入状态计数器中的 Pod 的 UID 的集合。

    任务控制器所创建 Pod 带有终结器。当 Pod 终止(成功或失败)时,控制器将执行三个步骤以在任务状态中对其进行说明:

    1. 将 Pod UID 添加到此字段的列表中。
    2. 去掉 Pod 中的终结器。
    3. 从数组中删除 Pod UID,同时为相应的计数器加一。

    使用此字段可能无法跟踪旧任务,在这种情况下,该字段保持为空。对于已完成的任务,此结构为空。

    UncountedTerminatedPods 持有已经终止的 Pod 的 UID,但还没有被计入工作状态计数器中。

    • uncountedTerminatedPods.failed ([]string)

      集合:合并期间保留唯一值

      failed 字段包含已失败 Pod 的 UID。

    • uncountedTerminatedPods.succeeded ([]string)

      集合:合并期间保留唯一值

      succeeded 包含已成功的 Pod 的 UID。

Beta 级别

  • ready (int32)

    具有 Ready 状况且未处于终止过程中(没有设置 deletionTimestamp)的活动 Pod 的数量。

Alpha 级别

  • failedIndexes (string)

    当设置了 spec.backoffLimitPerIndex 时,failedIndexes 保存失败的索引。 索引以文本格式表示,类似于 completedIndexes 字段,即这些索引是使用逗号分隔的十进制整数。 这些数字按升序列出。三个或更多连续的数字会被压缩,整个序列表示为第一个数字、连字符和最后一个数字。 例如,如果失败的索引是 1、3、4、5 和 7,则表示为 “1,3-5,7”。 失败索引集不能与完成索引集重叠。

    该字段是 Beta 级别的。当 JobBackoffLimitPerIndex 特性门控被启用时(默认被启用),可以使用此字段。

  • terminating(int32)

    正在终止的 Pod 数量(处于 Pending 或 Running 阶段且具有 deletionTimestamp)。

    此字段是 Beta 级别的。当特性门控 JobPodReplacementPolicy 被启用时(默认被启用), Job 控制器会填充该字段。

JobList

JobList 是 Job 的集合。


操作


get 读取指定的 Job

HTTP 请求

GET /apis/batch/v1/namespaces/{namespace}/jobs/{name}

参数

  • name (路径参数):string,必需

    Job 的名称。

  • namespace (路径参数): string, 必需

    namespace

  • pretty (查询参数): string

    pretty

响应

200 (Job): OK

401: Unauthorized

get 读取指定任务的状态

HTTP 请求

GET /apis/batch/v1/namespaces/{namespace}/jobs/{name}/status

参数

  • name (路径参数): string, 必需

    Job 的名称。

  • namespace (路径参数): string, 必需

    namespace

  • pretty (查询参数): string

    pretty

响应

200 (Job): OK

401: Unauthorized

list 列举或监测 Job 类别的对象

HTTP 请求

GET /apis/batch/v1/namespaces/{namespace}/jobs

参数

响应

200 (JobList): OK

401: Unauthorized

list 列举或监测 Job 类别的对象

HTTP 请求

GET /apis/batch/v1/jobs

参数

响应

200 (JobList): OK

401: Unauthorized

create 创建一个 Job

HTTP 请求

POST /apis/batch/v1/namespaces/{namespace}/jobs

参数

响应

200 (Job): OK

201 (Job): Created

202 (Job): Accepted

401: Unauthorized

update 替换指定的 Job

HTTP 请求

PUT /apis/batch/v1/namespaces/{namespace}/jobs/{name}

参数

  • name (路径参数): string, 必需

    Job 的名称。

  • namespace (路径参数): string, 必需

    namespace

  • body: Job, 必需

  • dryRun (查询参数): string

    dryRun

  • fieldManager (查询参数): string

    fieldManager

  • fieldValidation (查询参数): string

    fieldValidation

  • pretty (查询参数): string

    pretty

响应

200 (Job): OK

201 (Job): Created

401: Unauthorized

update 替换指定 Job 的状态

HTTP 请求

PUT /apis/batch/v1/namespaces/{namespace}/jobs/{name}/status

参数

  • name (路径参数): string, 必需

    Job 的名称。

  • namespace (路径参数): string, 必需

    namespace

  • body: Job, 必需

  • dryRun (查询参数): string

    dryRun

  • fieldManager (查询参数): string

    fieldManager

  • fieldValidation (查询参数): string

    fieldValidation

  • pretty (查询参数): string

    pretty

响应

200 (Job): OK

201 (Job): Created

401: Unauthorized

patch 部分更新指定的 Job

HTTP 请求

PATCH /apis/batch/v1/namespaces/{namespace}/jobs/{name}

参数

  • name (路径参数): string, 必需

    Job 的名称。

  • namespace (路径参数): string, 必需

    namespace

  • body: Patch, 必需

  • dryRun (查询参数): string

    dryRun

  • fieldManager (查询参数): string

    fieldManager

  • fieldValidation (查询参数): string

    fieldValidation

  • force (查询参数): boolean

    force

  • pretty (查询参数): string

    pretty

响应

200 (Job): OK

201 (Job): Created

401: Unauthorized

patch 部分更新指定 Job 的状态

HTTP 请求

PATCH /apis/batch/v1/namespaces/{namespace}/jobs/{name}/status

参数

  • name (路径参数): string, 必需

    Job 的名称。

  • namespace (路径参数): string, 必需

    namespace

  • body: Patch, 必需

  • dryRun (查询参数): string

    dryRun

  • fieldManager (查询参数): string

    fieldManager

  • fieldValidation (查询参数): string

    fieldValidation

  • force (查询参数): boolean

    force

  • pretty (查询参数): string

    pretty

响应

200 (Job): OK

201 (Job): Created

401: Unauthorized

delete 删除一个 Job

HTTP 请求

DELETE /apis/batch/v1/namespaces/{namespace}/jobs/{name}

参数

响应

200 (Status): OK

202 (Status): Accepted

401: Unauthorized

deletecollection 删除 Job 的集合

HTTP 请求

DELETE /apis/batch/v1/namespaces/{namespace}/jobs

参数

响应

200 (Status): OK

401: Unauthorized