Querying a Federated Workload

Function

This API is used to query a federated workload.

URI

GET /v1/clustergroups/{clustergroupid}/unitedworkload

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
clustergroupid	Yes	String	Fleet ID

**Table 2** Query Parameters
Parameter	Mandatory	Type	Description
kind	Yes	String	Workload type
namespace	No	String	Namespace
name	No	String	Workload name

Request Parameters

**Table 3** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	No	String	Identity authentication information. Requests for calling an API can be authenticated using either a token or AK/SK. If token-based authentication is used, this parameter is mandatory and must be set to a user token.

Response Parameters

Status code: 200

**Table 4** Response body parameters
Parameter	Type	Description
kind	String	Resource type. Options: Deployment: manages stateless applications. Service: implements service discovery and load balancing. Ingress: manages external HTTP/HTTPS access to services in a cluster. ConfigMap: stores non-sensitive configuration data. Secret: stores sensitive information. Job: runs one-off tasks. StatefulSet: manages stateful applications. DaemonSet: runs a pod on each node. PersistentVolumeClaim: requests and uses persistent storage resources.
apiVersion	String	API version
metadata	ObjectMeta object	Workload metadata
template	Object	Application template to be deployed
propagationPolicy	PropagationPolicy object	Policy for propagating resources across clusters
overridePolicy	OverridePolicy object	Resource override policy
resourceBinding	ResourceBinding object	Binding between resources and propagation policies

**Table 5** PropagationPolicy
Parameter	Type	Description
kind	String	API type. The value is fixed at PropagationPolicy.
apiVersion	String	API version
metadata	ObjectMeta object	Basic information
spec	PropagationSpec object	Propagation policy description

**Table 6** PropagationSpec
Parameter	Type	Description
resourceSelectors	Array of ResourceSelector objects	Resource selector, which is used to select resources to be propagated.
propagateDeps	Boolean	Whether to automatically propagate the referent.
placement	Placement object	Rule for defining the clusters that resources are propagated to
priority	Integer	Policy priority. The default value is 0.
schedulerName	String	Scheduler name. The default value is default-scheduler.

**Table 7** OverridePolicy
Parameter	Type	Description
kind	String	API type. The value is fixed at OverridePolicy.
apiVersion	String	API version
spec	OverrideSpec object	Override policy description

**Table 8** OverrideSpec
Parameter	Type	Description
resourceSelectors	Array of ResourceSelector objects	Resource selector, which restricts the resource types that the override policy is applied to
overriders	Object	Override rule that will be applied to resources

**Table 9** ResourceSelector
Parameter	Type	Description
apiVersion	String	API version of the target resource
kind	String	Type of the target resource
namespace	String	Name of the target resource
name	String	Namespace of the target resource

**Table 10** ResourceBinding
Parameter	Type	Description
kind	String	API type. The value is fixed at ResourceBinding.
apiVersion	String	API version
metadata	ObjectMeta object	Resource metadata
spec	ResourceBindingSpec object	Desired resource binding behavior
status	ResourceBindingStatus object	Current status of the resource binding

**Table 11** ObjectMeta
Parameter	Type	Description
uid	String	Resource ID
name	String	Resource name
generateName	String	If no name is provided, the server uses the prefix to generate a unique name.
namespace	String	Namespace
labels	Map<String,String>	Label
annotations	Map<String,String>	Annotation
creationTimestamp	String	Creation time
updateTimestamp	String	Update time
resourceVersion	String	Internal version of a resource
generation	String	Generation of the desired resource state
managedFields	Array of ManagedFieldsEntry objects	Fields managed by workflows
ownerReferences	Array of OwnerReference objects	Ownership, dependencies, and garbage collection mechanism of objects. It supports resource management by the controller.

**Table 12** ManagedFieldsEntry
Parameter	Type	Description
manager	String	Manager name
operation	String	Operation type that causes this entry being created. The value can only be Apply or Update.
apiVersion	String	Resource API version used by a manager for defining fields
time	String	Timestamp when this entry was created or last updated
fieldsType	String	Field structure format. The value is fixed at "FieldsV1".
fieldsV1	Object	Information about the managed fields

**Table 13** OwnerReference
Parameter	Type	Description
apiVersion	String	API version of the referent
kind	String	Type of the referent
name	String	Name of the referent
uid	String	UID of the referent
controller	Boolean	If the value is true, this reference points to the controller that manages the resource.
blockOwnerDeletion	Boolean	If the value is true and the owner has a finalizer named foregroundDeletion, the owner cannot be deleted until this reference is removed.

**Table 14** ResourceBindingSpec
Parameter	Type	Description
resource	Object	Kubernetes resource reference to be propagated
propagateDeps	Boolean	Whether to automatically propagate related resources
replicaRequirements	Object	Requirements for each replica
replicas	Integer	The number of replicas to be created
placement	Placement object	Cluster selection rule
clusters	Array of TargetCluster objects	Target member cluster list

**Table 15** Placement
Parameter	Type	Description
clusterAffinity	ClusterAffinity object	Cluster affinity rule
clusterTolerations	Array of Toleration objects	Cluster tolerance rule
replicaScheduling	Object	The way how to allocate replicas across member clusters

**Table 16** ClusterAffinity
Parameter	Type	Description
clusterNames	Array of strings	List of cluster names to be selected
exclude	Array of strings	List of cluster names to be excluded

**Table 17** Toleration
Parameter	Type	Description
key	String	Key name of the taint to be tolerated
operator	String	Relationship between the key and value. The value can be Exists or Equal. The default value is Equal.
value	String	Taint value to be matched. When Operator is set to Exists, Value must be empty.
effect	String	Taint effect to be matched. The value can be NoSchedule, PreferNoSchedule, or NoExecute. If the value is empty, all effects are matched.
tolerationSeconds	Integer	Duration during which a pod can tolerate a taint. This parameter is valid only for NoExecute.

**Table 18** TargetCluster
Parameter	Type	Description
name	String	Name of the target cluster
replicas	String	The number of replicas created in a cluster

**Table 19** ResourceBindingStatus
Parameter	Type	Description
schedulerObservedGeneration	Integer	Generation of the resource observed by the scheduler
conditions	Array of ConditionStatus objects	Resource status conditions

**Table 20** ConditionStatus
Parameter	Type	Description
type	String	Status type
status	String	Status
observedgeneration	Integer	Version of a status object
lastTransitionTime	String	Last status update time
reason	String	Cause of status
message	String	Status information

Status code: 400

**Table 21** Response body parameters
Parameter	Type	Description
-	String	-

Status code: 403

**Table 22** Response body parameters
Parameter	Type	Description
-	String	-

Status code: 404

**Table 23** Response body parameters
Parameter	Type	Description
-	String	-

Status code: 500

**Table 24** Response body parameters
Parameter	Type	Description
-	String	-

Example Requests

None

Example Responses

Status code: 200

Federated workload information obtained

{
	"kind": "Deployment",
	"apiVersion": "apps/v1",
	"metadata": {
		"name": "test1111111",
		"namespace": "default",
		"creationTimestamp": null
	},
	"template": {},
	"propagationPolicy": {
		"kind": "PropagationPolicy",
		"apiVersion": "policy.karmada.io/v1alpha1",
		"metadata": {
			"name": "test1111111-deployment",
			"namespace": "default",
			"uid": "ba1c3027-0084-4194-9cb9-e29adaf88712",
			"resourceVersion": "62874",
			"generation": 2,
			"creationTimestamp": "2025-10-30T13:03:02Z",
			"labels": {
				"propagationpolicy.karmada.io/permanent-id": "51b25f78-1c19-4e0b-82b2-93a7f92b01f8"
			},
			"finalizers": [
				"karmada.io/propagation-policy-controller"
			]
		},
		"spec": {
			"resourceSelectors": [
				{
					"apiVersion": "apps/v1",
					"kind": "Deployment",
					"namespace": "default",
					"name": "test1111111"
				}
			],
			"propagateDeps": true,
			"placement": {
				"clusterAffinity": {
					"clusterNames": [
						"test"
					]
				},
				"clusterTolerations": [
					{
						"key": "cluster.karmada.io/not-ready",
						"operator": "Exists"
					}
				]
			},
			"priority": 0,
			"schedulerName": "default-scheduler"
		}
	},
	"overridePolicy": {
		"kind": "OverridePolicy",
		"apiVersion": "policy.karmada.io/v1alpha1",
		"metadata": {
			"name": "test1111111-deployment",
			"namespace": "default",
			"uid": "9def0688-474c-4cb9-bdaa-55ddb689e76c",
			"resourceVersion": "60554",
			"generation": 1,
			"creationTimestamp": "2025-10-30T13:03:02Z"
		},
		"spec": {
			"resourceSelectors": [
				{
					"apiVersion": "apps/v1",
					"kind": "Deployment",
					"namespace": "default",
					"name": "test1111111"
				}
			],
			"overriders": {}
		}
	},
	"resourceBinding": {
		"kind": "ResourceBinding",
		"apiVersion": "work.karmada.io/v1alpha2",
		"metadata": {
			"name": "test1111111-deployment",
			"namespace": "default",
			"uid": "ae97e9db-3550-4ef8-b737-191ea87a7fa1",
			"resourceVersion": "86599",
			"generation": 13,
			"creationTimestamp": "2025-10-30T13:03:03Z",
			"labels": {
				"propagationpolicy.karmada.io/name": "test1111111-deployment",
				"propagationpolicy.karmada.io/namespace": "default"
			},
			"ownerReferences": [
				{
					"apiVersion": "apps/v1",
					"kind": "Deployment",
					"name": "test1111111",
					"uid": "84cffd49-f561-4214-afcd-e58dae2670bb",
					"controller": true,
					"blockOwnerDeletion": true
				}
			],
			"finalizers": [
				"karmada.io/binding-controller",
				"karmada.io/binding-dependencies-distributor"
			],
		},
		"spec": {
			"resource": {
				"apiVersion": "apps/v1",
				"kind": "Deployment",
				"namespace": "default",
				"name": "test1111111",
				"uid": "84cffd49-f561-4214-afcd-e58dae2670bb",
				"resourceVersion": "69362"
			},
			"propagateDeps": true,
			"replicaRequirements": {},
			"replicas": 1,
			"clusters": [
				{
					"name": "test",
					"replicas": 1
				}
			],
			"placement": {
				"clusterAffinity": {
					"clusterNames": [
						"test"
					]
				}
			},
			"schedulerName": "default-scheduler"
		},
		"status": {
			"schedulerObservedGeneration": 13,
			"conditions": [
				{
					"type": "FullyApplied",
					"status": "True",
					"lastTransitionTime": "2025-10-30T14:23:19Z",
					"reason": "FullyAppliedSuccess",
					"message": "All works have been successfully applied"
				}
			]
		}
	}
}

Status Codes

Status Code	Description
200	Federated workload information obtained
400	Client request error. The server could not execute the request.
403	The server refused the request.
404	Resources not found
500	Internal server error