feat: implement core metrics provider for workspace resource usage by richabanker · Pull Request #1241 · kubeflow/notebooks

richabanker · 2026-07-10T00:33:48Z

This PR introduces the core models and provider logic for surfacing live, point-in-time pod resource utilization (CPU and Memory) for workspaces. This implements the foundation for the Resource Utilization Metrics proposal.

Changes:

Added metrics package containing domain models (WorkspaceResourceUsage) and schema mappings for the API response
Implemented metricsServerProvider to read PodMetrics from the metrics.k8s.io aggregated API using the controller-runtime client
Updated helper.NewManager() to disable caching for PodMetrics, as the aggregated API does not support WATCHes
Added helper functions to join usage with configured requests and limits, gracefully degrading when metrics are absent or unavailable
Added unit tests

Issue: #1222
Design Doc

google-oss-prow · 2026-07-10T00:33:55Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign andyatmiami for approval. For more information see the Kubernetes Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

workspaces/backend/OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

richabanker · 2026-07-10T00:39:02Z

I have kept this first PR intentionally scoped to just the data layer for the resource metrics API. Currently it adds no HTTP paths, handlers, Repositories wiring and RBAC changes (which I plan to split in smaller follow-ups). Please let me know if granularity works or if I should split this PR further into smaller chunks?

Happy to go whichever way makes review easiest.

cc @andyatmiami @thesuperzapper

christian-heusel

Hey @richabanker, thanks a lot for driving this and starting out with an implementation of your proposal! 🥳

I have left a few thoughts below!

/ok-to-test

christian-heusel · 2026-07-11T00:24:08Z

+	if err := metricsv1beta1.AddToScheme(scheme); err != nil {
+		return nil, fmt.Errorf("failed to add metrics types to scheme: %w", err)
+	}


I think you also need to do this for the tests:

[FAILED] in [BeforeSuite] - /home/chris/Documents/shared_projects/kion/kubeflow-notebooks/workspaces/backend/api/suite_test.go:132 @ 07/11/26 02:20:34.521 << Timeline [FAILED] Unexpected error: <*fmt.wrapError | 0x17a49b88b620>: unable to create manager: no kind is registered for the type v1beta1.PodMetrics in scheme "pkg/runtime/scheme.go:100" { msg: "unable to create manager: no kind is registered for the type v1beta1.PodMetrics in scheme \"pkg/runtime/scheme.go:100\"", err: <*runtime.notRegisteredErr | 0x17a49b3c26c0>{ schemeName: "pkg/runtime/scheme.go:100", gvk: {Group: "", Version: "", Kind: ""}, target: nil, t: <*reflect.rtype | 0x2065a40>{ t: {Size_: 0x140, PtrBytes: 0x130, Hash: 614274612, TFlag: 7, Align_: 8, FieldAlign_: 8, Kind_: 25, Equal: nil, GCData: 85, Str: 253661, PtrToThis: 5271776}, }, }, } occurred In [BeforeSuite] at: /home/chris/Documents/shared_projects/kion/kubeflow-notebooks/workspaces/backend/api/suite_test.go:132 @ 07/11/26 02:20:34.521 ------------------------------

🤖-generated reason

api/suite_test.go builds its manager's scheme manually (scheme.Scheme + kubefloworgv1beta1.AddToScheme), not via helper.BuildScheme(). helper.NewManager() was changed in this PR to unconditionally add &metricsv1beta1.PodMetrics{} to Cache.DisableFor, which requires the passed-in scheme to know that GVK.

yep, I was not registering metricsv1beta1 to the scheme used by the test client. Added it now.

christian-heusel · 2026-07-11T00:28:09Z

+func podWithContainer(name string, containers ...corev1.Container) corev1.Pod {
+	return corev1.Pod{
+		ObjectMeta: metav1.ObjectMeta{Name: name},
+		Spec: corev1.PodSpec{
+			Containers: containers,
+		},
+	}
+}


Should be fine to just //nolint here given that its in a test file:

$ make -C workspaces/backend lint make: Entering directory '/home/chris/Documents/shared_projects/kion/kubeflow-notebooks/workspaces/backend' /home/chris/Documents/shared_projects/kion/kubeflow-notebooks/workspaces/backend/bin/golangci-lint run internal/models/metrics/funcs_test.go:168:23: `podWithContainer` - `name` always receives `"pod-1"` (unparam) func podWithContainer(name string, containers ...corev1.Container) corev1.Pod { ^ make: *** [Makefile:77: lint] Error 1 make: Leaving directory '/home/chris/Documents/shared_projects/kion/kubeflow-notebooks/workspaces/backend'

Actually changed a test to pass a value other than "pod-1" for the name param. That should make it go away.

christian-heusel · 2026-07-11T00:39:31Z

+type WorkspaceResourceUsage struct {
+	// Available is true when live usage metrics were successfully retrieved.
+	Available bool `json:"available"`
+
+	// Source identifies which provider produced the data (e.g. "metrics-server").
+	Source string `json:"source,omitempty"`
+
+	// Reason is a machine-readable code present only when Available is false.
+	Reason string `json:"reason,omitempty"`
+
+	// Message is a human-readable explanation present only when Available is false.
+	Message string `json:"message,omitempty"`
+
+	// Pods holds the per-pod usage.
+	Pods []PodResourceUsage `json:"pods"`
+}


I'm not 100% sure with this, however I think we usually have API design that revolves around error states instead of success states, so the way that this types combines both paths (i.e. via Available & Reason) feels odd to me. However the last call regarding design decisions is of course with Andy and Mathew so would be good if they'd weigh in on this at some point 🤗

See for example this snippet:

notebooks/workspaces/backend/internal/models/common/assets/types.go

Lines 17 to 33 in e51895d

package assets

// ImageRef represents a reference to an image (icon or logo) that can be sourced from a URL or ConfigMap.

type ImageRef struct {

URL string `json:"url"`

Error *ImageRefErrorCode `json:"error,omitempty"`

}

// ImageRefErrorCode represents error codes for asset retrieval errors.

type ImageRefErrorCode string

const (

ImageRefErrorCodeConfigMapMissing ImageRefErrorCode = "CONFIGMAP_MISSING"

ImageRefErrorCodeConfigMapKeyMissing ImageRefErrorCode = "CONFIGMAP_KEY_MISSING"

ImageRefErrorCodeConfigMapOther ImageRefErrorCode = "CONFIGMAP_OTHER"

ImageRefErrorCodeConfigMapUnknown ImageRefErrorCode = "CONFIGMAP_UNKNOWN"

)

If we apply this pattern here, we would get something like this:

type WorkspaceResourceUsage struct { // Source identifies which provider produced the data (e.g. "metrics-server"). // Empty when Error is set. Source string `json:"source,omitempty"` // Error is set when live usage metrics could not be retrieved. Error *ResourceUsageError `json:"error,omitempty"` // Pods holds the per-pod usage. Empty when Error is set. Pods []PodResourceUsage `json:"pods"` } type ResourceUsageError struct { Code ResourceUsageErrorCode `json:"code"` Message string `json:"message,omitempty"` } type ResourceUsageErrorCode string const ( ResourceUsageErrorMetricsAPIUnavailable ResourceUsageErrorCode = "METRICS_API_UNAVAILABLE" ResourceUsageErrorWorkspaceNotRunning ResourceUsageErrorCode = "WORKSPACE_NOT_RUNNING" )

Also the ImageRefErrorCode values are in 'SCREAMING_SNAKE' casing ("CONFIGMAP_MISSING"), while this PR's constants are 'PascalCase' ("MetricsAPIUnavailable").

ah good point. I like the proposed schema, can pivot to this to keep things consistent once @andyatmiami or @thesuperzapper confirm. Thanks for this suggestion!

Signed-off-by: Richa Banker <richabanker@google.com>

github-project-automation Bot added this to Kubeflow Notebooks Jul 10, 2026

github-project-automation Bot moved this to Needs Triage in Kubeflow Notebooks Jul 10, 2026

google-oss-prow Bot added the area/backend area - related to backend components label Jul 10, 2026

google-oss-prow Bot requested review from andyatmiami and thesuperzapper July 10, 2026 00:33

google-oss-prow Bot added area/v2 area - version - kubeflow notebooks v2 size/XL labels Jul 10, 2026

richabanker changed the title ~~feat(backend): implement core metrics provider for workspace resource usage~~ feat: implement core metrics provider for workspace resource usage Jul 10, 2026

christian-heusel reviewed Jul 11, 2026

View reviewed changes

google-oss-prow Bot added the ok-to-test label Jul 11, 2026

richabanker force-pushed the resource-util-metrics branch 4 times, most recently from 5709569 to 8adbd44 Compare July 16, 2026 05:04

implement core metrics provider for workspace resource usage

41996c1

Signed-off-by: Richa Banker <richabanker@google.com>

richabanker force-pushed the resource-util-metrics branch from 8adbd44 to 41996c1 Compare July 16, 2026 05:07

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: implement core metrics provider for workspace resource usage#1241

feat: implement core metrics provider for workspace resource usage#1241
richabanker wants to merge 1 commit into
kubeflow:notebooks-v2from
richabanker:resource-util-metrics

richabanker commented Jul 10, 2026 •

edited

Loading

Uh oh!

google-oss-prow Bot commented Jul 10, 2026

Uh oh!

richabanker commented Jul 10, 2026 •

edited

Loading

Uh oh!

christian-heusel left a comment

Uh oh!

christian-heusel Jul 11, 2026

Uh oh!

richabanker Jul 13, 2026

Uh oh!

christian-heusel Jul 11, 2026

Uh oh!

richabanker Jul 13, 2026

Uh oh!

christian-heusel Jul 11, 2026

Uh oh!

richabanker Jul 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	package assets

	// ImageRef represents a reference to an image (icon or logo) that can be sourced from a URL or ConfigMap.
	type ImageRef struct {
	URL string `json:"url"`
	Error *ImageRefErrorCode `json:"error,omitempty"`
	}

	// ImageRefErrorCode represents error codes for asset retrieval errors.
	type ImageRefErrorCode string

	const (
	ImageRefErrorCodeConfigMapMissing ImageRefErrorCode = "CONFIGMAP_MISSING"
	ImageRefErrorCodeConfigMapKeyMissing ImageRefErrorCode = "CONFIGMAP_KEY_MISSING"
	ImageRefErrorCodeConfigMapOther ImageRefErrorCode = "CONFIGMAP_OTHER"
	ImageRefErrorCodeConfigMapUnknown ImageRefErrorCode = "CONFIGMAP_UNKNOWN"
	)

Uh oh!

Conversation

richabanker commented Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

google-oss-prow Bot commented Jul 10, 2026

Uh oh!

richabanker commented Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

christian-heusel left a comment

Choose a reason for hiding this comment

Uh oh!

christian-heusel Jul 11, 2026

Choose a reason for hiding this comment

Uh oh!

richabanker Jul 13, 2026

Choose a reason for hiding this comment

Uh oh!

christian-heusel Jul 11, 2026

Choose a reason for hiding this comment

Uh oh!

richabanker Jul 13, 2026

Choose a reason for hiding this comment

Uh oh!

christian-heusel Jul 11, 2026

Choose a reason for hiding this comment

Uh oh!

richabanker Jul 13, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

richabanker commented Jul 10, 2026 •

edited

Loading

richabanker commented Jul 10, 2026 •

edited

Loading