diff --git a/content/en/docs/writing-policies/cleanup.md b/content/en/docs/writing-policies/cleanup.md index ac858b68d..4be2417ca 100644 --- a/content/en/docs/writing-policies/cleanup.md +++ b/content/en/docs/writing-policies/cleanup.md @@ -25,17 +25,17 @@ metadata: spec: match: any: - - resources: - kinds: - - Deployment - selector: - matchLabels: - canremove: "true" + - resources: + kinds: + - Deployment + selector: + matchLabels: + canremove: "true" conditions: any: - - key: "{{ target.spec.replicas }}" - operator: LessThan - value: 2 + - key: "{{ target.spec.replicas }}" + operator: LessThan + value: 2 schedule: "*/5 * * * *" ``` @@ -55,23 +55,23 @@ metadata: app.kubernetes.io/part-of: kyverno name: kyverno:cleanup-pods rules: -- apiGroups: - - "" - resources: - - pods - verbs: - - get - - watch - - list - - delete + - apiGroups: + - "" + resources: + - pods + verbs: + - get + - watch + - list + - delete ``` ## Cleanup Label In addition to policies which can declaratively define what resources to remove and when to remove them, the second option for cleanup involves assignment of a reserved label called `cleanup.kyverno.io/ttl` to the exact resource(s) which should be removed. The value of this label can be one of two supported formats. Any unrecognized formats will trigger a warning. -* An absolute time specified in ISO 8601 format (ex., `2023-10-04T003000Z` or `2023-10-04`) -* A remaining time calculated from when the label was observed (ex., `5m`, `4h`, or `1d`) +- An absolute time specified in ISO 8601 format (ex., `2023-10-04T003000Z` or `2023-10-04`) +- A remaining time calculated from when the label was observed (ex., `5m`, `4h`, or `1d`) This label can be assigned to any resource and so long as Kyverno has the needed permissions to delete the resource (see above section for an example), it will be removed at the designated time. @@ -86,13 +86,82 @@ metadata: name: foo spec: containers: - - args: - - sleep - - 1d - image: busybox:1.35 - name: foo + - args: + - sleep + - 1d + image: busybox:1.35 + name: foo ``` Although labeled resources are watched by Kyverno, the cleanup interval (the time resolution at which any cleanup can be performed) is controlled by a flag passed to the cleanup controller called `ttlReconciliationInterval`. This value is set to `1m` by default and can be changed if a longer resolution is required. Because this is a label, there is opportunity to chain other Kyverno functionality around it. For example, it is possible to use a Kyverno mutate rule to assign this label to matching resources. A validate rule could be written prohibiting, for example, users from the `infra-ops` group from assigning the label to resources in certain Namespaces. Or, Kyverno could generate a new resource with this label as part of the resource definition. + +## DeletionPropagationPolicy (Common to both ClusterCleanupPolicy and TTL based Cleanup) + +The `deletionPropagationPolicy` field is an optional setting available in both CleanupPolicy and TTL-based cleanup configurations. It determines how Kubernetes handles the deletion of dependent resources when the primary resource is deleted. + +Supported values: + +- **Foreground**: Ensures dependent resources are deleted before the primary resource is removed. +- **Background**: Deletes the primary resource first, while dependents are removed asynchronously. +- **Orphan**: Deletes the primary resource but leaves its dependents untouched. + +{{% alert title="Note" color="info" %}} +If deletionPropagationPolicy is not set, Kyverno defers to the Kubernetes API server's default behavior, which typically handles dependents based on cluster settings. +{{% /alert %}} + +### Cleanup Policy Example with deletionPropagationPolicy + +A ClusterCleanupPolicy can include deletionPropagationPolicy to control the cleanup of dependents. Here's an example: + +```yaml +apiVersion: kyverno.io/v2 +kind: ClusterCleanupPolicy +metadata: + name: cleandeploy +spec: + match: + any: + - resources: + kinds: + - Deployment + selector: + matchLabels: + canremove: "true" + conditions: + any: + - key: "{{ target.spec.replicas }}" + operator: LessThan + value: 2 + schedule: "*/5 * * * *" + deleteOptions: "Foreground" +``` + +This policy schedules the deletion of Deployments labeled `canremove: "true"` with fewer than two replicas every 5 minutes, ensuring dependent resources are deleted before the Deployment itself. + +### TTL-Based Cleanup Example with deletionPropagationPolicy + +Resources with a `cleanup.kyverno.io/ttl` label can also use the deletionPropagationPolicy to manage dependent resources: + +```yaml +apiVersion: v1 +kind: Pod +metadata: + labels: + cleanup.kyverno.io/ttl: 2m + annotations: + PropagationPolicy: "Orphan" + name: foo +spec: + containers: + - args: + - sleep + - 1d + image: busybox:1.35 + name: foo +``` + +In this example: +The TTL label specifies that the Pod will be deleted 2 minutes after creation. +The deletionPropagationPolicy: "Orphan" ensures that any dependents remain in the cluster after the Pod is deleted.