goharbor / goharbor/harbor-cli
[feature]: implement registry-wide Garbage Collection (gc) command group
- Dominant language
- Go
- Stars
- 163
- Forks
- 211
- Avg merge
- 1m
- Merged PRs (30d)
- 1
Description
### Problem / Limitation (Before State)
Currently, `harbor-cli` lacks support for managing registry-wide Garbage Collection (GC) operations.
**What was happening earlier:**
1. **No Terminal Automation:** Registry administrators automating cluster maintenance or performing cleanup tasks inside CI/CD pipelines had no way to trigger or monitor registry GC jobs via the terminal.
2. **Forced Context-Switching:** Administrators were forced to leave their terminal, open the Harbor WebUI, log in, navigate to Admin -> Garbage Collection, and manually trigger or inspect runs.
3. **No Log Auditing:** Inspecting which blobs were deleted or checking for storage/permission errors during a GC run required manual download of execution logs from the WebUI.
4. **Schedule Limitations:** Modifying automatic GC cron schedules required WebUI interactions.
---
### Motivation & Value
Implementing the `gc` command group directly advances the project towards its core goal of **WebUI Feature Parity**. It empowers operations teams to perform complete administrative cleanup workflows programmatically.
---
### Proposed Architecture & Command Structure
We propose introducing a native `gc` subcommand group under the `system` category. The commands leverage the SDK's existing `client.GC` endpoints:
1. **`harbor gc history`**
* *Purpose:* Displays a formatted table of all past GC executions.
* *Flags:* Supports pagination (`--page`, `--page-size`), queries (`--query`), and sorting (`--sort`).
2. **`harbor gc schedule`**
* *Purpose:* Displays the current automatic GC schedule (type, cron expression, next execution time, and settings).
3. **`harbor gc trigger`**
* *Purpose:* Triggers an immediate manual GC execution.
* *Flags:* `--delete-untagged`, `--dry-run`, and `-i/--interactive` (launches a visual `huh` prompt to select options).
4. **`harbor gc log [gc-id]`**
* *Purpose:* Fetches and outputs the raw text execution log for a specific GC job.
5. **`harbor gc stop [gc-id]`**
* *Purpose:* Instantly stops a currently running GC execution to prevent resource exhaustion during peak hours.
6. **`harbor gc update-schedule [schedule-type]`**
* *Purpose:* Updates the automatic schedule config (`none`, `hourly`, `daily`, `weekly`, or `custom`).
* *Flags:* `--cron` (for custom types), `--delete-untagged`, `--dry-run`, and `-i/--interactive`.
---
### Alternatives Considered
1. **Option A (Trigger-Only):** Only implement `trigger` and `history`. This was rejected because log auditing and stopping jobs are critical for operational safety when performing deletions.
2. **Option B (Complete Group - Chosen):** Implement the full control loop (trigger, stop, log, schedule, history) to ensure administrative completeness.
Contributor guide
Research direction
Start by inspecting the existing CLI command structure and the SDK's client.GC endpoints referenced in the proposal. Define the gc command group under the system category, then verify that history, schedule, trigger, log, stop, and update-schedule support the listed arguments and flags and complete the corresponding administrative workflows.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go
- Domain
- cli, devops
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100