Job

Job 表示单个任务的配置。

apiVersion: batch/v1

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

Job

Job 表示单个任务的配置。

  • apiVersion: batch/v1

  • kind: Job

JobSpec

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

Replicas

Lifecycle

  • 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 状况类型匹配的模式。

          - **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 描述了将任务声明为成功的规则。每条规则必须至少指定 succeededIndexes 或 succeededCount 之一。

  • successPolicy.rules.succeededCount (int32)

    succeededCount 指定任务成功索引集所需的最小规模。当 succeededCount 与 succeededIndexes 一起使用时， 仅检查由 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 的集合。

  • apiVersion: batch/v1

  • kind: JobList

操作

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

参数

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

    namespace

  • limit (查询参数): integer

    limit

  • pretty (查询参数): string

    pretty

响应

200 (JobList): OK

401: Unauthorized

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

HTTP 请求

GET /apis/batch/v1/jobs

参数

  • limit (查询参数): integer

    limit

  • pretty (查询参数): string

    pretty

响应

200 (JobList): OK

401: Unauthorized

create 创建一个 Job

HTTP 请求

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

参数

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

    namespace

  • body: Job, 必需

响应

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, 必需

响应

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, 必需

响应

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, 必需

  • 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, 必需

  • pretty (查询参数): string

    pretty

响应

200 (Job): OK

201 (Job): Created

401: Unauthorized

delete 删除一个 Job

HTTP 请求

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

参数

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

    Job 的名称。

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

    namespace

  • body: DeleteOptions

响应

200 (Status): OK

202 (Status): Accepted

401: Unauthorized

deletecollection 删除 Job 的集合

HTTP 请求

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

参数

  • continue (查询参数): string

    continue

  • dryRun (查询参数): string

    dryRun

响应

200 (Status): OK

401: Unauthorized

最后修改 September 16, 2024 at 4:26 PM PST: [zh-cn] sync job-v1.md (eded315618)