feat(omnicontrol): add resource topology aggregation backend

pkg/resource/omnicontrol/README.md

@@ -0,0 +1,33 @@
+# OmniControl
+
+Backend package for unified resource topology visualization in Karmada Dashboard.
+
+## Purpose
+
+Aggregates the propagation path of a resource:
+```
+ResourceTemplate → PropagationPolicy → ResourceBinding → Work → Member Cluster
+```
+
+This enables users to trace exactly where a resource is distributed and identify propagation failures.
+
+## Usage
+
+```go
+topology, err := omnicontrol.GetDeploymentTopology(ctx, k8sClient, karmadaClient, "default", "nginx")
+if err != nil {
+    // handle error
+}
+
+if topology.Policy != nil {
+    fmt.Println("Policy:", topology.Policy.Name)
+}
+if topology.Binding != nil {
+    fmt.Println("Binding:", topology.Binding.Name)
+}
+fmt.Println("Clusters:", len(topology.ClusterStatuses))
+```
+
+## Status
+
+**PoC** - Initial implementation for Deployments. Future work includes support for all resource types and API endpoint integration.

pkg/resource/omnicontrol/deployment.go

@@ -0,0 +1,104 @@
+/*
+Copyright 2024 The Karmada Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package omnicontrol
+
+import (
+	"context"
+	"fmt"
+
+	karmadaworkv1alpha1 "github.com/karmada-io/karmada/pkg/apis/work/v1alpha1"
+	karmadaclientset "github.com/karmada-io/karmada/pkg/generated/clientset/versioned"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/apis/meta/v1/unstructured"
+	"k8s.io/apimachinery/pkg/runtime"
+	client "k8s.io/client-go/kubernetes"
+	"k8s.io/klog/v2"
+)
+
+// GetDeploymentTopology returns the propagation topology for a Deployment.
+func GetDeploymentTopology(ctx context.Context, k8sClient client.Interface, karmadaClient karmadaclientset.Interface, namespace, name string) (*ResourceTopology, error) {
+	klog.V(4).InfoS("Building topology", "namespace", namespace, "name", name)
+
+	deployment, err := k8sClient.AppsV1().Deployments(namespace).Get(ctx, name, metav1.GetOptions{})
+	if err != nil {
+		return nil, fmt.Errorf("failed to get deployment %s/%s: %w", namespace, name, err)
+	}
+
+	unstructuredMap, err := runtime.DefaultUnstructuredConverter.ToUnstructured(deployment)
+	if err != nil {
+		return nil, fmt.Errorf("failed to convert deployment: %w", err)
+	}
+
+	topology := &ResourceTopology{
+		Resource: &unstructured.Unstructured{Object: unstructuredMap},
+	}
+
+	// Karmada binding naming: "<name>-<kind>"
+	bindingName := name + "-deployment"
+	rb, err := karmadaClient.WorkV1alpha2().ResourceBindings(namespace).Get(ctx, bindingName, metav1.GetOptions{})
+	if err != nil {
+		klog.V(4).InfoS("ResourceBinding not found", "name", bindingName)
+		return topology, nil
+	}
+	topology.Binding = rb
+
+	// Get policy from binding labels
+	policyName := rb.Labels["propagationpolicy.karmada.io/name"]
+	policyNS := rb.Labels["propagationpolicy.karmada.io/namespace"]
+	if policyNS == "" {
+		policyNS = namespace
+	}
+	if policyName != "" {
+		policy, err := karmadaClient.PolicyV1alpha1().PropagationPolicies(policyNS).Get(ctx, policyName, metav1.GetOptions{})
+		if err == nil {
+			topology.Policy = policy
+		} else {
+			klog.V(4).InfoS("Could not retrieve PropagationPolicy", "namespace", policyNS, "name", policyName, "error", err)
+		}
+	}
+
+	// Get Work objects from execution namespaces
+	for _, status := range rb.Status.AggregatedStatus {
+		execNS := "karmada-es-" + status.ClusterName
+		works, err := karmadaClient.WorkV1alpha1().Works(execNS).List(ctx, metav1.ListOptions{
+			LabelSelector: fmt.Sprintf("resourcebinding.karmada.io/uid=%s", rb.UID),
+		})
+		if err != nil {
+			klog.Warningf("Failed to list works in execution namespace %s: %v", execNS, err)
+			continue
+		}
+
+		for i := range works.Items {
+			topology.ClusterStatuses = append(topology.ClusterStatuses, ClusterStatus{
+				ClusterName: status.ClusterName,
+				SyncStatus:  deriveSyncStatus(&works.Items[i]),
+				Work:        &works.Items[i],
+			})
+		}
+	}
+
+	return topology, nil
+}
+
+func deriveSyncStatus(work *karmadaworkv1alpha1.Work) string {
+	for _, cond := range work.Status.Conditions {
+		if cond.Type == karmadaworkv1alpha1.WorkApplied {
+			return string(cond.Status)
+		}
+	}
+	return "Unknown"
+}

pkg/resource/omnicontrol/deployment_test.go

@@ -0,0 +1,93 @@
+/*
+Copyright 2024 The Karmada Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package omnicontrol
+
+import (
+	"context"
+	"testing"
+
+	karmadapolicyv1alpha1 "github.com/karmada-io/karmada/pkg/apis/policy/v1alpha1"
+	karmadaworkv1alpha2 "github.com/karmada-io/karmada/pkg/apis/work/v1alpha2"
+	karmadafake "github.com/karmada-io/karmada/pkg/generated/clientset/versioned/fake"
+	appsv1 "k8s.io/api/apps/v1"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/client-go/kubernetes/fake"
+)
+
+func TestGetDeploymentTopology_NotFound(t *testing.T) {
+	k8sClient := fake.NewSimpleClientset()
+	karmadaClient := karmadafake.NewSimpleClientset()
+
+	_, err := GetDeploymentTopology(context.Background(), k8sClient, karmadaClient, "default", "nonexistent")
+	if err == nil {
+		t.Error("expected error when deployment does not exist, got nil")
+	}
+}
+
+func TestGetDeploymentTopology_NoBinding(t *testing.T) {
+	deployment := &appsv1.Deployment{
+		ObjectMeta: metav1.ObjectMeta{Name: "nginx", Namespace: "default"},
+	}
+	k8sClient := fake.NewSimpleClientset(deployment)
+	karmadaClient := karmadafake.NewSimpleClientset()
+
+	topology, err := GetDeploymentTopology(context.Background(), k8sClient, karmadaClient, "default", "nginx")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if topology.Binding != nil {
+		t.Error("expected no binding, got one")
+	}
+	if topology.Resource == nil {
+		t.Error("expected resource to be populated")
+	}
+}
+
+func TestGetDeploymentTopology_FullTopology(t *testing.T) {
+	deployment := &appsv1.Deployment{
+		ObjectMeta: metav1.ObjectMeta{Name: "nginx", Namespace: "default"},
+	}
+	policy := &karmadapolicyv1alpha1.PropagationPolicy{
+		ObjectMeta: metav1.ObjectMeta{Name: "nginx-policy", Namespace: "default"},
+	}
+	binding := &karmadaworkv1alpha2.ResourceBinding{
+		ObjectMeta: metav1.ObjectMeta{
+			Name:      "nginx-deployment",
+			Namespace: "default",
+			Labels: map[string]string{
+				"propagationpolicy.karmada.io/name":      "nginx-policy",
+				"propagationpolicy.karmada.io/namespace": "default",
+			},
+		},
+	}
+	k8sClient := fake.NewSimpleClientset(deployment)
+	karmadaClient := karmadafake.NewSimpleClientset(binding, policy)
+
+	topology, err := GetDeploymentTopology(context.Background(), k8sClient, karmadaClient, "default", "nginx")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if topology.Resource == nil {
+		t.Error("expected resource")
+	}
+	if topology.Binding == nil {
+		t.Error("expected binding")
+	}
+	if topology.Policy == nil {
+		t.Error("expected policy")
+	}
+}

pkg/resource/omnicontrol/types.go

@@ -0,0 +1,39 @@
+/*
+Copyright 2024 The Karmada Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package omnicontrol
+
+import (
+	karmadapolicyv1alpha1 "github.com/karmada-io/karmada/pkg/apis/policy/v1alpha1"
+	karmadaworkv1alpha1 "github.com/karmada-io/karmada/pkg/apis/work/v1alpha1"
+	karmadaworkv1alpha2 "github.com/karmada-io/karmada/pkg/apis/work/v1alpha2"
+	"k8s.io/apimachinery/pkg/apis/meta/v1/unstructured"
+)
+
+// ClusterStatus holds the sync state of a resource in a member cluster.
+type ClusterStatus struct {
+	ClusterName string                    `json:"clusterName"`
+	SyncStatus  string                    `json:"syncStatus"`
+	Work        *karmadaworkv1alpha1.Work `json:"work,omitempty"`
+}
+
+// ResourceTopology aggregates a resource's propagation path: Template → Policy → Binding → Work.
+type ResourceTopology struct {
+	Resource        *unstructured.Unstructured               `json:"resource"`
+	Policy          *karmadapolicyv1alpha1.PropagationPolicy `json:"policy,omitempty"`
+	Binding         *karmadaworkv1alpha2.ResourceBinding     `json:"binding,omitempty"`
+	ClusterStatuses []ClusterStatus                          `json:"clusterStatuses,omitempty"`
+}