Finalizer Cleaner

A Kubernetes tool to safely remove finalizers from resources based on specified criteria. Features both CLI flags and an interactive TUI mode for easy finalizer management.

Features

• Interactive TUI Mode: User-friendly interface for selecting namespaces, resource types, and finalizers
• Batch Operations: Remove finalizers from multiple resources at once
• Dry Run Mode: Preview changes before applying them
• Flexible Filtering: Filter by namespaces, resource kinds, and specific finalizer names
• Comprehensive Logging: Detailed logging with different log levels
• Safe Operations: Only removes specified finalizers, preserving others

Installation

From Source

go install github.com/risen228/finalizer-cleaner@latest

Build Locally

git clone https://github.com/risen228/finalizer-cleaner.git
cd finalizer-cleaner
go build .

Usage

Interactive Mode

Run without arguments or with limited arguments to enter interactive TUI mode:

finalizer-cleaner

The interactive mode will guide you through:

1. Selecting namespaces (or all namespaces)
2. Selecting resource types (or all types)
3. Selecting which finalizers to remove

CLI Mode

Specify all parameters via command-line flags:

./finalizer-cleaner \
  --namespaces "default,kube-system" \
  --kinds "apps/v1/Deployment,v1/Pod" \
  --finalizers "kubernetes.io/pvc-protection,example.com/finalizer"

Flags

• --namespaces: Comma-separated list of namespaces (empty = all namespaces)
• --kinds: Comma-separated list of Group/Version/Kind triplets (empty = all kinds)
• --finalizers: Comma-separated list of finalizers to remove (empty = all finalizers)
• --dry-run: Print what would be changed without making actual modifications
• --interactive: Force interactive mode even when other flags are provided
• --verbose: Enable verbose logging for detailed operation information
• --timeout: HTTP timeout for Kubernetes API calls (default: 30s)

Examples

Remove specific finalizer from all deployments in default namespace

./finalizer-cleaner \
  --namespaces default \
  --kinds apps/v1/Deployment \
  --finalizers "example.com/my-finalizer"

Dry run to see what would be removed

./finalizer-cleaner \
  --namespaces default \
  --dry-run

Verbose logging for detailed operation information

./finalizer-cleaner \
  --namespaces default \
  --kinds apps/v1/Deployment \
  --verbose

Remove all finalizers from failed pods (dangerous!)

./finalizer-cleaner \
  --namespaces default \
  --kinds v1/Pod \
  --finalizers ""

Safety Considerations

1. Always use dry-run first: Before performing actual removal, use --dry-run to preview changes
2. Be specific with finalizers: Only remove finalizers you understand. Removing system finalizers can cause data loss
3. Understand the impact: Finalizers exist to ensure proper cleanup. Removing them bypasses this cleanup
4. Backup important resources: Consider backing up critical resources before removing finalizers

Common Use Cases

Stuck Namespace Deletion

When a namespace is stuck in "Terminating" state:

./finalizer-cleaner \
  --namespaces stuck-namespace \
  --finalizers "kubernetes"

PVC Protection Removal

To force-delete protected PVCs:

./finalizer-cleaner \
  --kinds v1/PersistentVolumeClaim \
  --finalizers "kubernetes.io/pvc-protection"

Custom Operator Cleanup

Remove custom operator finalizers:

./finalizer-cleaner \
  --kinds "example.com/v1/CustomResource" \
  --finalizers "example.com/operator-finalizer"

Architecture

The tool is structured into several modules:

• main.go: Entry point and orchestration
• config.go: Configuration parsing and validation
• tui.go: Interactive terminal UI components
• kubernetes.go: Kubernetes client and operations
• logger.go: Structured logging utilities
• utils.go: Helper functions

Requirements

• Go 1.21 or later
• Access to a Kubernetes cluster (via ~/.kube/config or KUBECONFIG environment variable)
• Appropriate RBAC permissions to list and patch target resources

Known Issues

Dependency Conflicts

This project currently uses replace directives in go.mod to resolve protobuf registration conflicts between gnostic and gnostic-models libraries. See DEPENDENCY_NOTES.md for details and future migration plans.

License

MIT License

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.