add status proxy for namespace scoped access only

Signed-off-by: Britania Rodriguez Reyes <[email protected]>

Author: britaniar

.github/.copilot/breadcrumbs/2025-07-31-0000-placement-status-proxy-api.md

@@ -0,0 +1,75 @@
+# Placement Status Proxy API Implementation
+
+## Final Implementation Status - COMPLETED ✅
+
+### API Implementation Complete
+- ✅ **PlacementStatusProxy Resource**: Namespaced resource that mirrors ClusterResourcePlacement status
+- ✅ **PlacementStatusProxyList**: List type for the proxy resource
+- ✅ **EnableStatusProxy Field**: Boolean field in ClusterResourcePlacementSpec to enable proxy creation
+- ✅ **Kubebuilder Annotations**: Proper annotations for CRD generation
+- ✅ **Documentation**: Comprehensive comments explaining usage and naming convention
+- ✅ **Code Generation**: DeepCopyObject methods generated successfully
+- ✅ **Schema Registration**: Types properly registered in SchemeBuilder
+- ✅ **Compile Validation**: No compilation errors
+
+### Naming Convention Implemented
+- **Template**: `<clusterResourcePlacementName>-status`
+- **Example**: CRP named "my-app-crp" creates proxy named "my-app-crp-status"
+- **Rationale**: Shorter than original proposal, clear identification of source CRP
+
+### Enhanced Documentation Features
+- **Multi-CRP Namespace Support**: Clear explanation of how multiple CRPs in same namespace are distinguished
+- **Status Field Clarity**: Documentation explains namespace and resource information display
+- **Usage Examples**: Concrete examples of naming patterns
+
+## Completed TODO Checklist ✅
+- [x] Task 1.1: Analyze existing PlacementStatus structure
+- [x] Task 1.2: Design the new namespaced resource structure  
+- [x] Task 1.3: Define naming convention and template
+- [x] Task 1.4: Add appropriate kubebuilder annotations
+- [x] Task 2.1: Create the new resource type definition
+- [x] Task 2.2: Add proper documentation and comments
+- [x] Task 2.3: Register the new type in scheme
+- [x] Task 2.4: Add EnableStatusProxy boolean field to ClusterResourcePlacementSpec
+- [x] Task 3.1: Run code generation to ensure API is valid
+- [x] Task 3.2: Verify CRD generation works properly
+
+## Implementation Journey
+
+### Design Evolution
+1. **Initial Design**: Complex spec with namespace targeting field
+2. **Simplified Design**: Removed spec portion as CRP name provides identification
+3. **Naming Optimization**: Changed from `<CRP_NAME>-placement-status` to `<crp-name>-status`
+4. **Field Design**: Changed from `StatusProxyNamespace *string` to `EnableStatusProxy bool`
+5. **Documentation Enhancement**: Added clarity about namespace and resource information
+
+### Final API Structure
+```go
+type PlacementStatusProxy struct {
+    metav1.TypeMeta   `json:",inline"`
+    metav1.ObjectMeta `json:"metadata,omitempty"`
+    Status PlacementStatus `json:"status,omitempty"`
+}
+
+type PlacementSpec struct {
+    // ... existing fields ...
+    EnableStatusProxy bool `json:"enableStatusProxy,omitempty"`
+}
+```
+
+## Success Criteria - ALL MET ✅
+- [x] New namespaced resource is defined with proper structure
+- [x] Resource includes PlacementStatus from ClusterResourcePlacement
+- [x] Naming template is documented in comments
+- [x] Kubebuilder annotations are correctly applied
+- [x] Code generation produces valid CRDs
+- [x] Resource is properly registered in scheme
+- [x] No compilation errors
+- [x] Multiple CRP support in same namespace clearly documented
+
+## Next Steps for Controller Implementation
+The API is complete and ready for controller implementation. Future work would involve:
+1. Creating a controller to watch ClusterResourcePlacement objects
+2. Creating/updating PlacementStatusProxy objects when EnableStatusProxy=true
+3. Managing lifecycle and cleanup of proxy objects
+4. Handling status synchronization between CRP and proxy objects

apis/placement/v1beta1/clusterresourceplacement_types.go

@@ -148,6 +148,14 @@ type PlacementSpec struct {
 	// +kubebuilder:default=10
 	// +kubebuilder:validation:Optional
 	RevisionHistoryLimit *int32 `json:"revisionHistoryLimit,omitempty"`
+
+	// EnableStatusProxy indicates whether a PlacementStatusProxy object should be created to mirror the placement status.
+	// When enabled, PlacementStatusProxy objects will be created in the same namespaces selected by the ResourceSelectors.
+	// This allows namespace-scoped access to the cluster-scoped ClusterResourcePlacement status.
+	// Defaults to false.
+	// +kubebuilder:default=false
+	// +kubebuilder:validation:Optional
+	EnableStatusProxy bool `json:"enableStatusProxy,omitempty"`
 }
 
 // Tolerations returns tolerations for PlacementSpec to handle nil policy case.
@@ -1495,6 +1503,61 @@ func (rpl *ResourcePlacementList) GetPlacementObjs() []PlacementObj {
 	return objs
 }
 
+// +genclient
+// +genclient:Namespaced
+// +kubebuilder:object:root=true
+// +kubebuilder:resource:scope="Namespaced",shortName=psp,categories={fleet,fleet-placement}
+// +kubebuilder:subresource:status
+// +kubebuilder:storageversion
+// +kubebuilder:printcolumn:JSONPath=`.status.observedResourceIndex`,name="Resource-Index",type=string
+// +kubebuilder:printcolumn:JSONPath=`.metadata.creationTimestamp`,name="Age",type=date
+// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
+
+// PlacementStatusProxy is a namespaced resource that mirrors the PlacementStatus of a corresponding
+// ClusterResourcePlacement object. This allows namespace-scoped access to cluster-scoped placement status.
+//
+// This object will be created within the target namespace that contains resources being managed by the CRP.
+// When multiple ClusterResourcePlacements target the same namespace, each PlacementStatusProxy within that
+// namespace is uniquely identified by its object name, which corresponds to the specific ClusterResourcePlacement
+// that created it.
+//
+// The name of this object should follow the template: <clusterResourcePlacementName>-status
+// where <clusterResourcePlacementName> is the name of the corresponding ClusterResourcePlacement.
+//
+// For example, if you have a ClusterResourcePlacement named "my-app-crp", the corresponding
+// PlacementStatusProxy should be named "my-app-crp-status".
+type PlacementStatusProxy struct {
+	metav1.TypeMeta   `json:",inline"`
+	metav1.ObjectMeta `json:"metadata,omitempty"`
+
+	// The observed status of PlacementStatusProxy which mirrors the PlacementStatus of the corresponding ClusterResourcePlacement.
+	// This includes information about the namespace and resources within that namespace that are being managed by the placement.
+	// The status will show placement details for resources selected by the ClusterResourcePlacement's ResourceSelectors.
+	// +kubebuilder:validation:Optional
+	Status PlacementStatus `json:"status,omitempty"`
+}
+
+// PlacementStatusProxyList contains a list of PlacementStatusProxy.
+// +kubebuilder:resource:scope="Namespaced"
+// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
+type PlacementStatusProxyList struct {
+	metav1.TypeMeta `json:",inline"`
+	metav1.ListMeta `json:"metadata,omitempty"`
+	Items           []PlacementStatusProxy `json:"items"`
+}
+
+// SetConditions sets the conditions of the PlacementStatusProxy.
+func (m *PlacementStatusProxy) SetConditions(conditions ...metav1.Condition) {
+	for _, c := range conditions {
+		meta.SetStatusCondition(&m.Status.Conditions, c)
+	}
+}
+
+// GetCondition returns the condition of the PlacementStatusProxy objects.
+func (m *PlacementStatusProxy) GetCondition(conditionType string) *metav1.Condition {
+	return meta.FindStatusCondition(m.Status.Conditions, conditionType)
+}
+
 func init() {
-	SchemeBuilder.Register(&ClusterResourcePlacement{}, &ClusterResourcePlacementList{}, &ResourcePlacement{}, &ResourcePlacementList{})
+	SchemeBuilder.Register(&ClusterResourcePlacement{}, &ClusterResourcePlacementList{}, &ResourcePlacement{}, &ResourcePlacementList{}, &PlacementStatusProxy{}, &PlacementStatusProxyList{})
 }

apis/placement/v1beta1/zz_generated.deepcopy.go

@@ -1144,6 +1144,14 @@ spec:
           spec:
             description: The desired state of ClusterResourcePlacement.
             properties:
+              enableStatusProxy:
+                default: false
+                description: |-
+                  EnableStatusProxy indicates whether a PlacementStatusProxy object should be created to mirror the placement status.
+                  When enabled, PlacementStatusProxy objects will be created in the same namespaces selected by the ResourceSelectors.
+                  This allows namespace-scoped access to the cluster-scoped ClusterResourcePlacement status.
+                  Defaults to false.
+                type: boolean
               policy:
                 description: |-
                   Policy defines how to select member clusters to place the selected resources.