From 65fadf3618deb1f13376e9d901420357b0d4a8eb Mon Sep 17 00:00:00 2001 From: Janet Kuo Date: Mon, 10 Sep 2018 17:19:45 -0700 Subject: [PATCH] Address comments --- .../controllers/jobs-run-to-completion.md | 20 +++++++--- .../workloads/controllers/ttlafterfinished.md | 40 ++++++++++++------- 2 files changed, 39 insertions(+), 21 deletions(-) diff --git a/content/en/docs/concepts/workloads/controllers/jobs-run-to-completion.md b/content/en/docs/concepts/workloads/controllers/jobs-run-to-completion.md index c8e9364d0ae9d..39324b6b2800f 100644 --- a/content/en/docs/concepts/workloads/controllers/jobs-run-to-completion.md +++ b/content/en/docs/concepts/workloads/controllers/jobs-run-to-completion.md @@ -250,10 +250,14 @@ Note that both the Job Spec and the [Pod Template Spec](https://kubernetes.io/do ## Clean Up Finished Jobs Automatically Finished Jobs are usually no longer needed in the system. Keeping them around in -the system will put pressure on API server. If the Jobs are managed directly by -a higher level controller, such as +the system will put pressure on the API server. If the Jobs are managed directly +by a higher level controller, such as [CronJobs](/docs/concepts/workloads/controllers/cron-jobs/), the Jobs can be -cleaned up by CronJobs based on specified cleanup policy. +cleaned up by CronJobs based on the specified capacity-based cleanup policy. + +### TTL Mechanism for Finished Jobs + +{{< feature-state for_k8s_version="v1.12" state="alpha" >}} Another way to clean up finished Jobs (either `Complete` or `Failed`) automatically is to use a TTL mechanism provided by a @@ -261,6 +265,11 @@ automatically is to use a TTL mechanism provided by a finished resources, by specifying the `.spec.ttlSecondsAfterFinished` field of the Job. +When the TTL controller cleans up the Job, it will delete the Job cascadingly, +i.e. delete its dependent objects, such as Pods, together with the Job. Note +that when the Job is deleted, its lifecycle guarantees, such as finalizers, will +be honored. + For example: ```yaml @@ -281,11 +290,10 @@ spec: ``` The Job `pi-with-ttl` will be eligible to be automatically deleted, `100` -seconds after it finishes. Note that when the Job is deleted, its lifecycle -guarantees, such as finalizers, will be honored. +seconds after it finishes. If the field is set to `0`, the Job will be eligible to be automatically deleted -immediately after it finishes. If the field is unset, this Jobs won't be cleaned +immediately after it finishes. If the field is unset, this Job won't be cleaned up by the TTL controller after it finishes. Note that this TTL mechanism is alpha, with feature gate `TTLAfterFinished`. For diff --git a/content/en/docs/concepts/workloads/controllers/ttlafterfinished.md b/content/en/docs/concepts/workloads/controllers/ttlafterfinished.md index 7a6fb767125eb..6a5b418a2c74e 100644 --- a/content/en/docs/concepts/workloads/controllers/ttlafterfinished.md +++ b/content/en/docs/concepts/workloads/controllers/ttlafterfinished.md @@ -3,13 +3,15 @@ reviewers: - janetkuo title: TTL Controller for Finished Resources content_template: templates/concept -weight: ?? +weight: 65 --- {{% capture overview %}} +{{< feature-state for_k8s_version="v1.12" state="alpha" >}} + The TTL controller provides a TTL mechanism to limit the lifetime of resource -objects that have finished execution. Currently, TTL controller only handles +objects that have finished execution. TTL controller only handles [Jobs](/docs/concepts/workloads/controllers/jobs-run-to-completion/) for now, and may be expanded to handle other resources that will finish execution, such as Pods and custom resources. @@ -31,21 +33,29 @@ Alpha Disclaimer: this feature is currently alpha, and can be enabled with The TTL controller only supports Jobs for now. You can use this feature to clean up finished Jobs (either `Complete` or `Failed`) automatically by specifying the -`.spec.ttlSecondsAfterFinished` field of a Job, -see [example](/docs/concepts/workloads/controllers/jobs-run-to-completion/#clean-up-finished-jobs-automatically). +`.spec.ttlSecondsAfterFinished` field of a Job, as in this +[example](/docs/concepts/workloads/controllers/jobs-run-to-completion/#clean-up-finished-jobs-automatically). The TTL controller will assume that a resource is eligible to be cleaned up TTL seconds after the resource has finished, i.e. TTL has expired. When the -resource is deleted, its lifecycle guarantees, such as finalizers, will be -honored. - -The TTL seconds can be set at any time -- for example, you can specify it in the -resource manifest, set it at resource creation time, or set it after the -resource has finished. You can also use -[mutating admission webhooks](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/#admission-webhooks) -to set this field dynamically. - -In the future, we plan to expand TTL controller to other resources that will -finish execution, such as Pods and custom resources. +TTL controller cleans up a resource, it will delete it cascadingly, i.e. delete +its dependent objects together with it. Note that when the resource is deleted, +its lifecycle guarantees, such as finalizers, will be honored. + +The TTL seconds can be set at any time. Here are some examples for setting the +`.spec.ttlSecondsAfterFinished` field of a Job: + +* Specify this field in the resource manifest, so that a Job can be cleaned up + automatically some time after it finishes. +* Set this field of existing, already finished resources, to adopt this new + feature. +* Use a + [mutating admission webhook](/docs/reference/access-authn-authz/extensible-admission-controllers/#admission-webhooks) + to set this field dynamically at resource creation time. Cluster admins can + use this to enforce a TTL policy for finished resources. +* Use a + [mutating admission webhook](/docs/reference/access-authn-authz/extensible-admission-controllers/#admission-webhooks) + to set this field dynamically after the resource has finished, and choose + different TTL values based on resource status, labels, etc. ## Caveat