diff --git a/content/en/docs/concepts/workloads/controllers/job.md b/content/en/docs/concepts/workloads/controllers/job.md index be5775973b83d..ff8321445c49f 100644 --- a/content/en/docs/concepts/workloads/controllers/job.md +++ b/content/en/docs/concepts/workloads/controllers/job.md @@ -1006,6 +1006,50 @@ status: terminating: 3 # three Pods are terminating and have not yet reached the Failed phase ``` +### Delegation of managing a Job object to external controller + +{{< feature-state for_k8s_version="v1.30" state="alpha" >}} + +{{< note >}} +You can only set the `managedBy` field on Jobs if you enable the `JobManagedBy` +[feature gate](/docs/reference/command-line-tools-reference/feature-gates/) +(disabled by default). +{{< /note >}} + +This feature allows you to disable the built-in Job controller, for a specific +Job, and delegate reconciliation of the Job to an external controller. + +You indicate the controller that reconciles the Job by setting a custom value +for the `spec.managedBy` field - any value +other than `kubernetes.io/job-controller`. The value of the field is immutable. + +{{< note >}} +When using this feature, make sure the controller indicated by the field is +installed, otherwise the Job may not be reconciled at all. +{{< /note >}} + +{{< note >}} +When developing an external Job controller be aware that your controller needs +to operate in a fashion conformant with the definitions of the API spec and +status fields of the Job object. + +Please review these in detail the [Job API](/docs/reference/kubernetes-api/workload-resources/job-v1/). +We also recommend you running the e2e conformance tests for the Job object to +verify your implementation. + +Finally, when developing an external Job controller make sure it does not use the +`batch.kubernetes.io/job-tracking` finalizer, reserved for the built-in controller. +{{< /note >}} + +{{< warning >}} +If you are considering to disable the `JobManagedBy` feature gate, or to +downgrade the cluster to a version without the feature gate enabled, check if +there are jobs with a custom value of the `spec.managedBy` field. If there +are such jobs, there is a risk that they might be reconciled by two controllers +after the operation: the built-in Job controller and the external controller +indicated by the field value. +{{< /warning >}} + ## Alternatives ### Bare Pods diff --git a/content/en/docs/reference/command-line-tools-reference/feature-gates/job-managed-by.md b/content/en/docs/reference/command-line-tools-reference/feature-gates/job-managed-by.md new file mode 100644 index 0000000000000..38733b6de66ff --- /dev/null +++ b/content/en/docs/reference/command-line-tools-reference/feature-gates/job-managed-by.md @@ -0,0 +1,14 @@ +--- +title: JobManagedBy +content_type: feature_gate + +_build: + list: never + render: false + +stages: + - stage: alpha + defaultValue: false + fromVersion: "1.30" +--- +Allows to delegate reconciliation of a Job object to an external controller.