Hyphen
Log In

Kubernetes Resource Cleanup

Learn how Hyphen Agent automates Kubernetes resource cleanup, identifying and suggesting stale, dead, or unused resources for auditable deletion, thereby reducing cluster clutter and manual risk.

Hyphen Agent can scan a registered Kubernetes cluster for stale, dead, or unused resources and present cleanup candidates for review. Kubernetes resource cleanup helps reduce cluster clutter by turning risky manual cleanup work into an auditable Agent run with explicit approval for each candidate.

Use Kubernetes resource cleanup when you want Agent to find cleanup candidates in a cluster. The internal Agent task type is KubernetesResourceCleanup.

Table of Contents

Requirements

Kubernetes resource cleanup needs:

  • A registered Kubernetes cluster that Hyphen Agent can inspect.
  • Permission to view the cluster and run Agent tasks for the organization.
  • Permission to manage Agent task policies when changing organization or cluster cleanup policy settings.

Agent must be able to collect cluster inventory, including namespaces, workloads, pods, services, endpoints, ingresses, config maps, and events.

Automatic and Manual Runs

By default, Kubernetes resource cleanup is enabled with a daily recurring schedule and a 14-day cleanup threshold.

Scheduled runs are created from the effective Kubernetes cleanup policy for each registered cluster. If the effective policy is set to manual only, Hyphen does not create scheduled cleanup scans for that cluster.

If you have permission, ask Hyphen Agent to scan a registered Kubernetes cluster manually. Manual cleanup scans are one-off tasks. Agent uses attached cluster context first; if the request does not identify exactly one cluster, Agent asks you to choose the intended cluster before starting the scan.

Policies

Kubernetes resource cleanup is controlled by an Agent task policy. The organization policy defines the default behavior for registered clusters.

For step-by-step Kubernetes management instructions, see Cleanup Policies in the Kubernetes section.

The organization policy can configure:

  • Whether scheduled Kubernetes cleanup is enabled.
  • The recurring schedule, including manual-only mode.
  • The cleanup threshold in days.
  • Ignored namespaces.
  • Ignored Kubernetes resource UIDs.

Individual Kubernetes clusters can override the organization policy. Use a cluster override when one cluster needs a different schedule, cleanup threshold, ignored namespaces, or ignored UIDs than the organization default.

Cluster policy overrides apply only to that cluster. Removing the cluster override returns the cluster to the organization policy. The effective ignored namespace and UID lists also include Hyphen's built-in platform exclusions, such as Kubernetes system namespaces.

How It Works

Agent starts by collecting inventory from the selected cluster. It filters out ignored namespaces and ignored UIDs, then scores resources against the cleanup threshold and Kubernetes state signals.

Agent can identify cleanup candidates such as:

  • Empty namespaces.
  • Workloads scaled to zero.
  • Completed or failed jobs.
  • Suspended cron jobs.
  • Terminal standalone pods.
  • Unreferenced config maps.
  • Services without endpoints.
  • Ingresses without live backends.
  • Orphan endpoint objects.
  • Unready workloads with warning events.

Each finding includes the resource, category, confidence, reason, and evidence. If Agent finds no cleanup candidates, the run completes without requesting decisions.

Approvals and Decisions

Kubernetes cleanup scans are read-only until a cleanup candidate is explicitly approved. When Agent finds candidates, each candidate becomes an input request.

Approved deletions are scoped to the single flagged Kubernetes resource. Agent does not delete related application workloads, namespaces, or other resources unless those resources are separately flagged and explicitly approved.

Decision options include:

  • Clean up - Approves deletion of the candidate Kubernetes resource.
  • Do nothing - Skips the candidate for this run.
  • Always ignore - Adds the namespace or resource UID to the cleanup ignore policy when possible.
  • Ignore namespace always - Adds the candidate's namespace to the ignore policy. This option appears for namespaced resources.

If an input request times out, Agent records the timeout and does not clean up that resource. If a cleanup deletion fails, the run records the failure so you can review what happened.

Results

Kubernetes resource cleanup task and run views show the scan, cluster, threshold, inventory summary, findings, approval requests, decisions, and cleanup output. Results can include counts for cleaned up resources, skipped resources, ignored resources, timed-out requests, successful deletes, already-absent resources, and delete failures.

Things to Know

  • Kubernetes resource cleanup is scoped to one registered cluster per run.
  • The default cleanup threshold is 14 days.
  • Built-in platform namespaces are excluded from cleanup scans by default.
  • Ignored namespaces and ignored UIDs prevent matching resources from being flagged.
  • Agent does not delete Kubernetes resources unless a cleanup candidate is explicitly approved.
  • Cluster overrides are useful for clusters with different operational rules than the organization default.