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,91 @@
+# Placement Status Proxy API Implementation
+## 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
+- [ ] Task 3.1: Run code generation to ensure API is valid
+- [ ] Task 3.2: Verify CRD generation works properly
+
+## Implementation Status
+- ✅ Added PlacementStatusProxy and PlacementStatusProxyList types
+- ✅ Added proper kubebuilder annotations and documentation
+- ✅ Included naming template in comments: `<clusterResourcePlacementName>-status`
+- ✅ Added finalizer constant
+- ✅ Registered types in scheme
+- ✅ Added EnableStatusProxy boolean field to PlacementSpec to enable/disable proxy creation
+- ✅ Enhanced Status field comment to clarify namespace and resource information display
+- ⚠️ Need to run code generation for DeepCopyObject methods
+
+## Field Design Change
+- **Changed from**: `StatusProxyNamespace *string` - specified target namespace
+- **Changed to**: `EnableStatusProxy bool` - simple enable/disable flag
+- **Rationale**: Namespace is already specified in ResourceSelectors, so we just need a boolean to enable the feature
+- **Behavior**: When enabled, PlacementStatusProxy objects are created in namespaces containing selected resources
+
+## Status Field Enhancement
+- Added clarifying comment that the Status field includes information about the namespace and resources within that namespace
+- Explains that placement details are shown for resources selected by the ClusterResourcePlacement's ResourceSelectors to create a namespaced object that will take the PlacementStatus of a corresponding ClusterResourcePlacement. This will serve as a proxy or mirror of the cluster-scoped CRP status in a namespace-scoped resource.
+
+## Requirements Analysis
+1. Create a new namespaced custom resource
+2. The resource should contain PlacementStatus from corresponding ClusterResourcePlacement
+3. The name should follow a template that includes the ClusterResourcePlacement name
+4. Only implement the API (no controllers needed for now)
+5. Add appropriate documentation as comments
+
+## Implementation Plan
+
+### Phase 1: API Design
+- **Task 1.1**: Analyze existing PlacementStatus structure
+- **Task 1.2**: Design the new namespaced resource structure
+- **Task 1.3**: Define naming convention and template
+- **Task 1.4**: Add appropriate kubebuilder annotations
+
+### Phase 2: API Implementation  
+- **Task 2.1**: Create the new resource type definition
+- **Task 2.2**: Add proper documentation and comments
+- **Task 2.3**: Register the new type in scheme
+- **Task 2.4**: Verify code generation markers
+
+### Phase 3: Validation
+- **Task 3.1**: Run code generation to ensure API is valid
+- **Task 3.2**: Verify CRD generation works properly
+
+## Success Criteria
+- [ ] New namespaced resource is defined with proper structure
+- [ ] Resource includes PlacementStatus from ClusterResourcePlacement
+- [ ] Naming template is documented in comments
+- [ ] Kubebuilder annotations are correctly applied
+- [ ] Code generation produces valid CRDs
+- [ ] Resource is properly registered in scheme
+
+## Naming Convention
+The object name template should be: `<crp-name>-status` 
+This will be documented in the API comments.
+
+Updated from the original `<crp-name>-placement-status` to be shorter and more concise.
+
+## 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
+- [ ] Task 2.4: Verify code generation markers
+- [ ] Task 3.1: Run code generation to ensure API is valid
+- [ ] Task 3.2: Verify CRD generation works properly
+
+## Implementation Status
+- ✅ Added PlacementStatusProxy and PlacementStatusProxyList types
+- ✅ Added proper kubebuilder annotations and documentation
+- ✅ Included naming template in comments: `<clusterResourcePlacementName>-placement-status`
+- ✅ Added finalizer constant
+- ✅ Registered types in scheme
+- ⚠️ Need to run code generation for DeepCopyObject methods

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,67 @@ func (rpl *ResourcePlacementList) GetPlacementObjs() []PlacementObj {
 	return objs
 }
 
+const (
+	// PlacementStatusProxyCleanupFinalizer is a finalizer added by the controller to all PlacementStatusProxy objects, to make sure
+	// that the controller can react to PlacementStatusProxy deletions if necessary.
+	PlacementStatusProxyCleanupFinalizer = fleetPrefix + "placement-status-proxy-cleanup"
+)
+
+// +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.