Feature/generic subresource

[AnnaYue]

1. Does this PR affect any open issues?(Y/N) and add issue references (e.g. "fix #123", "re #123".):

• N
• Y

2. What is the scope of this PR (e.g. component or file name):

3. Provide a description of the PR(e.g. more details, effects, motivations or doc link):

• Affects user behaviors
• Contains syntax changes
• Contains variable changes
• Contains experimental features
• Performance regression: Consumes more CPU
• Performance regression: Consumes more Memory
• Other

4. Are there any breaking changes?(Y/N) and describe the breaking changes(e.g. more details, motivations or doc link):

• N
• Y

5. Are there test cases for these changes?(Y/N) select and add more details, references or doc links:

• Unit test
• Integration test
• Benchmark (add benchmark stats below)
• Manual test (add detailed scripts or steps below)
• Other

6. Release note

Please refer to Release Notes Language Style Guide to write a quality release note.

None

[Copilot]

Pull request overview

This PR refactors kube-xset’s subresource handling from a PVC-specific implementation to a generic, adapter-driven SubResourceControl, and adds controller-configurable target name prefixes.

Changes:

• Replace legacy PVC-only subresource management with a generic SubResourceControl driven by SubResourceAdapter implementations (with bridging support for legacy SubResourcePvcAdapter).
• Update sync/scale/update/replace flows to operate on generic subresources (ExistingSubResources, template-change detection, orphan/adopt/reclaim).
• Add TargetPrefixGetter support and update GetTargetsPrefix behavior + tests.

Reviewed changes

Copilot reviewed 20 out of 21 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
xset_controller.go	Wires SubResourceControl into controller setup and deletion-time reclaim flow.
synccontrols/x_utils.go	Adds controller-provided target prefix override; adjusts generateName behavior.
synccontrols/x_utils_test.go	Unit tests for updated GetTargetsPrefix signature/behavior.
synccontrols/x_update.go	Switches update checks from PVC template change to generic subresource template change.
synccontrols/x_scale.go	Replaces PVC orphan/adopt logic with SubResourceControl include/exclude handling.
synccontrols/x_replace.go	Replaces PVC provisioning with generic subresource creation for replace-created targets.
synccontrols/types.go	Changes SyncContext to store ExistingSubResources and renames update-change flag.
synccontrols/sync_control.go	Integrates subresource listing/adoption/cleanup, creation on scale-out, deletion on scale-in, and template-change update hooks; refactors BatchDeleteTargetsByLabel.
subresources/utils.go	Introduces shared helpers (template hashing, key formatting, truncation, label helpers).
subresources/utils_test.go	Adds unit tests for new utility helpers.
subresources/subresource_control.go	New generic subresource controller implementation (list/adopt/create/delete/orphan/check).
subresources/subresource_control_test.go	Adds initial tests/skeletons for subresource control.
subresources/getter.go	Adds adapter discovery + legacy PVC adapter bridge (BuildAdapters, PvcSubResourceAdapter).
subresources/getter_test.go	Tests adapter discovery/bridging logic.
subresources/pvc_control.go	Removes the legacy PVC-only control implementation.
api/xset_controller_types.go	Adds SubResourceAdapterGetter and TargetPrefixGetter optional interfaces.
api/well_knowns.go	Adds generic subresource template label keys (with PVC label backward compatibility).
api/well_knowns_test.go	Tests label alias/backward compatibility behavior.
api/subresource_types.go	Introduces SubResourceAdapter, SubResourceDecorator, and SubResourceTemplate API types.
CLAUDE.md	Adds project guide documentation describing the new architecture and usage patterns.
.gitignore	Adds ignores for worktrees and local planning artifacts.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

GetTargetsPrefix no longer validates whether the default "{controllerName}-" prefix is a valid DNS subdomain (or within length limits). If controllerName is already at the max length, adding "-" can make GenerateName invalid and cause target creation to fail. Consider restoring the previous validation/fallback behavior (or truncating safely) for the default case; keep override behavior as-is if you intentionally delegate validation to the controller.

[Copilot]

SyncTargets now deletes "unused" subresources for every active target. With the new generic deletion logic, this can delete subresources that are still referenced by the running target (e.g., PVC template removed from XSet spec but the Pod still mounts it until the Pod is recreated), which can break workloads. Defer deletion until the target is being deleted/recreated, or make DeleteTargetUnusedResources verify the subresource is not currently in use by the target before deleting.

Suggested change

	// delete unused subresources
	if r.subResourceControl != nil {
	// delete unused subresources only when the target is already being removed/recreated.
	// Active targets may still reference subresources that are no longer present in the
	// latest spec until the target is actually recreated.
	if r.subResourceControl != nil && (target.GetDeletionTimestamp() != nil || targetDuringReplace(r.xsetLabelAnnoMgr, target)) {

[Copilot]

The doc comment for BatchDeleteTargetsByLabel still says PVC cleanup is handled by ensureReclaimPvcs in xset_controller.go, but that function was removed and cleanup is now routed through SubResourceControl/ReclaimSubResourcesOnDeletion. Please update the comment to reflect the current deletion/cleanup flow to avoid misleading future changes.

Suggested change

	// Note: PVC cleanup is handled separately by ensureReclaimPvcs in xset_controller.go.
	// Any deletion-related subresource cleanup (including PVC reclamation) is handled separately through
	// SubResourceControl/ReclaimSubResourcesOnDeletion rather than in this method.

[Copilot]

setUpCacheForAdapters silently skips adapters whose GVK isn't registered in the scheme (scheme.New error). That can lead to partially-enabled subresource management with hard-to-debug behavior (e.g., resources created but never listed/adopted/deleted). Consider returning an explicit error (or at least logging) when an adapter's GVK isn't recognized so controller authors know they must add the type to the scheme.

Suggested change

	continue // Skip unknown GVKs
	return fmt.Errorf("failed to set up cache for adapter GVK %s: type is not registered in the scheme; ensure this type is added to the controller scheme: %w", gvk, err)

[Copilot]

deleteResource forcefully removes all finalizers before deleting the subresource. This is risky for resources that rely on finalizers for safety (e.g., PVC protection) and can cause premature deletion/data loss or violate Kubernetes controller contracts. Prefer issuing a normal delete and requeueing while waiting for finalizers/controllers to complete, or make finalizer removal narrowly scoped/opt-in per adapter with clear safety guarantees.

[Copilot]

DeleteTargetUnusedResources deletes "unclaimed" old resources solely based on template presence. For PVCs (and likely other subresources), a template can be removed from the XSet spec while existing targets still reference/mount that resource until they are recreated/updated. Deleting here can remove in-use resources. Consider checking whether the target still references the subresource (adapter-provided usage check) before deletion, or only performing this cleanup when the target is terminating.

Suggested change

	// Delete unclaimed old resources (not in templates)
	for templateName, state := range oldResources {
	// If resource template is still in use, keep it
	if templateNames[templateName] {
	continue
	}
	if err := sc.deleteResource(ctx, xset, state.Object, state.GVK); err != nil {
	return fmt.Errorf("failed to delete unclaimed %s %s: %w", gvk.Kind, state.Object.GetName(), err)
	// Delete old resources whose templates were removed only when the target is terminating.
	// A template may be removed from the XSet while an existing target still references the
	// previously created subresource until that target is recreated or updated.
	if target.GetDeletionTimestamp() != nil {
	for templateName, state := range oldResources {
	// If resource template is still in use, keep it
	if templateNames[templateName] {
	continue
	}
	if err := sc.deleteResource(ctx, xset, state.Object, state.GVK); err != nil {
	return fmt.Errorf("failed to delete unclaimed %s %s: %w", gvk.Kind, state.Object.GetName(), err)
	}

[Copilot]

Several tests here define table cases but the t.Run bodies are empty and make no assertions, so they add no coverage and can be misleading. Either implement meaningful unit tests (e.g., with a fake client + index/selector behavior) or remove these placeholder tests until they’re ready.