interface: progress drift/diff detection APIs to v1

apis/placement/v1/binding_types.go

@@ -105,6 +105,30 @@ type ResourceBindingStatus struct {
 	// +optional
 	FailedPlacements []FailedResourcePlacement `json:"failedPlacements,omitempty"`
 
+	// DriftedPlacements is a list of resources that have drifted from their desired states
+	// kept in the hub cluster, as found by Fleet using the drift detection mechanism.
+	//
+	// To control the object size, only the first 100 drifted resources will be included.
+	// This field is only meaningful if the `ClusterName` is not empty.
+	// +kubebuilder:validation:Optional
+	// +kubebuilder:validation:MaxItems=100
+	DriftedPlacements []DriftedResourcePlacement `json:"driftedPlacements,omitempty"`
+
+	// DiffedPlacements is a list of resources that have configuration differences from their
+	// corresponding hub cluster manifests. Fleet will report such differences when:
+	//
+	// * The CRP uses the ReportDiff apply strategy, which instructs Fleet to compare the hub
+	//   cluster manifests against the live resources without actually performing any apply op; or
+	// * Fleet finds a pre-existing resource on the member cluster side that does not match its
+	//   hub cluster counterpart, and the CRP has been configured to only take over a resource if
+	//   no configuration differences are found.
+	//
+	// To control the object size, only the first 100 diffed resources will be included.
+	// This field is only meaningful if the `ClusterName` is not empty.
+	// +kubebuilder:validation:Optional
+	// +kubebuilder:validation:MaxItems=100
+	DiffedPlacements []DiffedResourcePlacement `json:"diffedPlacements,omitempty"`
+
 	// +patchMergeKey=type
 	// +patchStrategy=merge
 	// +listType=map
@@ -156,6 +180,18 @@ const (
 	// - "False" means not all the resources are available in the target cluster yet.
 	// - "Unknown" means we haven't finished the apply yet so that we cannot check the resource availability.
 	ResourceBindingAvailable ResourceBindingConditionType = "Available"
+
+	// ResourceBindingDiffReported indicates that Fleet has successfully reported configuration
+	// differences between the hub cluster and a specific member cluster for the given resources.
+	//
+	// This condition is added only when the ReportDiff apply strategy is used.
+	//
+	// It can have the following condition statuses:
+	// * True: Fleet has successfully reported configuration differences for all resources.
+	// * False: Fleet has not yet reported configuration differences for some resources, or an
+	//   error has occurred.
+	// * Unknown: Fleet has not finished processing the diff reporting yet.
+	ResourceBindingDiffReported ResourceBindingConditionType = "DiffReported"
 )
 
 // ClusterResourceBindingList is a collection of ClusterResourceBinding.

apis/placement/v1/work_types.go

@@ -110,6 +110,74 @@ type WorkResourceIdentifier struct {
 	Name string `json:"name,omitempty"`
 }
 
+// DriftDetails describes the observed configuration drifts.
+type DriftDetails struct {
+	// ObservationTime is the timestamp when the drift was last detected.
+	//
+	// +kubebuilder:validation:Required
+	// +kubebuilder:validation:Type=string
+	// +kubebuilder:validation:Format=date-time
+	ObservationTime metav1.Time `json:"observationTime"`
+
+	// ObservedInMemberClusterGeneration is the generation of the applied manifest on the member
+	// cluster side.
+	// +kubebuilder:validation:Required
+	ObservedInMemberClusterGeneration int64 `json:"observedInMemberClusterGeneration"`
+
+	// FirstDriftedObservedTime is the timestamp when the drift was first detected.
+	//
+	// +kubebuilder:validation:Required
+	// +kubebuilder:validation:Type=string
+	// +kubebuilder:validation:Format=date-time
+	FirstDriftedObservedTime metav1.Time `json:"firstDriftedObservedTime"`
+
+	// ObservedDrifts describes each drifted field found from the applied manifest.
+	// Fleet might truncate the details as appropriate to control object size.
+	//
+	// Each entry specifies how the live state (the state on the member cluster side) compares
+	// against the desired state (the state kept in the hub cluster manifest).
+	//
+	// +kubebuilder:validation:Optional
+	ObservedDrifts []PatchDetail `json:"observedDrifts,omitempty"`
+}
+
+// DiffDetails describes the observed configuration differences.
+type DiffDetails struct {
+	// ObservationTime is the timestamp when the configuration difference was last detected.
+	//
+	// +kubebuilder:validation:Required
+	// +kubebuilder:validation:Type=string
+	// +kubebuilder:validation:Format=date-time
+	ObservationTime metav1.Time `json:"observationTime"`
+
+	// ObservedInMemberClusterGeneration is the generation of the applied manifest on the member
+	// cluster side.
+	//
+	// This might be nil if the resource has not been created yet in the member cluster.
+	//
+	// +kubebuilder:validation:Optional
+	ObservedInMemberClusterGeneration *int64 `json:"observedInMemberClusterGeneration"`
+
+	// FirstDiffedObservedTime is the timestamp when the configuration difference
+	// was first detected.
+	//
+	// +kubebuilder:validation:Required
+	// +kubebuilder:validation:Type=string
+	// +kubebuilder:validation:Format=date-time
+	FirstDiffedObservedTime metav1.Time `json:"firstDiffedObservedTime"`
+
+	// ObservedDiffs describes each field with configuration difference as found from the
+	// member cluster side.
+	//
+	// Fleet might truncate the details as appropriate to control object size.
+	//
+	// Each entry specifies how the live state (the state on the member cluster side) compares
+	// against the desired state (the state kept in the hub cluster manifest).
+	//
+	// +kubebuilder:validation:Optional
+	ObservedDiffs []PatchDetail `json:"observedDiffs,omitempty"`
+}
+
 // ManifestCondition represents the conditions of the resources deployed on
 // spoke cluster.
 type ManifestCondition struct {
@@ -120,6 +188,28 @@ type ManifestCondition struct {
 	// Conditions represents the conditions of this resource on spoke cluster
 	// +required
 	Conditions []metav1.Condition `json:"conditions"`
+
+	// DriftDetails explains about the observed configuration drifts.
+	// Fleet might truncate the details as appropriate to control object size.
+	//
+	// Note that configuration drifts can only occur on a resource if it is currently owned by
+	// Fleet and its corresponding placement is set to use the ClientSideApply or ServerSideApply
+	// apply strategy. In other words, DriftDetails and DiffDetails will not be populated
+	// at the same time.
+	//
+	// +kubebuilder:validation:Optional
+	DriftDetails *DriftDetails `json:"driftDetails,omitempty"`
+
+	// DiffDetails explains the details about the observed configuration differences.
+	// Fleet might truncate the details as appropriate to control object size.
+	//
+	// Note that configuration differences can only occur on a resource if it is not currently owned
+	// by Fleet (i.e., it is a pre-existing resource that needs to be taken over), or if its
+	// corresponding placement is set to use the ReportDiff apply strategy. In other words,
+	// DiffDetails and DriftDetails will not be populated at the same time.
+	//
+	// +kubebuilder:validation:Optional
+	DiffDetails *DiffDetails `json:"diffDetails,omitempty"`
 }
 
 // +genclient