readme.md

keps/2145-list-admitted-workloads/README.md

@@ -33,21 +33,66 @@ visibility endpoint, users can list running workloads by `kubectl get`.
 
 ### Non-Goals
 
-
 ## Proposal
 
-We will add a new visibility endpoint in Kueue. Users can list the running workloads by using
-``` bash
-kubectl get --raw "/apis/visibility.kueue.x-k8s.io/v1alpha1/clusterqueues/cluster-queue/runningworkloads"
+We will add a new visibility endpoint in Kueue. 
+``` go
+// RunningWorkload is a user-facing representation of a running workload that summarizes the relevant information for
+// assumed resources in the cluster queue.
+type RunningWorkload struct {
+	metav1.ObjectMeta `json:"metadata,omitempty"`
+
+	// Priority indicates the workload's priority
+	Priority int32 `json:"priority"`
+	// AdmissionTime indecates the time workloads admitted
+	AdmissionTime metav1.Time `json:"admissionTime"`
+}
+
+// +k8s:openapi-gen=true
+// +kubebuilder:object:root=true
+
+// RunningWorkloadsSummary contains a list of running workloads in the context
+// of the query (within LocalQueue or ClusterQueue).
+type RunningWorkloadsSummary struct {
+	metav1.TypeMeta   `json:",inline"`
+	metav1.ObjectMeta `json:"metadata,omitempty"`
+
+	Items []RunningWorkload `json:"items"`
+}
+
+// +kubebuilder:object:root=true
+type RunningWorkloadsSummaryList struct {
+	metav1.TypeMeta `json:",inline"`
+	metav1.ListMeta `json:"metadata,omitempty"`
+
+	Items []RunningWorkloadsSummary `json:"items"`
+}
+
+// +kubebuilder:object:root=true
+// +k8s:openapi-gen=true
+// +k8s:conversion-gen:explicit-from=net/url.Values
+// +k8s:defaulter-gen=true
+
+// RunningWorkloadOptions are query params used in the visibility queries
+type RunningWorkloadOptions struct {
+	metav1.TypeMeta `json:",inline"`
+
+	// Offset indicates position of the first pending workload that should be fetched, starting from 0. 0 by default
+	Offset int64 `json:"offset"`
+
+	// Limit indicates max number of pending workloads that should be fetched. 1000 by default
+	Limit int64 `json:"limit,omitempty"`
+}
 ```
-and 
+
+Users can list the running workloads by using
 ``` bash
-kubectl get --raw "/apis/visibility.kueue.x-k8s.io/v1alpha1/namespaces/default/localqueues/user-queue/runningworkloads"
+kubectl get --raw "/apis/visibility.kueue.x-k8s.io/v1alpha1/clusterqueues/cluster-queue/runningworkloads"
 ```
 
 We will show priority and localqueue information in response. Like this:
 ```
-{"kind":"RunningWorkloadsSummary","apiVersion":"visibility.kueue.x-k8s.io/v1alpha1","metadata":{"creationTimestamp":null},"items":[{"metadata":{"name":"job-sample-job-jz228-ef938","namespace":"default","creationTimestamp":"2024-05-06T02:15:26Z","ownerReferences":[{"apiVersion":"batch/v1","kind":"Job","name":"sample-job-jz228","uid":"2de8a359-4c95-4159-b677-0279066149b6"}]},"priority":0,"localQueue":"lqA"}]}
+{"kind":"RunningWorkloadsSummary","apiVersion":"visibility.kueue.x-k8s.io/v1alpha1","metadata":{"creationTimestamp":null},"items":[{"metadata":{"name":"job-sample-job-jz228-ef938","namespace":"default","creationTimestamp":"2024-05-06T02:15:26Z","ownerReferences":[{"apiVersion":"batch/v1","kind":"Job","name":"sample-job-jz228","uid":"2de8a359-4c95-4159-b677-0279066149b6"}]},"priority":0,"admissionTime":"xxxx"}]}
 ```
 
 ### Risks and Mitigations
@@ -83,7 +128,7 @@ implementing this enhancement to ensure the enhancements have also solid foundat
 
 #### Unit Tests
 
-New unit tests should be added testing the functionality for jobs and pods.
+New unit tests should be added testing the functionality for new api.
 
 #### Integration tests