Keep Alpha Visibility API.

apis/visibility/v1alpha1/conversion_test.go

@@ -0,0 +1,93 @@
+/*
+Copyright 2023 The Kubernetes 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 v1alpha1
+
+import (
+	"net/url"
+	"testing"
+
+	"github.com/google/go-cmp/cmp"
+	"k8s.io/apimachinery/pkg/runtime"
+	"k8s.io/apimachinery/pkg/util/diff"
+)
+
+func TestPendingWorkloadsOptions(t *testing.T) {
+	scheme := runtime.NewScheme()
+	err := AddToScheme(scheme)
+	if err != nil {
+		t.Fatal(err)
+	}
+	codec := runtime.NewParameterCodec(scheme)
+
+	cases := map[string]struct {
+		inputQueryParams           url.Values
+		wantQueryParams            url.Values
+		wantPendingWorkloadOptions PendingWorkloadOptions
+	}{
+		"correct parameters": {
+			inputQueryParams: url.Values{
+				"limit":  {"1"},
+				"offset": {"2"},
+			},
+			wantQueryParams: url.Values{
+				"limit":  {"1"},
+				"offset": {"2"},
+			},
+			wantPendingWorkloadOptions: PendingWorkloadOptions{
+				Limit:  1,
+				Offset: 2,
+			},
+		},
+		"default values": {
+			inputQueryParams: url.Values{
+				"limit":  {"0"},
+				"offset": {"0"},
+			},
+			wantQueryParams: url.Values{
+				"limit":  {"1000"},
+				"offset": {"0"},
+			},
+			wantPendingWorkloadOptions: PendingWorkloadOptions{
+				Limit:  1000,
+				Offset: 0,
+			},
+		},
+	}
+
+	for name, tc := range cases {
+		t.Run(name, func(t *testing.T) {
+			// versioned -> query params
+			actualParameters, err := codec.EncodeParameters(&tc.wantPendingWorkloadOptions, SchemeGroupVersion)
+			if err != nil {
+				t.Fatal(err)
+			}
+			if d := cmp.Diff(actualParameters, tc.wantQueryParams); d != "" {
+				t.Fatalf("Unexpected serialization:\n%s", diff.ObjectGoPrintSideBySide(tc.wantQueryParams, actualParameters))
+			}
+
+			// query params -> versioned
+			convertedPendingWorkloadOptions := PendingWorkloadOptions{}
+			err = codec.DecodeParameters(tc.inputQueryParams, SchemeGroupVersion, &convertedPendingWorkloadOptions)
+			if err != nil {
+				t.Fatal(err)
+			}
+			if d := cmp.Diff(convertedPendingWorkloadOptions, tc.wantPendingWorkloadOptions); d != "" {
+				t.Fatalf("Unexpected deserialization:\n%s", diff.ObjectGoPrintSideBySide(tc.wantPendingWorkloadOptions, convertedPendingWorkloadOptions))
+			}
+		})
+	}
+}

apis/visibility/v1alpha1/defaults.go

@@ -0,0 +1,37 @@
+/*
+Copyright 2023 The Kubernetes 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 v1alpha1
+
+import (
+	"k8s.io/apimachinery/pkg/runtime"
+)
+
+func init() {
+	localSchemeBuilder.Register(addDefaultingFuncs)
+}
+
+func addDefaultingFuncs(scheme *runtime.Scheme) error {
+	return RegisterDefaults(scheme)
+}
+
+//nolint:revive // format required by generated code for defaulting
+func SetDefaults_PendingWorkloadOptions(obj *PendingWorkloadOptions) {
+	defaultPendingWorkloadsLimit := int64(1000)
+	if obj.Limit == 0 {
+		obj.Limit = defaultPendingWorkloadsLimit
+	}
+}

apis/visibility/v1alpha1/doc.go

@@ -0,0 +1,23 @@
+/*
+Copyright 2023 The Kubernetes 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.
+*/
+
+// +kubebuilder:object:generate=true
+// +kubebuilder:skip
+// +groupName=visibility.kueue.x-k8s.io
+// +k8s:openapi-gen=true
+// +k8s:conversion-gen=false
+
+package v1alpha1

apis/visibility/v1alpha1/groupversion_info.go

@@ -0,0 +1,53 @@
+/*
+Copyright 2023 The Kubernetes 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 v1alpha1 contains API Schema definitions for the pending workloads kueue v1alpha1 API group
+// +kubebuilder:object:generate=true
+// +kubebuilder:skip
+// +groupName=visibility.kueue.x-k8s.io
+// +k8s:openapi-gen=true
+// +k8s:conversion-gen=false
+
+package v1alpha1
+
+import (
+	"k8s.io/apimachinery/pkg/runtime/schema"
+	"sigs.k8s.io/controller-runtime/pkg/scheme"
+)
+
+var (
+	// GroupVersion is group version used to register these objects.
+	GroupVersion = schema.GroupVersion{Group: "visibility.kueue.x-k8s.io", Version: "v1alpha1"}
+
+	// SchemeGroupVersion is alias to GroupVersion for client-go libraries.
+	// It is required by pkg/client/informers/externalversions/...
+	SchemeGroupVersion = GroupVersion
+
+	// SchemeBuilder is used to add go types to the GroupVersionKind scheme
+	SchemeBuilder = &scheme.Builder{GroupVersion: GroupVersion}
+
+	// localSchemeBuilder is used to register autogenerated conversion and defaults functions
+	// It is required by ./zz_generated.conversion.go and ./zz_generated.defaults.go
+	localSchemeBuilder = &SchemeBuilder.SchemeBuilder
+
+	// AddToScheme adds the types in this group-version to the given scheme.
+	AddToScheme = SchemeBuilder.AddToScheme
+)
+
+// Resource is required by pkg/client/listers/...
+func Resource(resource string) schema.GroupResource {
+	return GroupVersion.WithResource(resource).GroupResource()
+}

apis/visibility/v1alpha1/types.go

@@ -0,0 +1,113 @@
+/*
+Copyright 2023 The Kubernetes 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 v1alpha1
+
+import (
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+)
+
+// +genclient
+// +kubebuilder:object:root=true
+// +k8s:openapi-gen=true
+// +genclient:nonNamespaced
+// +genclient:method=GetPendingWorkloadsSummary,verb=get,subresource=pendingworkloads,result=sigs.k8s.io/kueue/apis/visibility/v1alpha1.PendingWorkloadsSummary
+type ClusterQueue struct {
+	metav1.TypeMeta   `json:",inline"`
+	metav1.ObjectMeta `json:"metadata,omitempty"`
+
+	Summary PendingWorkloadsSummary `json:"pendingWorkloadsSummary"`
+}
+
+// +kubebuilder:object:root=true
+type ClusterQueueList struct {
+	metav1.TypeMeta `json:",inline"`
+	metav1.ListMeta `json:"metadata,omitempty"`
+
+	Items []ClusterQueue `json:"items"`
+}
+
+// +genclient
+// +kubebuilder:object:root=true
+// +k8s:openapi-gen=true
+// +genclient:method=GetPendingWorkloadsSummary,verb=get,subresource=pendingworkloads,result=sigs.k8s.io/kueue/apis/visibility/v1alpha1.PendingWorkloadsSummary
+type LocalQueue struct {
+	metav1.TypeMeta   `json:",inline"`
+	metav1.ObjectMeta `json:"metadata,omitempty"`
+
+	Summary PendingWorkloadsSummary `json:"pendingWorkloadsSummary"`
+}
+
+// +kubebuilder:object:root=true
+type LocalQueueList struct {
+	metav1.TypeMeta `json:",inline"`
+	metav1.ListMeta `json:"metadata,omitempty"`
+
+	Items []LocalQueue `json:"items"`
+}
+
+// PendingWorkload is a user-facing representation of a pending workload that summarizes the relevant information for
+// position in the cluster queue.
+type PendingWorkload struct {
+	metav1.ObjectMeta `json:"metadata,omitempty"`
+
+	// Priority indicates the workload's priority
+	Priority int32 `json:"priority"`
+
+	// LocalQueueName indicates the name of the LocalQueue the workload is submitted to
+	LocalQueueName string `json:"localQueueName"`
+
+	// PositionInClusterQueue indicates the workload's position in the ClusterQueue, starting from 0
+	PositionInClusterQueue int32 `json:"positionInClusterQueue"`
+
+	// PositionInLocalQueue indicates the workload's position in the LocalQueue, starting from 0
+	PositionInLocalQueue int32 `json:"positionInLocalQueue"`
+}
+
+// +k8s:openapi-gen=true
+// +kubebuilder:object:root=true
+
+// PendingWorkloadsSummary contains a list of pending workloads in the context
+// of the query (within LocalQueue or ClusterQueue).
+type PendingWorkloadsSummary struct {
+	metav1.TypeMeta   `json:",inline"`
+	metav1.ObjectMeta `json:"metadata,omitempty"`
+
+	Items []PendingWorkload `json:"items"`
+}
+
+// +kubebuilder:object:root=true
+// +k8s:openapi-gen=true
+// +k8s:conversion-gen:explicit-from=net/url.Values
+// +k8s:defaulter-gen=true
+
+// PendingWorkloadOptions are query params used in the visibility queries
+type PendingWorkloadOptions 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"`
+}
+
+func init() {
+	SchemeBuilder.Register(
+		&PendingWorkloadsSummary{},
+		&PendingWorkloadOptions{},
+	)
+}