From 6959fc05c1922993705d555d6c42b76024f9e140 Mon Sep 17 00:00:00 2001 From: Michal Wozniak Date: Wed, 14 Feb 2024 10:16:13 +0100 Subject: [PATCH 1/4] Add placeholder for job managed-by label docs --- .../feature-gates/job-managed-by-label.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) create mode 100644 content/en/docs/reference/command-line-tools-reference/feature-gates/job-managed-by-label.md diff --git a/content/en/docs/reference/command-line-tools-reference/feature-gates/job-managed-by-label.md b/content/en/docs/reference/command-line-tools-reference/feature-gates/job-managed-by-label.md new file mode 100644 index 0000000000000..ab4464356fe95 --- /dev/null +++ b/content/en/docs/reference/command-line-tools-reference/feature-gates/job-managed-by-label.md @@ -0,0 +1,14 @@ +--- +title: JobManagedByLabel +content_type: feature_gate + +_build: + list: never + render: false + +stages: + - stage: beta + defaultValue: false + fromVersion: "1.30" +--- +Allows to delegate reconciliation of a Job object to an external controller. From 47490b873f47fd3d986014e99e7f9e94d05279c6 Mon Sep 17 00:00:00 2001 From: Michal Wozniak Date: Thu, 15 Feb 2024 19:16:13 +0100 Subject: [PATCH 2/4] Add the information about the managedBy field --- .../concepts/workloads/controllers/job.md | 21 +++++++++++++++++++ ...-managed-by-label.md => job-managed-by.md} | 4 ++-- 2 files changed, 23 insertions(+), 2 deletions(-) rename content/en/docs/reference/command-line-tools-reference/feature-gates/{job-managed-by-label.md => job-managed-by.md} (83%) diff --git a/content/en/docs/concepts/workloads/controllers/job.md b/content/en/docs/concepts/workloads/controllers/job.md index be5775973b83d..3b59333b05200 100644 --- a/content/en/docs/concepts/workloads/controllers/job.md +++ b/content/en/docs/concepts/workloads/controllers/job.md @@ -1006,6 +1006,27 @@ 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" >}} + +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. + +By setting a custom value of the `spec.managedBy` field - any value +other than `kubernetes.io/job-controller` - you indicate the controller which +reconciles the Job. 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 make sure it does not use the +`batch.kubernetes.io/job-tracking` finalizer, reserved for the built-in controller. +{{< /note >}} + ## Alternatives ### Bare Pods diff --git a/content/en/docs/reference/command-line-tools-reference/feature-gates/job-managed-by-label.md b/content/en/docs/reference/command-line-tools-reference/feature-gates/job-managed-by.md similarity index 83% rename from content/en/docs/reference/command-line-tools-reference/feature-gates/job-managed-by-label.md rename to content/en/docs/reference/command-line-tools-reference/feature-gates/job-managed-by.md index ab4464356fe95..38733b6de66ff 100644 --- a/content/en/docs/reference/command-line-tools-reference/feature-gates/job-managed-by-label.md +++ b/content/en/docs/reference/command-line-tools-reference/feature-gates/job-managed-by.md @@ -1,5 +1,5 @@ --- -title: JobManagedByLabel +title: JobManagedBy content_type: feature_gate _build: @@ -7,7 +7,7 @@ _build: render: false stages: - - stage: beta + - stage: alpha defaultValue: false fromVersion: "1.30" --- From 8f6b617fd9010d3a88296eba014dbf450dd6bc13 Mon Sep 17 00:00:00 2001 From: Michal Wozniak Date: Thu, 7 Mar 2024 20:58:44 +0100 Subject: [PATCH 3/4] review remarks --- .../concepts/workloads/controllers/job.md | 25 ++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) diff --git a/content/en/docs/concepts/workloads/controllers/job.md b/content/en/docs/concepts/workloads/controllers/job.md index 3b59333b05200..479b780ee5b4c 100644 --- a/content/en/docs/concepts/workloads/controllers/job.md +++ b/content/en/docs/concepts/workloads/controllers/job.md @@ -1010,6 +1010,12 @@ status: {{< feature-state for_k8s_version="v1.30" state="alpha" >}} +{{< note >}} +You can only set `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. @@ -1023,10 +1029,27 @@ installed, otherwise the Job may not be reconciled at all. {{< /note >}} {{< note >}} -When developing an external Job controller make sure it does not use the +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, inspect +there are no 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 From 6b1afc274ab6e76e55d05aca5fa506b5ae8c5471 Mon Sep 17 00:00:00 2001 From: Michal Wozniak Date: Fri, 8 Mar 2024 07:36:16 +0100 Subject: [PATCH 4/4] Review remarks --- .../en/docs/concepts/workloads/controllers/job.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/content/en/docs/concepts/workloads/controllers/job.md b/content/en/docs/concepts/workloads/controllers/job.md index 479b780ee5b4c..ff8321445c49f 100644 --- a/content/en/docs/concepts/workloads/controllers/job.md +++ b/content/en/docs/concepts/workloads/controllers/job.md @@ -1011,7 +1011,7 @@ status: {{< feature-state for_k8s_version="v1.30" state="alpha" >}} {{< note >}} -You can only set `ManagedBy` field on Jobs if you enable the `JobManagedBy` +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 >}} @@ -1019,12 +1019,12 @@ You can only set `ManagedBy` field on Jobs if you enable the `JobManagedBy` 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. -By setting a custom value of the `spec.managedBy` field - any value -other than `kubernetes.io/job-controller` - you indicate the controller which -reconciles the Job. The value of the field is immutable. +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 +When using this feature, make sure the controller indicated by the field is installed, otherwise the Job may not be reconciled at all. {{< /note >}} @@ -1043,8 +1043,8 @@ Finally, when developing an external Job controller make sure it does not use th {{< warning >}} If you are considering to disable the `JobManagedBy` feature gate, or to -downgrade the cluster to a version without the feature gate enabled, inspect -there are no jobs with a custom value of the `spec.managedBy` field. If there +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.