Add steps how to access VisibilityOnDemand via curl (kubernetes-sigs#…

…3160) * Add steps how to access VisibilityOnDemand via curl. Co-authored-by: Marek Molisch <[email protected]> * Review remarks. --------- Co-authored-by: Marek Molisch <[email protected]>
openshift-kannon92 · Nov 19, 2024 · 981fe99 · 981fe99
1 parent 1fb9bb0
commit 981fe99
Show file tree

Hide file tree

Showing 2 changed files with 226 additions and 3 deletions.
diff --git a/...t/en/docs/tasks/manage/monitor_pending_workloads/pending_workloads_on_demand.md b/...t/en/docs/tasks/manage/monitor_pending_workloads/pending_workloads_on_demand.md
@@ -1,6 +1,6 @@
 ---
 title: "Pending Workloads on-demand"
-date: 2024-09-19
+date: 2024-09-30
 weight: 3
 description: >
   Monitor pending Workloads with the on-demand visibility API
@@ -31,6 +31,39 @@ To install the [API Priority and Fairness](https://kubernetes.io/docs/concepts/c
 {{< tab header="Kubernetes 1.28" >}} kubectl apply --server-side -f https://github.com/kubernetes-sigs/kueue/releases/download/{{< param "version" >}}/visibility-apf-1-28.yaml {{< /tab >}}
 {{< /tabpane >}}
 
+### Directly accessing the Visibility API
+
+If you want to directly access the Visibility API with a http client like 
+`curl` or `wget`, or a browser, there are multiple ways you can locate and 
+authenticate against the Visibility API server:
+
+#### (Recommended) Using kubectl proxy
+
+Run kubectl in proxy mode. This method is recommended, since it uses 
+the stored API server location and verifies the identity of the API server using 
+a self-signed certificate. No man-in-the-middle (MITM) attack is possible using 
+this method. 
+
+For more details, see [kubectl documentation](https://kubernetes.io/docs/tasks/administer-cluster/access-cluster-api/#using-kubectl-proxy).
+
+#### Without kubectl proxy
+
+Alternatively, you can provide the location and credentials directly to the http client. 
+This works with client code that is confused by proxies. To protect against man in 
+the middle attacks, you'll need to import a root cert into your browser.
+
+For more details, see [kubectl documentation](https://kubernetes.io/docs/tasks/administer-cluster/access-cluster-api/#without-kubectl-proxy).
+
+You then need to create `ClusterRole` and `ClusterRoleBinding` for that same (default) k8s service account
+
+{{< include "examples/visibility/cluster-role-and-binding.yaml" "yaml" >}}
+
+using a command:
+
+```shell
+kubectl apply -f https://kueue.sigs.k8s.io/examples/admin/cluster-role-and-binding.yaml
+```
+
 ## Monitor pending workloads on demand
 
 {{< feature-state state="beta" for_version="v0.9" >}}
@@ -63,7 +96,7 @@ for i in {1..6}; do kubectl create -f https://kueue.sigs.k8s.io/examples/jobs/sa
 
 3 of them saturate the ClusterQueue and the other 3 should be pending.
 
-### Cluster Queue visibility
+### Cluster Queue visibility via kubectl
 
 To view pending workloads in ClusterQueue `cluster-queue` run the following command:
 
@@ -185,7 +218,88 @@ You should get results similar to
 }
 ```
 
-### Local Queue visibility
+### Cluster Queue visibility via curl
+
+If you followed steps described in [Directly accessing the Visibility API](#directly-accessing-the-visibility-api) above,
+you can use curl to view pending workloads in ClusterQueue using following commands:
+
+{{< tabpane lang="shell" persist=disabled >}}
+{{< tab header="Using kubectl proxy" >}} curl http://localhost:8080/apis/visibility.kueue.x-k8s.io/v1beta1/clusterqueues/cluster-queue/pendingworkloads {{< /tab >}}
+{{< tab header="Without kubectl proxy" >}} curl -X GET $APISERVER/apis/visibility.kueue.x-k8s.io/v1beta1/clusterqueues/cluster-queue/pendingworkloads --header "Authorization: Bearer $TOKEN" --insecure {{< /tab >}}
+{{< /tabpane >}}
+
+You should get results similar to:
+
+```json
+{
+  "kind": "PendingWorkloadsSummary",
+  "apiVersion": "visibility.kueue.x-k8s.io/v1beta1",
+  "metadata": {
+    "creationTimestamp": null
+  },
+  "items": [
+    {
+      "metadata": {
+        "name": "job-sample-job-z8sc5-223e8",
+        "namespace": "default",
+        "creationTimestamp": "2024-09-29T10:58:32Z",
+        "ownerReferences": [
+          {
+            "apiVersion": "batch/v1",
+            "kind": "Job",
+            "name": "sample-job-z8sc5",
+            "uid": "7086b1bb-39b7-42e5-9f6b-ee07d0100051"
+          }
+        ]
+      },
+      "priority": 0,
+      "localQueueName": "user-queue",
+      "positionInClusterQueue": 0,
+      "positionInLocalQueue": 0
+    },
+    {
+      "metadata": {
+        "name": "job-sample-job-2mfzb-28f54",
+        "namespace": "default",
+        "creationTimestamp": "2024-09-29T10:58:32Z",
+        "ownerReferences": [
+          {
+            "apiVersion": "batch/v1",
+            "kind": "Job",
+            "name": "sample-job-2mfzb",
+            "uid": "51ae8e48-8785-4bbb-9811-f9c1f041b368"
+          }
+        ]
+      },
+      "priority": 0,
+      "localQueueName": "user-queue",
+      "positionInClusterQueue": 1,
+      "positionInLocalQueue": 1
+    },
+    {
+      "metadata": {
+        "name": "job-sample-job-dpggt-3ecac",
+        "namespace": "default",
+        "creationTimestamp": "2024-09-29T10:58:32Z",
+        "ownerReferences": [
+          {
+            "apiVersion": "batch/v1",
+            "kind": "Job",
+            "name": "sample-job-dpggt",
+            "uid": "870655da-07d5-4910-be99-7650bf89b0d2"
+          }
+        ]
+      },
+      "priority": 0,
+      "localQueueName": "user-queue",
+      "positionInClusterQueue": 2,
+      "positionInLocalQueue": 2
+    }
+  ]
+}
+```
+
+### Local Queue visibility via kubectl
 
 Similarly to ClusterQueue, to view pending workloads in LocalQueue `user-queue` run the following command:
 
@@ -306,3 +420,84 @@ You should get results similar to
   ]
 }
 ```
+
+### Local Queue visibility via curl
+
+If you followed steps described in [Directly accessing the Visibility API](#directly-accessing-the-visibility-api) 
+above, you can use curl to view pending workloads in LocalQueue using following commands:
+
+{{< tabpane lang="shell" persist=disabled >}}
+{{< tab header="Using kubectl proxy" >}} curl http://localhost:8080/apis/visibility.kueue.x-k8s.io/v1beta1/namespaces/default/localqueues/user-queue/pendingworkloads {{< /tab >}}
+{{< tab header="Without kubectl proxy" >}} curl -X GET $APISERVER/apis/visibility.kueue.x-k8s.io/v1beta1/namespaces/default/localqueues/user-queue/pendingworkloads --header "Authorization: Bearer $TOKEN" --insecure {{< /tab >}}
+{{< /tabpane >}}
+
+You should get results similar to:
+
+```json
+{
+  "kind": "PendingWorkloadsSummary",
+  "apiVersion": "visibility.kueue.x-k8s.io/v1beta1",
+  "metadata": {
+    "creationTimestamp": null
+  },
+  "items": [
+    {
+      "metadata": {
+        "name": "job-sample-job-z8sc5-223e8",
+        "namespace": "default",
+        "creationTimestamp": "2024-09-29T10:58:32Z",
+        "ownerReferences": [
+          {
+            "apiVersion": "batch/v1",
+            "kind": "Job",
+            "name": "sample-job-z8sc5",
+            "uid": "7086b1bb-39b7-42e5-9f6b-ee07d0100051"
+          }
+        ]
+      },
+      "priority": 0,
+      "localQueueName": "user-queue",
+      "positionInClusterQueue": 0,
+      "positionInLocalQueue": 0
+    },
+    {
+      "metadata": {
+        "name": "job-sample-job-2mfzb-28f54",
+        "namespace": "default",
+        "creationTimestamp": "2024-09-29T10:58:32Z",
+        "ownerReferences": [
+          {
+            "apiVersion": "batch/v1",
+            "kind": "Job",
+            "name": "sample-job-2mfzb",
+            "uid": "51ae8e48-8785-4bbb-9811-f9c1f041b368"
+          }
+        ]
+      },
+      "priority": 0,
+      "localQueueName": "user-queue",
+      "positionInClusterQueue": 1,
+      "positionInLocalQueue": 1
+    },
+    {
+      "metadata": {
+        "name": "job-sample-job-dpggt-3ecac",
+        "namespace": "default",
+        "creationTimestamp": "2024-09-29T10:58:32Z",
+        "ownerReferences": [
+          {
+            "apiVersion": "batch/v1",
+            "kind": "Job",
+            "name": "sample-job-dpggt",
+            "uid": "870655da-07d5-4910-be99-7650bf89b0d2"
+          }
+        ]
+      },
+      "priority": 0,
+      "localQueueName": "user-queue",
+      "positionInClusterQueue": 2,
+      "positionInLocalQueue": 2
+    }
+  ]
+}
+```
diff --git a/site/static/examples/visibility/cluster-role-and-binding.yaml b/site/static/examples/visibility/cluster-role-and-binding.yaml
@@ -0,0 +1,28 @@
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: kueue-visibility-server-api
+rules:
+- apiGroups:
+  - "visibility.kueue.x-k8s.io"
+  resources:
+  - "clusterqueues/pendingworkloads"
+  - "localqueues/pendingworkloads"
+  verbs:
+  - get
+  - list
+  - watch
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  name: kueue-visibility-server-api
+  namespace: default
+subjects:
+- kind: ServiceAccount
+  name: default
+  namespace: default
+roleRef:
+  kind: ClusterRole
+  name: kueue-visibility-server-api
+  apiGroup: rbac.authorization.k8s.io