diff --git a/content/zh-cn/docs/reference/kubernetes-api/workload-resources/job-v1.md b/content/zh-cn/docs/reference/kubernetes-api/workload-resources/job-v1.md new file mode 100644 index 0000000000..e13f9909be --- /dev/null +++ b/content/zh-cn/docs/reference/kubernetes-api/workload-resources/job-v1.md @@ -0,0 +1,1668 @@ +--- +api_metadata: +apiVersion: "batch/v1" +import: "k8s.io/api/batch/v1" +kind: "Job" +content_type: "api_reference" +description: "Job 表示单个作业的配置。" +title: "Job" +weight: 9 +--- + + + +`apiVersion: batch/v1` + +`import "k8s.io/api/batch/v1"` + +## Job {#Job} + + +Job 表示单个作业的配置。 + +
+ +- **apiVersion**: batch/v1 + + +- **kind**: Job + + +- **metadata** (}}">ObjectMeta) + + 标准的对象元数据。更多信息: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata + + +- **spec** (}}">JobSpec) + + 作业的预期行为的规约。更多信息: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status + + +- **status** (}}">JobStatus) + + 作业的当前状态。更多信息: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status + + +## JobSpec {#JobSpec} + + +JobSpec 描述了作业执行的情况。 + +
+ +### Replicas + + + +- **template** (}}">PodTemplateSpec), 必需 + + 描述执行作业时将创建的 Pod。更多信息: https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/ + +- **parallelism** (int32) + + 指定作业应在任何给定时刻预期运行的 Pod 个数上限。 + 当(.spec.completions - .status.successful) \< .spec.parallelism 时, + 即当剩余的工作小于最大并行度时,在稳定状态下运行的 Pod 的实际数量将小于此数量。 + 更多信息: https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/ + +### Lifecycle + + + +- **completions** (int32) + + 指定作业应该运行并预期成功完成的 Pod 个数。设置为 nil 意味着任何 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 + + + +- **selector** (}}">LabelSelector) + + 对应与 Pod 计数匹配的 Pod 的标签查询。通常,系统会为你设置此字段。更多信息: + https://kubernetes.io/zh-cn/docs/concepts/overview/working-with-objects/labels/#label-selectors + +- **manualSelector** (boolean) + + manualSelector 控制 Pod 标签和 Pod 选择器的生成。除非你确定你在做什么,否则不要设置 `manualSelector`。 + 当此字段为 false 或未设置时,系统会选择此 Pod 唯一的标签并将这些标签附加到 Pod 模板。 + 当此字段为 true 时,用户负责选择唯一标签并指定选择器。 + 未能选择唯一标签可能会导致此作业和其他作业无法正常运行。 + 但是,你可能会在使用旧的 `extensions/v1beta1` API 创建的作业中看到 `manualSelector=true`。 + 更多信息: https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/#specifying-your-own-pod-selector + +## JobStatus {#JobStatus} + + + +JobStatus 表示 Job 的当前状态。 + +
+ + +- **startTime** (Time) + + 表示作业控制器开始处理作业的时间。在挂起状态下创建 Job 时,直到第一次恢复时才会设置此字段。 + 每次从暂停中恢复作业时都会重置此字段。它表示为 RFC3339 格式的 UTC 时间。 + + + **Time 是 time.Time 的包装器,支持正确编码为 YAML 和 JSON。time 包提供的许多工厂方法都提供了包装器。** + + +- **completionTime** (Time) + + 表示作业完成的时间。不能保证对多个独立操作按发生的先后顺序设置。此字段表示为 RFC3339 格式的 UTC 时间。 + 仅当作业成功完成时才设置完成时间。 + + **Time 是 time.Time 的包装器,支持正确编码为 YAML 和 JSON。time 包提供的许多工厂方法都提供了包装器。** + + +- **active** (int32) + + 待处理和正在运行的 Pod 的数量。 + +- **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。更多信息: + 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,同时为相应的计数器加一。 + + + 此字段为 Beta 级别。作业控制器仅在启用特性门控 JobTrackingWithFinalizers 时使用此字段(默认启用)。 + 使用此字段可能无法跟踪旧作业,在这种情况下,该字段保持为空。 + + + **UncountedTerminatedPods 持有已经终止的 Pod 的 UID,但还没有被计入工作状态计数器中。** + + + + - **uncountedTerminatedPods.failed** ([]string) + + **Set: 在合并过程中,唯一的值将被保留** + + failed 字段包含已失败 Pod 的 UID。 + + + + - **uncountedTerminatedPods.succeeded** ([]string) + + **Set: 在合并过程中,唯一的值将被保留** + + succeeded 包含已成功的 Pod 的 UID。 + + + + +### Alpha 级别 + + + +- **ready** (int32) + + 状况为 Ready 的 Pod 数量。 + + 此字段为 Beta 级别。当特性门控 JobReadyPods 启用(默认启用)时,作业控制器会填充该字段。 + +## JobList {#JobList} + + +JobList 是 Job 的集合。 + +
+ +- **apiVersion**: batch/v1 + + +- **kind**: JobList + + + +- **metadata** (}}">ListMeta) + + 标准列表元数据。更多信息: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata + + +- **items** ([]}}">Job), required + + items 是 Job 对象的列表。 + + + +## 操作 {#Operations} + +
+ + +### `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 + + + +- **allowWatchBookmarks** (**查询参数**): boolean + + }}">allowWatchBookmarks + + +- **continue** (**查询参数**): string + + }}">continue + + + +- **fieldSelector** (**查询参数**): string + + }}">fieldSelector + + +- **labelSelector** (**查询参数**): string + + }}">labelSelector + + + +- **limit** (**查询参数**): integer + + }}">limit + + +- **pretty** (**查询参数**): string + + }}">pretty + + + +- **resourceVersion** (**查询参数**): string + + }}">resourceVersion + + +- **resourceVersionMatch** (**查询参数**): string + + }}">resourceVersionMatch + + + +- **timeoutSeconds** (**查询参数**): integer + + }}">timeoutSeconds + + +- **watch** (**查询参数**): boolean + + }}">watch + + +#### 响应 + +200 (}}">JobList): OK + +401: Unauthorized + +### `list` 列举或监测 Job 类别的对象 + +#### HTTP 请求 + +GET /apis/batch/v1/jobs + +#### 参数 + + + +- **allowWatchBookmarks** (**查询参数**): boolean + + }}">allowWatchBookmarks + + +- **continue** (**查询参数**): string + + }}">continue + + + +- **fieldSelector** (**查询参数**): string + + }}">fieldSelector + + +- **labelSelector** (**查询参数**): string + + }}">labelSelector + + + +- **limit** (**查询参数**): integer + + }}">limit + + +- **pretty** (**查询参数**): string + + }}">pretty + + + +- **resourceVersion** (**查询参数**): string + + }}">resourceVersion + + +- **resourceVersionMatch** (**查询参数**): string + + }}">resourceVersionMatch + + + +- **timeoutSeconds** (**查询参数**): integer + + }}">timeoutSeconds + + +- **watch** (**查询参数**): boolean + + }}">watch + + +#### 响应 + +200 (}}">JobList): OK + +401: Unauthorized + +### `create` 创建一个 Job + +#### HTTP 请求 + +POST /apis/batch/v1/namespaces/{namespace}/jobs + +#### 参数 + + +- **namespace** (**路径参数**): string, 必需 + + }}">namespace + + +- **body**: }}">Job, 必需 + + + +- **dryRun** (**查询参数**): string + + }}">dryRun + + +- **fieldManager** (**查询参数**): string + + }}">fieldManager + + + +- **fieldValidation** (**查询参数**): string + + }}">fieldValidation + + +- **pretty** (**查询参数**): string + + }}">pretty + + +#### 响应 + + +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} + +#### 参数 + + +- **name** (**路径参数**): string, 必需 + + Job的名称 + + +- **namespace** (**路径参数**): string, 必需 + + }}">namespace + + +- **body**: }}">DeleteOptions + + + +- **dryRun** (**查询参数**): string + + }}">dryRun + + +- **gracePeriodSeconds** (**查询参数**): integer + + }}">gracePeriodSeconds + + + +- **pretty** (**查询参数**): string + + }}">pretty + + +- **propagationPolicy** (**查询参数**): string + + }}">propagationPolicy + + +#### 响应 + +200 (}}">Status): OK + +202 (}}">Status): Accepted + +401: Unauthorized + +### `deletecollection` 删除 Job 的集合 + +#### HTTP 请求 + +DELETE /apis/batch/v1/namespaces/{namespace}/jobs + +#### 参数 + +- **namespace** (**路径参数**): string, 必需 + + }}">namespace + + +- **body**: }}">DeleteOptions + + + +- **continue** (**查询参数**): string + + }}">continue + + +- **dryRun** (**查询参数**): string + + }}">dryRun + + + +- **fieldSelector** (**查询参数**): string + + }}">fieldSelector + + +- **gracePeriodSeconds** (**查询参数**): integer + + }}">gracePeriodSeconds + + + +- **labelSelector** (**查询参数**): string + + }}">labelSelector + + +- **limit** (**查询参数**): integer + + }}">limit + + + +- **pretty** (**查询参数**): string + + }}">pretty + + +- **propagationPolicy** (**查询参数**): string + + }}">propagationPolicy + + + +- **resourceVersion** (**查询参数**): string + + }}">resourceVersion + + +- **resourceVersionMatch** (**查询参数**): string + + }}">resourceVersionMatch + + + +- **timeoutSeconds** (**查询参数**): integer + + }}">timeoutSeconds + + +#### 响应 + +200 (}}">Status): OK + +401: Unauthorized +