Enable KueueViz

KueueViz is a web-based visualization tool that provides real-time monitoring of Kueue workloads, queues, and resource allocation. It offers an intuitive dashboard for observing job queue status, resource utilization, and workload progression.

This page shows how to install and configure KueueViz in your cluster.

The page is intended for batch administrators.

Before you begin

Make sure the following conditions are met:

• A Kubernetes cluster is running
• The kubectl command-line tool has communication with your cluster
• The Helm command-line tool is installed
• Kueue is installed in your cluster
• (Optional) An ingress controller for external access (e.g. Nginx Ingress Controller)

KueueViz can be installed using Helm (recommended), or kubectl. Choose the method that best fits your workflow.

Installation with Kueue

To install KueueViz as part of a new Kueue installation:

helm install kueue oci://registry.k8s.io/kueue/charts/kueue \
  --version=0.19.5 \
  --namespace kueue-system \
  --create-namespace \
  --wait --timeout 300s \
  --set enableKueueViz=true # enable KueueViz

For more information on installing Kueue, please refer to Installation.

Enable KueueViz (Kueue is already installed)

If Kueue is already installed, you can enable KueueViz by Helm or kubectl.

Enable KueueViz by Helm

To enable KueueViz on an existing Kueue installation by Helm:

helm upgrade kueue oci://registry.k8s.io/kueue/charts/kueue \
  --version=0.19.5 \
  --namespace kueue-system \
  --set enableKueueViz=true # enable KueueViz

Enable KueueViz by YAML

To enable KueueViz on an existing Kueue installation by YAML:

kubectl apply --server-side -f https://github.com/kubernetes-sigs/kueue/releases/download/v0.19.5/kueueviz.yaml

Accessing the Dashboard

Port Forwarding (Only for development)

For quick access during development or testing, first patch the frontend ConfigMap to point at the port-forwarded backend.

If you installed via Helm, the ConfigMap name is kueue-kueueviz-frontend-env. If you installed via kubectl apply -f kueueviz.yaml, the ConfigMap name includes a hash suffix generated by kustomize. Find it with:

kubectl -n kueue-system get configmap | grep frontend-env

Edit the ConfigMap (replace <configmap-name> with the actual name):

kubectl edit configmap <configmap-name> -n kueue-system

Update env.js to point to ws://localhost:8081:

data:
  env.js: |
    window.env = {
      VITE_WEBSOCKET_URL: "ws://localhost:8081",
      REACT_APP_WEBSOCKET_URL: "ws://localhost:8081"
    };

Set the backend’s CORS allowed origins to match the frontend URL:

kubectl -n kueue-system set env deployment/kueue-kueueviz-backend KUEUEVIZ_ALLOWED_ORIGINS=http://localhost:8080

Restart the frontend pod to pick up the ConfigMap change:

kubectl rollout restart deployment kueue-kueueviz-frontend -n kueue-system

Then start port-forwarding:

kubectl port-forward svc/kueue-kueueviz-frontend -n kueue-system 8080 &
kubectl port-forward svc/kueue-kueueviz-backend  -n kueue-system 8081:8080

Then access the dashboard at http://localhost:8080.

Ingress

The chart can expose the dashboard and its backend on a single host by path, which avoids a second DNS record and removes the need for CORS configuration. Enable it with:

helm upgrade kueue oci://registry.k8s.io/kueue/charts/kueue \
  --version=0.19.5 \
  --namespace kueue-system \
  --set enableKueueViz=true \
  --set kueueViz.ingress.enabled=true \
  --set kueueViz.ingress.host=kueueviz.example.com \
  --set kueueViz.ingress.tlsSecretName=kueueviz-tls

This renders one Ingress that routes /ws, /api and /auth to the backend Service and everything else to the frontend Service. The per-host kueueViz.backend.ingress and kueueViz.frontend.ingress objects are not created while it is enabled, and KUEUEVIZ_ALLOWED_ORIGINS on the backend is unused because the browser never makes a cross-origin request.

The frontend env.js ConfigMap carries no backend URL in this mode. The dashboard talks to whichever origin served it, so something in front of both Services has to do the path routing. The Ingress above does; the frontend container does not, because it only serves the static bundle. Pointing a LoadBalancer Service or kubectl port-forward at the frontend alone leaves /ws, /api and /auth unrouted, and the dashboard loads with empty panels. Use Port Forwarding for local access instead.

Without Helm

The kueueviz.yaml install ships a separate Ingress per component, on the hosts backend.kueueviz.local and frontend.kueueviz.local. To serve both from one host instead, delete those two:

kubectl delete ingress kueue-kueueviz-backend-ingress kueue-kueueviz-frontend-ingress \
  -n kueue-system

Then apply an Ingress that routes by path. Do not add rewrite-target here either:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: kueueviz-ingress
  namespace: kueue-system
spec:
  tls:
    - hosts:
        - kueueviz.example.com # replace with your domain
      secretName: kueueviz-tls # you need to create a TLS secret at first
  rules:
    - host: kueueviz.example.com
      http:
        paths:
          - path: /ws
            pathType: Prefix
            backend:
              service:
                name: kueue-kueueviz-backend
                port:
                  number: 8080
          - path: /api
            pathType: Prefix
            backend:
              service:
                name: kueue-kueueviz-backend
                port:
                  number: 8080
          - path: /auth
            pathType: Prefix
            backend:
              service:
                name: kueue-kueueviz-backend
                port:
                  number: 8080
          - path: /
            pathType: Prefix
            backend:
              service:
                name: kueue-kueueviz-frontend
                port:
                  number: 8080

Finally, clear the backend URL from the kueue-kueueviz-frontend-env ConfigMap so the dashboard falls back to the origin that served it:

data:
  env.js: |
    window.env = {
      VITE_WEBSOCKET_URL: "",
      REACT_APP_WEBSOCKET_URL: ""
    };

kubectl rollout restart deployment kueue-kueueviz-frontend -n kueue-system

LoadBalancer

For cloud environments with LoadBalancer support. This exposes the frontend only, so the backend still needs an address of its own, or an Ingress that routes /ws, /api and /auth to it:

apiVersion: v1
kind: Service
metadata:
  name: kueueviz-loadbalancer
  namespace: kueue-system
spec:
  type: LoadBalancer
  ports:
    - name: http
      port: 80
      targetPort: 8080
      protocol: TCP
  selector:
    app.kubernetes.io/name: kueue
    app.kubernetes.io/component: kueueviz-frontend

Upgrade

Upgrade by Helm

To upgrade KueueViz by Helm:

helm upgrade kueue oci://registry.k8s.io/kueue/charts/kueue \
  --version=0.19.5 \
  --namespace kueue-system \
  --set enableKueueViz=true

Upgrade by YAML

To upgrade KueueViz by YAML:

kubectl apply --server-side -f https://github.com/kubernetes-sigs/kueue/releases/download/v0.19.5/kueueviz.yaml

Uninstall

Note: Be sure to uninstall KueueViz, and not to accidentally uninstall Kueue instead.

To uninstall KueueViz components:

kubectl delete -f https://github.com/kubernetes-sigs/kueue/releases/download/v0.19.5/kueueviz.yaml

What’s next

• Explore more Tasks
• Learn about Concepts