Merge pull request #45132 from mimowo/job-managed-by-docs

Add docs for Job managedBy field (alpha)

Author: k8s-ci-robot

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

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.