recovery: add the kubectl-gpurecovery plugin

[tkatila]

Kubectl plugin that helps with gpurecovery plan handling. Supports auto-complete so it's easier to list, approve, observe what's happening with the execution.

[Copilot]

🟡 Changes recommended

The plugin currently has correctness/UX issues around kubeconfig loading semantics and conflict-prone Update mutations (plus a Makefile build target fragility) that should be addressed before approval.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR introduces a new kubectl-gpurecovery kubectl plugin for inspecting and managing GPURecoveryPlan resources (plans, events, approvals, messages) with shell completion support, plus build/install targets and documentation updates.

Changes:

• Add a Cobra-based kubectl-gpurecovery plugin with commands for listing plans/events, viewing messages, and managing approvals (approve/confirm/remove).
• Add -o wide|yaml output handling for events, plus YAML rendering helpers and unit tests for formatting/rendering.
• Update build/test tooling and docs (Makefile targets, go.mod direct dependency, RECOVERY.md usage notes).

File summaries

File	Description
RECOVERY.md	Documents updated events output options and behavior.
Makefile	Adjusts test package exclusions; adds build/install/completion targets for the plugin.
go.mod	Promotes spf13/cobra from indirect to direct dependency for the new CLI.
cmd/kubectl-gpurecovery/main.go	Plugin entrypoint executing the root Cobra command.
cmd/kubectl-gpurecovery/root.go	Root command wiring, kubeconfig/client creation, and completion helpers.
cmd/kubectl-gpurecovery/apitypes.go	Mirrors CRD enums/states and provides validation/completion helpers.
cmd/kubectl-gpurecovery/client.go	Dynamic-client helpers to GET plans and mutate approvals.
cmd/kubectl-gpurecovery/plans.go	plans command to list GPURecoveryPlans with summary columns.
cmd/kubectl-gpurecovery/events.go	events command with table/wide/YAML output and derived columns.
cmd/kubectl-gpurecovery/output.go	-o/--output parsing, completion, and YAML printing helper.
cmd/kubectl-gpurecovery/format.go	Shared formatting helpers (durations, truncation, placeholders).
cmd/kubectl-gpurecovery/messages.go	messages command with filtering and tailing.
cmd/kubectl-gpurecovery/approvals.go	approvals command listing spec approvals with stable formatting.
cmd/kubectl-gpurecovery/approve.go	approve command to add a singular event approval.
cmd/kubectl-gpurecovery/confirm.go	confirm command to add selector-based (group) approvals.
cmd/kubectl-gpurecovery/remove.go	remove command to delete approvals by ID.
cmd/kubectl-gpurecovery/render_test.go	Unit tests covering formatting/output and YAML rendering behavior.

Review details

Suppressed comments (2)

cmd/kubectl-gpurecovery/client.go:58

• addApproval does a read-modify-update without any conflict retry; if the operator updates the plan between the GET and UPDATE (e.g., status/events), this will fail with 409 Conflict and force users to rerun. Wrap the mutation in retry.RetryOnConflict so it retries with the latest object.

	_, err = cl.Resource(gpuRecoveryPlanGVR).Update(
		context.Background(), plan, metav1.UpdateOptions{},
	)

	return err

cmd/kubectl-gpurecovery/client.go:100

• removeApprovalByID also does a read-modify-update with no conflict retry; concurrent plan writes (especially status updates) can make this fail with 409 Conflict. Consider using retry.RetryOnConflict around the full mutation or switching to a Patch-based update to avoid forcing users to rerun the command.

	_, err = cl.Resource(gpuRecoveryPlanGVR).Update(
		context.Background(), plan, metav1.UpdateOptions{},
	)

	return err

• Files reviewed: 17/17 changed files
• Comments generated: 4
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.