What type of PR is this?

/kind feature
/kind api

What this PR does / why we need it:

Implements GREP-390: Hierarchical Resource Sharing for Grove PodCliqueSets using Kubernetes Dynamic Resource Allocation (DRA).

This PR introduces a flexible, multi-level resource sharing model that allows ResourceClaim objects to be created and shared at the PCS, PCSG, and PCLQ levels with two scoping modes:

• AllReplicas: A single ResourceClaim shared across all replicas of the owner (named <ownerName>-all-<rctName>).
• PerReplica: A dedicated ResourceClaim per replica (named <ownerName>-<replicaIndex>-<rctName>).

Key changes:

1. API types (podcliqueset.go):

• ResourceClaimTemplateConfig for defining inline ResourceClaimTemplate specs at the PCS level, with a TemplateSpec field holding the ResourceClaimTemplateSpec.
• ResourceSharingSpecBase with Name, Scope, and Namespace fields — used directly for PCLQ-level sharing (no filter needed).
• PCSResourceSharingSpec embeds ResourceSharingSpecBase and adds an optional PCSResourceSharingFilter with ChildCliqueNames and ChildScalingGroupNames for targeting specific children.
• PCSGResourceSharingSpec embeds ResourceSharingSpecBase and adds an optional PCSGResourceSharingFilter with only ChildCliqueNames (PCSGs cannot target sibling scaling groups).
• This level-specific type design enforces valid states at the API level — PCLQ entries have no filter field, and PCSG entries cannot specify childScalingGroupNames — eliminating the need for webhook checks on these constraints.
• ResourceSharing field added at PCS ([]PCSResourceSharingSpec), PCSG ([]PCSGResourceSharingSpec), and PCLQ ([]ResourceSharingSpecBase) levels.

2. ResourceClaim lifecycle (internal/resourceclaim/):

• naming.go: Deterministic naming via AllReplicasRCName and PerReplicaRCName.
• resolve.go: Resolves ResourceSharingSpecBase to a ResourceClaimTemplateSpec (internal or external). Includes a defensive namespace check: when base.Namespace is set, internal resolution is skipped to ensure external resolution is used even if webhook validation is bypassed.
• reconcile.go: ResourceSharer interface with GetBase() and FilterMatches() methods, plus ResourceSharersFromPCS, ResourceSharersFromPCSG, ResourceSharersFromPCLQ adapter functions. EnsureResourceClaim uses a Get/Create flow — new RCs are created with the full spec, while existing RCs only receive metadata updates (labels, ownerReference) since ResourceClaim.spec is immutable in Kubernetes. InjectResourceClaimRefs injects both pod-level spec.resourceClaims and container-level resources.claims; DeletePerReplicaRCs handles explicit per-name deletion; CleanupStalePerReplicaRCs handles scale-in cleanup using a unified label selector with server-side DeleteCollection.
• injectAllResourceClaimRefs returns errors instead of silently swallowing them, with failures propagated through buildResource.

3. Ownership model:

Each level owns its own ResourceClaims via SetControllerReference:

• PCS controller: Creates and owns PCS-level AllReplicas and PerReplica ResourceClaims.
• PCSG controller: Creates and owns PCSG-level ResourceClaims.
• PCLQ controller: Creates and owns PCLQ-level AllReplicas and PerReplica ResourceClaims.

This aligns RC lifecycle with the owning resource — deleting a PCLQ, PCSG, or PCS automatically garbage-collects its RCs. Parent controllers (PCS, PCSG) inject claim references into child PodSpecs using filter matching.

4. Scale-in cleanup:

Stale PerReplica RCs are cleaned up using label-based selectors scoped to the owning resource. Each RC is stamped with labels identifying its owner and replica index. The cleanup builds a unified labels.Selector combining equality, Exists, and NotIn requirements to target only stale replicas without affecting other owners.

5. Validation webhooks:

• No duplicate RCT names within a single resourceSharing list.
• Filter must specify at least one name.
• childCliqueNames/childScalingGroupNames in filters must reference actual children defined in the PCS spec.
• Scope validation: rejects invalid scope values as defense-in-depth (in addition to CRD-level +kubebuilder:validation:Enum).
• Immutability enforcement: resourceClaimTemplates and resourceSharing are validated as immutable on update at PCS, PCSG, and PCLQ levels — consistent with the guarantees documented in the README.
• Note: childScalingGroupNames at the PCSG level and Filter at the PCLQ level are prevented by the type system (those types simply don't have those fields), so no webhook checks are needed for them.

6. E2E test (e2e/tests/resource_sharing_test.go):

• 14-step hierarchical resource sharing test (Test_RS1_HierarchicalResourceSharing) covering all filter paths:

  • PCS → childCliqueNames (int-tpl targets worker-a only)
  • PCS → childScalingGroupNames (int-tpl7 targets sga only)
  • PCSG → childCliqueNames (int-tpl8 targets worker-b only)
  • Cross-namespace external RCT (ext-ns-tpl in rs-shared namespace, referenced from PCLQ worker-a)

  Steps:

  1. Create cross-namespace ResourceClaimTemplate (rs-shared/ext-ns-tpl)
  2. Deploy workload with PCS=1, PCSG sga=2 replicas, standalone PCLQ worker-a=1 replica
  3. Verify initial 12 ResourceClaims with correct names, labels, and pod-to-RC references
  4. Verify ownerReferences correctness (PCS→PodCliqueSet, PCSG→PodCliqueScalingGroup, PCLQ→PodClique)
  5. PCSG scale-in (2→1): verify 2 RCs cleaned up (10 remaining)
  6. PCSG scale-out (1→3): verify 4 new RCs created (14 total)
  7. PCLQ scale-out (1→2): verify 1 new PerReplica RC created (15 total), verify per-pod RC wiring (common + unique PerReplica refs)
  8. PCLQ scale-in (2→1): verify 1 PerReplica RC cleaned up (14 remaining)
  9. PCS scale-out (1→2): verify 10 new RCs created (24 total, asymmetric state: rep 0 sga=3, rep 1 sga=2 from template)
  10. PCS scale-in (2→1): verify cleanup back to post-PCSG-scale-out state (14 remaining)
  11. Immutability rejection: attempt to modify resourceSharing scope on a deployed PCS, assert webhook rejects with "field is immutable"

• Added resource_sharing entry to the CI E2E test matrix in .github/workflows/build-check-test.yaml

7. RBAC: Added resourceclaims and resourceclaimtemplates permissions to the operator ClusterRole.

Which issue(s) this PR fixes:

Fixes #390

Special notes for your reviewer:

• The ResourceClaim naming convention uses the RCT name (not an index) for readability and determinism. all replaces the replica index for AllReplicas scope to avoid naming collisions with PerReplica claims.
  • Theoretical RC name collision: Because Kubernetes names only allow [a-z0-9-], there is no reserved delimiter character. The all keyword in <pcs>-all-<tpl> could theoretically collide if a PCS name contains -all- and another PCS+template combination produces the same concatenated string. In practice this requires two PCS instances in the same namespace with overlapping name/template segments, which is extremely unlikely. Random suffixes were considered but rejected because deterministic naming is essential for idempotent reconciliation (Get-by-name), pure in-memory pod injection, and stale RC cleanup. Documented as a known limitation in naming.go.
• InjectResourceClaimRefs injects both pod.spec.resourceClaims (pod-level) and containers[].resources.claims (container-level) for all containers and init containers, which is required by DRA for devices to actually be accessible.
• The API uses level-specific types (PCSResourceSharingSpec, PCSGResourceSharingSpec, ResourceSharingSpecBase) to enforce valid filter combinations at the type level rather than relying solely on webhook validation.
• EnsureResourceClaim uses a Get/Create pattern: new RCs are created with the full spec; existing RCs only get metadata updates (labels, ownerReference). This respects the Kubernetes immutability constraint on ResourceClaim.spec.
• resolveInternalRef includes a defensive namespace check — when base.Namespace is non-empty, internal template resolution is skipped entirely, ensuring external resolution even if webhook validation is bypassed.
• The E2E test exercises all scaling operations at every level (PCSG, standalone PCLQ, PCS) and verifies RC creation/cleanup, pod-to-RC references (including per-pod PerReplica wiring after PCLQ scale-out), ownerReferences, cross-namespace RCT resolution, and immutability webhook rejection — covering all three filter paths (PCS→clique, PCS→scalingGroup, PCSG→clique).

Does this PR introduce an API change?

Added hierarchical resource sharing support (GREP-390) for PodCliqueSets using Kubernetes DRA. New API fields: resourceClaimTemplates and resourceSharing on PodCliqueSetTemplateSpec, resourceSharing on PodCliqueScalingGroupConfig and PodCliqueTemplateSpec. ResourceClaims can be scoped as AllReplicas (shared) or PerReplica (dedicated). Level-specific types enforce valid API states: PCSResourceSharingSpec supports filtering by childCliqueNames and childScalingGroupNames; PCSGResourceSharingSpec supports filtering by childCliqueNames only; ResourceSharingSpecBase (used at PCLQ level) has no filter field. The resourceClaimTemplates and resourceSharing fields are immutable on update at all levels.