Configuring Namespace-Specific KubeArchive Policies

This document explains how to configure namespace-specific policies using KubeArchiveConfig. These policies apply only to the namespace where the KubeArchiveConfig is created.

For a comprehensive guide with more examples, see Configuring KubeArchive.

Prerequisites

  • KubeArchive installed and running in a cluster (Installation)

  • Appropriate permissions to create resources in the target namespace

The KubeArchiveConfig Resource

To configure namespace-specific KubeArchive policies create a KubeArchiveConfig custom resource. Only one KubeArchiveConfig is allowed per namespace and it must be named kubearchive. KubeArchiveConfigs have this general form:

---
apiVersion: kubearchive.org/v1
kind: KubeArchiveConfig
metadata:
  name: kubearchive
  namespace: default
spec:
  resources: [...] (1)
1 spec.resources is a list of elements, each defining namespace-specific rules for a specific kind.

selector: Selecting Resources

The key selector within KubeArchiveConfigs define resources. It requires two keys: kind and apiVersion. Each entry on spec.resources requires a selector:

---
apiVersion: kubearchive.org/v1
kind: KubeArchiveConfig
metadata:
  name: kubearchive
  namespace: default
spec:
  resources:
    - selector:
        apiVersion: v1
        kind: Pod
      ...
    - selector:
        apiVersion: batch/v1
        kind: Job
      ...
    - selector:
        apiVersion: apps/v1
        kind: Deployment
      ...

With each entry on spec.resources KubeArchiveConfig supports archiveWhen, deleteWhen, archiveOnDelete, and keepLastWhen. These keys accept a string which is an expression in the CEL language format. When a resource defined by selector changes or gets deleted KubeArchive evaluates the expressions. They must evaluate to either true or false.

archiveWhen: Archiving Resources

The archiveWhen key defines when KubeArchive should archive resources in this namespace. The following example configures KubeArchive to archive pods when they match the status.phase == "Succeeded" condition:

---
apiVersion: kubearchive.org/v1
kind: KubeArchiveConfig
metadata:
  name: kubearchive
  namespace: default
spec:
  resources:
    - selector:
        apiVersion: v1
        kind: Pod
      archiveWhen: status.phase == "Succeeded"

archiveWhen: "true" is also a valid expression that configures KubeArchive to archive the resource every time its updated.

archiveWhen is processed by both the controller and vacuums. Resources processed by the controller are handled immediately after Kubernetes sends the event. Resources processed by vacuums are handled based on how often the vacuum operations are scheduled to run.

deleteWhen: Deleting Resources

The deleteWhen key enables automatic deletion of resources from the Kubernetes cluster based on a CEL expression. This helps keep the cluster free of resources that are no longer needed.

KubeArchive archives resources deleted using deleteWhen.

deleteWhen is processed by the controller only. Resources are handled immediately after Kubernetes sends the event.

While deleteWhen is not used in vacuum operations, similar functionality can be achieved using keepLastWhen with a count of 0.

For example, these two approaches have similar effects but different timing:

Using deleteWhen (processed immediately by controller):

deleteWhen: has(status.completionTime)

Using keepLastWhen (processed during vacuum operations):

keepLastWhen:
  keep:
    - when: "has(status.completionTime)"
      count: 0

The deleteWhen approach deletes resources immediately when they match the condition, while the keepLastWhen approach with count 0 deletes matching resources only when vacuums run.

The following KubeArchiveConfig configures KubeArchive to delete (and archive) completed pods in the namespace:

---
apiVersion: kubearchive.org/v1
kind: KubeArchiveConfig
metadata:
  name: kubearchive
  namespace: default
spec:
  resources:
    - selector:
        apiVersion: v1
        kind: Pod
      deleteWhen: status.phase == "Succeeded"

keepLastWhen: Keeping the Last N Resources

The keepLastWhen key provides a way to automatically retain only the most recent N resources that match specific criteria, while deleting older ones. This is particularly useful for managing resources like completed jobs, where you want to keep only the latest few for reference while cleaning up older ones.

KubeArchive archives resources deleted using keepLastWhen.

keepLastWhen is processed by vacuums only. Resources are handled based on how often the vacuum operations are scheduled to run, not immediately after Kubernetes sends events.

The keepLastWhen configuration has two sections:

The keep Section

The keep section contains an array of rules for defining retention policies. Each rule in the keep array has:

  • when - CEL expression defining which resources to consider

  • count - Number of resources to keep (must be greater than or equal to 0; when 0, all matching resources are deleted)

  • sortBy - (optional) Field to sort by (defaults to metadata.creationTimestamp)

The following KubeArchiveConfig configures KubeArchive to keep only the last 3 completed jobs in the namespace:

---
apiVersion: kubearchive.org/v1
kind: KubeArchiveConfig
metadata:
  name: kubearchive
  namespace: default
spec:
  resources:
    - selector:
        apiVersion: batch/v1
        kind: Job
      keepLastWhen:
        keep:
          - when: "has(status.completionTime) && metadata.name.startsWith('backup-')"
            count: 3

You can also sort by other fields, such as the resource name:

keepLastWhen:
  keep:
    - when: "has(status.completionTime)"
      count: 5
      sortBy: "metadata.name"

Multiple rules can be specified in the keep section to handle different types of resources with different retention policies:

keepLastWhen:
  keep:
    - when: "metadata.name.startsWith('daily-backup-')"
      count: 7
    - when: "metadata.name.startsWith('weekly-backup-')"
      count: 4

The override Section

When a ClusterKubeArchiveConfig defines keepLastWhen rules, namespaces can override those rules to apply stricter retention policies. This is done using the override section within keepLastWhen.

Each override must reference a cluster rule by its name and specify a count that is less than or equal to the cluster rule’s count. This allows individual namespaces to keep fewer resources than the cluster-wide default while preventing them from keeping more resources than the cluster policy allows.

For example, if a ClusterKubeArchiveConfig has this rule:

apiVersion: kubearchive.org/v1
kind: ClusterKubeArchiveConfig
metadata:
  name: kubearchive
spec:
  resources:
    - selector:
        apiVersion: batch/v1
        kind: Job
      keepLastWhen:
        - name: completed-jobs
          when: "has(status.completionTime)"
          count: 10

A namespace can override it to keep fewer jobs:

apiVersion: kubearchive.org/v1
kind: KubeArchiveConfig
metadata:
  name: kubearchive
  namespace: production
spec:
  resources:
    - selector:
        apiVersion: batch/v1
        kind: Job
      keepLastWhen:
        override:
          - name: completed-jobs
            count: 5

In this example, the cluster policy allows keeping up to 10 completed jobs, but the production namespace chooses to keep only 5.

Override rules can only reduce the count, not increase it. If an override specifies a count greater than the cluster rule, the webhook will reject the configuration.

Combining keep and override Sections

You can combine both keep and override sections in the same keepLastWhen configuration:

apiVersion: kubearchive.org/v1
kind: KubeArchiveConfig
metadata:
  name: kubearchive
  namespace: production
spec:
  resources:
    - selector:
        apiVersion: batch/v1
        kind: Job
      keepLastWhen:
        keep:
          - when: "metadata.name.startsWith('local-job-')"
            count: 3
        override:
          - name: completed-jobs
            count: 5

This configuration will: 1. Apply the namespace-specific rule to keep the last 3 local jobs 2. Override the cluster rule to keep only 5 completed jobs instead of the cluster default

archiveOnDelete: Archiving on Deletion From the Cluster

The archiveOnDelete key enables KubeArchive to work with other applications that clean up resources. This allows you to use specialized deletion tools while still archiving resources with KubeArchive.

archiveOnDelete is processed by the controller only. Resources are handled immediately after Kubernetes sends the event.

The following KubeArchiveConfig configures KubeArchive to archive pods when they get deleted from the cluster only if they match the condition status.phase == "Succeeded", so failed pods that get deleted do not get archived:

---
apiVersion: kubearchive.org/v1
kind: KubeArchiveConfig
metadata:
  name: kubearchive
  namespace: default
spec:
  resources:
    - selector:
        apiVersion: v1
        kind: Pod
      archiveOnDelete: status.phase == "Succeeded"

Interaction With Cluster Filters

Namespace filters configured in KubeArchiveConfig work together with cluster-wide filters configured in ClusterKubeArchiveConfig. Both cluster and namespace filters are combined with an "OR" type of logic and used for that specific namespace.

For example, if you have this ClusterKubeArchiveConfig:

---
apiVersion: kubearchive.org/v1
kind: ClusterKubeArchiveConfig
metadata:
  name: kubearchive
spec:
  resources:
    - selector:
        apiVersion: v1
        kind: Pod
      archiveOnDelete: "true"

And the following KubeArchiveConfig in the namespace "my-team":

---
apiVersion: kubearchive.org/v1
kind: KubeArchiveConfig
metadata:
  name: kubearchive
  namespace: my-team
spec:
  resources:
    - selector:
        apiVersion: batch/v1
        kind: Job
      archiveWhen: has(status.startTime)
      deleteWhen: has(status.completionTime)

KubeArchive will archive jobs when they have status.startTime and delete them when they have status.completionTime in the "my-team" namespace. Additionally, KubeArchive will also archive pods when they are deleted, as configured in the global ClusterKubeArchiveConfig.

Next Steps

All ClusterKubeArchiveConfig and KubeArchiveConfig resources must be named "kubearchive".