Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

feat(cyclops): add usage POC dashboard with feature-flagged API (#6843)

r33drichards83d8da136cdf
diff --git a/libs/fleet/backend/auth/authz.rego b/libs/fleet/backend/auth/authz.rego
index 66c89c4121..366c957265 100644
--- a/libs/fleet/backend/auth/authz.rego
+++ b/libs/fleet/backend/auth/authz.rego
@@ -44,6 +44,15 @@ chat_enabled {
input.flags.chat_subs[_] == input.user.sub
}
+# Usage preview is restricted to administrators and the initial internal rollout set.
+usage_enabled {
+ is_admin
+}
+
+usage_enabled {
+ input.flags.usage_subs[_] == input.user.sub
+}
+
# ── Token families ──────────────────────────────────────────────────────────
#
# Three families reach the policy, distinguished by `azp`. A fourth kind of
diff --git a/libs/fleet/backend/auth/authz_usage.rego b/libs/fleet/backend/auth/authz_usage.rego
new file mode 100644
index 0000000000..68bcc21ee9
--- /dev/null
+++ b/libs/fleet/backend/auth/authz_usage.rego
@@ -0,0 +1,9 @@
+package authz_usage
+
+default allow = false
+
+allow {
+ startswith(input.route, "/api/usage/")
+ input.method == "GET"
+ input.user.azp == "cyclops-cs-spa"
+}
diff --git a/libs/fleet/backend/auth/authz_usage_test.rego b/libs/fleet/backend/auth/authz_usage_test.rego
new file mode 100644
index 0000000000..31e9deaf79
--- /dev/null
+++ b/libs/fleet/backend/auth/authz_usage_test.rego
@@ -0,0 +1,11 @@
+package authz_usage_test
+
+import rego.v1
+import data.authz_base
+import data.authz_usage
+
+route_allow if { authz_base.allow; authz_usage.allow }
+
+test_spa_get_allowed if { route_allow with input as {"route":"/api/usage/overview","method":"GET","path":"/api/usage/overview","params":{},"user":{"sub":"user-1","azp":"cyclops-cs-spa","namespace":"","email":""}} }
+test_spa_post_denied if { not route_allow with input as {"route":"/api/usage/overview","method":"POST","path":"/api/usage/overview","params":{},"user":{"sub":"user-1","azp":"cyclops-cs-spa","namespace":"","email":""}} }
+test_cli_get_denied if { not route_allow with input as {"route":"/api/usage/overview","method":"GET","path":"/api/usage/overview","params":{},"user":{"sub":"user-1","azp":"cua-cli","namespace":"","email":""}} }
diff --git a/libs/fleet/backend/auth/flags_test.go b/libs/fleet/backend/auth/flags_test.go
index 49e4a4d137..55b961878d 100644
--- a/libs/fleet/backend/auth/flags_test.go
+++ b/libs/fleet/backend/auth/flags_test.go
@@ -113,16 +113,21 @@ func TestFlagsDataLoadsCardRequirementExemptSubs(t *testing.T) {
}
}
-func TestComputeFlagsDataFailsClosedOnTypeMismatch(t *testing.T) {
+func TestComputeFlagsDataLoadsOnlyOPAStringListFlags(t *testing.T) {
t.Setenv("CYCLOPS_CS_ADMIN_SUBS", `["admin-sub"]`)
+ t.Setenv("CYCLOPS_CS_USAGE_SUBS", `["usage-sub"]`)
t.Setenv("CYCLOPS_CS_BILLING_ENABLED", "true")
+ t.Setenv("CYCLOPS_CS_CHAT_ACCESS", "restricted")
if err := featureflags.SetupProvider(context.Background(), "development", featureflags.AWSCredentials{}); err != nil {
t.Fatalf("setup dev provider: %v", err)
}
got := computeFlagsData(context.Background())
- if len(got) != 0 {
- t.Fatalf("computeFlagsData() = %v, want empty flags after type mismatch", got)
+ if admins := asStrings(got["admin_subs"]); len(admins) != 1 || admins[0] != "admin-sub" {
+ t.Fatalf("admin_subs = %v, want [admin-sub]", admins)
+ }
+ if usage := asStrings(got["usage_subs"]); len(usage) != 1 || usage[0] != "usage-sub" {
+ t.Fatalf("usage_subs = %v, want [usage-sub]", usage)
}
}
@@ -175,3 +180,22 @@ func TestEvalChatEnabledFailsClosedForMalformedAllowlist(t *testing.T) {
t.Fatalf("EvalChatEnabled(malformed allowlist) = %v, %v; want false, nil", enabled, err)
}
}
+
+func TestEvalUsageEnabledAllowsAdminsAndAllowlistedUsers(t *testing.T) {
+ t.Setenv("CYCLOPS_CS_ADMIN_SUBS", `["admin"]`)
+ t.Setenv("CYCLOPS_CS_USAGE_SUBS", `["internal"]`)
+ if err := featureflags.SetupProvider(context.Background(), "development", featureflags.AWSCredentials{}); err != nil {
+ t.Fatal(err)
+ }
+ LoadOpa()
+ resetFlagsCache()
+ for _, tc := range []struct {
+ id string
+ want bool
+ }{{"admin", true}, {"internal", true}, {"other", false}} {
+ got, err := EvalUsageEnabled(context.Background(), &User{ID: tc.id, AZP: "cyclops-cs-spa"})
+ if err != nil || got != tc.want {
+ t.Fatalf("%s: %v %v", tc.id, got, err)
+ }
+ }
+}
diff --git a/libs/fleet/backend/auth/middlewares.go b/libs/fleet/backend/auth/middlewares.go
index 700cd0c6e8..99f8d99a0a 100644
--- a/libs/fleet/backend/auth/middlewares.go
+++ b/libs/fleet/backend/auth/middlewares.go
@@ -28,6 +28,7 @@ const UserKey ctxKey = 1
var (
opaAdminQuery *rego.PreparedEvalQuery
opaChatQuery *rego.PreparedEvalQuery
+ opaUsageQuery *rego.PreparedEvalQuery
)
// authzPolicy is the shared principal vocabulary every surface module imports.
@@ -65,6 +66,7 @@ var surfacePolicySources = map[string]struct {
"authz-config": {"authz_config.rego", authzConfigPolicy},
"authz-chat": {"authz_chat.rego", authzChatPolicy},
"authz-billing": {"authz_billing.rego", authzBillingPolicy},
+ "authz-usage": {"authz_usage.rego", authzUsagePolicy},
"authz-namespaces": {"authz_namespaces.rego", authzNamespacesPolicy},
"authz-github-trust": {"authz_github_trust.rego", authzGitHubTrustPolicy},
"authz-user-keys": {"authz_user_keys.rego", authzUserKeysPolicy},
@@ -88,6 +90,9 @@ var authzChatPolicy string
//go:embed authz_billing.rego
var authzBillingPolicy string
+//go:embed authz_usage.rego
+var authzUsagePolicy string
+
//go:embed authz_namespaces.rego
var authzNamespacesPolicy string
@@ -114,10 +119,15 @@ var authzStateQueryPolicy string
//
// /feature-flags/cyclops-cs/admin-subs → CYCLOPS_CS_ADMIN_SUBS
//
-// Values are JSON string arrays (e.g. '["sub1","sub2"]').
+// OPA list values are JSON string arrays (e.g. '["sub1","sub2"]').
const (
- flagPrefix = "/feature-flags/cyclops-cs/"
- cardAdmissionFlag = flagPrefix + "require-card-for-custom-resource-creation"
+ flagPrefix = "/feature-flags/cyclops-cs/"
+ adminSubsFlag = flagPrefix + "admin-subs"
+ billingFlag = flagPrefix + "billing-enabled"
+ cardAdmissionFlag = flagPrefix + "require-card-for-custom-resource-creation"
+ cardRequirementExemptSubsFlag = flagPrefix + "card-requirement-exempt-subs"
+ chatSubsFlag = flagPrefix + "chat-subs"
+ usageSubsFlag = flagPrefix + "usage-subs"
)
// flagsTTL bounds how long flagsData returns its last computed result
@@ -201,7 +211,7 @@ func computeFlagsData(ctx context.Context) map[string]interface{} {
}
flags := map[string]interface{}{}
for _, key := range keys {
- if key == cardAdmissionFlag {
+ if !isOPAStringListFlag(key) {
continue
}
name := opaNameFromFlagKey(key)
@@ -227,6 +237,15 @@ func computeFlagsData(ctx context.Context) map[string]interface{} {
return flags
}
+func isOPAStringListFlag(key string) bool {
+ switch key {
+ case adminSubsFlag, cardRequirementExemptSubsFlag, chatSubsFlag, usageSubsFlag:
+ return true
+ default:
+ return false
+ }
+}
+
// opaNameFromFlagKey maps a discovered flag path to the Rego identifier
// used by the policy (under input.flags). Nested paths under flagPrefix are
// skipped — the policy only references single-leaf flag names.
@@ -296,6 +315,7 @@ func LoadOpa() {
opaAdminQuery = prepareAuthzQuery("data.authz.is_admin")
opaChatQuery = prepareAuthzQuery("data.authz.chat_enabled")
+ opaUsageQuery = prepareAuthzQuery("data.authz.usage_enabled")
// Warm the flag cache once so the first request isn't slowed by the
// initial resolve and any SSM/provider misconfiguration surfaces in the
@@ -316,6 +336,10 @@ func EvalChatEnabled(ctx context.Context, user *User) (bool, error) {
return evalUserDecision(ctx, user, opaChatQuery)
}
+func EvalUsageEnabled(ctx context.Context, user *User) (bool, error) {
+ return evalUserDecision(ctx, user, opaUsageQuery)
+}
+
func evalUserDecision(ctx context.Context, user *User, query *rego.PreparedEvalQuery) (bool, error) {
if user == nil {
return false, nil
@@ -346,7 +370,7 @@ func EvalBillingEnabled(ctx context.Context, user *User) (bool, error) {
})
callCtx, cancel := context.WithTimeout(ctx, 3*time.Second)
defer cancel()
- return ffClient.BooleanValue(callCtx, "/feature-flags/cyclops-cs/billing-enabled", false, openfeature.NewEvaluationContext(user.ID, nil))
+ return ffClient.BooleanValue(callCtx, billingFlag, false, openfeature.NewEvaluationContext(user.ID, nil))
}
func writeJSONErr(w http.ResponseWriter, status int, msg string) {
diff --git a/libs/fleet/backend/auth/policy_characterization_test.go b/libs/fleet/backend/auth/policy_characterization_test.go
index ababa10122..2c318ed00e 100644
--- a/libs/fleet/backend/auth/policy_characterization_test.go
+++ b/libs/fleet/backend/auth/policy_characterization_test.go
@@ -159,6 +159,8 @@ func characterizationCases() map[string][]routeCase {
}
simple("/api/config", "/api/config")
simple("/api/state/query", "/api/state/query")
+ simple("/api/usage/overview", "/api/usage/overview")
+ simple("/api/usage/pool", "/api/usage/pool")
simple("/api/chat/conversations", "/api/chat/conversations")
simple("/api/billing/summary", "/api/billing/summary")
simple("/api/billing/setup-session", "/api/billing/setup-session")
diff --git a/libs/fleet/backend/auth/policy_routes.go b/libs/fleet/backend/auth/policy_routes.go
index d1dc865daf..8d7871a777 100644
--- a/libs/fleet/backend/auth/policy_routes.go
+++ b/libs/fleet/backend/auth/policy_routes.go
@@ -80,6 +80,10 @@ func BillingRoutePolicy() Node {
return All(BasePolicy(), surfaceLeaf("authz-billing", "data.authz_billing.allow"))
}
+func UsageRoutePolicy() Node {
+ return All(BasePolicy(), surfaceLeaf("authz-usage", "data.authz_usage.allow"))
+}
+
// NamespaceOwnershipPolicy is the tenancy boundary for routes that name a
// namespace in their path. It is a conjunct rather than a surface, because
// three surfaces carry it and one of them (namespaces) holds routes on both
@@ -244,6 +248,7 @@ var surfacePolicies = map[string]surfacePolicy{
"config": {tree: ConfigRoutePolicy},
"chat": {tree: ChatRoutePolicy},
"billing": {tree: BillingRoutePolicy},
+ "usage": {tree: UsageRoutePolicy},
"namespaces": {tree: NamespacesRoutePolicy},
"github-trust": {tree: GitHubTrustRoutePolicy},
"user-keys": {tree: UserKeysRoutePolicy},
@@ -263,8 +268,10 @@ var surfacePolicies = map[string]surfacePolicy{
// memoized per surface: the three billing routes share one module, one tree,
// and one compiled plan.
var routeSurfaces = map[string]string{
- "/api/config": "config",
- "/api/state/query": "state-query",
+ "/api/config": "config",
+ "/api/state/query": "state-query",
+ "/api/usage/overview": "usage",
+ "/api/usage/pool": "usage",
"/api/chat/conversations": "chat",
"/api/chat/conversations/{id}": "chat",
diff --git a/libs/fleet/backend/auth/testdata/route-authorization-table.txt b/libs/fleet/backend/auth/testdata/route-authorization-table.txt
index 4805c10aa4..abca683948 100644
--- a/libs/fleet/backend/auth/testdata/route-authorization-table.txt
+++ b/libs/fleet/backend/auth/testdata/route-authorization-table.txt
@@ -2913,6 +2913,116 @@
/api/svc/{namespace}/{service}/{path...} | unreachable-ns | QUERY | spa = error
/api/svc/{namespace}/{service}/{path...} | unreachable-ns | QUERY | user-key = error
/api/svc/{namespace}/{service}/{path...} | unreachable-ns | QUERY | user-key-verified = error
+/api/usage/overview | plain | DELETE | admin-spa = deny
+/api/usage/overview | plain | DELETE | cua-cli = deny
+/api/usage/overview | plain | DELETE | dcr-client = deny
+/api/usage/overview | plain | DELETE | empty-sub = deny
+/api/usage/overview | plain | DELETE | github-oidc = deny
+/api/usage/overview | plain | DELETE | oauth2-proxy = deny
+/api/usage/overview | plain | DELETE | per-key-other-ns = deny
+/api/usage/overview | plain | DELETE | per-key-owned-ns = deny
+/api/usage/overview | plain | DELETE | spa = deny
+/api/usage/overview | plain | DELETE | user-key = deny
+/api/usage/overview | plain | DELETE | user-key-verified = deny
+/api/usage/overview | plain | GET | admin-spa = allow
+/api/usage/overview | plain | GET | cua-cli = deny
+/api/usage/overview | plain | GET | dcr-client = deny
+/api/usage/overview | plain | GET | empty-sub = deny
+/api/usage/overview | plain | GET | github-oidc = deny
+/api/usage/overview | plain | GET | oauth2-proxy = deny
+/api/usage/overview | plain | GET | per-key-other-ns = deny
+/api/usage/overview | plain | GET | per-key-owned-ns = deny
+/api/usage/overview | plain | GET | spa = allow
+/api/usage/overview | plain | GET | user-key = deny
+/api/usage/overview | plain | GET | user-key-verified = deny
+/api/usage/overview | plain | PATCH | admin-spa = deny
+/api/usage/overview | plain | PATCH | cua-cli = deny
+/api/usage/overview | plain | PATCH | dcr-client = deny
+/api/usage/overview | plain | PATCH | empty-sub = deny
+/api/usage/overview | plain | PATCH | github-oidc = deny
+/api/usage/overview | plain | PATCH | oauth2-proxy = deny
+/api/usage/overview | plain | PATCH | per-key-other-ns = deny
+/api/usage/overview | plain | PATCH | per-key-owned-ns = deny
+/api/usage/overview | plain | PATCH | spa = deny
+/api/usage/overview | plain | PATCH | user-key = deny
+/api/usage/overview | plain | PATCH | user-key-verified = deny
+/api/usage/overview | plain | POST | admin-spa = deny
+/api/usage/overview | plain | POST | cua-cli = deny
+/api/usage/overview | plain | POST | dcr-client = deny
+/api/usage/overview | plain | POST | empty-sub = deny
+/api/usage/overview | plain | POST | github-oidc = deny
+/api/usage/overview | plain | POST | oauth2-proxy = deny
+/api/usage/overview | plain | POST | per-key-other-ns = deny
+/api/usage/overview | plain | POST | per-key-owned-ns = deny
+/api/usage/overview | plain | POST | spa = deny
+/api/usage/overview | plain | POST | user-key = deny
+/api/usage/overview | plain | POST | user-key-verified = deny
+/api/usage/overview | plain | QUERY | admin-spa = deny
+/api/usage/overview | plain | QUERY | cua-cli = deny
+/api/usage/overview | plain | QUERY | dcr-client = deny
+/api/usage/overview | plain | QUERY | empty-sub = deny
+/api/usage/overview | plain | QUERY | github-oidc = deny
+/api/usage/overview | plain | QUERY | oauth2-proxy = deny
+/api/usage/overview | plain | QUERY | per-key-other-ns = deny
+/api/usage/overview | plain | QUERY | per-key-owned-ns = deny
+/api/usage/overview | plain | QUERY | spa = deny
+/api/usage/overview | plain | QUERY | user-key = deny
+/api/usage/overview | plain | QUERY | user-key-verified = deny
+/api/usage/pool | plain | DELETE | admin-spa = deny
+/api/usage/pool | plain | DELETE | cua-cli = deny
+/api/usage/pool | plain | DELETE | dcr-client = deny
+/api/usage/pool | plain | DELETE | empty-sub = deny
+/api/usage/pool | plain | DELETE | github-oidc = deny
+/api/usage/pool | plain | DELETE | oauth2-proxy = deny
+/api/usage/pool | plain | DELETE | per-key-other-ns = deny
+/api/usage/pool | plain | DELETE | per-key-owned-ns = deny
+/api/usage/pool | plain | DELETE | spa = deny
+/api/usage/pool | plain | DELETE | user-key = deny
+/api/usage/pool | plain | DELETE | user-key-verified = deny
+/api/usage/pool | plain | GET | admin-spa = allow
+/api/usage/pool | plain | GET | cua-cli = deny
+/api/usage/pool | plain | GET | dcr-client = deny
+/api/usage/pool | plain | GET | empty-sub = deny
+/api/usage/pool | plain | GET | github-oidc = deny
+/api/usage/pool | plain | GET | oauth2-proxy = deny
+/api/usage/pool | plain | GET | per-key-other-ns = deny
+/api/usage/pool | plain | GET | per-key-owned-ns = deny
+/api/usage/pool | plain | GET | spa = allow
+/api/usage/pool | plain | GET | user-key = deny
+/api/usage/pool | plain | GET | user-key-verified = deny
+/api/usage/pool | plain | PATCH | admin-spa = deny
+/api/usage/pool | plain | PATCH | cua-cli = deny
+/api/usage/pool | plain | PATCH | dcr-client = deny
+/api/usage/pool | plain | PATCH | empty-sub = deny
+/api/usage/pool | plain | PATCH | github-oidc = deny
+/api/usage/pool | plain | PATCH | oauth2-proxy = deny
+/api/usage/pool | plain | PATCH | per-key-other-ns = deny
+/api/usage/pool | plain | PATCH | per-key-owned-ns = deny
+/api/usage/pool | plain | PATCH | spa = deny
+/api/usage/pool | plain | PATCH | user-key = deny
+/api/usage/pool | plain | PATCH | user-key-verified = deny
+/api/usage/pool | plain | POST | admin-spa = deny
+/api/usage/pool | plain | POST | cua-cli = deny
+/api/usage/pool | plain | POST | dcr-client = deny
+/api/usage/pool | plain | POST | empty-sub = deny
+/api/usage/pool | plain | POST | github-oidc = deny
+/api/usage/pool | plain | POST | oauth2-proxy = deny
+/api/usage/pool | plain | POST | per-key-other-ns = deny
+/api/usage/pool | plain | POST | per-key-owned-ns = deny
+/api/usage/pool | plain | POST | spa = deny
+/api/usage/pool | plain | POST | user-key = deny
+/api/usage/pool | plain | POST | user-key-verified = deny
+/api/usage/pool | plain | QUERY | admin-spa = deny
+/api/usage/pool | plain | QUERY | cua-cli = deny
+/api/usage/pool | plain | QUERY | dcr-client = deny
+/api/usage/pool | plain | QUERY | empty-sub = deny
+/api/usage/pool | plain | QUERY | github-oidc = deny
+/api/usage/pool | plain | QUERY | oauth2-proxy = deny
+/api/usage/pool | plain | QUERY | per-key-other-ns = deny
+/api/usage/pool | plain | QUERY | per-key-owned-ns = deny
+/api/usage/pool | plain | QUERY | spa = deny
+/api/usage/pool | plain | QUERY | user-key = deny
+/api/usage/pool | plain | QUERY | user-key-verified = deny
/api/user-keys | plain | DELETE | admin-spa = allow
/api/user-keys | plain | DELETE | cua-cli = allow
/api/user-keys | plain | DELETE | dcr-client = deny
diff --git a/libs/fleet/backend/auth/testdata/usage-route-plan.txt b/libs/fleet/backend/auth/testdata/usage-route-plan.txt
new file mode 100644
index 0000000000..cbfb0772c7
--- /dev/null
+++ b/libs/fleet/backend/auth/testdata/usage-route-plan.txt
@@ -0,0 +1,3 @@
+All
+ Leaf query=data.authz_base.allow source=registered:authz-base
+ Leaf query=data.authz_usage.allow source=multi["registered:authz","registered:authz-usage"]
diff --git a/libs/fleet/backend/cmd/db-migrate/main.go b/libs/fleet/backend/cmd/db-migrate/main.go
index caaf040f51..8417bc9b48 100644
--- a/libs/fleet/backend/cmd/db-migrate/main.go
+++ b/libs/fleet/backend/cmd/db-migrate/main.go
@@ -35,6 +35,7 @@ func main() {
Exporter: required("STATE_EXPORTER_DATABASE_URL"),
RoleAdmin: required("STATE_ROLE_ADMIN_DATABASE_URL"),
Metabase: required("METABASE_DATABASE_URL"),
+ Usage: required("USAGE_DATABASE_URL"),
},
}
if err := database.Run(context.Background(), config); err != nil {
diff --git a/libs/fleet/backend/config/config.go b/libs/fleet/backend/config/config.go
index b8c94dfd3b..20c0368532 100644
--- a/libs/fleet/backend/config/config.go
+++ b/libs/fleet/backend/config/config.go
@@ -13,8 +13,13 @@ package config
import (
"fmt"
+ "net/url"
"slices"
+ "strconv"
"strings"
+ "time"
+
+ "github.com/jackc/pgx/v5/pgxpool"
"github.com/spf13/pflag"
"github.com/spf13/viper"
@@ -30,6 +35,7 @@ type Configuration struct {
Chat ChatConfiguration
Metrics MetricsConfiguration
Telemetry TelemetryConfiguration
+ Usage UsageConfiguration
}
type WebServerConfiguration struct {
@@ -117,6 +123,23 @@ type ChatConfiguration struct {
Model string
}
+// UsageConfiguration enables the usage provider only when DatabaseURL is set.
+// OpenCostBaseURL may be configured before the usage credential arrives; in
+// that state the provider remains disabled so serving readiness is unaffected.
+type UsageConfiguration struct {
+ DatabaseURL string
+ OpenCostBaseURL string
+ QueryTimeout time.Duration
+ MaxResponseBytes int64
+}
+
+const (
+ minUsageQueryTimeout = time.Second
+ maxUsageQueryTimeout = 2 * time.Minute
+ minUsageResponseSize = 64 * 1024
+ maxUsageResponseSize = 32 * 1024 * 1024
+)
+
type MetricsConfiguration struct {
Addr string // METRICS_ADDR — Prometheus listen addr
}
@@ -161,6 +184,10 @@ var specs = []flagSpec{
{"database.url", "database-url", "DATABASE_URL", "", "Postgres URL for trust-policy storage (enables /api/github-trust-policies)"},
{"database.state-query-dsn", "state-query-database-dsn", "STATE_QUERY_DATABASE_DSN", "", "Postgres connection options for tenant state queries"},
{"database.state-query-tenant-password", "state-query-tenant-password", "STATE_QUERY_TENANT_PASSWORD", "", "Shared password for tenant query login roles"},
+ {"usage.database-url", "usage-database-url", "USAGE_DATABASE_URL", "", "Postgres URL for usage events"},
+ {"usage.opencost-base-url", "opencost-base-url", "OPENCOST_BASE_URL", "", "OpenCost base URL for usage allocations"},
+ {"usage.query-timeout", "usage-query-timeout", "USAGE_QUERY_TIMEOUT", "20s", "Usage provider query timeout"},
+ {"usage.max-response-bytes", "usage-max-response-bytes", "USAGE_MAX_RESPONSE_BYTES", "8388608", "Maximum OpenCost response bytes"},
{"stripe.secret-key", "stripe-secret-key", "STRIPE_SECRET_KEY", "", "Stripe secret key (server-only)"},
{"stripe.webhook-secret", "stripe-webhook-secret", "STRIPE_WEBHOOK_SECRET", "", "Stripe webhook signing secret"},
{"stripe.checkout-success-url", "stripe-checkout-success-url", "STRIPE_CHECKOUT_SUCCESS_URL", "", "Stripe Checkout success redirect URL"},
@@ -204,6 +231,15 @@ func splitCommaSeparated(value string) []string {
}
func LoadConfig() (*Configuration, error) {
+ usageQueryTimeout, err := parseUsageQueryTimeout(viper.GetString("usage.query-timeout"))
+ if err != nil {
+ return nil, err
+ }
+ usageMaxResponseBytes, err := parseUsageMaxResponseBytes(viper.GetString("usage.max-response-bytes"))
+ if err != nil {
+ return nil, err
+ }
+
base := strings.TrimRight(viper.GetString("kc.base-url"), "/")
realm := viper.GetString("kc.realm")
realmPath := fmt.Sprintf("%s/realms/%s", base, realm)
@@ -269,6 +305,12 @@ func LoadConfig() (*Configuration, error) {
APIKey: viper.GetString("chat.api-key"),
Model: viper.GetString("chat.model"),
},
+ Usage: UsageConfiguration{
+ DatabaseURL: strings.TrimSpace(viper.GetString("usage.database-url")),
+ OpenCostBaseURL: strings.TrimSpace(viper.GetString("usage.opencost-base-url")),
+ QueryTimeout: usageQueryTimeout,
+ MaxResponseBytes: usageMaxResponseBytes,
+ },
Metrics: MetricsConfiguration{Addr: viper.GetString("metrics.addr")},
Telemetry: TelemetryConfiguration{
Endpoint: viper.GetString("telemetry.endpoint"),
@@ -285,6 +327,9 @@ func LoadConfig() (*Configuration, error) {
if cfg.Chat.Access.Enabled() && (cfg.Chat.BaseURL == "" || cfg.Chat.APIKey == "") {
return nil, fmt.Errorf("enabled chat access requires LITELLM_BASE_URL and LITELLM_API_KEY")
}
+ if err := validateUsageConfiguration(cfg.Usage); err != nil {
+ return nil, err
+ }
return cfg, nil
}
@@ -303,3 +348,59 @@ func chatAccessMode(access string, legacyEnabled bool) ChatAccessMode {
}
return ChatAccessDisabled
}
+
+func validateUsageConfiguration(cfg UsageConfiguration) error {
+ if cfg.QueryTimeout < minUsageQueryTimeout || cfg.QueryTimeout > maxUsageQueryTimeout {
+ return fmt.Errorf("USAGE_QUERY_TIMEOUT must be between 1s and 2m")
+ }
+ if cfg.MaxResponseBytes < minUsageResponseSize || cfg.MaxResponseBytes > maxUsageResponseSize {
+ return fmt.Errorf("USAGE_MAX_RESPONSE_BYTES must be between 65536 and 33554432")
+ }
+ // Deployments set OPENCOST_BASE_URL before the usage ExternalSecret is
+ // available. An absent database URL therefore disables usage, while a
+ // database URL without OpenCost remains an unsafe configuration error.
+ if cfg.DatabaseURL == "" {
+ return nil
+ }
+ if cfg.OpenCostBaseURL == "" {
+ return fmt.Errorf("USAGE_DATABASE_URL requires OPENCOST_BASE_URL")
+ }
+ databaseURL, err := url.Parse(cfg.DatabaseURL)
+ if err != nil {
+ return newSanitizedError("invalid usage database URL", err)
+ }
+ if (databaseURL.Scheme != "postgres" && databaseURL.Scheme != "postgresql") || databaseURL.Host == "" {
+ return fmt.Errorf("invalid usage database URL")
+ }
+ postgresConfig, err := pgxpool.ParseConfig(cfg.DatabaseURL)
+ if err != nil {
+ return newSanitizedError("invalid usage database URL", err)
+ }
+ if postgresConfig.ConnConfig.User != "cyclops_usage_reader" {
+ return fmt.Errorf("usage database URL must use cyclops_usage_reader")
+ }
+ openCostURL, err := url.Parse(cfg.OpenCostBaseURL)
+ if err != nil {
+ return newSanitizedError("invalid OpenCost URL", err)
+ }
+ if (openCostURL.Scheme != "http" && openCostURL.Scheme != "https") || openCostURL.Host == "" || openCostURL.RawQuery != "" || openCostURL.Fragment != "" || openCostURL.User != nil {
+ return fmt.Errorf("invalid OpenCost URL")
+ }
+ return nil
+}
+
+func parseUsageQueryTimeout(raw string) (time.Duration, error) {
+ value, err := time.ParseDuration(strings.TrimSpace(raw))
+ if err != nil {
+ return 0, fmt.Errorf("invalid USAGE_QUERY_TIMEOUT: %w", err)
+ }
+ return value, nil
+}
+
+func parseUsageMaxResponseBytes(raw string) (int64, error) {
+ value, err := strconv.ParseInt(strings.TrimSpace(raw), 10, 64)
+ if err != nil {
+ return 0, fmt.Errorf("invalid USAGE_MAX_RESPONSE_BYTES: %w", err)
+ }
+ return value, nil
+}
diff --git a/libs/fleet/backend/config/config_test.go b/libs/fleet/backend/config/config_test.go
index 8bdec3e066..0070304d9f 100644
--- a/libs/fleet/backend/config/config_test.go
+++ b/libs/fleet/backend/config/config_test.go
@@ -5,6 +5,7 @@ import (
"slices"
"strings"
"testing"
+ "time"
"github.com/spf13/pflag"
"github.com/spf13/viper"
@@ -273,3 +274,64 @@ func TestLoadConfig_ChatDisabledDoesNotRequireCredentials(t *testing.T) {
t.Fatalf("LoadConfig() error = %v, want disabled mode without credentials", err)
}
}
+
+func TestLoadConfig_UsageConfiguration(t *testing.T) {
+ validDatabaseURL := "postgres://cyclops_usage_reader:[email protected]/cyclops?sslmode=require"
+ validOpenCostURL := "https://opencost.example/api"
+ tests := []struct {
+ name string
+ env map[string]string
+ wantError string
+ want UsageConfiguration
+ }{
+ {name: "absent disables usage", want: UsageConfiguration{QueryTimeout: 20 * time.Second, MaxResponseBytes: 8388608}},
+ {name: "database only is rejected", env: map[string]string{"USAGE_DATABASE_URL": validDatabaseURL}, wantError: "USAGE_DATABASE_URL requires OPENCOST_BASE_URL"},
+ {name: "OpenCost only disables usage", env: map[string]string{"OPENCOST_BASE_URL": validOpenCostURL}, want: UsageConfiguration{OpenCostBaseURL: validOpenCostURL, QueryTimeout: 20 * time.Second, MaxResponseBytes: 8388608}},
+ {
+ name: "valid values",
+ env: map[string]string{
+ "USAGE_DATABASE_URL": validDatabaseURL, "OPENCOST_BASE_URL": validOpenCostURL,
+ "USAGE_QUERY_TIMEOUT": "45s", "USAGE_MAX_RESPONSE_BYTES": "1048576",
+ },
+ want: UsageConfiguration{DatabaseURL: validDatabaseURL, OpenCostBaseURL: validOpenCostURL, QueryTimeout: 45 * time.Second, MaxResponseBytes: 1048576},
+ },
+ {name: "libpq database DSN is rejected", env: map[string]string{"USAGE_DATABASE_URL": "user=cyclops_usage_reader host=db.example dbname=cyclops", "OPENCOST_BASE_URL": validOpenCostURL}, wantError: "invalid usage database URL"},
+ {name: "database reader role is required", env: map[string]string{"USAGE_DATABASE_URL": "postgres://[email protected]/cyclops", "OPENCOST_BASE_URL": validOpenCostURL}, wantError: "usage database URL must use cyclops_usage_reader"},
+ {name: "OpenCost URL cannot have a query", env: map[string]string{"USAGE_DATABASE_URL": validDatabaseURL, "OPENCOST_BASE_URL": "https://opencost.example?token=secret"}, wantError: "invalid OpenCost URL"},
+ {name: "malformed timeout is rejected while disabled", env: map[string]string{"USAGE_QUERY_TIMEOUT": "not-a-duration"}, wantError: "invalid USAGE_QUERY_TIMEOUT"},
+ {name: "malformed response limit is rejected while disabled", env: map[string]string{"USAGE_MAX_RESPONSE_BYTES": "not-a-number"}, wantError: "invalid USAGE_MAX_RESPONSE_BYTES"},
+ {name: "short timeout is rejected while disabled", env: map[string]string{"USAGE_QUERY_TIMEOUT": "500ms"}, wantError: "USAGE_QUERY_TIMEOUT must be between 1s and 2m"},
+ {name: "small response limit is rejected while disabled", env: map[string]string{"USAGE_MAX_RESPONSE_BYTES": "1"}, wantError: "USAGE_MAX_RESPONSE_BYTES must be between 65536 and 33554432"},
+ {name: "timeout is bounded", env: map[string]string{"USAGE_DATABASE_URL": validDatabaseURL, "OPENCOST_BASE_URL": validOpenCostURL, "USAGE_QUERY_TIMEOUT": "500ms"}, wantError: "USAGE_QUERY_TIMEOUT must be between 1s and 2m"},
+ {name: "response limit is bounded", env: map[string]string{"USAGE_DATABASE_URL": validDatabaseURL, "OPENCOST_BASE_URL": validOpenCostURL, "USAGE_MAX_RESPONSE_BYTES": "1"}, wantError: "USAGE_MAX_RESPONSE_BYTES must be between 65536 and 33554432"},
+ }
+
+ for _, test := range tests {
+ t.Run(test.name, func(t *testing.T) {
+ viper.Reset()
+ t.Cleanup(viper.Reset)
+ t.Setenv("KC_ADMIN_CLIENT_SECRET", "secret")
+ for _, key := range []string{"USAGE_DATABASE_URL", "OPENCOST_BASE_URL", "USAGE_QUERY_TIMEOUT", "USAGE_MAX_RESPONSE_BYTES"} {
+ t.Setenv(key, "")
+ }
+ for key, value := range test.env {
+ t.Setenv(key, value)
+ }
+ RegisterFlags(pflag.NewFlagSet("test", pflag.ContinueOnError))
+
+ cfg, err := LoadConfig()
+ if test.wantError != "" {
+ if err == nil || !strings.Contains(err.Error(), test.wantError) {
+ t.Fatalf("LoadConfig() error = %v, want containing %q", err, test.wantError)
+ }
+ return
+ }
+ if err != nil {
+ t.Fatalf("LoadConfig() error = %v", err)
+ }
+ if cfg.Usage != test.want {
+ t.Fatalf("Usage = %#v, want %#v", cfg.Usage, test.want)
+ }
+ })
+ }
+}
diff --git a/libs/fleet/backend/config/safe_error.go b/libs/fleet/backend/config/safe_error.go
new file mode 100644
index 0000000000..24c41dbd05
--- /dev/null
+++ b/libs/fleet/backend/config/safe_error.go
@@ -0,0 +1,17 @@
+package config
+
+type sanitizedError struct {
+ message string
+ cause error
+}
+
+func (err *sanitizedError) Error() string { return err.message }
+
+func (err *sanitizedError) Unwrap() error { return err.cause }
+
+func newSanitizedError(message string, cause error) error {
+ if cause == nil {
+ return nil
+ }
+ return &sanitizedError{message: message, cause: cause}
+}
diff --git a/libs/fleet/backend/config/safe_error_test.go b/libs/fleet/backend/config/safe_error_test.go
new file mode 100644
index 0000000000..5e405163a6
--- /dev/null
+++ b/libs/fleet/backend/config/safe_error_test.go
@@ -0,0 +1,17 @@
+package config
+
+import (
+ "errors"
+ "testing"
+)
+
+func TestNewSanitizedErrorRedactsAndPreservesCause(t *testing.T) {
+ cause := errors.New("secret connection detail")
+ err := newSanitizedError("invalid usage database URL", cause)
+ if err.Error() != "invalid usage database URL" {
+ t.Fatalf("Error() = %q", err.Error())
+ }
+ if !errors.Is(err, cause) {
+ t.Fatal("sanitized error lost cause identity")
+ }
+}
diff --git a/libs/fleet/backend/database/migrations/000002_usage_sandbox_events.sql b/libs/fleet/backend/database/migrations/000002_usage_sandbox_events.sql
new file mode 100644
index 0000000000..5c43a50af3
--- /dev/null
+++ b/libs/fleet/backend/database/migrations/000002_usage_sandbox_events.sql
@@ -0,0 +1,82 @@
+CREATE ROLE cyclops_usage_reader LOGIN NOINHERIT NOCREATEROLE NOSUPERUSER NOCREATEDB NOREPLICATION NOBYPASSRLS;
+ALTER ROLE cyclops_usage_reader SET default_transaction_read_only = on;
+ALTER ROLE cyclops_usage_reader SET statement_timeout = '10000ms';
+ALTER ROLE cyclops_usage_reader SET idle_in_transaction_session_timeout = '10000ms';
+
+SET LOCAL ROLE k8s_state_owner;
+CREATE INDEX resource_event_outbox_usage_lookup_idx
+ON k8s_state.resource_event_outbox
+(capsule_tenant, api_group, resource, observed_at, namespace, name);
+GRANT SELECT ON k8s_state.resource_event_outbox TO k8s_reporting_owner;
+RESET ROLE;
+
+SET LOCAL ROLE k8s_reporting_owner;
+CREATE FUNCTION k8s_reporting.usage_sandbox_events(
+ p_capsule_tenant text,
+ p_start timestamptz,
+ p_end timestamptz
+)
+RETURNS TABLE (
+ event_id uuid,
+ namespace text,
+ sandbox_name text,
+ sandbox_uid text,
+ pool_name text,
+ runtime text,
+ vm_name text,
+ event_type text,
+ observed_at timestamptz
+)
+LANGUAGE plpgsql
+STABLE
+SECURITY DEFINER
+SET search_path = k8s_state, pg_catalog
+AS $$
+BEGIN
+ IF p_capsule_tenant IS NULL OR p_capsule_tenant = '' THEN
+ RAISE EXCEPTION 'capsule tenant is required';
+ END IF;
+ IF p_start IS NULL OR p_end IS NULL OR p_end <= p_start OR p_end - p_start > interval '31 days' THEN
+ RAISE EXCEPTION 'usage window must be positive and at most 31 days';
+ END IF;
+
+ RETURN QUERY
+ WITH tenant_events AS (
+ SELECT event.*
+ FROM k8s_state.resource_event_outbox AS event
+ WHERE event.capsule_tenant = p_capsule_tenant
+ AND event.api_group = 'osgym.cua.ai'
+ AND event.resource = 'osgymsandboxes'
+ AND event.observed_at < p_end
+ ), baseline AS (
+ SELECT DISTINCT ON (event.namespace, event.uid) event.*
+ FROM tenant_events AS event
+ WHERE event.observed_at < p_start
+ ORDER BY event.namespace, event.uid, event.observed_at DESC, event.observed_sequence DESC, event.event_id DESC
+ ), window_events AS (
+ SELECT event.*
+ FROM tenant_events AS event
+ WHERE event.observed_at >= p_start
+ )
+ SELECT
+ event.event_id,
+ event.namespace,
+ event.name,
+ event.uid,
+ event.object -> 'metadata' -> 'labels' ->> 'osgym.cua.ai/warmpool',
+ event.object -> 'spec' -> 'vmTemplate' ->> 'runtime',
+ event.object -> 'status' ->> 'vmName',
+ event.event_type,
+ event.observed_at
+ FROM (
+ SELECT * FROM baseline
+ UNION ALL
+ SELECT * FROM window_events
+ ) AS event
+ ORDER BY event.namespace, event.uid, event.observed_at, event.observed_sequence, event.event_id;
+END
+$$;
+REVOKE ALL ON FUNCTION k8s_reporting.usage_sandbox_events(text, timestamptz, timestamptz) FROM PUBLIC;
+GRANT USAGE ON SCHEMA k8s_reporting TO cyclops_usage_reader;
+GRANT EXECUTE ON FUNCTION k8s_reporting.usage_sandbox_events(text, timestamptz, timestamptz) TO cyclops_usage_reader;
+RESET ROLE;
diff --git a/libs/fleet/backend/database/migrator.go b/libs/fleet/backend/database/migrator.go
index 3a81be7dbd..f1177a53d4 100644
--- a/libs/fleet/backend/database/migrator.go
+++ b/libs/fleet/backend/database/migrator.go
@@ -53,6 +53,7 @@ type CredentialURLs struct {
Exporter string
RoleAdmin string
Metabase string
+ Usage string
}
type migrationFile struct {
@@ -159,6 +160,7 @@ var expectedCredentialRoles = map[string]string{
"exporter": "k8s_state_exporter",
"role-admin": "k8s_role_admin",
"metabase": "k8s_metabase",
+ "usage": "cyclops_usage_reader",
}
const selectAppliedMigrationsStatement = `select version, filename, sha256 from cyclops_migrations.applied_migrations order by application_order`
@@ -339,10 +341,6 @@ func Run(ctx context.Context, config Config) (runErr error) {
}
defer transaction.Rollback(ctx)
- if err := validateNoPublicSecurityDefiner(ctx, transaction); err != nil {
- return err
- }
-
ddl := newRuntimeDDL(transaction)
started := time.Now()
if err := ddl.ensureMigrationLedger(ctx); err != nil {
@@ -422,6 +420,9 @@ func Run(ctx context.Context, config Config) (runErr error) {
if err := reconcileReportingBoundary(ctx, transaction); err != nil {
return err
}
+ if err := validateNoPublicSecurityDefiner(ctx, transaction); err != nil {
+ return err
+ }
credentialEvents, err := reconcilePasswords(ctx, transaction, credentials)
if err != nil {
return err
@@ -475,6 +476,7 @@ func parseCredentialURLs(urls CredentialURLs) ([]credential, error) {
{Name: "exporter", URL: urls.Exporter},
{Name: "role-admin", URL: urls.RoleAdmin},
{Name: "metabase", URL: urls.Metabase},
+ {Name: "usage", URL: urls.Usage},
}
credentials := make([]credential, 0, len(inputs))
@@ -507,11 +509,17 @@ func staticRoleContracts() []staticRoleContract {
{role: "k8s_role_admin", login: true, createRole: true, connectionLimit: -1, validUntil: staticRoleValidUntilInfinity},
{role: "k8s_reporting_owner", inherit: true, connectionLimit: -1, validUntil: staticRoleValidUntilInfinity},
{role: "k8s_metabase", login: true, connectionLimit: -1, validUntil: staticRoleValidUntilInfinity},
+ {role: "cyclops_usage_reader", login: true, connectionLimit: -1, validUntil: staticRoleValidUntilInfinity},
}
}
func staticRoleSettingsContracts() map[string]staticRoleSettingsContract {
return map[string]staticRoleSettingsContract{
+ "cyclops_usage_reader": {
+ staticRoleSettingDefaultTransactionReadOnly: "on",
+ staticRoleSettingStatementTimeout: "10000ms",
+ staticRoleSettingIdleInTransactionSessionTimeout: "10000ms",
+ },
"k8s_metabase": {
staticRoleSettingDefaultTransactionReadOnly: "on",
staticRoleSettingStatementTimeout: "20000ms",
@@ -552,12 +560,13 @@ func readStaticRoleAttributes(ctx context.Context, transaction pgx.Tx, role stri
}
type reportingACL struct {
- object reportingObject
- owner string
- privilege reportingPrivilege
- grantee string
- grantor string
- grantable bool
+ object reportingObject
+ routineIdentity string
+ owner string
+ privilege reportingPrivilege
+ grantee string
+ grantor string
+ grantable bool
}
func reconcileReportingBoundary(ctx context.Context, transaction pgx.Tx) error {
@@ -591,10 +600,16 @@ func reconcileReportingBoundary(ctx context.Context, transaction pgx.Tx) error {
}
}
for _, acl := range expectedReportingACLs() {
+ if acl.object.kind == reportingObjectRoutine {
+ continue
+ }
if err := newRuntimeDDL(transaction).grantReportingACL(ctx, acl); err != nil {
return fmt.Errorf("reconcile reporting ACLs: %w", err)
}
}
+ if err := reconcileUsageRoutineExecute(ctx, transaction); err != nil {
+ return err
+ }
finalACLs, err := readReportingACLs(ctx, transaction)
if err != nil {
@@ -641,13 +656,14 @@ func validateReportingBoundary(ctx context.Context, transaction pgx.Tx) error {
func readReportingACLs(ctx context.Context, transaction pgx.Tx) ([]reportingACL, error) {
rows, err := transaction.Query(ctx, `
- select object_type, schema_name, object_name, routine_oid, owner_name, privilege_type, grantee_name, grantor_name, is_grantable
+ select object_type, schema_name, object_name, routine_oid, routine_identity, owner_name, privilege_type, grantee_name, grantor_name, is_grantable
from (
select
'schema'::text as object_type,
namespace.nspname as schema_name,
''::text as object_name,
0::oid as routine_oid,
+ ''::text as routine_identity,
namespace.nspowner::regrole::text as owner_name,
acl.privilege_type,
case when acl.grantee = 0 then 'PUBLIC' else acl.grantee::regrole::text end as grantee_name,
@@ -658,7 +674,7 @@ func readReportingACLs(ctx context.Context, transaction pgx.Tx) ([]reportingACL,
where namespace.nspname !~ '^pg_'
and namespace.nspname <> 'information_schema'
and acl.grantee <> namespace.nspowner
- and (acl.grantee in ('k8s_reporting_owner'::regrole, 'k8s_metabase'::regrole)
+ and (acl.grantee in ('k8s_reporting_owner'::regrole, 'k8s_metabase'::regrole, 'cyclops_usage_reader'::regrole)
or (namespace.nspname = 'k8s_reporting' and acl.grantee <> namespace.nspowner))
union all
select
@@ -666,6 +682,7 @@ func readReportingACLs(ctx context.Context, transaction pgx.Tx) ([]reportingACL,
namespace.nspname,
relation.relname,
0::oid,
+ ''::text,
relation.relowner::regrole::text,
acl.privilege_type,
case when acl.grantee = 0 then 'PUBLIC' else acl.grantee::regrole::text end,
@@ -678,7 +695,7 @@ func readReportingACLs(ctx context.Context, transaction pgx.Tx) ([]reportingACL,
and namespace.nspname <> 'information_schema'
and acl.grantee <> relation.relowner
and relation.relkind in ('r', 'p', 'v', 'm', 'f', 'S')
- and (acl.grantee in ('k8s_reporting_owner'::regrole, 'k8s_metabase'::regrole)
+ and (acl.grantee in ('k8s_reporting_owner'::regrole, 'k8s_metabase'::regrole, 'cyclops_usage_reader'::regrole)
or (namespace.nspname = 'k8s_reporting' and relation.relname = 'current_resources' and acl.grantee <> relation.relowner))
union all
select
@@ -686,6 +703,12 @@ func readReportingACLs(ctx context.Context, transaction pgx.Tx) ([]reportingACL,
''::text,
''::text,
routine.oid,
+ case
+ when namespace.nspname = 'k8s_reporting'
+ and routine.proname = 'usage_sandbox_events'
+ and routine.proargtypes = '25 1184 1184'::oidvector then 'usage_sandbox_events'
+ else routine.oid::regprocedure::text
+ end,
routine.proowner::regrole::text,
acl.privilege_type,
case when acl.grantee = 0 then 'PUBLIC' else acl.grantee::regrole::text end,
@@ -697,9 +720,16 @@ func readReportingACLs(ctx context.Context, transaction pgx.Tx) ([]reportingACL,
where namespace.nspname !~ '^pg_'
and namespace.nspname <> 'information_schema'
and acl.grantee <> routine.proowner
- and acl.grantee in ('k8s_reporting_owner'::regrole, 'k8s_metabase'::regrole)
+ and (
+ acl.grantee in ('k8s_reporting_owner'::regrole, 'k8s_metabase'::regrole, 'cyclops_usage_reader'::regrole)
+ or (
+ namespace.nspname = 'k8s_reporting'
+ and routine.proname = 'usage_sandbox_events'
+ and routine.proargtypes = '25 1184 1184'::oidvector
+ )
+ )
) as reporting_acl
- order by object_type, schema_name, object_name, routine_oid, privilege_type, grantee_name, grantor_name`)
+ order by object_type, schema_name, object_name, routine_oid, routine_identity, privilege_type, grantee_name, grantor_name`)
if err != nil {
return nil, fmt.Errorf("enumerate reporting ACLs: %w", err)
}
@@ -714,6 +744,7 @@ func readReportingACLs(ctx context.Context, transaction pgx.Tx) ([]reportingACL,
&acl.object.schema,
&acl.object.name,
&acl.object.routineOID,
+ &acl.routineIdentity,
&acl.owner,
&privilegeSQL,
&acl.grantee,
@@ -743,8 +774,11 @@ func expectedReportingACLs() []reportingACL {
return []reportingACL{
{object: reportingObject{kind: reportingObjectSchema, schema: "k8s_state"}, owner: "k8s_state_owner", privilege: reportingPrivilegeUsage, grantee: "k8s_reporting_owner", grantor: "k8s_state_owner"},
{object: reportingObject{kind: reportingObjectRelation, schema: "k8s_state", name: "resource_state"}, owner: "k8s_state_owner", privilege: reportingPrivilegeSelect, grantee: "k8s_reporting_owner", grantor: "k8s_state_owner"},
+ {object: reportingObject{kind: reportingObjectRelation, schema: "k8s_state", name: "resource_event_outbox"}, owner: "k8s_state_owner", privilege: reportingPrivilegeSelect, grantee: "k8s_reporting_owner", grantor: "k8s_state_owner"},
{object: reportingObject{kind: reportingObjectSchema, schema: "k8s_reporting"}, owner: "k8s_reporting_owner", privilege: reportingPrivilegeUsage, grantee: "k8s_metabase", grantor: "k8s_reporting_owner"},
{object: reportingObject{kind: reportingObjectRelation, schema: "k8s_reporting", name: "current_resources"}, owner: "k8s_reporting_owner", privilege: reportingPrivilegeSelect, grantee: "k8s_metabase", grantor: "k8s_reporting_owner"},
+ {object: reportingObject{kind: reportingObjectSchema, schema: "k8s_reporting"}, owner: "k8s_reporting_owner", privilege: reportingPrivilegeUsage, grantee: "cyclops_usage_reader", grantor: "k8s_reporting_owner"},
+ {object: reportingObject{kind: reportingObjectRoutine}, routineIdentity: "usage_sandbox_events", owner: "k8s_reporting_owner", privilege: reportingPrivilegeExecute, grantee: "cyclops_usage_reader", grantor: "k8s_reporting_owner"},
}
}
@@ -754,13 +788,42 @@ func isExpectedReportingACL(acl reportingACL) bool {
func containsReportingACL(acls []reportingACL, want reportingACL) bool {
for _, acl := range acls {
- if acl.object == want.object && acl.owner == want.owner && acl.privilege == want.privilege && acl.grantee == want.grantee && acl.grantor == want.grantor && acl.grantable == want.grantable {
+ objectMatches := acl.object == want.object
+ if want.object.kind == reportingObjectRoutine {
+ objectMatches = acl.object.kind == reportingObjectRoutine && acl.routineIdentity == want.routineIdentity
+ }
+ if objectMatches && acl.owner == want.owner && acl.privilege == want.privilege && acl.grantee == want.grantee && acl.grantor == want.grantor && acl.grantable == want.grantable {
return true
}
}
return false
}
+func reconcileUsageRoutineExecute(ctx context.Context, transaction pgx.Tx) error {
+ var routineOID uint32
+ if err := transaction.QueryRow(ctx, `
+ select routine.oid
+ from pg_proc as routine
+ join pg_namespace as namespace on namespace.oid = routine.pronamespace
+ where namespace.nspname = 'k8s_reporting'
+ and routine.proname = 'usage_sandbox_events'
+ and routine.proargtypes = '25 1184 1184'::oidvector`).Scan(&routineOID); err != nil {
+ return fmt.Errorf("resolve usage reporting routine: %w", err)
+ }
+ acl := reportingACL{
+ object: reportingObject{kind: reportingObjectRoutine, routineOID: routineOID},
+ routineIdentity: "usage_sandbox_events",
+ owner: "k8s_reporting_owner",
+ privilege: reportingPrivilegeExecute,
+ grantee: "cyclops_usage_reader",
+ grantor: "k8s_reporting_owner",
+ }
+ if err := newRuntimeDDL(transaction).grantReportingACL(ctx, acl); err != nil {
+ return fmt.Errorf("reconcile usage routine execute grant: %w", err)
+ }
+ return nil
+}
+
func isSafeReportingACLAuthority(acl reportingACL, migrationOwner string) bool {
if acl.grantor != acl.owner {
return false
diff --git a/libs/fleet/backend/database/migrator_pg_test.go b/libs/fleet/backend/database/migrator_pg_test.go
index 3306575461..3ba5b45bbe 100644
--- a/libs/fleet/backend/database/migrator_pg_test.go
+++ b/libs/fleet/backend/database/migrator_pg_test.go
@@ -1,9 +1,12 @@
package database
import (
+ "bytes"
"context"
"crypto/rand"
"encoding/hex"
+ "encoding/json"
+ "log/slog"
"net/url"
"os"
"reflect"
@@ -20,6 +23,7 @@ const tenantCredentialFingerprintLookup = `select credential_fingerprint from k8
var staticMigrationRoles = []string{
"cyclops_app",
+ "cyclops_usage_reader",
"k8s_state_owner",
"k8s_state_writer",
"k8s_state_exporter",
@@ -114,9 +118,31 @@ func TestInitialMigrationBuildsCompleteDatabase(t *testing.T) {
assertExporterBoundary(t, ctx, credentials.Exporter)
assertTenantReadPath(t, ctx, tenantURL)
assertMetabaseBoundary(t, ctx, inspectionURL, credentials.Metabase)
+ assertUsageReaderBoundary(t, ctx, inspectionURL, credentials.Usage)
assertApplicationBoundary(t, ctx, credentials.Application)
}
+func TestRunUpgradesVersionOneAndThenNoOps(t *testing.T) {
+ maintenanceURL := requireMigratorIntegration(t)
+ ctx := context.Background()
+ migrationURL, credentials := isolatedMigrationDatabase(t, ctx, maintenanceURL)
+ applyOnlyMigrationOne(t, ctx, migrationURL)
+
+ upgrade := captureRunSummary(t, func() error {
+ return Run(ctx, Config{MigrationURL: migrationURL, Credentials: credentials})
+ })
+ if upgrade.Current != 1 || upgrade.Target != 2 || upgrade.Pending != 1 || upgrade.Applied != 1 || upgrade.Skipped != 1 || upgrade.Result != "success" {
+ t.Fatalf("version-one upgrade summary = %+v", upgrade)
+ }
+
+ noOp := captureRunSummary(t, func() error {
+ return Run(ctx, Config{MigrationURL: migrationURL, Credentials: credentials})
+ })
+ if noOp.Current != 2 || noOp.Target != 2 || noOp.Pending != 0 || noOp.Applied != 0 || noOp.Skipped != 2 || noOp.Result != "success" {
+ t.Fatalf("post-upgrade no-op summary = %+v", noOp)
+ }
+}
+
func TestRunReconcilesReportingDirectACLDrift(t *testing.T) {
maintenanceURL := requireMigratorIntegration(t)
ctx := context.Background()
@@ -361,6 +387,29 @@ func TestRunRechecksPublicSecurityDefinerBeforeMutations(t *testing.T) {
}
}
+func TestRunReconcilesPublicExecuteOnExpectedUsageRoutine(t *testing.T) {
+ maintenanceURL := requireMigratorIntegration(t)
+ ctx := context.Background()
+ migrationURL, credentials := isolatedMigrationDatabase(t, ctx, maintenanceURL)
+ if err := Run(ctx, Config{MigrationURL: migrationURL, Credentials: credentials}); err != nil {
+ t.Fatal(err)
+ }
+
+ connection := connect(t, ctx, migrationURL)
+ defer connection.Close(ctx)
+ if _, err := connection.Exec(ctx, `set role k8s_reporting_owner; grant execute on function k8s_reporting.usage_sandbox_events(text, timestamptz, timestamptz) to public; reset role`); err != nil {
+ t.Fatal("introduce PUBLIC usage routine execute drift")
+ }
+
+ if err := Run(ctx, Config{MigrationURL: migrationURL, Credentials: credentials}); err != nil {
+ t.Fatalf("Run() reconcile PUBLIC usage routine execute drift: %v", err)
+ }
+ inspection := connect(t, ctx, maintenanceURLForDatabase(t, maintenanceURL, migrationURL))
+ defer inspection.Close(ctx)
+ assertNoPublicFunctionExecute(t, ctx, inspection, "k8s_reporting.usage_sandbox_events(text,timestamptz,timestamptz)")
+ assertExactReportingACLContract(t, ctx, inspection)
+}
+
func TestRunDeniesMetabaseProcedureWriteAfterReadOnlyGUCBypass(t *testing.T) {
maintenanceURL := requireMigratorIntegration(t)
ctx := context.Background()
@@ -535,7 +584,7 @@ func TestRunFailsClosedForUnsafeStaticRoleAttributeDrift(t *testing.T) {
}
}
-func TestRunFailsClosedForStaticRoleCreateDBDrift(t *testing.T) {
+func TestRunReconcilesStaticRoleCreateDBDrift(t *testing.T) {
maintenanceURL := os.Getenv("CYCLOPS_TEST_DATABASE_URL")
if maintenanceURL == "" {
t.Skip("set CYCLOPS_TEST_DATABASE_URL to run PostgreSQL migration tests")
@@ -551,22 +600,48 @@ func TestRunFailsClosedForStaticRoleCreateDBDrift(t *testing.T) {
}
maintenance := connect(t, ctx, maintenanceURL)
defer maintenance.Close(ctx)
- if _, err := maintenance.Exec(ctx, `alter role cyclops_app nologin createdb`); err != nil {
+ migrationOwner := currentRole(t, ctx, migrationURL)
+ if _, err := maintenance.Exec(ctx, "alter role "+pgx.Identifier{migrationOwner}.Sanitize()+` createdb; alter role cyclops_app nologin createdb`); err != nil {
t.Fatal("introduce static role createdb drift")
}
- err := Run(ctx, Config{MigrationURL: migrationURL, Credentials: credentials})
- const want = "static role cyclops_app has unsafe privileged drift: rolcreatedb=true; the migration owner cannot safely repair these attributes"
- if err == nil || err.Error() != want {
- t.Fatalf("Run() error = %v, want %q", err, want)
+ if err := Run(ctx, Config{MigrationURL: migrationURL, Credentials: credentials}); err != nil {
+ t.Fatalf("Run() reconcile static role createdb drift: %v", err)
}
var login, createDB bool
if err := maintenance.QueryRow(ctx, `select rolcanlogin, rolcreatedb from pg_roles where rolname = 'cyclops_app'`).Scan(&login, &createDB); err != nil {
t.Fatal("read static role after rejected createdb drift")
}
+ if !login || createDB {
+ t.Fatalf("static role after createdb reconciliation: login:%t createdb:%t", login, createDB)
+ }
+}
+
+func TestRunFailsClosedForStaticRoleCreateDBDriftWithoutAuthority(t *testing.T) {
+ maintenanceURL := requireMigratorIntegration(t)
+ ctx := context.Background()
+ migrationURL, credentials := isolatedMigrationDatabase(t, ctx, maintenanceURL)
+ if err := Run(ctx, Config{MigrationURL: migrationURL, Credentials: credentials}); err != nil {
+ t.Fatal(err)
+ }
+ maintenance := connect(t, ctx, maintenanceURL)
+ defer maintenance.Close(ctx)
+ if _, err := maintenance.Exec(ctx, `alter role cyclops_app nologin createdb`); err != nil {
+ t.Fatal("introduce static role createdb drift without migrator authority")
+ }
+
+ err := Run(ctx, Config{MigrationURL: migrationURL, Credentials: credentials})
+ if err == nil || !strings.Contains(err.Error(), "permission denied to alter role") {
+ t.Fatalf("Run() error = %v, want fail-closed role authority error", err)
+ }
+
+ var login, createDB bool
+ if err := maintenance.QueryRow(ctx, `select rolcanlogin, rolcreatedb from pg_roles where rolname = 'cyclops_app'`).Scan(&login, &createDB); err != nil {
+ t.Fatal("read static role after unauthorized createdb reconciliation")
+ }
if login || !createDB {
- t.Fatalf("static role changed after rejected createdb drift: login:%t createdb:%t", login, createDB)
+ t.Fatalf("static role changed after unauthorized createdb reconciliation: login:%t createdb:%t", login, createDB)
}
}
@@ -1117,6 +1192,7 @@ func TestRunReconcilesStaticRoleSettingsContract(t *testing.T) {
`alter role k8s_metabase set default_transaction_read_only = off`,
`alter role k8s_metabase set search_path = public`,
`alter role k8s_metabase in database ` + pgx.Identifier{connection.Config().Database}.Sanitize() + ` set work_mem = '64MB'`,
+ `alter role cyclops_usage_reader set statement_timeout = '1ms'`,
} {
if _, err := connection.Exec(ctx, statement); err != nil {
t.Fatalf("introduce static role setting drift %q: %v", statement, err)
@@ -1130,8 +1206,13 @@ func TestRunReconcilesStaticRoleSettingsContract(t *testing.T) {
"statement_timeout": "20000ms",
"idle_in_transaction_session_timeout": "20000ms",
})
+ assertStaticRoleSettings(t, ctx, connection, "cyclops_usage_reader", map[string]string{
+ "default_transaction_read_only": "on",
+ "statement_timeout": "10000ms",
+ "idle_in_transaction_session_timeout": "10000ms",
+ })
for _, role := range staticMigrationRoles {
- if role == "k8s_metabase" {
+ if role == "k8s_metabase" || role == "cyclops_usage_reader" {
continue
}
assertStaticRoleSettings(t, ctx, connection, role, map[string]string{})
@@ -1232,6 +1313,75 @@ type ledgerRow struct {
AppliedAt time.Time
}
+func applyOnlyMigrationOne(t *testing.T, ctx context.Context, migrationURL string) {
+ t.Helper()
+ files, err := embeddedMigrations()
+ if err != nil {
+ t.Fatal(err)
+ }
+ if len(files) < 2 || files[0].Version != 1 {
+ t.Fatalf("embedded migrations = %+v, want immutable version one followed by current migrations", files)
+ }
+
+ connection := connect(t, ctx, migrationURL)
+ defer connection.Close(ctx)
+ transaction, err := connection.Begin(ctx)
+ if err != nil {
+ t.Fatal("begin version-one migration fixture")
+ }
+ defer transaction.Rollback(ctx)
+ if err := newRuntimeDDL(transaction).ensureMigrationLedger(ctx); err != nil {
+ t.Fatalf("prepare version-one migration ledger: %v", err)
+ }
+ if _, err := transaction.Exec(ctx, files[0].SQL); err != nil {
+ t.Fatalf("apply immutable migration one: %v", err)
+ }
+ if _, err := transaction.Exec(ctx, insertAppliedMigrationStatement, files[0].Version, files[0].Name, files[0].SHA256); err != nil {
+ t.Fatalf("record immutable migration one: %v", err)
+ }
+ if err := transaction.Commit(ctx); err != nil {
+ t.Fatalf("commit immutable migration one: %v", err)
+ }
+}
+
+func captureRunSummary(t *testing.T, run func() error) migrationSummary {
+ t.Helper()
+ var output bytes.Buffer
+ previous := slog.Default()
+ slog.SetDefault(slog.New(slog.NewJSONHandler(&output, nil)))
+ defer slog.SetDefault(previous)
+
+ if err := run(); err != nil {
+ t.Fatal(err)
+ }
+ for _, line := range strings.Split(strings.TrimSpace(output.String()), "\n") {
+ var entry struct {
+ Message string `json:"msg"`
+ Current int64 `json:"current_version"`
+ Target int64 `json:"target_version"`
+ Pending int `json:"pending"`
+ Applied int `json:"applied"`
+ Skipped int `json:"skipped"`
+ Result string `json:"result"`
+ }
+ if err := json.Unmarshal([]byte(line), &entry); err != nil {
+ t.Fatalf("decode migration log entry: %v", err)
+ }
+ if entry.Message == "database migration summary" {
+ return migrationSummary{
+ Current: entry.Current,
+ Target: entry.Target,
+ Pending: entry.Pending,
+ Applied: entry.Applied,
+ Skipped: entry.Skipped,
+ Result: entry.Result,
+ }
+ }
+ }
+ t.Fatalf("migration summary missing from logs: %s", output.String())
+ return migrationSummary{}
+}
+
func isolatedMigrationDatabase(t *testing.T, ctx context.Context, maintenanceURL string) (string, CredentialURLs) {
t.Helper()
parsed, err := url.Parse(maintenanceURL)
@@ -1350,6 +1500,7 @@ func testCredentialURLs(t *testing.T, adminURL string) CredentialURLs {
Exporter: withRole("k8s_state_exporter"),
RoleAdmin: withRole("k8s_role_admin"),
Metabase: withRole("k8s_metabase"),
+ Usage: withRole("cyclops_usage_reader"),
}
}
@@ -1382,8 +1533,19 @@ func migrationLedgerRows(t *testing.T, ctx context.Context, adminURL string) []l
if err := rows.Err(); err != nil {
t.Fatal("iterate migration ledger")
}
- if len(ledger) != 1 {
- t.Fatalf("migration ledger row count = %d, want 1", len(ledger))
+ if len(ledger) != 2 {
+ t.Fatalf("migration ledger row count = %d, want 2", len(ledger))
+ }
+ for index, want := range []struct {
+ version int64
+ filename string
+ }{
+ {1, "000001_initial_schema.sql"},
+ {2, "000002_usage_sandbox_events.sql"},
+ } {
+ if ledger[index].Version != want.version || ledger[index].ApplicationOrder != int64(index+1) || ledger[index].Filename != want.filename {
+ t.Fatalf("migration ledger row %d = version:%d order:%d filename:%q", index, ledger[index].Version, ledger[index].ApplicationOrder, ledger[index].Filename)
+ }
}
return ledger
}
@@ -1506,15 +1668,16 @@ func assertRoleContract(t *testing.T, ctx context.Context, adminURL string) {
defer connection.Close(ctx)
expected := map[string]struct{ login, inherit, createRole bool }{
- "cyclops_app": {true, false, false},
- "k8s_state_owner": {false, true, false},
- "k8s_state_writer": {true, false, false},
- "k8s_state_exporter": {true, false, false},
- "k8s_query_tenant": {false, true, false},
- "k8s_query_admin": {false, true, false},
- "k8s_role_admin": {true, false, true},
- "k8s_reporting_owner": {false, true, false},
- "k8s_metabase": {true, false, false},
+ "cyclops_app": {true, false, false},
+ "k8s_state_owner": {false, true, false},
+ "k8s_state_writer": {true, false, false},
+ "k8s_state_exporter": {true, false, false},
+ "k8s_query_tenant": {false, true, false},
+ "k8s_query_admin": {false, true, false},
+ "k8s_role_admin": {true, false, true},
+ "k8s_reporting_owner": {false, true, false},
+ "k8s_metabase": {true, false, false},
+ "cyclops_usage_reader": {true, false, false},
}
for role, want := range expected {
var login, inherit, createRole, super, createDB, replication, bypassRLS bool
@@ -1617,6 +1780,7 @@ func assertOwnershipAndPublicACLs(t *testing.T, ctx context.Context, adminURL, m
{"public", "github_trust_policies", migrationOwner},
{"k8s_state", "resource_state", "k8s_state_owner"},
{"k8s_state", "resource_event_outbox", "k8s_state_owner"},
+ {"k8s_state", "resource_event_outbox_usage_lookup_idx", "k8s_state_owner"},
{"k8s_api", "current_resources", "k8s_state_owner"},
{"k8s_reporting", "current_resources", "k8s_reporting_owner"},
} {
@@ -1707,7 +1871,7 @@ func assertRuntimeLedgerAccess(t *testing.T, ctx context.Context, credentials Cr
var count int
err := connection.QueryRow(ctx, `select count(*) from cyclops_migrations.applied_migrations`).Scan(&count)
connection.Close(ctx)
- if err != nil || count != 1 {
+ if err != nil || count != 2 {
t.Errorf("%s ledger select = count:%d err:%v", role, count, err)
}
assertStatementFails(t, ctx, databaseURL, `insert into cyclops_migrations.applied_migrations (version, filename, sha256) values (99, 'invalid.sql', 'invalid')`)
@@ -1718,6 +1882,111 @@ func assertRuntimeLedgerAccess(t *testing.T, ctx context.Context, credentials Cr
assertStatementFails(t, ctx, credentials.Metabase, `insert into cyclops_migrations.applied_migrations (version, filename, sha256) values (99, 'invalid.sql', 'invalid')`)
assertStatementFails(t, ctx, credentials.Metabase, `update cyclops_migrations.applied_migrations set filename = 'invalid.sql' where version = 1`)
assertStatementFails(t, ctx, credentials.Metabase, `delete from cyclops_migrations.applied_migrations where version = 1`)
+ assertStatementFails(t, ctx, credentials.Usage, `select 1 from cyclops_migrations.applied_migrations limit 1`)
+}
+
+func assertUsageReaderBoundary(t *testing.T, ctx context.Context, inspectionURL, usageURL string) {
+ t.Helper()
+ inspection := connect(t, ctx, inspectionURL)
+ defer inspection.Close(ctx)
+ var owner, volatility, config string
+ var securityDefiner bool
+ if err := inspection.QueryRow(ctx, `
+ select routine.proowner::regrole::text, routine.provolatile::text, routine.prosecdef, coalesce(array_to_string(routine.proconfig, ','), '')
+ from pg_proc as routine
+ join pg_namespace as namespace on namespace.oid = routine.pronamespace
+ where namespace.nspname = 'k8s_reporting'
+ and routine.proname = 'usage_sandbox_events'
+ and routine.proargtypes = '25 1184 1184'::oidvector`).Scan(&owner, &volatility, &securityDefiner, &config); err != nil {
+ t.Fatalf("read usage reporting function contract: %v", err)
+ }
+ if owner != "k8s_reporting_owner" || volatility != "s" || !securityDefiner || config != "search_path=k8s_state, pg_catalog" {
+ t.Fatalf("usage reporting function = owner:%s volatility:%s definer:%t config:%q", owner, volatility, securityDefiner, config)
+ }
+ assertNoPublicFunctionExecute(t, ctx, inspection, "k8s_reporting.usage_sandbox_events(text,timestamptz,timestamptz)")
+ for privilege, want := range map[string]bool{"SELECT": false, "DELETE": false} {
+ var allowed bool
+ if err := inspection.QueryRow(ctx, `select has_table_privilege('cyclops_usage_reader', 'k8s_state.resource_event_outbox', $1)`, privilege).Scan(&allowed); err != nil || allowed != want {
+ t.Fatalf("usage reader outbox %s privilege = %t err=%v, want %t", privilege, allowed, err, want)
+ }
+ }
+ _, err := inspection.Exec(ctx, `
+ insert into k8s_state.resource_event_outbox
+ (event_id, cluster_id, api_group, resource, namespace, name, capsule_tenant, uid, schema_hash, event_type, watch_epoch, observed_sequence, object, observed_at)
+ values
+ ('10000000-0000-0000-0000-000000000010', 'migration-test', 'osgym.cua.ai', 'osgymsandboxes', 'alice-ns', 'sandbox-a', 'user-alice', 'sandbox-uid-a', 'schema', 'ADDED', 2, 100, '{"metadata":{"labels":{"osgym.cua.ai/warmpool":"pool-old"}},"spec":{"vmTemplate":{"runtime":"qemu"}},"status":{"vmName":"vm-old"}}', '2026-08-17T00:00:00Z'),
+ ('10000000-0000-0000-0000-000000000011', 'migration-test', 'osgym.cua.ai', 'osgymsandboxes', 'alice-ns', 'sandbox-a', 'user-alice', 'sandbox-uid-a', 'schema', 'MODIFIED', 2, 101, '{"metadata":{"labels":{"osgym.cua.ai/warmpool":"pool-a"}},"spec":{"vmTemplate":{"runtime":"qemu"}},"status":{"vmName":"vm-a"}}', '2026-08-17T23:00:00Z'),
+ ('10000000-0000-0000-0000-000000000012', 'migration-test', 'osgym.cua.ai', 'osgymsandboxes', 'alice-ns', 'sandbox-a', 'user-alice', 'sandbox-uid-a', 'schema', 'MODIFIED', 2, 102, '{"metadata":{"labels":{"osgym.cua.ai/warmpool":"pool-a"}},"spec":{"vmTemplate":{"runtime":"qemu"}},"status":{"vmName":"vm-a-2"}}', '2026-08-18T06:00:00Z'),
+ ('10000000-0000-0000-0000-000000000013', 'migration-test', 'osgym.cua.ai', 'osgymsandboxes', 'alice-ns', 'sandbox-a', 'user-alice', 'sandbox-uid-a', 'schema', 'DELETED', 2, 103, '{"metadata":{"labels":{"osgym.cua.ai/warmpool":"pool-a"}},"spec":{"vmTemplate":{"runtime":"qemu"}},"status":{"vmName":"vm-a-2"}}', '2026-08-18T12:00:00Z'),
+ ('10000000-0000-0000-0000-000000000014', 'migration-test', 'osgym.cua.ai', 'osgymsandboxes', 'bob-ns', 'sandbox-b', 'user-bob', 'sandbox-uid-b', 'schema', 'ADDED', 2, 104, '{"metadata":{"labels":{"osgym.cua.ai/warmpool":"pool-b"}},"spec":{"vmTemplate":{"runtime":"qemu"}},"status":{"vmName":"vm-b"}}', '2026-08-18T08:00:00Z'),
+ ('10000000-0000-0000-0000-000000000015', 'migration-test', '', 'pods', 'alice-ns', 'sandbox-pod', 'user-alice', 'pod-uid', 'schema', 'ADDED', 2, 105, '{}', '2026-08-18T09:00:00Z'),
+ ('10000000-0000-0000-0000-000000000016', 'migration-test', 'osgym.cua.ai', 'osgymsandboxes', 'alice-ns', 'sandbox-after', 'user-alice', 'sandbox-uid-after', 'schema', 'ADDED', 2, 106, '{}', '2026-08-19T00:00:00Z'),
+ ('10000000-0000-0000-0000-000000000017', 'migration-test', 'osgym.cua.ai', 'osgymsandboxes', 'alice-ns', 'sandbox-b', 'user-alice', 'sandbox-uid-b', 'schema', 'ADDED', 2, 107, '{"metadata":{"labels":{"osgym.cua.ai/warmpool":"pool-b-old"}},"spec":{"vmTemplate":{"runtime":"qemu"}},"status":{"vmName":"vm-b-old"}}', '2026-08-17T20:00:00Z'),
+ ('10000000-0000-0000-0000-000000000018', 'migration-test', 'osgym.cua.ai', 'osgymsandboxes', 'alice-ns', 'sandbox-b', 'user-alice', 'sandbox-uid-b', 'schema', 'MODIFIED', 2, 108, '{"metadata":{"labels":{"osgym.cua.ai/warmpool":"pool-b"}},"spec":{"vmTemplate":{"runtime":"qemu"}},"status":{"vmName":"vm-b"}}', '2026-08-17T22:00:00Z'),
+ ('10000000-0000-0000-0000-000000000019', 'migration-test', 'osgym.cua.ai', 'osgymsandboxes', 'alice-other', 'sandbox-a', 'user-alice', 'sandbox-uid-a', 'schema', 'ADDED', 2, 109, '{"metadata":{"labels":{"osgym.cua.ai/warmpool":"pool-other-old"}},"spec":{"vmTemplate":{"runtime":"qemu"}},"status":{"vmName":"vm-other-old"}}', '2026-08-17T19:00:00Z'),
+ ('10000000-0000-0000-0000-000000000020', 'migration-test', 'osgym.cua.ai', 'osgymsandboxes', 'alice-other', 'sandbox-a', 'user-alice', 'sandbox-uid-a', 'schema', 'MODIFIED', 2, 110, '{"metadata":{"labels":{"osgym.cua.ai/warmpool":"pool-other"}},"spec":{"vmTemplate":{"runtime":"qemu"}},"status":{"vmName":"vm-other"}}', '2026-08-17T21:00:00Z')`)
+ if err != nil {
+ t.Fatal("seed usage sandbox events")
+ }
+
+ type usageEvent struct {
+ eventID, namespace, name, uid, pool, runtime, vmName, eventType string
+ observedAt time.Time
+ }
+ connection := connect(t, ctx, usageURL)
+ defer connection.Close(ctx)
+ for setting, want := range map[string]string{
+ "default_transaction_read_only": "on",
+ "statement_timeout": "10s",
+ "idle_in_transaction_session_timeout": "10s",
+ } {
+ var got string
+ if err := connection.QueryRow(ctx, "show "+setting).Scan(&got); err != nil || got != want {
+ t.Fatalf("usage reader %s = %q err=%v, want %q", setting, got, err, want)
+ }
+ }
+ rows, err := connection.Query(ctx, `select event_id, namespace, sandbox_name, sandbox_uid, pool_name, runtime, vm_name, event_type, observed_at from k8s_reporting.usage_sandbox_events($1, $2, $3)`, "user-alice", time.Date(2026, 8, 18, 0, 0, 0, 0, time.UTC), time.Date(2026, 8, 19, 0, 0, 0, 0, time.UTC))
+ if err != nil {
+ t.Fatalf("query usage sandbox events: %v", err)
+ }
+ defer rows.Close()
+ var got []usageEvent
+ for rows.Next() {
+ var event usageEvent
+ if err := rows.Scan(&event.eventID, &event.namespace, &event.name, &event.uid, &event.pool, &event.runtime, &event.vmName, &event.eventType, &event.observedAt); err != nil {
+ t.Fatal("scan usage sandbox event")
+ }
+ event.observedAt = event.observedAt.UTC()
+ got = append(got, event)
+ }
+ if err := rows.Err(); err != nil {
+ t.Fatalf("read usage sandbox events: %v", err)
+ }
+ want := []usageEvent{
+ {"10000000-0000-0000-0000-000000000011", "alice-ns", "sandbox-a", "sandbox-uid-a", "pool-a", "qemu", "vm-a", "MODIFIED", time.Date(2026, 8, 17, 23, 0, 0, 0, time.UTC)},
+ {"10000000-0000-0000-0000-000000000012", "alice-ns", "sandbox-a", "sandbox-uid-a", "pool-a", "qemu", "vm-a-2", "MODIFIED", time.Date(2026, 8, 18, 6, 0, 0, 0, time.UTC)},
+ {"10000000-0000-0000-0000-000000000013", "alice-ns", "sandbox-a", "sandbox-uid-a", "pool-a", "qemu", "vm-a-2", "DELETED", time.Date(2026, 8, 18, 12, 0, 0, 0, time.UTC)},
+ {"10000000-0000-0000-0000-000000000018", "alice-ns", "sandbox-b", "sandbox-uid-b", "pool-b", "qemu", "vm-b", "MODIFIED", time.Date(2026, 8, 17, 22, 0, 0, 0, time.UTC)},
+ {"10000000-0000-0000-0000-000000000020", "alice-other", "sandbox-a", "sandbox-uid-a", "pool-other", "qemu", "vm-other", "MODIFIED", time.Date(2026, 8, 17, 21, 0, 0, 0, time.UTC)},
+ }
+ if !reflect.DeepEqual(got, want) {
+ t.Fatalf("usage sandbox events = %#v, want %#v", got, want)
+ }
+
+ for _, statement := range []string{
+ `select * from k8s_reporting.usage_sandbox_events('', '2026-08-18T00:00:00Z', '2026-08-19T00:00:00Z')`,
+ `select * from k8s_reporting.usage_sandbox_events('user-alice', '2026-08-19T00:00:00Z', '2026-08-18T00:00:00Z')`,
+ `select * from k8s_reporting.usage_sandbox_events('user-alice', '2026-07-18T00:00:00Z', '2026-08-19T00:00:00Z')`,
+ `select * from k8s_state.resource_event_outbox`,
+ } {
+ assertStatementFails(t, ctx, usageURL, statement)
+ }
+ if _, err := connection.Exec(ctx, `set default_transaction_read_only = off`); err != nil {
+ t.Fatal("disable usage read-only default for ACL test")
+ }
+ if _, err := connection.Exec(ctx, `delete from k8s_state.resource_event_outbox`); err == nil || !strings.Contains(strings.ToLower(err.Error()), "permission denied") {
+ t.Fatalf("usage outbox delete error = %v, want permission denied", err)
+ }
}
func createTenantRolePath(t *testing.T, ctx context.Context, roleAdminURL, tenantRole, tenantPassword, tenant string) string {
@@ -2017,7 +2286,7 @@ func assertExactReportingACLContract(t *testing.T, ctx context.Context, connecti
from pg_namespace as namespace
join lateral aclexplode(namespace.nspacl) as acl on true
where acl.grantee <> namespace.nspowner
- and acl.grantee in ('k8s_reporting_owner'::regrole, 'k8s_metabase'::regrole)
+ and acl.grantee in ('k8s_reporting_owner'::regrole, 'k8s_metabase'::regrole, 'cyclops_usage_reader'::regrole)
union all
select 'relation:' || namespace.nspname || '.' || relation.relname, acl.privilege_type, acl.grantee::regrole::text, acl.grantor::regrole::text, acl.is_grantable
from pg_class as relation
@@ -2025,20 +2294,23 @@ func assertExactReportingACLContract(t *testing.T, ctx context.Context, connecti
join lateral aclexplode(relation.relacl) as acl on true
where relation.relkind in ('r', 'p', 'v', 'm', 'f', 'S')
and acl.grantee <> relation.relowner
- and acl.grantee in ('k8s_reporting_owner'::regrole, 'k8s_metabase'::regrole)
+ and acl.grantee in ('k8s_reporting_owner'::regrole, 'k8s_metabase'::regrole, 'cyclops_usage_reader'::regrole)
union all
- select 'routine:' || namespace.nspname || '.' || routine.oid::regprocedure::text, acl.privilege_type, acl.grantee::regrole::text, acl.grantor::regrole::text, acl.is_grantable
+ select 'routine:' || routine.oid::regprocedure::text, acl.privilege_type, acl.grantee::regrole::text, acl.grantor::regrole::text, acl.is_grantable
from pg_proc as routine
join pg_namespace as namespace on namespace.oid = routine.pronamespace
join lateral aclexplode(routine.proacl) as acl on true
where acl.grantee <> routine.proowner
- and acl.grantee in ('k8s_reporting_owner'::regrole, 'k8s_metabase'::regrole)
+ and acl.grantee in ('k8s_reporting_owner'::regrole, 'k8s_metabase'::regrole, 'cyclops_usage_reader'::regrole)
), expected as (
values
('schema:k8s_state', 'USAGE', 'k8s_reporting_owner', 'k8s_state_owner', false),
('relation:k8s_state.resource_state', 'SELECT', 'k8s_reporting_owner', 'k8s_state_owner', false),
+ ('relation:k8s_state.resource_event_outbox', 'SELECT', 'k8s_reporting_owner', 'k8s_state_owner', false),
('schema:k8s_reporting', 'USAGE', 'k8s_metabase', 'k8s_reporting_owner', false),
- ('relation:k8s_reporting.current_resources', 'SELECT', 'k8s_metabase', 'k8s_reporting_owner', false)
+ ('relation:k8s_reporting.current_resources', 'SELECT', 'k8s_metabase', 'k8s_reporting_owner', false),
+ ('schema:k8s_reporting', 'USAGE', 'cyclops_usage_reader', 'k8s_reporting_owner', false),
+ ('routine:k8s_reporting.usage_sandbox_events(text,timestamp with time zone,timestamp with time zone)', 'EXECUTE', 'cyclops_usage_reader', 'k8s_reporting_owner', false)
)
select count(*) from (
(select * from actual except select * from expected)
@@ -2059,7 +2331,7 @@ func assertExactReportingACLContract(t *testing.T, ctx context.Context, connecti
join lateral aclexplode(namespace.nspacl) as acl on true
where namespace.nspname = 'k8s_reporting'
and acl.grantee <> namespace.nspowner
- and (acl.grantee <> 'k8s_metabase'::regrole or acl.privilege_type <> 'USAGE' or acl.is_grantable)
+ and (acl.grantee not in ('k8s_metabase'::regrole, 'cyclops_usage_reader'::regrole) or acl.privilege_type <> 'USAGE' or acl.is_grantable)
union all
select 1
from pg_class as relation
@@ -2068,6 +2340,16 @@ func assertExactReportingACLContract(t *testing.T, ctx context.Context, connecti
where namespace.nspname = 'k8s_reporting' and relation.relname = 'current_resources'
and acl.grantee <> relation.relowner
and (acl.grantee <> 'k8s_metabase'::regrole or acl.privilege_type <> 'SELECT' or acl.is_grantable)
+ union all
+ select 1
+ from pg_proc as routine
+ join pg_namespace as namespace on namespace.oid = routine.pronamespace
+ join lateral aclexplode(routine.proacl) as acl on true
+ where namespace.nspname = 'k8s_reporting'
+ and routine.proname = 'usage_sandbox_events'
+ and routine.proargtypes = '25 1184 1184'::oidvector
+ and acl.grantee <> routine.proowner
+ and (acl.grantee <> 'cyclops_usage_reader'::regrole or acl.privilege_type <> 'EXECUTE' or acl.is_grantable)
)`).Scan(&reportingObjectDrift); err != nil {
t.Fatalf("read reporting schema and view ACLs: %v", err)
}
diff --git a/libs/fleet/backend/database/migrator_test.go b/libs/fleet/backend/database/migrator_test.go
index 7500f78075..29fdeda457 100644
--- a/libs/fleet/backend/database/migrator_test.go
+++ b/libs/fleet/backend/database/migrator_test.go
@@ -89,6 +89,11 @@ func TestStaticRoleAlterClausesOnlyContainPermittedDrift(t *testing.T) {
func TestStaticRoleSettingsContractsAreExact(t *testing.T) {
want := map[string]staticRoleSettingsContract{
+ "cyclops_usage_reader": {
+ staticRoleSettingDefaultTransactionReadOnly: "on",
+ staticRoleSettingStatementTimeout: "10000ms",
+ staticRoleSettingIdleInTransactionSessionTimeout: "10000ms",
+ },
"k8s_metabase": {
staticRoleSettingDefaultTransactionReadOnly: "on",
staticRoleSettingStatementTimeout: "20000ms",
@@ -110,13 +115,27 @@ func TestStaticRoleAlterClausesRejectUnsupportedValidUntilContract(t *testing.T)
}
}
-func TestStaticRoleAlterClausesRejectCreateDBDrift(t *testing.T) {
- _, err := staticRoleAlterClauses(staticRoleContract{role: "cyclops_app", login: true}, staticRoleAttributes{
- login: true,
- createDB: true,
+func TestStaticRoleAlterClausesReconcileCreateDBDrift(t *testing.T) {
+ clauses, err := staticRoleAlterClauses(staticRoleContract{role: "cyclops_app", login: true, validUntil: staticRoleValidUntilInfinity}, staticRoleAttributes{
+ login: true,
+ createDB: true,
+ validUntil: "infinity",
})
- if err == nil || !strings.Contains(err.Error(), "rolcreatedb=true") {
- t.Fatalf("static role createdb drift error = %v, want fail-closed rolcreatedb error", err)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if clauses != "NOCREATEDB" {
+ t.Fatalf("static role createdb clauses = %q, want NOCREATEDB", clauses)
+ }
+}
+
+func TestStaticRoleAlterClausesRejectCreateDBContract(t *testing.T) {
+ _, err := staticRoleAlterClauses(
+ staticRoleContract{role: "cyclops_app", login: true, createDB: true, validUntil: staticRoleValidUntilInfinity},
+ staticRoleAttributes{login: true, validUntil: "infinity"},
+ )
+ if err == nil || !strings.Contains(err.Error(), "unsupported CREATEDB contract") {
+ t.Fatalf("static role CREATEDB contract error = %v, want fail-closed unsupported contract", err)
}
}
@@ -501,15 +520,15 @@ func TestEmbeddedMigrationsAreOrderedAndImmutable(t *testing.T) {
if err != nil {
t.Fatal(err)
}
- if len(files) != 1 {
- t.Fatalf("expected exactly one initial migration, got %d", len(files))
+ if len(files) != 2 {
+ t.Fatalf("expected exactly two migrations, got %d", len(files))
}
- file := files[0]
- if file.Version != 1 || file.Name != "000001_initial_schema.sql" {
- t.Fatalf("expected version 1 initial schema migration, got version=%d name=%q", file.Version, file.Name)
+ initial := files[0]
+ if initial.Version != 1 || initial.Name != "000001_initial_schema.sql" {
+ t.Fatalf("expected version 1 initial schema migration, got version=%d name=%q", initial.Version, initial.Name)
}
- digest := sha256.Sum256([]byte(file.SQL))
- if file.SHA256 != hex.EncodeToString(digest[:]) {
+ digest := sha256.Sum256([]byte(initial.SQL))
+ if initial.SHA256 != hex.EncodeToString(digest[:]) {
t.Fatal("embedded initial schema migration digest does not match its contents")
}
for _, expected := range []string{
@@ -530,13 +549,36 @@ func TestEmbeddedMigrationsAreOrderedAndImmutable(t *testing.T) {
"GRANT EXECUTE ON FUNCTION k8s_state.register_tenant_role(name, text, text) TO k8s_role_admin",
"GRANT EXECUTE ON FUNCTION k8s_state.unregister_tenant_role(name) TO k8s_role_admin",
} {
- if !strings.Contains(file.SQL, expected) {
+ if !strings.Contains(initial.SQL, expected) {
t.Errorf("initial schema is missing direct tenant role contract %q", expected)
}
}
- if strings.Contains(file.SQL, "k8s_query_broker") {
+ if strings.Contains(initial.SQL, "k8s_query_broker") {
t.Fatal("initial schema must not create or grant a shared query broker role")
}
+
+ usage := files[1]
+ if usage.Version != 2 || usage.Name != "000002_usage_sandbox_events.sql" {
+ t.Fatalf("expected version 2 usage migration, got version=%d name=%q", usage.Version, usage.Name)
+ }
+ for _, expected := range []string{
+ "CREATE ROLE cyclops_usage_reader LOGIN NOINHERIT NOCREATEROLE NOSUPERUSER NOCREATEDB NOREPLICATION NOBYPASSRLS",
+ "CREATE INDEX resource_event_outbox_usage_lookup_idx",
+ "GRANT SELECT ON k8s_state.resource_event_outbox TO k8s_reporting_owner",
+ "CREATE FUNCTION k8s_reporting.usage_sandbox_events",
+ "SECURITY DEFINER",
+ "SET search_path = k8s_state, pg_catalog",
+ "REVOKE ALL ON FUNCTION k8s_reporting.usage_sandbox_events(text, timestamptz, timestamptz) FROM PUBLIC",
+ "GRANT USAGE ON SCHEMA k8s_reporting TO cyclops_usage_reader",
+ "GRANT EXECUTE ON FUNCTION k8s_reporting.usage_sandbox_events(text, timestamptz, timestamptz) TO cyclops_usage_reader",
+ } {
+ if !strings.Contains(usage.SQL, expected) {
+ t.Errorf("usage migration is missing contract %q", expected)
+ }
+ }
+ if strings.Contains(usage.SQL, "GRANT SELECT ON k8s_state.resource_event_outbox TO cyclops_usage_reader") {
+ t.Fatal("usage reader must not receive direct outbox table access")
+ }
}
func TestAppliedMigrationLedgerUsesApplicationOrder(t *testing.T) {
@@ -653,12 +695,13 @@ func TestCredentialURLsExcludeDynamicTenantRoles(t *testing.T) {
Exporter: "postgres://k8s_state_exporter:pw@db/cyclops",
RoleAdmin: "postgres://k8s_role_admin:pw@db/cyclops",
Metabase: "postgres://k8s_metabase:pw@db/cyclops",
+ Usage: "postgres://cyclops_usage_reader:pw@db/cyclops",
})
if err != nil {
t.Fatalf("parse fixed runtime credentials: %v", err)
}
- if len(credentials) != 5 {
- t.Fatalf("credential count = %d, want 5", len(credentials))
+ if len(credentials) != 6 {
+ t.Fatalf("credential count = %d, want 6", len(credentials))
}
for _, credential := range credentials {
if credential.Role == "k8s_query_broker" || strings.HasPrefix(credential.Role, "k8s_tenant_") {
@@ -674,15 +717,16 @@ func TestStaticRoleContractsAreAllowlistedAndFixed(t *testing.T) {
connectionLimit int
validUntil staticRoleValidUntil
}{
- "cyclops_app": {true, false, false, false, -1, staticRoleValidUntilInfinity},
- "k8s_state_owner": {false, true, false, false, -1, staticRoleValidUntilInfinity},
- "k8s_state_writer": {true, false, false, false, -1, staticRoleValidUntilInfinity},
- "k8s_state_exporter": {true, false, false, false, -1, staticRoleValidUntilInfinity},
- "k8s_query_tenant": {false, true, false, false, -1, staticRoleValidUntilInfinity},
- "k8s_query_admin": {false, true, false, false, -1, staticRoleValidUntilInfinity},
- "k8s_role_admin": {true, false, true, false, -1, staticRoleValidUntilInfinity},
- "k8s_reporting_owner": {false, true, false, false, -1, staticRoleValidUntilInfinity},
- "k8s_metabase": {true, false, false, false, -1, staticRoleValidUntilInfinity},
+ "cyclops_app": {true, false, false, false, -1, staticRoleValidUntilInfinity},
+ "k8s_state_owner": {false, true, false, false, -1, staticRoleValidUntilInfinity},
+ "k8s_state_writer": {true, false, false, false, -1, staticRoleValidUntilInfinity},
+ "k8s_state_exporter": {true, false, false, false, -1, staticRoleValidUntilInfinity},
+ "k8s_query_tenant": {false, true, false, false, -1, staticRoleValidUntilInfinity},
+ "k8s_query_admin": {false, true, false, false, -1, staticRoleValidUntilInfinity},
+ "k8s_role_admin": {true, false, true, false, -1, staticRoleValidUntilInfinity},
+ "k8s_reporting_owner": {false, true, false, false, -1, staticRoleValidUntilInfinity},
+ "k8s_metabase": {true, false, false, false, -1, staticRoleValidUntilInfinity},
+ "cyclops_usage_reader": {true, false, false, false, -1, staticRoleValidUntilInfinity},
}
if len(contracts) != len(want) {
t.Fatalf("static role contract count = %d, want %d", len(contracts), len(want))
@@ -730,6 +774,7 @@ func TestCredentialURLsRequireExpectedRoleNames(t *testing.T) {
Exporter: "postgres://k8s_state_exporter:pw@db/cyclops",
RoleAdmin: "postgres://k8s_role_admin:pw@db/cyclops",
Metabase: "postgres://k8s_metabase:pw@db/cyclops",
+ Usage: "postgres://cyclops_usage_reader:pw@db/cyclops",
})
if err == nil {
t.Fatal("expected application role-name validation")
@@ -746,6 +791,7 @@ func TestCredentialURLsRejectEmptyPassword(t *testing.T) {
Exporter: "postgres://k8s_state_exporter:pw@db/cyclops",
RoleAdmin: "postgres://k8s_role_admin:pw@db/cyclops",
Metabase: "postgres://k8s_metabase:pw@db/cyclops",
+ Usage: "postgres://cyclops_usage_reader:pw@db/cyclops",
})
if err == nil || err.Error() != "application credential database URL must include a password" {
t.Fatalf("expected empty password rejection, got %v", err)
@@ -759,6 +805,7 @@ func TestCredentialURLParseErrorsPreserveCauseForBoundaryClassification(t *testi
Exporter: "postgres://k8s_state_exporter:pw@db/cyclops",
RoleAdmin: "postgres://k8s_role_admin:pw@db/cyclops",
Metabase: "postgres://k8s_metabase:pw@db/cyclops",
+ Usage: "postgres://cyclops_usage_reader:pw@db/cyclops",
})
if !errors.Is(err, ErrInvalidConfiguration) {
t.Fatalf("error = %v, want ErrInvalidConfiguration", err)
diff --git a/libs/fleet/backend/database/runtime_ddl.go b/libs/fleet/backend/database/runtime_ddl.go
index 72016e6bcf..f7a5eb1e57 100644
--- a/libs/fleet/backend/database/runtime_ddl.go
+++ b/libs/fleet/backend/database/runtime_ddl.go
@@ -222,10 +222,7 @@ func postgresBoolean(value bool) string {
}
func staticRoleAlterClauses(contract staticRoleContract, attributes staticRoleAttributes) (string, error) {
- unsafeAttributes := make([]string, 0, 4)
- if attributes.createDB {
- unsafeAttributes = append(unsafeAttributes, "rolcreatedb=true")
- }
+ unsafeAttributes := make([]string, 0, 3)
if attributes.super {
unsafeAttributes = append(unsafeAttributes, "rolsuper=true")
}
@@ -238,11 +235,14 @@ func staticRoleAlterClauses(contract staticRoleContract, attributes staticRoleAt
if len(unsafeAttributes) != 0 {
return "", fmt.Errorf("static role %s has unsafe privileged drift: %s; the migration owner cannot safely repair these attributes", contract.role, strings.Join(unsafeAttributes, ", "))
}
+ if contract.createDB {
+ return "", fmt.Errorf("static role %s has unsupported CREATEDB contract; the migrator only reconciles roles to NOCREATEDB", contract.role)
+ }
if contract.validUntil != staticRoleValidUntilInfinity {
return "", fmt.Errorf("static role %s has unsupported valid-until contract %d; only infinity is supported", contract.role, contract.validUntil)
}
- clauses := make([]string, 0, 6)
+ clauses := make([]string, 0, 7)
if attributes.login != contract.login {
clauses = append(clauses, map[bool]string{true: "LOGIN", false: "NOLOGIN"}[contract.login])
}
@@ -252,6 +252,9 @@ func staticRoleAlterClauses(contract staticRoleContract, attributes staticRoleAt
if attributes.createRole != contract.createRole {
clauses = append(clauses, map[bool]string{true: "CREATEROLE", false: "NOCREATEROLE"}[contract.createRole])
}
+ if attributes.createDB {
+ clauses = append(clauses, "NOCREATEDB")
+ }
if attributes.connectionLimit != contract.connectionLimit {
clauses = append(clauses, "CONNECTION LIMIT "+strconv.Itoa(contract.connectionLimit))
}
diff --git a/libs/fleet/backend/database/test-setup.sh b/libs/fleet/backend/database/test-setup.sh
index 06387025e3..7390be1555 100755
--- a/libs/fleet/backend/database/test-setup.sh
+++ b/libs/fleet/backend/database/test-setup.sh
@@ -23,6 +23,7 @@ static_roles=(
k8s_role_admin
k8s_reporting_owner
k8s_metabase
+ cyclops_usage_reader
)
base_url="${admin_url%%\?*}"
@@ -82,6 +83,7 @@ writer_url="$(url_for k8s_state_writer state-writer-password)"
exporter_url="$(url_for k8s_state_exporter state-exporter-password)"
role_admin_url="$(url_for k8s_role_admin role-admin-password)"
metabase_url="$(url_for k8s_metabase metabase-password)"
+usage_url="$(url_for cyclops_usage_reader usage-reader-password)"
env_file="${CYCLOPS_TEST_DATABASE_ENV_FILE:-${GITHUB_ENV:-}}"
if [[ -z "$env_file" ]]; then
@@ -150,6 +152,7 @@ STATE_WRITER_DATABASE_URL="$writer_url" \
STATE_EXPORTER_DATABASE_URL="$exporter_url" \
STATE_ROLE_ADMIN_DATABASE_URL="$role_admin_url" \
METABASE_DATABASE_URL="$metabase_url" \
+USAGE_DATABASE_URL="$usage_url" \
go run ./cmd/db-migrate
cat >> "$env_file" <<EOF_ENV
diff --git a/libs/fleet/backend/handlers/config.go b/libs/fleet/backend/handlers/config.go
index 187e0b3826..960039edf0 100644
--- a/libs/fleet/backend/handlers/config.go
+++ b/libs/fleet/backend/handlers/config.go
@@ -17,6 +17,7 @@ type ConfigResponse struct {
Admin bool `json:"admin"`
Billing bool `json:"billing"`
Chat bool `json:"chat"`
+ Usage bool `json:"usage"`
}
// GetConfig returns per-user feature flags evaluated by OPA.
@@ -33,7 +34,7 @@ func (h Handlers) GetConfig(w http.ResponseWriter, r *http.Request) {
user := currentUser(r)
ctx := r.Context()
- isAdmin, err := auth.EvalIsAdmin(ctx, user)
+ isAdmin, err := h.isAdmin(ctx, user)
if err != nil {
// Fail closed to the most restrictive view, and log so a
// misconfigured OPA store / provider is visible to operators.
@@ -47,11 +48,17 @@ func (h Handlers) GetConfig(w http.ResponseWriter, r *http.Request) {
billingEnabled = false
}
+ usageEnabled, err := h.usageEnabled(ctx, user)
+ if err != nil {
+ slog.WarnContext(ctx, "usage access eval failed; defaulting off", "err", err)
+ usageEnabled = false
+ }
+
chatEnabled, err := h.chatEnabled(ctx, user)
if err != nil {
slog.WarnContext(ctx, "chat access eval failed; defaulting off", "err", err)
chatEnabled = false
}
- writeJSON(w, http.StatusOK, ConfigResponse{Admin: isAdmin, Billing: billingEnabled, Chat: chatEnabled})
+ writeJSON(w, http.StatusOK, ConfigResponse{Admin: isAdmin, Billing: billingEnabled, Chat: chatEnabled, Usage: usageEnabled})
}
diff --git a/libs/fleet/backend/handlers/config_test.go b/libs/fleet/backend/handlers/config_test.go
index 62041f9515..2813b29d3d 100644
--- a/libs/fleet/backend/handlers/config_test.go
+++ b/libs/fleet/backend/handlers/config_test.go
@@ -50,3 +50,16 @@ func TestGetConfigReturnsEffectiveChatAccess(t *testing.T) {
})
}
}
+
+func TestGetConfigReturnsEffectiveUsageAccess(t *testing.T) {
+ h := Handlers{usageAccessEvaluator: func(context.Context, *auth.User) (bool, error) { return true, nil }, adminAccessEvaluator: func(context.Context, *auth.User) (bool, error) { return false, nil }}
+ w := httptest.NewRecorder()
+ h.GetConfig(w, withUser(httptest.NewRequest(http.MethodGet, "/api/config", nil), &auth.User{ID: "user", AZP: "cyclops-cs-spa"}))
+ var r ConfigResponse
+ if err := json.Unmarshal(w.Body.Bytes(), &r); err != nil {
+ t.Fatal(err)
+ }
+ if !r.Usage {
+ t.Fatal("usage false")
+ }
+}
diff --git a/libs/fleet/backend/handlers/handlers.go b/libs/fleet/backend/handlers/handlers.go
index eb296e23f5..2d7ddfe5aa 100644
--- a/libs/fleet/backend/handlers/handlers.go
+++ b/libs/fleet/backend/handlers/handlers.go
@@ -16,6 +16,7 @@ import (
"cyclops-cs-backend/chat"
"cyclops-cs-backend/config"
"cyclops-cs-backend/keycloak"
+ "cyclops-cs-backend/usage"
"go.opentelemetry.io/otel"
"go.opentelemetry.io/otel/trace"
)
@@ -38,6 +39,10 @@ type Handlers struct {
// executor and the GitHub trust policy store). It is a pointer because
// setupRouter copies Handlers by value; see features.go.
Features *Features
+ Usage usage.Provider
+
+ usageAccessEvaluator func(context.Context, *auth.User) (bool, error)
+ adminAccessEvaluator func(context.Context, *auth.User) (bool, error)
ChatAccess config.ChatAccessMode
Conversations chat.ConversationStore
@@ -69,6 +74,22 @@ func New(admin *keycloak.Admin, cfg *config.Configuration) Handlers {
}
}
+func (h Handlers) usageEnabled(ctx context.Context, user *auth.User) (bool, error) {
+ evaluator := h.usageAccessEvaluator
+ if evaluator == nil {
+ evaluator = auth.EvalUsageEnabled
+ }
+ return evaluator(ctx, user)
+}
+
+func (h Handlers) isAdmin(ctx context.Context, user *auth.User) (bool, error) {
+ evaluator := h.adminAccessEvaluator
+ if evaluator == nil {
+ evaluator = auth.EvalIsAdmin
+ }
+ return evaluator(ctx, user)
+}
+
func (h Handlers) chatEnabled(ctx context.Context, user *auth.User) (bool, error) {
if user == nil || user.ID == "" {
return false, nil
diff --git a/libs/fleet/backend/handlers/usage.go b/libs/fleet/backend/handlers/usage.go
new file mode 100644
index 0000000000..0613fbfc93
--- /dev/null
+++ b/libs/fleet/backend/handlers/usage.go
@@ -0,0 +1,127 @@
+package handlers
+
+import (
+ "errors"
+ "log/slog"
+ "net/http"
+ "regexp"
+ "strings"
+
+ "cyclops-cs-backend/usage"
+)
+
+type UsageTimeframe = usage.Timeframe
+type UsageInterval = usage.Interval
+type UsageQuery = usage.Query
+type UsagePoolQuery = usage.PoolQuery
+type UsageMetricTotals = usage.MetricTotals
+type UsagePoolSummary = usage.PoolSummary
+type UsageOverviewResponse = usage.OverviewResponse
+type UsagePoolIdentity = usage.PoolIdentity
+type UsageBucket = usage.Bucket
+type UsagePoolDetailResponse = usage.PoolDetailResponse
+type UsageProvider = usage.Provider
+
+const (
+ UsageTimeframe24H = usage.Timeframe24H
+ UsageTimeframe7D = usage.Timeframe7D
+ UsageTimeframe30D = usage.Timeframe30D
+ UsageIntervalHour = usage.IntervalHour
+ UsageIntervalDay = usage.IntervalDay
+)
+
+var usagePoolID = regexp.MustCompile(`^[A-Za-z0-9](?:[A-Za-z0-9._:-]{0,126}[A-Za-z0-9])?$`)
+
+func parseUsageTimeframe(raw string) (UsageTimeframe, UsageInterval, bool) {
+ switch UsageTimeframe(raw) {
+ case UsageTimeframe24H:
+ return UsageTimeframe24H, UsageIntervalHour, true
+ case UsageTimeframe7D:
+ return UsageTimeframe7D, UsageIntervalHour, true
+ case UsageTimeframe30D:
+ return UsageTimeframe30D, UsageIntervalDay, true
+ }
+ return "", "", false
+}
+
+func (h Handlers) authorizeUsage(w http.ResponseWriter, r *http.Request) (UsageQuery, UsageInterval, bool) {
+ u := currentUser(r)
+ if u == nil || u.ID == "" {
+ writeErr(w, 401, "authentication required")
+ return UsageQuery{}, "", false
+ }
+ tf, iv, ok := parseUsageTimeframe(r.URL.Query().Get("timeframe"))
+ if !ok {
+ writeErr(w, 400, "timeframe must be one of 24h, 7d, or 30d")
+ return UsageQuery{}, "", false
+ }
+ enabled, err := h.usageEnabled(r.Context(), u)
+ if err != nil || !enabled {
+ if err != nil {
+ slog.WarnContext(r.Context(), "usage access evaluation failed", "err", err)
+ }
+ writeErr(w, 403, "usage preview is not enabled")
+ return UsageQuery{}, "", false
+ }
+ admin, err := h.isAdmin(r.Context(), u)
+ if err != nil {
+ admin = false
+ }
+ sub := strings.TrimSpace(r.URL.Query().Get("subject"))
+ if sub == "" {
+ sub = u.ID
+ } else if sub != u.ID && !admin {
+ writeErr(w, 403, "only administrators can select another subject")
+ return UsageQuery{}, "", false
+ }
+ if len(sub) > 255 {
+ writeErr(w, 400, "subject is too long")
+ return UsageQuery{}, "", false
+ }
+ return UsageQuery{ActorSubject: u.ID, Subject: sub, Admin: admin, Timeframe: tf}, iv, true
+}
+
+func (h Handlers) GetUsageOverview(w http.ResponseWriter, r *http.Request) {
+ w.Header().Set("Cache-Control", "private, no-store")
+ q, _, ok := h.authorizeUsage(w, r)
+ if !ok {
+ return
+ }
+ if h.Usage == nil {
+ writeErr(w, 503, "usage data provider is not configured")
+ return
+ }
+ v, err := h.Usage.Overview(r.Context(), q)
+ if err != nil {
+ writeErr(w, 502, "usage data is temporarily unavailable")
+ return
+ }
+ writeJSON(w, 200, v)
+}
+
+func (h Handlers) GetUsagePoolDetail(w http.ResponseWriter, r *http.Request) {
+ w.Header().Set("Cache-Control", "private, no-store")
+ q, iv, ok := h.authorizeUsage(w, r)
+ if !ok {
+ return
+ }
+ pool := strings.TrimSpace(r.URL.Query().Get("pool"))
+ if !usagePoolID.MatchString(pool) {
+ writeErr(w, 400, "pool is required and must be a bounded identifier")
+ return
+ }
+ if h.Usage == nil {
+ writeErr(w, 503, "usage data provider is not configured")
+ return
+ }
+ v, err := h.Usage.PoolDetail(r.Context(), UsagePoolQuery{Query: q, PoolID: pool, Interval: iv})
+ if errors.Is(err, usage.ErrPoolNotFound) {
+ writeErr(w, 404, "usage pool was not found")
+ return
+ }
+ if err != nil {
+ writeErr(w, 502, "usage data is temporarily unavailable")
+ return
+ }
+ writeJSON(w, 200, v)
+}
diff --git a/libs/fleet/backend/handlers/usage_test.go b/libs/fleet/backend/handlers/usage_test.go
new file mode 100644
index 0000000000..fdf1306222
--- /dev/null
+++ b/libs/fleet/backend/handlers/usage_test.go
@@ -0,0 +1,107 @@
+package handlers
+
+import (
+ "context"
+ "cyclops-cs-backend/auth"
+ "cyclops-cs-backend/usage"
+ "errors"
+ "net/http"
+ "net/http/httptest"
+ "testing"
+)
+
+type fakeUsageProvider struct {
+ overviewQuery UsageQuery
+ detailQuery UsagePoolQuery
+ overviewErr error
+ detailErr error
+}
+
+func (f *fakeUsageProvider) Overview(_ context.Context, q UsageQuery) (UsageOverviewResponse, error) {
+ f.overviewQuery = q
+ return UsageOverviewResponse{}, f.overviewErr
+}
+func (f *fakeUsageProvider) PoolDetail(_ context.Context, q UsagePoolQuery) (UsagePoolDetailResponse, error) {
+ f.detailQuery = q
+ return UsagePoolDetailResponse{}, f.detailErr
+}
+func uh(p UsageProvider, e, a bool) Handlers {
+ return Handlers{Usage: p, usageAccessEvaluator: func(context.Context, *auth.User) (bool, error) { return e, nil }, adminAccessEvaluator: func(context.Context, *auth.User) (bool, error) { return a, nil }}
+}
+func TestGetUsageOverviewScopesAndValidates(t *testing.T) {
+ p := &fakeUsageProvider{}
+ h := uh(p, true, false)
+ w := httptest.NewRecorder()
+ h.GetUsageOverview(w, withUser(httptest.NewRequest(http.MethodGet, "/api/usage/overview?timeframe=7d", nil), &auth.User{ID: "user"}))
+ if w.Code != 200 || p.overviewQuery.Subject != "user" || p.overviewQuery.ActorSubject != "user" {
+ t.Fatalf("status/query: %d %#v", w.Code, p.overviewQuery)
+ }
+ w = httptest.NewRecorder()
+ h.GetUsageOverview(w, withUser(httptest.NewRequest(http.MethodGet, "/api/usage/overview?timeframe=90d", nil), &auth.User{ID: "user"}))
+ if w.Code != 400 {
+ t.Fatalf("status=%d", w.Code)
+ }
+}
+func TestUsageAdminViewAsPreservesActor(t *testing.T) {
+ p := &fakeUsageProvider{}
+ w := httptest.NewRecorder()
+ uh(p, true, true).GetUsageOverview(w, withUser(httptest.NewRequest(http.MethodGet, "/api/usage/overview?timeframe=30d&subject=customer", nil), &auth.User{ID: "admin"}))
+ if w.Code != 200 || p.overviewQuery.ActorSubject != "admin" || p.overviewQuery.Subject != "customer" {
+ t.Fatalf("%d %#v", w.Code, p.overviewQuery)
+ }
+}
+func TestUsageNonAdminOverrideDeniedAndMissingProvider503(t *testing.T) {
+ p := &fakeUsageProvider{}
+ w := httptest.NewRecorder()
+ uh(p, true, false).GetUsageOverview(w, withUser(httptest.NewRequest(http.MethodGet, "/api/usage/overview?timeframe=24h&subject=other", nil), &auth.User{ID: "user"}))
+ if w.Code != 403 {
+ t.Fatalf("status=%d", w.Code)
+ }
+ w = httptest.NewRecorder()
+ uh(nil, true, false).GetUsageOverview(w, withUser(httptest.NewRequest(http.MethodGet, "/api/usage/overview?timeframe=24h", nil), &auth.User{ID: "user"}))
+ if w.Code != 503 {
+ t.Fatalf("status=%d", w.Code)
+ }
+}
+func TestUsagePoolValidationAndInterval(t *testing.T) {
+ p := &fakeUsageProvider{}
+ w := httptest.NewRecorder()
+ uh(p, true, false).GetUsagePoolDetail(w, withUser(httptest.NewRequest(http.MethodGet, "/api/usage/pool?timeframe=24h&pool=pool-a", nil), &auth.User{ID: "user"}))
+ if w.Code != 200 || p.detailQuery.Interval != UsageIntervalHour {
+ t.Fatalf("%d %#v", w.Code, p.detailQuery)
+ }
+ w = httptest.NewRecorder()
+ uh(p, true, false).GetUsagePoolDetail(w, withUser(httptest.NewRequest(http.MethodGet, "/api/usage/pool?timeframe=24h&pool=../../x", nil), &auth.User{ID: "user"}))
+ if w.Code != 400 {
+ t.Fatalf("status=%d", w.Code)
+ }
+}
+
+func TestUsageProviderErrorsAreRedacted(t *testing.T) {
+ t.Run("mandatory source failure", func(t *testing.T) {
+ p := &fakeUsageProvider{overviewErr: errors.New("postgres://[email protected]: source unavailable")}
+ w := httptest.NewRecorder()
+ uh(p, true, false).GetUsageOverview(w, withUser(httptest.NewRequest(http.MethodGet, "/api/usage/overview?timeframe=24h", nil), &auth.User{ID: "user"}))
+ if w.Code != http.StatusBadGateway {
+ t.Fatalf("status = %d, want %d", w.Code, http.StatusBadGateway)
+ }
+ if got, want := w.Body.String(), "{\"error\":\"usage data is temporarily unavailable\"}\n"; got != want {
+ t.Fatalf("body = %q, want %q", got, want)
+ }
+ if got, want := w.Header().Get("Cache-Control"), "private, no-store"; got != want {
+ t.Fatalf("Cache-Control = %q, want %q", got, want)
+ }
+ })
+
+ t.Run("missing pool", func(t *testing.T) {
+ p := &fakeUsageProvider{detailErr: usage.ErrPoolNotFound}
+ w := httptest.NewRecorder()
+ uh(p, true, false).GetUsagePoolDetail(w, withUser(httptest.NewRequest(http.MethodGet, "/api/usage/pool?timeframe=24h&pool=pool-a", nil), &auth.User{ID: "user"}))
+ if w.Code != http.StatusNotFound {
+ t.Fatalf("status = %d, want %d", w.Code, http.StatusNotFound)
+ }
+ if got, want := w.Body.String(), "{\"error\":\"usage pool was not found\"}\n"; got != want {
+ t.Fatalf("body = %q, want %q", got, want)
+ }
+ })
+}
diff --git a/libs/fleet/backend/main.go b/libs/fleet/backend/main.go
index 29081bb8f6..32c7bd81f5 100644
--- a/libs/fleet/backend/main.go
+++ b/libs/fleet/backend/main.go
@@ -43,6 +43,7 @@ import (
"cyclops-cs-backend/middlewares"
"cyclops-cs-backend/statequery"
"cyclops-cs-backend/telemetry"
+ "cyclops-cs-backend/usage"
httpSwagger "github.com/swaggo/http-swagger/v2"
"github.com/trycua/cloud/pkg/featureflags"
@@ -148,6 +149,8 @@ func setupRouter(c handlers.Handlers) http.Handler {
r.Handle("QUERY /api/state/query",
withAuthenticatedMiddlewares("/api/state/query", c.QueryState))
+ r.Handle("GET /api/usage/overview", withAuthenticatedMiddlewares("/api/usage/overview", c.GetUsageOverview))
+ r.Handle("GET /api/usage/pool", withAuthenticatedMiddlewares("/api/usage/pool", c.GetUsagePoolDetail))
// Stripe-hosted billing. Browser routes require the normal SPA JWT; the
// webhook uses Stripe signature verification as its authentication boundary.
@@ -241,6 +244,31 @@ func main() {
}
}
+func initializeTelemetry(ctx context.Context, cfg config.TelemetryConfiguration) (func(context.Context) error, error) {
+ shutdown, err := telemetry.Init(ctx, telemetry.Config{
+ Endpoint: cfg.Endpoint,
+ Protocol: cfg.Protocol,
+ ServiceName: cfg.ServiceName,
+ ServiceNamespace: cfg.ServiceNamespace,
+ Environment: cfg.Environment,
+ ResourceAttrs: cfg.ResourceAttrs,
+ })
+ if err != nil {
+ slog.Warn("otel: init failed; tracing disabled", "err", err)
+ return func(context.Context) error { return nil }, err
+ }
+ return shutdown, nil
+}
+
+func initializeFeatureFlags(ctx context.Context, environment string, credentials featureflags.AWSCredentials) error {
+ err := featureflags.SetupProvider(ctx, environment, credentials)
+ if err != nil {
+ slog.Warn("openfeature: provider setup degraded", "err", err)
+ return err
+ }
+ return nil
+}
+
func run() error {
slog.SetDefault(slog.New(slog.NewJSONHandler(os.Stdout, nil)))
ctx := context.Background()
@@ -253,20 +281,7 @@ func run() error {
}
configValues = cfg
- telemetryShutdown := func(context.Context) error { return nil }
- if shutdown, err := telemetry.Init(ctx, telemetry.Config{
- Endpoint: cfg.Telemetry.Endpoint,
- Protocol: cfg.Telemetry.Protocol,
- ServiceName: cfg.Telemetry.ServiceName,
- ServiceNamespace: cfg.Telemetry.ServiceNamespace,
- Environment: cfg.Telemetry.Environment,
- ResourceAttrs: cfg.Telemetry.ResourceAttrs,
- }); err != nil {
- telemetryErr = err
- slog.Warn("otel: init failed; tracing disabled", "err", err)
- } else {
- telemetryShutdown = shutdown
- }
+ telemetryShutdown, telemetryErr := initializeTelemetry(ctx, cfg.Telemetry)
defer func() {
if err := telemetryShutdown(context.Background()); err != nil {
slog.Warn("otel: shutdown failed", "err", err)
@@ -281,14 +296,11 @@ func run() error {
// SetupProvider returns a non-nil error when it falls back to the
// from-env provider (missing creds / SSM init failure). Log it but
// keep starting — flag evaluations still resolve via the fallback.
- if err := featureflags.SetupProvider(ctx, os.Getenv("ENVIRONMENT"), featureflags.AWSCredentials{
+ startupErrors = initializeFeatureFlags(ctx, os.Getenv("ENVIRONMENT"), featureflags.AWSCredentials{
AccessKeyID: os.Getenv("AWS_ACCESS_KEY_ID"),
SecretAccessKey: os.Getenv("AWS_SECRET_ACCESS_KEY"),
Region: os.Getenv("AWS_REGION"),
- }); err != nil {
- startupErrors = errors.Join(startupErrors, err)
- slog.Warn("openfeature: provider setup degraded", "err", err)
- }
+ })
slog.Info("init: OpenFeature ok, loading OPA")
auth.LoadOpa()
slog.Info("init: OPA ok")
@@ -325,6 +337,17 @@ func run() error {
}
h := handlers.New(admin, cfg)
+ usageProvider, closeUsageProvider, err := initializeUsageProvider(ctx, cfg.Usage)
+ if err != nil {
+ return errors.Join(fmt.Errorf("initialize usage provider: %w", err), startupErrors, telemetryErr)
+ }
+ defer closeUsageProvider()
+ h.Usage = usageProvider
+ if usageProvider == nil {
+ slog.Info("usage: disabled")
+ } else {
+ slog.Info("usage: enabled")
+ }
if cfg.Stripe.SecretKey != "" {
h.Billing = billing.NewService(billing.NewStripeGateway(cfg.Stripe.SecretKey))
slog.Info("stripe billing: hosted flows enabled")
@@ -356,7 +379,7 @@ func run() error {
if err := srv.ListenAndServe(); err != nil {
return errors.Join(fmt.Errorf("server exited: %w", err), startupErrors, telemetryErr)
}
- return nil
+ return errors.Join(startupErrors, telemetryErr)
}
const (
@@ -508,3 +531,25 @@ func retryDatabaseFeatures(ctx context.Context, cfg config.DatabaseConfiguration
}
}
}
+
+func initializeUsageProvider(ctx context.Context, cfg config.UsageConfiguration) (usage.Provider, func(), error) {
+ noop := func() {}
+ // OpenCost is deployed independently from the usage credential. Keep the
+ // provider disabled until the database URL arrives so serving stays ready.
+ if cfg.DatabaseURL == "" {
+ return nil, noop, nil
+ }
+ if cfg.OpenCostBaseURL == "" {
+ return nil, noop, fmt.Errorf("usage provider requires OpenCost when the database URL is configured")
+ }
+ events, err := usage.NewPostgresEventStore(ctx, cfg.DatabaseURL)
+ if err != nil {
+ return nil, noop, fmt.Errorf("create usage event store: %w", err)
+ }
+ allocations, err := usage.NewOpenCostClient(cfg.OpenCostBaseURL, cfg.QueryTimeout, cfg.MaxResponseBytes)
+ if err != nil {
+ events.Close()
+ return nil, noop, fmt.Errorf("create OpenCost client: %w", err)
+ }
+ return usage.NewProvider(events, allocations, nil), events.Close, nil
+}
diff --git a/libs/fleet/backend/main_test.go b/libs/fleet/backend/main_test.go
index 57fdfd672a..9052ce2b35 100644
--- a/libs/fleet/backend/main_test.go
+++ b/libs/fleet/backend/main_test.go
@@ -30,6 +30,7 @@ import (
"cyclops-cs-backend/handlers"
"cyclops-cs-backend/metrics"
"cyclops-cs-backend/statequery"
+ "cyclops-cs-backend/usage"
"github.com/prometheus/client_golang/prometheus"
dto "github.com/prometheus/client_model/go"
@@ -1081,3 +1082,46 @@ func TestRetryDatabaseFeaturesStopsOnceReady(t *testing.T) {
t.Fatalf("attempts kept climbing after recovery (%d -> %d); the loop did not stop", settled, attempts)
}
}
+
+func TestInitializeUsageProviderDoesNotGateReadiness(t *testing.T) {
+ provider, closeProvider, err := initializeUsageProvider(context.Background(), config.UsageConfiguration{
+ DatabaseURL: "postgres://cyclops_usage_reader:[email protected]:1/cyclops?sslmode=disable",
+ OpenCostBaseURL: "http://127.0.0.1:1",
+ QueryTimeout: time.Second,
+ MaxResponseBytes: 64 * 1024,
+ })
+ if err != nil {
+ t.Fatalf("initializeUsageProvider() error = %v", err)
+ }
+ defer closeProvider()
+ if provider == nil {
+ t.Fatal("initializeUsageProvider() provider = nil")
+ }
+
+ router := setupRouter(handlers.Handlers{Usage: provider})
+ response := httptest.NewRecorder()
+ router.ServeHTTP(response, httptest.NewRequest(http.MethodGet, "/readyz", nil))
+ if response.Code != http.StatusOK {
+ t.Fatalf("readyz status = %d, want %d", response.Code, http.StatusOK)
+ }
+
+ _, err = provider.Overview(context.Background(), usage.Query{ActorSubject: "user", Subject: "user", Timeframe: usage.Timeframe24H})
+ if err == nil {
+ t.Fatal("Overview() error = nil, want unavailable dependency error")
+ }
+}
+
+func TestInitializeUsageProviderOpenCostOnlyIsDisabled(t *testing.T) {
+ provider, closeProvider, err := initializeUsageProvider(context.Background(), config.UsageConfiguration{
+ OpenCostBaseURL: "http://127.0.0.1:1",
+ QueryTimeout: time.Second,
+ MaxResponseBytes: 64 * 1024,
+ })
+ if err != nil {
+ t.Fatalf("initializeUsageProvider() error = %v", err)
+ }
+ defer closeProvider()
+ if provider != nil {
+ t.Fatal("initializeUsageProvider() provider != nil, want disabled provider")
+ }
+}
diff --git a/libs/fleet/backend/usage/opencost.go b/libs/fleet/backend/usage/opencost.go
new file mode 100644
index 0000000000..e154392397
--- /dev/null
+++ b/libs/fleet/backend/usage/opencost.go
@@ -0,0 +1,321 @@
+package usage
+
+import (
+ "context"
+ "encoding/json"
+ "fmt"
+ "io"
+ "math"
+ "net/http"
+ "net/url"
+ "regexp"
+ "sort"
+ "strings"
+ "time"
+)
+
+const maxAllocationRows = 100000
+
+var dns1123Label = regexp.MustCompile(`^[a-z0-9](?:[-a-z0-9]*[a-z0-9])?$`)
+
+type openCostClient struct {
+ baseURL *url.URL
+ httpClient *http.Client
+ timeout time.Duration
+ maxResponseBytes int64
+}
+
+func NewOpenCostClient(rawURL string, timeout time.Duration, maxResponseBytes int64) (*openCostClient, error) {
+ baseURL, err := url.Parse(rawURL)
+ if err != nil {
+ return nil, newSanitizedError("invalid OpenCost URL", err)
+ }
+ if (baseURL.Scheme != "http" && baseURL.Scheme != "https") || baseURL.Host == "" || baseURL.RawQuery != "" || baseURL.Fragment != "" || baseURL.User != nil {
+ return nil, fmt.Errorf("invalid OpenCost URL")
+ }
+ if timeout <= 0 || maxResponseBytes <= 0 || maxResponseBytes == math.MaxInt64 {
+ return nil, fmt.Errorf("invalid OpenCost client limits")
+ }
+ return &openCostClient{
+ baseURL: baseURL,
+ timeout: timeout,
+ maxResponseBytes: maxResponseBytes,
+ httpClient: &http.Client{
+ Timeout: timeout,
+ CheckRedirect: func(_ *http.Request, _ []*http.Request) error {
+ return http.ErrUseLastResponse
+ },
+ },
+ }, nil
+}
+
+func (c *openCostClient) Allocations(ctx context.Context, start, end time.Time, step time.Duration, namespaces []string) ([]Allocation, time.Time, bool, error) {
+ if start.IsZero() || end.IsZero() || !end.After(start) || len(namespaces) == 0 {
+ return nil, time.Time{}, false, fmt.Errorf("invalid OpenCost allocation query")
+ }
+ stepText, err := openCostStep(step)
+ if err != nil {
+ return nil, time.Time{}, false, err
+ }
+ filter, namespaces, err := namespaceFilter(namespaces)
+ if err != nil {
+ return nil, time.Time{}, false, err
+ }
+
+ endpoint := *c.baseURL
+ endpoint.Path = strings.TrimRight(endpoint.Path, "/") + "/allocation/compute"
+ values := make(url.Values)
+ values.Set("window", start.UTC().Format(time.RFC3339)+","+end.UTC().Format(time.RFC3339))
+ values.Set("aggregate", "cluster,namespace,pod")
+ values.Set("includeIdle", "false")
+ values.Set("includeSharedCostBreakdown", "false")
+ values.Set("accumulate", "false")
+ values.Set("step", stepText)
+ values.Set("filter", filter)
+ endpoint.RawQuery = values.Encode()
+
+ requestCtx, cancel := context.WithTimeout(ctx, c.timeout)
+ defer cancel()
+ request, err := http.NewRequestWithContext(requestCtx, http.MethodGet, endpoint.String(), nil)
+ if err != nil {
+ return nil, time.Time{}, false, fmt.Errorf("build OpenCost request: %w", err)
+ }
+ response, err := c.httpClient.Do(request)
+ if err != nil {
+ return nil, time.Time{}, false, fmt.Errorf("request OpenCost allocations: %w", err)
+ }
+ defer response.Body.Close()
+ if response.StatusCode < http.StatusOK || response.StatusCode >= http.StatusMultipleChoices {
+ return nil, time.Time{}, false, fmt.Errorf("OpenCost allocation request failed with status %d", response.StatusCode)
+ }
+ body, err := io.ReadAll(io.LimitReader(response.Body, c.maxResponseBytes+1))
+ if err != nil {
+ return nil, time.Time{}, false, fmt.Errorf("read OpenCost allocation response: %w", err)
+ }
+ if int64(len(body)) > c.maxResponseBytes {
+ return nil, time.Time{}, false, fmt.Errorf("OpenCost allocation response exceeds limit")
+ }
+ allocations, asOf, incomplete, err := parseOpenCostAllocations(body, start, end, step, namespaces)
+ if err != nil {
+ return nil, time.Time{}, false, err
+ }
+ return allocations, asOf, incomplete, nil
+}
+
+func openCostStep(step time.Duration) (string, error) {
+ switch step {
+ case time.Hour:
+ return "1h", nil
+ case 24 * time.Hour:
+ return "1d", nil
+ default:
+ return "", fmt.Errorf("unsupported OpenCost allocation step")
+ }
+}
+
+func namespaceFilter(input []string) (string, []string, error) {
+ seen := make(map[string]struct{}, len(input))
+ namespaces := make([]string, 0, len(input))
+ for _, namespace := range input {
+ if len(namespace) > 63 || !dns1123Label.MatchString(namespace) {
+ return "", nil, fmt.Errorf("invalid namespace")
+ }
+ if _, ok := seen[namespace]; !ok {
+ seen[namespace] = struct{}{}
+ namespaces = append(namespaces, namespace)
+ }
+ }
+ sort.Strings(namespaces)
+ parts := make([]string, len(namespaces))
+ for index, namespace := range namespaces {
+ parts[index] = `namespace:"` + namespace + `"`
+ }
+ return strings.Join(parts, "|"), namespaces, nil
+}
+
+type openCostResponse struct {
+ Code *int `json:"code"`
+ Data json.RawMessage `json:"data"`
+ Error json.RawMessage `json:"error"`
+ Warnings json.RawMessage `json:"warnings"`
+}
+
+type openCostAllocation struct {
+ Properties struct {
+ Namespace string `json:"namespace"`
+ Pod string `json:"pod"`
+ } `json:"properties"`
+ Window json.RawMessage `json:"window"`
+ Minutes *float64 `json:"minutes"`
+ CPUUsageAverage *float64 `json:"cpuCoreUsageAverage"`
+ CPURequestAverage *float64 `json:"cpuCoreRequestAverage"`
+ RAMUsageAverageBytes *float64 `json:"ramByteUsageAverage"`
+ RAMRequestAverageBytes *float64 `json:"ramByteRequestAverage"`
+}
+
+type allocationFrame struct {
+ start time.Time
+ end time.Time
+}
+
+func parseOpenCostAllocations(body []byte, requestedStart, requestedEnd time.Time, step time.Duration, namespaces []string) ([]Allocation, time.Time, bool, error) {
+ var payload openCostResponse
+ if err := json.Unmarshal(body, &payload); err != nil {
+ return nil, time.Time{}, false, fmt.Errorf("parse OpenCost allocation response: %w", err)
+ }
+ if payload.Code == nil || *payload.Code != http.StatusOK || hasOpenCostError(payload.Error) {
+ return nil, time.Time{}, false, fmt.Errorf("OpenCost allocation response reports an error")
+ }
+ if len(payload.Data) == 0 || string(payload.Data) == "null" {
+ return nil, time.Time{}, false, fmt.Errorf("OpenCost allocation response has no data")
+ }
+ var frames []map[string]json.RawMessage
+ if err := json.Unmarshal(payload.Data, &frames); err != nil {
+ return nil, time.Time{}, false, newSanitizedError("OpenCost allocation response has invalid data", err)
+ }
+ if frames == nil {
+ return nil, time.Time{}, false, fmt.Errorf("OpenCost allocation response has invalid data")
+ }
+
+ allowed := make(map[string]struct{}, len(namespaces))
+ for _, namespace := range namespaces {
+ allowed[namespace] = struct{}{}
+ }
+ incomplete := hasOpenCostWarnings(payload.Warnings)
+ coverage := make([]allocationFrame, 0, len(frames))
+ for _, frame := range frames {
+ window, ok := openCostFrameWindow(frame, requestedStart, requestedEnd, step)
+ if !ok {
+ incomplete = true
+ continue
+ }
+ coverage = append(coverage, window)
+ }
+ asOf, coverageComplete := completeCoverageBoundary(coverage, requestedStart, requestedEnd)
+ incomplete = incomplete || !coverageComplete
+
+ allocations := make([]Allocation, 0)
+ rowCount := 0
+ for _, group := range frames {
+ for _, raw := range group {
+ rowCount++
+ if rowCount > maxAllocationRows {
+ return nil, time.Time{}, false, fmt.Errorf("OpenCost allocation response exceeds row limit")
+ }
+ var row openCostAllocation
+ if err := json.Unmarshal(raw, &row); err != nil {
+ return nil, time.Time{}, false, newSanitizedError("OpenCost allocation response contains malformed allocation data", err)
+ }
+ allocation, ok := validateOpenCostAllocation(row, requestedStart, requestedEnd, step, allowed)
+ if !ok {
+ incomplete = true
+ continue
+ }
+ if allocation.End.After(asOf) {
+ continue
+ }
+ allocations = append(allocations, allocation)
+ }
+ }
+ return allocations, asOf, incomplete, nil
+}
+
+func hasOpenCostError(raw json.RawMessage) bool {
+ return len(raw) > 0 && string(raw) != "null" && string(raw) != `""`
+}
+
+func hasOpenCostWarnings(raw json.RawMessage) bool {
+ return len(raw) > 0 && string(raw) != "null" && string(raw) != "[]"
+}
+
+func openCostFrameWindow(frame map[string]json.RawMessage, requestedStart, requestedEnd time.Time, step time.Duration) (allocationFrame, bool) {
+ if len(frame) == 0 {
+ return allocationFrame{}, false
+ }
+ var result allocationFrame
+ for _, raw := range frame {
+ var header struct {
+ Window json.RawMessage `json:"window"`
+ }
+ if err := json.Unmarshal(raw, &header); err != nil {
+ return allocationFrame{}, false
+ }
+ start, end, ok := parseOpenCostWindow(header.Window)
+ if !ok || start.Before(requestedStart) || end.After(requestedEnd) || !end.After(start) || end.Sub(start) != step {
+ return allocationFrame{}, false
+ }
+ if result.start.IsZero() {
+ result = allocationFrame{start: start, end: end}
+ continue
+ }
+ if !result.start.Equal(start) || !result.end.Equal(end) {
+ return allocationFrame{}, false
+ }
+ }
+ return result, !result.start.IsZero()
+}
+
+func completeCoverageBoundary(frames []allocationFrame, requestedStart, requestedEnd time.Time) (time.Time, bool) {
+ if len(frames) == 0 {
+ return requestedStart, false
+ }
+ sort.Slice(frames, func(i, j int) bool {
+ return frames[i].start.Before(frames[j].start)
+ })
+ cutoff := requestedStart
+ for _, frame := range frames {
+ if !frame.start.Equal(cutoff) {
+ return cutoff, false
+ }
+ cutoff = frame.end
+ }
+ if cutoff.After(requestedEnd) {
+ cutoff = requestedEnd
+ }
+ return cutoff, cutoff.Equal(requestedEnd)
+}
+
+func validateOpenCostAllocation(row openCostAllocation, requestedStart, requestedEnd time.Time, step time.Duration, allowed map[string]struct{}) (Allocation, bool) {
+ if _, ok := allowed[row.Properties.Namespace]; !ok || strings.TrimSpace(row.Properties.Pod) == "" || len(row.Properties.Pod) > 253 || row.Minutes == nil || row.CPUUsageAverage == nil || row.CPURequestAverage == nil || row.RAMUsageAverageBytes == nil || row.RAMRequestAverageBytes == nil {
+ return Allocation{}, false
+ }
+ start, end, ok := parseOpenCostWindow(row.Window)
+ if !ok || start.Before(requestedStart) || end.After(requestedEnd) || !end.After(start) || end.Sub(start) != step {
+ return Allocation{}, false
+ }
+ values := []float64{*row.Minutes, *row.CPUUsageAverage, *row.CPURequestAverage, *row.RAMUsageAverageBytes, *row.RAMRequestAverageBytes}
+ for _, value := range values {
+ if math.IsNaN(value) || math.IsInf(value, 0) || value < 0 || value > 1e15 {
+ return Allocation{}, false
+ }
+ }
+ if *row.Minutes > end.Sub(start).Minutes()+0.000001 {
+ return Allocation{}, false
+ }
+ return Allocation{Start: start, End: end, Namespace: row.Properties.Namespace, Pod: row.Properties.Pod, Minutes: *row.Minutes, CPUUsageAverage: *row.CPUUsageAverage, CPURequestAverage: *row.CPURequestAverage, RAMUsageAverageBytes: *row.RAMUsageAverageBytes, RAMRequestAverageBytes: *row.RAMRequestAverageBytes}, true
+}
+
+func parseOpenCostWindow(raw json.RawMessage) (time.Time, time.Time, bool) {
+ var object struct {
+ Start string `json:"start"`
+ End string `json:"end"`
+ }
+ if json.Unmarshal(raw, &object) == nil && object.Start != "" && object.End != "" {
+ start, startErr := time.Parse(time.RFC3339, object.Start)
+ end, endErr := time.Parse(time.RFC3339, object.End)
+ return start.UTC(), end.UTC(), startErr == nil && endErr == nil
+ }
+ var legacy string
+ if err := json.Unmarshal(raw, &legacy); err != nil || len(legacy) < 5 || legacy[0] != '[' || legacy[len(legacy)-1] != ')' {
+ return time.Time{}, time.Time{}, false
+ }
+ parts := strings.Split(strings.TrimSuffix(strings.TrimPrefix(legacy, "["), ")"), ",")
+ if len(parts) != 2 {
+ return time.Time{}, time.Time{}, false
+ }
+ start, startErr := time.Parse(time.RFC3339, strings.TrimSpace(parts[0]))
+ end, endErr := time.Parse(time.RFC3339, strings.TrimSpace(parts[1]))
+ return start.UTC(), end.UTC(), startErr == nil && endErr == nil
+}
+
+var _ AllocationClient = (*openCostClient)(nil)
diff --git a/libs/fleet/backend/usage/opencost_test.go b/libs/fleet/backend/usage/opencost_test.go
new file mode 100644
index 0000000000..93caef207e
--- /dev/null
+++ b/libs/fleet/backend/usage/opencost_test.go
@@ -0,0 +1,160 @@
+package usage
+
+import (
+ "context"
+ "fmt"
+ "math"
+ "net/http"
+ "net/http/httptest"
+ "testing"
+ "time"
+)
+
+func TestOpenCostClientUsesFixedScopedAllocationQuery(t *testing.T) {
+ t.Parallel()
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ if r.URL.Path != "/allocation/compute" {
+ t.Fatalf("path = %q", r.URL.Path)
+ }
+ q := r.URL.Query()
+ if q.Get("aggregate") != "cluster,namespace,pod" || q.Get("includeIdle") != "false" || q.Get("includeSharedCostBreakdown") != "false" || q.Get("accumulate") != "false" || q.Get("step") != "1h" || q.Get("filter") != `namespace:"ns-a"|namespace:"ns-b"` || q.Has("filterNamespaces") {
+ t.Fatalf("query = %#v", q)
+ }
+ _, _ = w.Write([]byte(`{"code":200,"data":[{"cluster/ns-a/virt-launcher-vm-a-x":{"properties":{"namespace":"ns-a","pod":"virt-launcher-vm-a-x"},"window":{"start":"2026-08-19T09:00:00Z","end":"2026-08-19T10:00:00Z"},"minutes":60,"cpuCoreUsageAverage":2,"cpuCoreRequestAverage":4,"ramByteUsageAverage":3221225472,"ramByteRequestAverage":6442450944}}],"meta":{"timeGenerated":"2026-08-19T10:01:00Z"}}`))
+ }))
+ defer server.Close()
+ client, err := NewOpenCostClient(server.URL, time.Second, 1<<20)
+ if err != nil {
+ t.Fatal(err)
+ }
+ start := time.Date(2026, 8, 19, 9, 0, 0, 0, time.UTC)
+ allocations, asOf, partial, err := client.Allocations(context.Background(), start, start.Add(time.Hour), time.Hour, []string{"ns-b", "ns-a"})
+ if err != nil || partial || !asOf.Equal(start.Add(time.Hour)) || len(allocations) != 1 {
+ t.Fatalf("allocations=%#v asOf=%s partial=%t err=%v", allocations, asOf, partial, err)
+ }
+ if allocations[0].CPUUsageAverage != 2 || allocations[0].CPURequestAverage != 4 || allocations[0].RAMUsageAverageBytes != 3*gibibyte || allocations[0].RAMRequestAverageBytes != 6*gibibyte {
+ t.Fatalf("allocation = %#v", allocations[0])
+ }
+}
+
+func TestParseOpenCostAllocationsUsesProductionWindowShapeAndCoverage(t *testing.T) {
+ t.Parallel()
+ start := time.Date(2026, 7, 13, 3, 0, 0, 0, time.UTC)
+ body := []byte(`{"code":200,"data":[{"default/api":{"properties":{"namespace":"default","pod":"virt-launcher-api-x"},"window":{"start":"2026-07-13T03:00:00Z","end":"2026-07-13T04:00:00Z"},"minutes":60,"cpuCoreUsageAverage":0,"cpuCoreRequestAverage":2,"ramByteUsageAverage":0,"ramByteRequestAverage":1073741824}}]}`)
+ allocations, asOf, partial, err := parseOpenCostAllocations(body, start, start.Add(time.Hour), time.Hour, []string{"default"})
+ if err != nil || partial || !asOf.Equal(start.Add(time.Hour)) || len(allocations) != 1 {
+ t.Fatalf("allocations=%#v asOf=%s partial=%t err=%v", allocations, asOf, partial, err)
+ }
+ if allocations[0].CPUUsageAverage != 0 || allocations[0].RAMUsageAverageBytes != 0 {
+ t.Fatalf("zero averages were not retained: %#v", allocations[0])
+ }
+}
+
+func TestParseOpenCostAllocationsMarksIncompleteCoverage(t *testing.T) {
+ t.Parallel()
+ start := time.Date(2026, 8, 19, 9, 0, 0, 0, time.UTC)
+ row := func(windowStart, windowEnd time.Time) string {
+ return fmt.Sprintf(`{"properties":{"namespace":"ns-a","pod":"virt-launcher-vm-a-x"},"window":{"start":"%s","end":"%s"},"minutes":60,"cpuCoreUsageAverage":1,"cpuCoreRequestAverage":2,"ramByteUsageAverage":1073741824,"ramByteRequestAverage":2147483648}`, windowStart.Format(time.RFC3339), windowEnd.Format(time.RFC3339))
+ }
+ for name, test := range map[string]struct {
+ body []byte
+ wantCutoff time.Time
+ wantRows int
+ }{
+ "empty": {[]byte(`{"code":200,"data":[]}`), start, 0},
+ "missing_frame": {[]byte(`{"code":200,"data":[{"first":` + row(start, start.Add(time.Hour)) + `},{}]}`), start.Add(time.Hour), 1},
+ "gap": {[]byte(`{"code":200,"data":[{"first":` + row(start, start.Add(time.Hour)) + `},{"third":` + row(start.Add(2*time.Hour), start.Add(3*time.Hour)) + `}]}`), start.Add(time.Hour), 1},
+ } {
+ t.Run(name, func(t *testing.T) {
+ allocations, asOf, partial, err := parseOpenCostAllocations(test.body, start, start.Add(3*time.Hour), time.Hour, []string{"ns-a"})
+ if err != nil || !partial || !asOf.Equal(test.wantCutoff) || len(allocations) != test.wantRows {
+ t.Fatalf("allocations=%#v asOf=%s partial=%t err=%v", allocations, asOf, partial, err)
+ }
+ })
+ }
+}
+
+func TestParseOpenCostAllocationsRejectsSourceErrorsAndMalformedRequiredValues(t *testing.T) {
+ t.Parallel()
+ start := time.Date(2026, 8, 19, 9, 0, 0, 0, time.UTC)
+ for name, body := range map[string][]byte{
+ "missing_code": []byte(`{"data":[]}`),
+ "error_code": []byte(`{"code":500,"error":"upstream failed"}`),
+ "success_error": []byte(`{"code":200,"error":"unexpected","data":[]}`),
+ } {
+ t.Run(name, func(t *testing.T) {
+ if _, _, _, err := parseOpenCostAllocations(body, start, start.Add(time.Hour), time.Hour, []string{"ns-a"}); err == nil {
+ t.Fatal("expected source envelope error")
+ }
+ })
+ }
+ body := []byte(`{"code":200,"data":[{"missing":{"properties":{"namespace":"ns-a","pod":"virt-launcher-vm-a-x"},"window":{"start":"2026-08-19T09:00:00Z","end":"2026-08-19T10:00:00Z"},"minutes":60,"cpuCoreUsageAverage":null,"cpuCoreRequestAverage":2,"ramByteUsageAverage":1073741824,"ramByteRequestAverage":2147483648}}]}`)
+ allocations, _, partial, err := parseOpenCostAllocations(body, start, start.Add(time.Hour), time.Hour, []string{"ns-a"})
+ if err != nil || !partial || len(allocations) != 0 {
+ t.Fatalf("allocations=%#v partial=%t err=%v", allocations, partial, err)
+ }
+}
+
+func TestOpenCostClientRejectsUnsafeNamespace(t *testing.T) {
+ t.Parallel()
+ client, err := NewOpenCostClient("https://opencost.invalid", time.Second, 1<<20)
+ if err != nil {
+ t.Fatal(err)
+ }
+ _, _, _, err = client.Allocations(context.Background(), time.Now().Add(-time.Hour), time.Now(), time.Hour, []string{"ns-a\"|cluster:\"all"})
+ if err == nil {
+ t.Fatal("expected namespace validation error")
+ }
+}
+
+func TestParseOpenCostAllocationsExcludesBadRowsAsIncomplete(t *testing.T) {
+ t.Parallel()
+ start := time.Date(2026, 8, 19, 9, 0, 0, 0, time.UTC)
+ body := []byte(`{"code":200,"data":[{"valid":{"properties":{"namespace":"ns-a","pod":"virt-launcher-vm-a-x"},"window":"[2026-08-19T09:00:00Z,2026-08-19T10:00:00Z)","minutes":60,"cpuCoreUsageAverage":1,"cpuCoreRequestAverage":2,"ramByteUsageAverage":1073741824,"ramByteRequestAverage":2147483648},"out-of-scope":{"properties":{"namespace":"other","pod":"pod"},"window":"[2026-08-19T09:00:00Z,2026-08-19T10:00:00Z)","minutes":60,"cpuCoreUsageAverage":1,"cpuCoreRequestAverage":2,"ramByteUsageAverage":1073741824,"ramByteRequestAverage":2147483648},"oversized":{"properties":{"namespace":"ns-a","pod":"pod"},"window":"[2026-08-19T09:00:00Z,2026-08-19T10:00:00Z)","minutes":60,"cpuCoreUsageAverage":1000000000000001,"cpuCoreRequestAverage":2,"ramByteUsageAverage":1073741824,"ramByteRequestAverage":2147483648}}],"warnings":["partial"]}`)
+ allocations, _, partial, err := parseOpenCostAllocations(body, start, start.Add(time.Hour), time.Hour, []string{"ns-a"})
+ if err != nil || !partial || len(allocations) != 1 {
+ t.Fatalf("allocations=%#v partial=%t err=%v", allocations, partial, err)
+ }
+}
+
+func TestOpenCostClientRejectsUnsafeBaseURLAndResponseLimitOverflow(t *testing.T) {
+ t.Parallel()
+ for _, rawURL := range []string{
+ "https://opencost.invalid?filterNamespaces=legacy",
+ "https://opencost.invalid#fragment",
+ "https://user:[email protected]",
+ "ftp://opencost.invalid",
+ } {
+ if _, err := NewOpenCostClient(rawURL, time.Second, 1<<20); err == nil {
+ t.Fatalf("expected unsafe URL rejection for %q", rawURL)
+ }
+ }
+ if _, err := NewOpenCostClient("https://opencost.invalid", time.Second, math.MaxInt64); err == nil {
+ t.Fatal("expected response limit overflow rejection")
+ }
+}
+
+func TestOpenCostClientRejectsRedirectAndResponseOverLimit(t *testing.T) {
+ t.Parallel()
+ for name, handler := range map[string]http.HandlerFunc{
+ "redirect": func(w http.ResponseWriter, r *http.Request) { http.Redirect(w, r, "/elsewhere", http.StatusFound) },
+ "limit": func(w http.ResponseWriter, r *http.Request) { _, _ = w.Write(make([]byte, 128)) },
+ } {
+ t.Run(name, func(t *testing.T) {
+ server := httptest.NewServer(handler)
+ defer server.Close()
+ limit := int64(1 << 20)
+ if name == "limit" {
+ limit = 64
+ }
+ client, err := NewOpenCostClient(server.URL, time.Second, limit)
+ if err != nil {
+ t.Fatal(err)
+ }
+ _, _, _, err = client.Allocations(context.Background(), time.Now().UTC().Truncate(time.Hour), time.Now().UTC().Truncate(time.Hour).Add(time.Hour), time.Hour, []string{"ns-a"})
+ if err == nil {
+ t.Fatal("expected request error")
+ }
+ })
+ }
+}
diff --git a/libs/fleet/backend/usage/postgres.go b/libs/fleet/backend/usage/postgres.go
new file mode 100644
index 0000000000..77b2e5d882
--- /dev/null
+++ b/libs/fleet/backend/usage/postgres.go
@@ -0,0 +1,96 @@
+package usage
+
+import (
+ "context"
+ "fmt"
+ "strings"
+ "time"
+
+ "github.com/jackc/pgx/v5/pgxpool"
+)
+
+const maxEvents = 10000
+
+const usageSandboxEventsQuery = `select event_id, namespace, sandbox_name, sandbox_uid, pool_name,
+ runtime, vm_name, event_type, observed_at
+from k8s_reporting.usage_sandbox_events($1, $2, $3)`
+
+type PostgresEventStore struct {
+ pool *pgxpool.Pool
+}
+
+func NewPostgresEventStore(ctx context.Context, databaseURL string) (*PostgresEventStore, error) {
+ config, err := pgxpool.ParseConfig(databaseURL)
+ if err != nil {
+ return nil, fmt.Errorf("parse usage database URL: %w", err)
+ }
+ if config.ConnConfig.User != "cyclops_usage_reader" {
+ return nil, fmt.Errorf("usage database URL must use cyclops_usage_reader")
+ }
+ config.MaxConns = 4
+ config.MinConns = 0
+ config.MaxConnIdleTime = time.Minute
+ config.MaxConnLifetime = 15 * time.Minute
+ pool, err := pgxpool.NewWithConfig(ctx, config)
+ if err != nil {
+ return nil, fmt.Errorf("open usage database pool: %w", err)
+ }
+ return &PostgresEventStore{pool: pool}, nil
+}
+
+func (s *PostgresEventStore) Close() {
+ if s != nil && s.pool != nil {
+ s.pool.Close()
+ }
+}
+
+func (s *PostgresEventStore) Events(ctx context.Context, tenant string, start, end time.Time) ([]SandboxEvent, error) {
+ if strings.TrimSpace(tenant) == "" || start.IsZero() || end.IsZero() || !end.After(start) {
+ return nil, fmt.Errorf("invalid usage event query")
+ }
+ rows, err := s.pool.Query(ctx, usageSandboxEventsQuery, tenant, start, end)
+ if err != nil {
+ return nil, fmt.Errorf("query usage sandbox events: %w", err)
+ }
+ defer rows.Close()
+
+ events := make([]SandboxEvent, 0)
+ for rows.Next() {
+ if len(events) >= maxEvents {
+ return nil, fmt.Errorf("usage event result exceeds %d events", maxEvents)
+ }
+ var event SandboxEvent
+ if err := rows.Scan(&event.EventID, &event.Namespace, &event.SandboxName, &event.SandboxUID, &event.PoolName, &event.Runtime, &event.VMName, &event.EventType, &event.ObservedAt); err != nil {
+ return nil, fmt.Errorf("scan usage sandbox event: %w", err)
+ }
+ if err := validateSandboxEvent(event); err != nil {
+ return nil, err
+ }
+ events = append(events, event)
+ }
+ if err := rows.Err(); err != nil {
+ return nil, fmt.Errorf("read usage sandbox events: %w", err)
+ }
+ return events, nil
+}
+
+func validateSandboxEvent(event SandboxEvent) error {
+ fields := []string{event.Namespace, event.SandboxName, event.SandboxUID, event.PoolName, event.Runtime, event.VMName, event.EventType}
+ if event.EventID == [16]byte{} || event.ObservedAt.IsZero() {
+ return fmt.Errorf("usage sandbox event contains empty required fields")
+ }
+ for _, field := range fields {
+ if field == "" || field != strings.TrimSpace(field) {
+ return fmt.Errorf("usage sandbox event contains unnormalized required fields")
+ }
+ }
+ if len(event.Namespace) > 63 || !dns1123Label.MatchString(event.Namespace) {
+ return fmt.Errorf("usage sandbox event contains invalid namespace")
+ }
+ if !validPoolName(event.PoolName) {
+ return fmt.Errorf("usage sandbox event contains invalid pool name")
+ }
+ return nil
+}
+
+var _ EventStore = (*PostgresEventStore)(nil)
diff --git a/libs/fleet/backend/usage/postgres_test.go b/libs/fleet/backend/usage/postgres_test.go
new file mode 100644
index 0000000000..aada4101f0
--- /dev/null
+++ b/libs/fleet/backend/usage/postgres_test.go
@@ -0,0 +1,53 @@
+package usage
+
+import (
+ "context"
+ "testing"
+ "time"
+)
+
+func TestNewPostgresEventStoreRequiresUsageReader(t *testing.T) {
+ t.Parallel()
+ if _, err := NewPostgresEventStore(context.Background(), "postgres://wrong:pw@db/cyclops"); err == nil {
+ t.Fatal("expected role validation error")
+ }
+}
+
+func TestUsageSandboxEventsQueryIsFixed(t *testing.T) {
+ t.Parallel()
+ const want = "select event_id, namespace, sandbox_name, sandbox_uid, pool_name,\n runtime, vm_name, event_type, observed_at\nfrom k8s_reporting.usage_sandbox_events($1, $2, $3)"
+ if usageSandboxEventsQuery != want {
+ t.Fatalf("unexpected query: %q", usageSandboxEventsQuery)
+ }
+}
+
+func TestNewPostgresEventStoreAcceptsUsageReaderAndCloses(t *testing.T) {
+ t.Parallel()
+ store, err := NewPostgresEventStore(context.Background(), "postgres://cyclops_usage_reader:[email protected]:1/cyclops")
+ if err != nil {
+ t.Fatal(err)
+ }
+ store.Close()
+}
+
+func TestValidateSandboxEventRejectsUnnormalizedOrUnsafeNamespace(t *testing.T) {
+ t.Parallel()
+ valid := SandboxEvent{EventID: mustUUID("00000000-0000-0000-0000-000000000050"), Namespace: "ns-a", SandboxName: "sandbox", SandboxUID: "uid", PoolName: "pool", Runtime: "kubevirt", VMName: "vm", EventType: "Added", ObservedAt: time.Now().UTC()}
+ for name, mutate := range map[string]func(*SandboxEvent){
+ "whitespace": func(event *SandboxEvent) { event.PoolName = " pool" },
+ "namespace": func(event *SandboxEvent) { event.Namespace = "ns-a\"" },
+ "pool_colon": func(event *SandboxEvent) { event.PoolName = "pool:a" },
+ "pool_case": func(event *SandboxEvent) { event.PoolName = "Pool" },
+ "pool_length": func(event *SandboxEvent) {
+ event.PoolName = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+ },
+ } {
+ t.Run(name, func(t *testing.T) {
+ event := valid
+ mutate(&event)
+ if err := validateSandboxEvent(event); err == nil {
+ t.Fatal("expected validation error")
+ }
+ })
+ }
+}
diff --git a/libs/fleet/backend/usage/provider.go b/libs/fleet/backend/usage/provider.go
new file mode 100644
index 0000000000..69e87ded38
--- /dev/null
+++ b/libs/fleet/backend/usage/provider.go
@@ -0,0 +1,451 @@
+package usage
+
+import (
+ "context"
+ "errors"
+ "fmt"
+ "sort"
+ "strings"
+ "time"
+
+ "cyclops-cs-backend/identity"
+)
+
+var ErrPoolNotFound = errors.New("usage pool not found")
+
+type provider struct {
+ events EventStore
+ allocations AllocationClient
+ clock func() time.Time
+}
+
+type liveSegment struct {
+ namespace string
+ uid string
+ pool string
+ runtime string
+ vmName string
+ start time.Time
+ end time.Time
+}
+
+func NewProvider(events EventStore, allocations AllocationClient, clock func() time.Time) *provider {
+ if clock == nil {
+ clock = time.Now
+ }
+ return &provider{events: events, allocations: allocations, clock: clock}
+}
+
+func (p *provider) Overview(ctx context.Context, query Query) (OverviewResponse, error) {
+ data, err := p.load(ctx, query)
+ if err != nil {
+ return OverviewResponse{}, err
+ }
+ response := OverviewResponse{DataAsOf: data.asOf, Partial: data.partial, Pools: make([]PoolSummary, 0)}
+ for _, pool := range data.pools {
+ response.Pools = append(response.Pools, PoolSummary{ID: pool.id, Name: pool.name, CPU: MetricTotals{Consumed: pool.cpuConsumed, Provisioned: pool.cpuProvisioned}, Memory: MetricTotals{Consumed: pool.memoryConsumed, Provisioned: pool.memoryProvisioned}})
+ }
+ return response, nil
+}
+
+func (p *provider) PoolDetail(ctx context.Context, query PoolQuery) (PoolDetailResponse, error) {
+ namespace, poolName, ok := parsePoolID(query.PoolID)
+ if !ok {
+ return PoolDetailResponse{}, fmt.Errorf("invalid pool ID")
+ }
+ data, err := p.load(ctx, query.Query)
+ if err != nil {
+ return PoolDetailResponse{}, err
+ }
+ step, err := intervalDuration(query.Interval)
+ if err != nil {
+ return PoolDetailResponse{}, err
+ }
+ pool, ok := findPool(data.pools, query.PoolID)
+ if !ok {
+ return PoolDetailResponse{}, fmt.Errorf("%w: %s", ErrPoolNotFound, query.PoolID)
+ }
+ response := PoolDetailResponse{DataAsOf: data.asOf, Partial: data.partial, Pool: PoolIdentity{ID: pool.id, Name: pool.name}, Buckets: make([]Bucket, 0)}
+ for start := data.start; start.Before(data.end); start = start.Add(step) {
+ key := bucketKey{namespace: namespace, pool: poolName, start: start}
+ totals := data.buckets[key]
+ response.Buckets = append(response.Buckets, Bucket{Start: start, End: start.Add(step), CPUConsumed: totals.cpuConsumed, CPUProvisioned: totals.cpuProvisioned, MemoryConsumed: totals.memoryConsumed, MemoryProvisioned: totals.memoryProvisioned})
+ }
+ return response, nil
+}
+
+type usageData struct {
+ start time.Time
+ end time.Time
+ asOf time.Time
+ partial bool
+ pools []usageTotals
+ buckets map[bucketKey]usageTotals
+}
+
+type usageTotals struct {
+ id string
+ name string
+ cpuConsumed float64
+ cpuProvisioned float64
+ memoryConsumed float64
+ memoryProvisioned float64
+}
+
+type bucketKey struct {
+ namespace string
+ pool string
+ start time.Time
+}
+
+func (p *provider) load(ctx context.Context, query Query) (usageData, error) {
+ if p.events == nil || p.allocations == nil {
+ return usageData{}, fmt.Errorf("usage provider is not configured")
+ }
+ start, end, step, err := usageWindow(query.Timeframe, p.clock())
+ if err != nil {
+ return usageData{}, err
+ }
+ events, err := p.events.Events(ctx, identity.PersonalGroup(ctx, query.Subject), start, end)
+ if err != nil {
+ return usageData{}, fmt.Errorf("read usage events: %w", err)
+ }
+ segments, namespaces, partial := buildSegments(events, start, end)
+ data := usageData{start: start, end: end, asOf: end, partial: partial, pools: make([]usageTotals, 0), buckets: make(map[bucketKey]usageTotals)}
+ if len(segments) == 0 || len(namespaces) == 0 {
+ return data, nil
+ }
+ allocations, asOf, sourcePartial, err := p.allocations.Allocations(ctx, start, end, step, namespaces)
+ if err != nil {
+ return usageData{}, fmt.Errorf("read OpenCost allocations: %w", err)
+ }
+ if asOf.IsZero() {
+ asOf = start
+ sourcePartial = true
+ }
+ data.asOf = minTime(end, asOf.UTC())
+ if data.asOf.Before(start) {
+ data.asOf = start
+ sourcePartial = true
+ }
+ data.partial = data.partial || sourcePartial || data.asOf.Before(end)
+ poolTotals := make(map[string]usageTotals)
+ for _, allocation := range allocations {
+ matched, allocationPartial := attributeAllocation(allocation, segments, start, end, step, poolTotals, data.buckets)
+ if !matched || allocationPartial {
+ data.partial = true
+ }
+ }
+ for _, totals := range poolTotals {
+ if !totals.isZero() {
+ data.pools = append(data.pools, totals)
+ }
+ }
+ disambiguatePoolNames(data.pools)
+ sort.Slice(data.pools, func(i, j int) bool { return data.pools[i].id < data.pools[j].id })
+ return data, nil
+}
+
+func usageWindow(timeframe Timeframe, now time.Time) (time.Time, time.Time, time.Duration, error) {
+ cutoff := now.UTC().Truncate(time.Hour)
+ switch timeframe {
+ case Timeframe24H:
+ return cutoff.Add(-24 * time.Hour), cutoff, time.Hour, nil
+ case Timeframe7D:
+ return cutoff.Add(-7 * 24 * time.Hour), cutoff, time.Hour, nil
+ case Timeframe30D:
+ return cutoff.Add(-30 * 24 * time.Hour), cutoff, 24 * time.Hour, nil
+ default:
+ return time.Time{}, time.Time{}, 0, fmt.Errorf("invalid usage timeframe")
+ }
+}
+
+func intervalDuration(interval Interval) (time.Duration, error) {
+ switch interval {
+ case IntervalHour:
+ return time.Hour, nil
+ case IntervalDay:
+ return 24 * time.Hour, nil
+ default:
+ return 0, fmt.Errorf("invalid usage interval")
+ }
+}
+
+func parsePoolID(id string) (string, string, bool) {
+ parts := strings.Split(id, ":")
+ if len(parts) != 2 || !dns1123Label.MatchString(parts[0]) || !validPoolName(parts[1]) {
+ return "", "", false
+ }
+ return parts[0], parts[1], true
+}
+
+func validPoolName(name string) bool {
+ return len(name) <= 63 && dns1123Label.MatchString(name)
+}
+
+func buildSegments(events []SandboxEvent, start, end time.Time) ([]liveSegment, []string, bool) {
+ bySandbox := make(map[string][]SandboxEvent)
+ seen := make(map[[16]byte]struct{}, len(events))
+ partial := false
+ for _, event := range events {
+ if _, ok := seen[event.EventID]; ok {
+ continue
+ }
+ seen[event.EventID] = struct{}{}
+ if err := validateSandboxEvent(event); err != nil || !event.ObservedAt.Before(end) {
+ partial = true
+ continue
+ }
+ key := event.Namespace + "\x00" + event.SandboxUID
+ bySandbox[key] = append(bySandbox[key], event)
+ }
+ segments := make([]liveSegment, 0)
+ namespaceSet := make(map[string]struct{})
+ for _, timeline := range bySandbox {
+ sort.SliceStable(timeline, func(i, j int) bool {
+ return timeline[i].ObservedAt.Before(timeline[j].ObservedAt)
+ })
+ var active *SandboxEvent
+ activeStart := start
+ certain := false
+ appendActive := func(until time.Time) {
+ if active == nil || !certain || !until.After(activeStart) {
+ return
+ }
+ segmentEnd := minTime(until, end)
+ if segmentEnd.After(activeStart) {
+ segments = append(segments, liveSegment{namespace: active.Namespace, uid: active.SandboxUID, pool: active.PoolName, runtime: active.Runtime, vmName: active.VMName, start: activeStart, end: segmentEnd})
+ namespaceSet[active.Namespace] = struct{}{}
+ }
+ }
+ invalidate := func(at time.Time) {
+ appendActive(at)
+ active = nil
+ activeStart = at
+ certain = false
+ }
+ for index := 0; index < len(timeline); {
+ event := timeline[index]
+ at := event.ObservedAt.UTC()
+ if index+1 < len(timeline) && at.Equal(timeline[index+1].ObservedAt) {
+ partial = true
+ invalidate(at)
+ for index < len(timeline) && at.Equal(timeline[index].ObservedAt.UTC()) {
+ index++
+ }
+ continue
+ }
+ isBaseline := index == 0 && at.Before(start)
+ if isBaseline {
+ switch strings.ToLower(event.EventType) {
+ case "added", "modified":
+ copy := event
+ active = &copy
+ activeStart = start
+ certain = true
+ case "deleted":
+ active = nil
+ activeStart = start
+ certain = true
+ default:
+ partial = true
+ invalidate(start)
+ }
+ index++
+ continue
+ }
+ if !at.Before(start) && index == 0 {
+ partial = true
+ }
+ switch strings.ToLower(event.EventType) {
+ case "added":
+ if active != nil && certain {
+ partial = true
+ invalidate(at)
+ index++
+ continue
+ }
+ copy := event
+ active = &copy
+ activeStart = maxTime(at, start)
+ certain = true
+ case "modified":
+ if active == nil || !certain {
+ partial = true
+ invalidate(at)
+ index++
+ continue
+ }
+ appendActive(at)
+ copy := event
+ active = &copy
+ activeStart = maxTime(at, start)
+ case "deleted":
+ if active == nil || !certain {
+ partial = true
+ invalidate(at)
+ index++
+ continue
+ }
+ appendActive(at)
+ active = nil
+ activeStart = at
+ certain = true
+ default:
+ partial = true
+ invalidate(at)
+ }
+ index++
+ }
+ appendActive(end)
+ }
+ namespaces := make([]string, 0, len(namespaceSet))
+ for namespace := range namespaceSet {
+ namespaces = append(namespaces, namespace)
+ }
+ sort.Strings(namespaces)
+ return segments, namespaces, partial
+}
+
+func findPool(pools []usageTotals, id string) (usageTotals, bool) {
+ for _, pool := range pools {
+ if pool.id == id {
+ return pool, true
+ }
+ }
+ return usageTotals{}, false
+}
+
+func (totals usageTotals) isZero() bool {
+ return totals.cpuConsumed == 0 && totals.cpuProvisioned == 0 && totals.memoryConsumed == 0 && totals.memoryProvisioned == 0
+}
+
+func disambiguatePoolNames(pools []usageTotals) {
+ counts := make(map[string]int, len(pools))
+ for _, pool := range pools {
+ counts[pool.name]++
+ }
+ for index := range pools {
+ if counts[pools[index].name] > 1 {
+ namespace, _, _ := strings.Cut(pools[index].id, ":")
+ pools[index].name = namespace + "/" + pools[index].name
+ }
+ }
+}
+
+func attributeAllocation(allocation Allocation, segments []liveSegment, windowStart, windowEnd time.Time, bucketDuration time.Duration, pools map[string]usageTotals, buckets map[bucketKey]usageTotals) (bool, bool) {
+ if allocation.Start.IsZero() || allocation.End.IsZero() || !allocation.End.After(allocation.Start) || allocation.Start.Before(windowStart) || allocation.End.After(windowEnd) || allocation.Minutes < 0 {
+ return false, true
+ }
+ matches := matchingSegments(allocation, segments)
+ if len(matches) == 0 {
+ return false, true
+ }
+ covered := 0.0
+ for _, match := range matches {
+ overlapStart := maxTime(allocation.Start, match.start)
+ overlapEnd := minTime(allocation.End, match.end)
+ if overlapEnd.After(overlapStart) {
+ covered += overlapEnd.Sub(overlapStart).Seconds()
+ }
+ }
+ partial := covered+0.000001 < allocation.End.Sub(allocation.Start).Seconds()
+ for _, match := range matches {
+ for bucketStart := bucketStartFor(allocation.Start, windowStart, bucketDuration); bucketStart.Before(allocation.End); bucketStart = bucketStart.Add(bucketDuration) {
+ bucketEnd := bucketStart.Add(bucketDuration)
+ overlapStart := maxTime(maxTime(allocation.Start, match.start), bucketStart)
+ overlapEnd := minTime(minTime(allocation.End, match.end), bucketEnd)
+ if !overlapEnd.After(overlapStart) {
+ continue
+ }
+ fraction := overlapEnd.Sub(overlapStart).Seconds() / allocation.End.Sub(allocation.Start).Seconds()
+ minutes := allocation.Minutes * fraction
+ cpuConsumed := allocation.CPUUsageAverage * minutes / 60
+ cpuProvisioned := allocation.CPURequestAverage * minutes / 60
+ memoryConsumed := allocation.RAMUsageAverageBytes * minutes / 60 / gibibyte
+ memoryProvisioned := allocation.RAMRequestAverageBytes * minutes / 60 / gibibyte
+ id := match.namespace + ":" + match.pool
+ pool := pools[id]
+ pool.id, pool.name = id, match.pool
+ pool.cpuConsumed += cpuConsumed
+ pool.cpuProvisioned += cpuProvisioned
+ pool.memoryConsumed += memoryConsumed
+ pool.memoryProvisioned += memoryProvisioned
+ pools[id] = pool
+ key := bucketKey{namespace: match.namespace, pool: match.pool, start: bucketStart}
+ bucket := buckets[key]
+ bucket.cpuConsumed += cpuConsumed
+ bucket.cpuProvisioned += cpuProvisioned
+ bucket.memoryConsumed += memoryConsumed
+ bucket.memoryProvisioned += memoryProvisioned
+ buckets[key] = bucket
+ }
+ }
+ return true, partial
+}
+
+func bucketStartFor(value, origin time.Time, duration time.Duration) time.Time {
+ value, origin = value.UTC(), origin.UTC()
+ if value.Before(origin) {
+ return origin
+ }
+ return origin.Add((value.Sub(origin) / duration) * duration)
+}
+
+func matchingSegments(allocation Allocation, segments []liveSegment) []liveSegment {
+ matches := make([]liveSegment, 0)
+ for _, segment := range segments {
+ if segment.namespace != allocation.Namespace || !allocation.End.After(segment.start) || !segment.end.After(allocation.Start) || !strings.EqualFold(segment.runtime, "kubevirt") {
+ continue
+ }
+ matches = append(matches, segment)
+ }
+ if len(matches) == 0 {
+ return nil
+ }
+ best := -1
+ for _, segment := range matches {
+ if kubeVirtPodMatches(allocation.Pod, segment.vmName) && len(segment.vmName) > best {
+ best = len(segment.vmName)
+ }
+ }
+ if best < 0 {
+ return nil
+ }
+ result := matches[:0]
+ for _, segment := range matches {
+ if len(segment.vmName) == best && kubeVirtPodMatches(allocation.Pod, segment.vmName) {
+ result = append(result, segment)
+ }
+ }
+ // Adjacent events for the same sandbox can produce multiple temporal pieces;
+ // reject competing sandboxes that overlap the same allocation instant.
+ for index, left := range result {
+ for _, right := range result[index+1:] {
+ if left.uid != right.uid && left.end.After(right.start) && right.end.After(left.start) {
+ return nil
+ }
+ }
+ }
+ return result
+}
+
+func kubeVirtPodMatches(pod, vmName string) bool {
+ prefix := "virt-launcher-" + vmName + "-"
+ return strings.HasPrefix(pod, prefix) && len(pod) > len(prefix)
+}
+
+func minTime(left, right time.Time) time.Time {
+ if left.Before(right) {
+ return left
+ }
+ return right
+}
+func maxTime(left, right time.Time) time.Time {
+ if left.After(right) {
+ return left
+ }
+ return right
+}
+
+var _ Provider = (*provider)(nil)
diff --git a/libs/fleet/backend/usage/provider_test.go b/libs/fleet/backend/usage/provider_test.go
new file mode 100644
index 0000000000..a5af3b7b09
--- /dev/null
+++ b/libs/fleet/backend/usage/provider_test.go
@@ -0,0 +1,390 @@
+package usage
+
+import (
+ "context"
+ "errors"
+ "github.com/google/uuid"
+ "strings"
+ "testing"
+ "time"
+)
+
+type fakeEventStore struct {
+ events []SandboxEvent
+ err error
+ calls int
+ tenant string
+ start time.Time
+ end time.Time
+}
+
+func (s *fakeEventStore) Events(_ context.Context, tenant string, start, end time.Time) ([]SandboxEvent, error) {
+ s.calls++
+ s.tenant, s.start, s.end = tenant, start, end
+ return s.events, s.err
+}
+
+type fakeAllocationClient struct {
+ allocations []Allocation
+ asOf time.Time
+ partial bool
+ err error
+ calls int
+ start time.Time
+ end time.Time
+ step time.Duration
+ namespaces []string
+}
+
+func (c *fakeAllocationClient) Allocations(_ context.Context, start, end time.Time, step time.Duration, namespaces []string) ([]Allocation, time.Time, bool, error) {
+ c.calls++
+ c.start, c.end, c.step = start, end, step
+ c.namespaces = append([]string(nil), namespaces...)
+ return c.allocations, c.asOf, c.partial, c.err
+}
+
+func TestProviderOverviewAggregatesTenantLauncherUsage(t *testing.T) {
+ t.Parallel()
+ cutoff := time.Date(2026, 8, 19, 10, 0, 0, 0, time.UTC)
+ events := &fakeEventStore{events: []SandboxEvent{{
+ EventID: mustUUID("00000000-0000-0000-0000-000000000001"), Namespace: "ns-a", SandboxName: "sandbox-a", SandboxUID: "uid-a",
+ PoolName: "pool-a", Runtime: "kubevirt", VMName: "vm-a", EventType: "Added", ObservedAt: cutoff.Add(-25 * time.Hour),
+ }}}
+ allocations := &fakeAllocationClient{asOf: cutoff, allocations: []Allocation{{
+ Start: cutoff.Add(-time.Hour), End: cutoff, Namespace: "ns-a", Pod: "virt-launcher-vm-a-abc",
+ Minutes: 60, CPUUsageAverage: 2, CPURequestAverage: 4,
+ RAMUsageAverageBytes: 3 * gibibyte, RAMRequestAverageBytes: 6 * gibibyte,
+ }}}
+ provider := NewProvider(events, allocations, func() time.Time { return cutoff })
+
+ got, err := provider.Overview(context.Background(), Query{Subject: "alice", Timeframe: Timeframe24H})
+ if err != nil {
+ t.Fatal(err)
+ }
+ if events.tenant != "user-alice" || !events.start.Equal(cutoff.Add(-24*time.Hour)) || !events.end.Equal(cutoff) {
+ t.Fatalf("event query = tenant %q [%s, %s)", events.tenant, events.start, events.end)
+ }
+ if allocations.calls != 1 || allocations.step != time.Hour || len(allocations.namespaces) != 1 || allocations.namespaces[0] != "ns-a" {
+ t.Fatalf("allocation request = calls %d step %s namespaces %#v", allocations.calls, allocations.step, allocations.namespaces)
+ }
+ if !got.DataAsOf.Equal(cutoff) || got.Partial || len(got.Pools) != 1 {
+ t.Fatalf("overview = %#v", got)
+ }
+ pool := got.Pools[0]
+ if pool.ID != "ns-a:pool-a" || pool.Name != "pool-a" || pool.CPU.Consumed != 2 || pool.CPU.Provisioned != 4 || pool.Memory.Consumed != 3 || pool.Memory.Provisioned != 6 {
+ t.Fatalf("pool = %#v", pool)
+ }
+}
+
+func TestProviderOverviewEmptyTenantSkipsOpenCost(t *testing.T) {
+ t.Parallel()
+ events := &fakeEventStore{}
+ allocations := &fakeAllocationClient{}
+ provider := NewProvider(events, allocations, func() time.Time { return time.Date(2026, 8, 19, 10, 22, 0, 0, time.UTC) })
+
+ got, err := provider.Overview(context.Background(), Query{Subject: "nobody", Timeframe: Timeframe7D})
+ if err != nil {
+ t.Fatal(err)
+ }
+ if allocations.calls != 0 || got.Partial || len(got.Pools) != 0 || !got.DataAsOf.Equal(time.Date(2026, 8, 19, 10, 0, 0, 0, time.UTC)) {
+ t.Fatalf("overview = %#v, allocation calls = %d", got, allocations.calls)
+ }
+}
+
+func TestProviderSourceErrorsNeverReturnPartialData(t *testing.T) {
+ t.Parallel()
+ cutoff := time.Date(2026, 8, 19, 10, 0, 0, 0, time.UTC)
+ for name, provider := range map[string]*provider{
+ "events": NewProvider(&fakeEventStore{err: errors.New("db unavailable")}, &fakeAllocationClient{}, func() time.Time { return cutoff }),
+ "allocations": NewProvider(&fakeEventStore{events: []SandboxEvent{{EventID: mustUUID("00000000-0000-0000-0000-000000000002"), Namespace: "ns-a", SandboxName: "sandbox", SandboxUID: "uid", PoolName: "pool", Runtime: "kubevirt", VMName: "vm", EventType: "Added", ObservedAt: cutoff.Add(-48 * time.Hour)}}}, &fakeAllocationClient{err: errors.New("opencost unavailable")}, func() time.Time { return cutoff }),
+ } {
+ t.Run(name, func(t *testing.T) {
+ got, err := provider.Overview(context.Background(), Query{Subject: "alice", Timeframe: Timeframe24H})
+ if err == nil || got.Partial || len(got.Pools) != 0 {
+ t.Fatalf("overview = %#v, err = %v", got, err)
+ }
+ })
+ }
+}
+
+func mustUUID(raw string) uuid.UUID {
+ return uuid.MustParse(raw)
+}
+
+func TestProviderOverviewCoverageAndMatchingExclusionsArePartial(t *testing.T) {
+ t.Parallel()
+ cutoff := time.Date(2026, 8, 19, 10, 0, 0, 0, time.UTC)
+ base := func(vmName, uid, pool string, eventType string, observedAt time.Time) SandboxEvent {
+ return SandboxEvent{EventID: mustUUID(map[string]string{"uid-a": "00000000-0000-0000-0000-000000000010", "uid-b": "00000000-0000-0000-0000-000000000011"}[uid]), Namespace: "ns-a", SandboxName: uid, SandboxUID: uid, PoolName: pool, Runtime: "kubevirt", VMName: vmName, EventType: eventType, ObservedAt: observedAt}
+ }
+ allocation := Allocation{Start: cutoff.Add(-time.Hour), End: cutoff, Namespace: "ns-a", Pod: "virt-launcher-vm-a-suffix", Minutes: 60, CPUUsageAverage: 1, CPURequestAverage: 2, RAMUsageAverageBytes: gibibyte, RAMRequestAverageBytes: 2 * gibibyte}
+ for name, events := range map[string][]SandboxEvent{
+ "missing_projector_baseline": {base("vm-a", "uid-a", "pool-a", "Modified", cutoff.Add(-time.Hour))},
+ "ambiguous_launcher": {
+ base("vm-a", "uid-a", "pool-a", "Added", cutoff.Add(-25*time.Hour)),
+ base("vm-a", "uid-b", "pool-b", "Added", cutoff.Add(-25*time.Hour)),
+ },
+ } {
+ t.Run(name, func(t *testing.T) {
+ provider := NewProvider(&fakeEventStore{events: events}, &fakeAllocationClient{asOf: cutoff, allocations: []Allocation{allocation}}, func() time.Time { return cutoff })
+ got, err := provider.Overview(context.Background(), Query{Subject: "alice", Timeframe: Timeframe24H})
+ if err != nil || !got.Partial {
+ t.Fatalf("overview=%#v err=%v", got, err)
+ }
+ })
+ }
+}
+
+func TestProviderOverviewUsesLongestKubeVirtVMName(t *testing.T) {
+ t.Parallel()
+ cutoff := time.Date(2026, 8, 19, 10, 0, 0, 0, time.UTC)
+ events := []SandboxEvent{
+ {EventID: mustUUID("00000000-0000-0000-0000-000000000020"), Namespace: "ns-a", SandboxName: "short", SandboxUID: "short", PoolName: "short-pool", Runtime: "kubevirt", VMName: "vm", EventType: "Added", ObservedAt: cutoff.Add(-25 * time.Hour)},
+ {EventID: mustUUID("00000000-0000-0000-0000-000000000021"), Namespace: "ns-a", SandboxName: "long", SandboxUID: "long", PoolName: "long-pool", Runtime: "kubevirt", VMName: "vm-a", EventType: "Added", ObservedAt: cutoff.Add(-25 * time.Hour)},
+ }
+ allocation := Allocation{Start: cutoff.Add(-time.Hour), End: cutoff, Namespace: "ns-a", Pod: "virt-launcher-vm-a-nonempty", Minutes: 60, CPUUsageAverage: 1, CPURequestAverage: 1, RAMUsageAverageBytes: gibibyte, RAMRequestAverageBytes: gibibyte}
+ got, err := NewProvider(&fakeEventStore{events: events}, &fakeAllocationClient{asOf: cutoff, allocations: []Allocation{allocation}}, func() time.Time { return cutoff }).Overview(context.Background(), Query{Subject: "alice", Timeframe: Timeframe24H})
+ if err != nil || got.Partial || len(got.Pools) != 1 || got.Pools[0].ID != "ns-a:long-pool" {
+ t.Fatalf("overview=%#v err=%v", got, err)
+ }
+}
+
+func TestProviderPoolDetailBuildsDeterministicBuckets(t *testing.T) {
+ t.Parallel()
+ cutoff := time.Date(2026, 8, 19, 10, 0, 0, 0, time.UTC)
+ events := []SandboxEvent{{EventID: mustUUID("00000000-0000-0000-0000-000000000030"), Namespace: "ns-a", SandboxName: "sandbox", SandboxUID: "uid", PoolName: "pool-a", Runtime: "kubevirt", VMName: "vm", EventType: "Added", ObservedAt: cutoff.Add(-31 * 24 * time.Hour)}}
+ allocation := Allocation{Start: cutoff.Add(-24 * time.Hour), End: cutoff, Namespace: "ns-a", Pod: "virt-launcher-vm-a", Minutes: 24 * 60, CPUUsageAverage: 1, CPURequestAverage: 2, RAMUsageAverageBytes: gibibyte, RAMRequestAverageBytes: 2 * gibibyte}
+ provider := NewProvider(&fakeEventStore{events: events}, &fakeAllocationClient{asOf: cutoff, allocations: []Allocation{allocation}}, func() time.Time { return cutoff })
+ got, err := provider.PoolDetail(context.Background(), PoolQuery{Query: Query{Subject: "alice", Timeframe: Timeframe30D}, PoolID: "ns-a:pool-a", Interval: IntervalDay})
+ if err != nil || len(got.Buckets) != 30 || !got.Buckets[0].Start.Equal(cutoff.Add(-30*24*time.Hour)) || !got.Buckets[29].End.Equal(cutoff) {
+ t.Fatalf("detail=%#v err=%v", got, err)
+ }
+ last := got.Buckets[29]
+ if last.CPUConsumed != 24 || last.CPUProvisioned != 48 || last.MemoryConsumed != 24 || last.MemoryProvisioned != 48 {
+ t.Fatalf("last bucket=%#v", last)
+ }
+}
+
+func TestProviderMarksPartiallyUncoveredAllocationPartial(t *testing.T) {
+ t.Parallel()
+ cutoff := time.Date(2026, 8, 19, 10, 0, 0, 0, time.UTC)
+ event := SandboxEvent{EventID: mustUUID("00000000-0000-0000-0000-000000000040"), Namespace: "ns-a", SandboxName: "sandbox", SandboxUID: "uid", PoolName: "pool-a", Runtime: "kubevirt", VMName: "vm", EventType: "Added", ObservedAt: cutoff.Add(-30 * time.Minute)}
+ allocation := Allocation{Start: cutoff.Add(-time.Hour), End: cutoff, Namespace: "ns-a", Pod: "virt-launcher-vm-a", Minutes: 60, CPUUsageAverage: 1, CPURequestAverage: 1, RAMUsageAverageBytes: gibibyte, RAMRequestAverageBytes: gibibyte}
+ got, err := NewProvider(&fakeEventStore{events: []SandboxEvent{event}}, &fakeAllocationClient{asOf: cutoff, allocations: []Allocation{allocation}}, func() time.Time { return cutoff }).Overview(context.Background(), Query{Subject: "alice", Timeframe: Timeframe24H})
+ if err != nil || !got.Partial || len(got.Pools) != 1 || got.Pools[0].CPU.Consumed != 0.5 {
+ t.Fatalf("overview=%#v err=%v", got, err)
+ }
+}
+
+func TestProviderPropagatesAllocationCoverageCutoff(t *testing.T) {
+ t.Parallel()
+ cutoff := time.Date(2026, 8, 19, 10, 0, 0, 0, time.UTC)
+ asOf := cutoff.Add(-time.Hour)
+ event := SandboxEvent{EventID: mustUUID("00000000-0000-0000-0000-000000000060"), Namespace: "ns-a", SandboxName: "sandbox", SandboxUID: "uid", PoolName: "pool-a", Runtime: "kubevirt", VMName: "vm", EventType: "Added", ObservedAt: cutoff.Add(-48 * time.Hour)}
+ allocation := Allocation{Start: asOf.Add(-time.Hour), End: asOf, Namespace: "ns-a", Pod: "virt-launcher-vm-a", Minutes: 60, CPUUsageAverage: 1, CPURequestAverage: 2, RAMUsageAverageBytes: gibibyte, RAMRequestAverageBytes: 2 * gibibyte}
+ got, err := NewProvider(&fakeEventStore{events: []SandboxEvent{event}}, &fakeAllocationClient{asOf: asOf, allocations: []Allocation{allocation}}, func() time.Time { return cutoff }).Overview(context.Background(), Query{Subject: "alice", Timeframe: Timeframe24H})
+ if err != nil || !got.Partial || !got.DataAsOf.Equal(asOf) || len(got.Pools) != 1 {
+ t.Fatalf("overview=%#v err=%v", got, err)
+ }
+}
+
+func TestProviderPoolDetailRejectsPoolOutsideSubjectOverview(t *testing.T) {
+ t.Parallel()
+ cutoff := time.Date(2026, 8, 19, 10, 0, 0, 0, time.UTC)
+ event := SandboxEvent{EventID: mustUUID("00000000-0000-0000-0000-000000000061"), Namespace: "ns-a", SandboxName: "sandbox", SandboxUID: "uid", PoolName: "pool-a", Runtime: "kubevirt", VMName: "vm", EventType: "Added", ObservedAt: cutoff.Add(-48 * time.Hour)}
+ allocation := Allocation{Start: cutoff.Add(-time.Hour), End: cutoff, Namespace: "ns-a", Pod: "virt-launcher-vm-a", Minutes: 60, CPUUsageAverage: 1, CPURequestAverage: 1, RAMUsageAverageBytes: gibibyte, RAMRequestAverageBytes: gibibyte}
+ provider := NewProvider(&fakeEventStore{events: []SandboxEvent{event}}, &fakeAllocationClient{asOf: cutoff, allocations: []Allocation{allocation}}, func() time.Time { return cutoff })
+ _, err := provider.PoolDetail(context.Background(), PoolQuery{Query: Query{Subject: "alice", Timeframe: Timeframe24H}, PoolID: "ns-a:pool-missing", Interval: IntervalHour})
+ if !errors.Is(err, ErrPoolNotFound) {
+ t.Fatalf("err=%v, want ErrPoolNotFound", err)
+ }
+}
+
+func TestProviderOmitsZeroUsagePools(t *testing.T) {
+ t.Parallel()
+ cutoff := time.Date(2026, 8, 19, 10, 0, 0, 0, time.UTC)
+ event := SandboxEvent{EventID: mustUUID("00000000-0000-0000-0000-000000000062"), Namespace: "ns-a", SandboxName: "sandbox", SandboxUID: "uid", PoolName: "pool-a", Runtime: "kubevirt", VMName: "vm", EventType: "Added", ObservedAt: cutoff.Add(-48 * time.Hour)}
+ allocation := Allocation{Start: cutoff.Add(-time.Hour), End: cutoff, Namespace: "ns-a", Pod: "virt-launcher-vm-a", Minutes: 0, CPUUsageAverage: 0, CPURequestAverage: 0, RAMUsageAverageBytes: 0, RAMRequestAverageBytes: 0}
+ got, err := NewProvider(&fakeEventStore{events: []SandboxEvent{event}}, &fakeAllocationClient{asOf: cutoff, allocations: []Allocation{allocation}}, func() time.Time { return cutoff }).Overview(context.Background(), Query{Subject: "alice", Timeframe: Timeframe24H})
+ if err != nil || len(got.Pools) != 0 {
+ t.Fatalf("overview=%#v err=%v", got, err)
+ }
+}
+
+func TestProviderDisambiguatesDuplicatePoolDisplayNames(t *testing.T) {
+ t.Parallel()
+ cutoff := time.Date(2026, 8, 19, 10, 0, 0, 0, time.UTC)
+ events := []SandboxEvent{
+ {EventID: mustUUID("00000000-0000-0000-0000-000000000063"), Namespace: "ns-a", SandboxName: "sandbox-a", SandboxUID: "uid-a", PoolName: "pool", Runtime: "kubevirt", VMName: "vm-a", EventType: "Added", ObservedAt: cutoff.Add(-48 * time.Hour)},
+ {EventID: mustUUID("00000000-0000-0000-0000-000000000064"), Namespace: "ns-b", SandboxName: "sandbox-b", SandboxUID: "uid-b", PoolName: "pool", Runtime: "kubevirt", VMName: "vm-b", EventType: "Added", ObservedAt: cutoff.Add(-48 * time.Hour)},
+ }
+ allocations := []Allocation{
+ {Start: cutoff.Add(-time.Hour), End: cutoff, Namespace: "ns-a", Pod: "virt-launcher-vm-a-x", Minutes: 60, CPUUsageAverage: 1, CPURequestAverage: 1, RAMUsageAverageBytes: gibibyte, RAMRequestAverageBytes: gibibyte},
+ {Start: cutoff.Add(-time.Hour), End: cutoff, Namespace: "ns-b", Pod: "virt-launcher-vm-b-x", Minutes: 60, CPUUsageAverage: 1, CPURequestAverage: 1, RAMUsageAverageBytes: gibibyte, RAMRequestAverageBytes: gibibyte},
+ }
+ got, err := NewProvider(&fakeEventStore{events: events}, &fakeAllocationClient{asOf: cutoff, allocations: allocations}, func() time.Time { return cutoff }).Overview(context.Background(), Query{Subject: "alice", Timeframe: Timeframe24H})
+ if err != nil || len(got.Pools) != 2 || got.Pools[0].Name != "ns-a/pool" || got.Pools[1].Name != "ns-b/pool" {
+ t.Fatalf("overview=%#v err=%v", got, err)
+ }
+}
+
+func TestBuildSegmentsMarksInitialAndImpossibleEventSequencesPartial(t *testing.T) {
+ t.Parallel()
+ start := time.Date(2026, 8, 19, 9, 0, 0, 0, time.UTC)
+ base := func(eventID, eventType string, observedAt time.Time) SandboxEvent {
+ return SandboxEvent{EventID: mustUUID(eventID), Namespace: "ns-a", SandboxName: "sandbox", SandboxUID: "uid", PoolName: "pool-a", Runtime: "kubevirt", VMName: "vm", EventType: eventType, ObservedAt: observedAt}
+ }
+ for name, events := range map[string][]SandboxEvent{
+ "initial_added_in_window": {
+ base("00000000-0000-0000-0000-000000000065", "Added", start.Add(time.Minute)),
+ },
+ "modified_after_deleted": {
+ base("00000000-0000-0000-0000-000000000066", "Added", start.Add(-time.Hour)),
+ base("00000000-0000-0000-0000-000000000067", "Deleted", start.Add(time.Minute)),
+ base("00000000-0000-0000-0000-000000000068", "Modified", start.Add(2*time.Minute)),
+ },
+ "duplicate_added_while_active": {
+ base("00000000-0000-0000-0000-000000000069", "Added", start.Add(-time.Hour)),
+ base("00000000-0000-0000-0000-000000000070", "Added", start.Add(time.Minute)),
+ },
+ "equal_timestamp_ambiguity": {
+ base("00000000-0000-0000-0000-000000000071", "Added", start.Add(-time.Hour)),
+ base("00000000-0000-0000-0000-000000000072", "Modified", start.Add(time.Minute)),
+ base("00000000-0000-0000-0000-000000000073", "Deleted", start.Add(time.Minute)),
+ },
+ } {
+ t.Run(name, func(t *testing.T) {
+ _, _, partial := buildSegments(events, start, start.Add(time.Hour))
+ if !partial {
+ t.Fatal("expected partial event coverage")
+ }
+ })
+ }
+}
+
+func TestProviderOverviewAttributesPreWindowModifiedBaseline(t *testing.T) {
+ t.Parallel()
+ cutoff := time.Date(2026, 8, 19, 10, 0, 0, 0, time.UTC)
+ event := SandboxEvent{EventID: mustUUID("00000000-0000-0000-0000-000000000080"), Namespace: "ns-a", SandboxName: "sandbox", SandboxUID: "uid", PoolName: "pool-a", Runtime: "kubevirt", VMName: "vm", EventType: "Modified", ObservedAt: cutoff.Add(-48 * time.Hour)}
+ allocation := Allocation{Start: cutoff.Add(-time.Hour), End: cutoff, Namespace: "ns-a", Pod: "virt-launcher-vm-a", Minutes: 60, CPUUsageAverage: 1, CPURequestAverage: 2, RAMUsageAverageBytes: gibibyte, RAMRequestAverageBytes: 2 * gibibyte}
+ got, err := NewProvider(&fakeEventStore{events: []SandboxEvent{event}}, &fakeAllocationClient{asOf: cutoff, allocations: []Allocation{allocation}}, func() time.Time { return cutoff }).Overview(context.Background(), Query{Subject: "alice", Timeframe: Timeframe24H})
+ if err != nil || got.Partial || len(got.Pools) != 1 || got.Pools[0].CPU.Consumed != 1 || got.Pools[0].CPU.Provisioned != 2 {
+ t.Fatalf("overview=%#v err=%v", got, err)
+ }
+}
+
+func TestProviderExcludesUncertainTimelineRemainder(t *testing.T) {
+ t.Parallel()
+ cutoff := time.Date(2026, 8, 19, 10, 0, 0, 0, time.UTC)
+ start := cutoff.Add(-24 * time.Hour)
+ base := func(eventID, eventType string, observedAt time.Time) SandboxEvent {
+ return SandboxEvent{EventID: mustUUID(eventID), Namespace: "ns-a", SandboxName: "sandbox", SandboxUID: "uid", PoolName: "pool-a", Runtime: "kubevirt", VMName: "vm", EventType: eventType, ObservedAt: observedAt}
+ }
+ before := Allocation{Start: start, End: start.Add(time.Hour), Namespace: "ns-a", Pod: "virt-launcher-vm-a", Minutes: 60, CPUUsageAverage: 1, CPURequestAverage: 1, RAMUsageAverageBytes: gibibyte, RAMRequestAverageBytes: gibibyte}
+ after := Allocation{Start: start.Add(2 * time.Hour), End: start.Add(3 * time.Hour), Namespace: "ns-a", Pod: "virt-launcher-vm-a", Minutes: 60, CPUUsageAverage: 1, CPURequestAverage: 1, RAMUsageAverageBytes: gibibyte, RAMRequestAverageBytes: gibibyte}
+ for name, events := range map[string][]SandboxEvent{
+ "duplicate_added": {
+ base("00000000-0000-0000-0000-000000000081", "Added", start.Add(-time.Hour)),
+ base("00000000-0000-0000-0000-000000000082", "Added", start.Add(time.Hour)),
+ },
+ "unknown_event": {
+ base("00000000-0000-0000-0000-000000000083", "Added", start.Add(-time.Hour)),
+ base("00000000-0000-0000-0000-000000000084", "Unexpected", start.Add(time.Hour)),
+ },
+ "equal_timestamp": {
+ base("00000000-0000-0000-0000-000000000085", "Added", start.Add(-time.Hour)),
+ base("00000000-0000-0000-0000-000000000086", "Modified", start.Add(time.Hour)),
+ base("00000000-0000-0000-0000-000000000087", "Deleted", start.Add(time.Hour)),
+ },
+ "modified_after_deleted": {
+ base("00000000-0000-0000-0000-000000000088", "Added", start.Add(-time.Hour)),
+ base("00000000-0000-0000-0000-000000000089", "Deleted", start.Add(time.Hour)),
+ base("00000000-0000-0000-0000-000000000090", "Modified", start.Add(2*time.Hour)),
+ },
+ "deleted_while_inactive": {
+ base("00000000-0000-0000-0000-000000000091", "Added", start.Add(-time.Hour)),
+ base("00000000-0000-0000-0000-000000000092", "Deleted", start.Add(time.Hour)),
+ base("00000000-0000-0000-0000-000000000093", "Deleted", start.Add(2*time.Hour)),
+ },
+ } {
+ t.Run(name, func(t *testing.T) {
+ got, err := NewProvider(&fakeEventStore{events: events}, &fakeAllocationClient{asOf: cutoff, allocations: []Allocation{before, after}}, func() time.Time { return cutoff }).Overview(context.Background(), Query{Subject: "alice", Timeframe: Timeframe24H})
+ if err != nil || !got.Partial || len(got.Pools) != 1 || got.Pools[0].CPU.Consumed != 1 {
+ t.Fatalf("overview=%#v err=%v", got, err)
+ }
+ })
+ }
+}
+
+func TestProviderPoolDetailPreservesRequestedWindowWhenOpenCostIsStale(t *testing.T) {
+ t.Parallel()
+ cutoff := time.Date(2026, 8, 19, 10, 0, 0, 0, time.UTC)
+ for name, test := range map[string]struct {
+ timeframe Timeframe
+ interval Interval
+ asOf time.Time
+ start time.Time
+ count int
+ }{
+ "24h": {Timeframe24H, IntervalHour, cutoff.Add(-time.Hour), cutoff.Add(-2 * time.Hour), 24},
+ "7d": {Timeframe7D, IntervalHour, cutoff.Add(-time.Hour), cutoff.Add(-2 * time.Hour), 7 * 24},
+ "30d": {Timeframe30D, IntervalDay, cutoff.Add(-24 * time.Hour), cutoff.Add(-48 * time.Hour), 30},
+ } {
+ t.Run(name, func(t *testing.T) {
+ event := SandboxEvent{EventID: mustUUID("00000000-0000-0000-0000-000000000094"), Namespace: "ns-a", SandboxName: "sandbox", SandboxUID: "uid", PoolName: "pool-a", Runtime: "kubevirt", VMName: "vm", EventType: "Added", ObservedAt: cutoff.Add(-31 * 24 * time.Hour)}
+ allocation := Allocation{Start: test.start, End: test.asOf, Namespace: "ns-a", Pod: "virt-launcher-vm-a", Minutes: test.asOf.Sub(test.start).Minutes(), CPUUsageAverage: 1, CPURequestAverage: 1, RAMUsageAverageBytes: gibibyte, RAMRequestAverageBytes: gibibyte}
+ client := &fakeAllocationClient{asOf: test.asOf, allocations: []Allocation{allocation}}
+ got, err := NewProvider(&fakeEventStore{events: []SandboxEvent{event}}, client, func() time.Time { return cutoff }).PoolDetail(context.Background(), PoolQuery{Query: Query{Subject: "alice", Timeframe: test.timeframe}, PoolID: "ns-a:pool-a", Interval: test.interval})
+ if err != nil || !got.Partial || !got.DataAsOf.Equal(test.asOf) || len(got.Buckets) != test.count || !got.Buckets[0].Start.Equal(cutoff.Add(-durationForTimeframe(test.timeframe))) || !got.Buckets[len(got.Buckets)-1].End.Equal(cutoff) {
+ t.Fatalf("detail=%#v err=%v", got, err)
+ }
+ if !client.start.Equal(cutoff.Add(-durationForTimeframe(test.timeframe))) || !client.end.Equal(cutoff) {
+ t.Fatalf("allocation query=[%s,%s)", client.start, client.end)
+ }
+ })
+ }
+}
+
+func TestParsePoolIDMatchesDNSLabelPoolContract(t *testing.T) {
+ t.Parallel()
+ for _, id := range []string{"ns-a:pool-a", "ns-a:pool:extra", "ns-a:Pool", "ns-a:pool_", "ns-a:", "ns-a:" + strings.Repeat("a", 64)} {
+ _, _, ok := parsePoolID(id)
+ want := id == "ns-a:pool-a"
+ if ok != want {
+ t.Fatalf("parsePoolID(%q) ok=%t, want %t", id, ok, want)
+ }
+ }
+}
+
+func durationForTimeframe(timeframe Timeframe) time.Duration {
+ switch timeframe {
+ case Timeframe24H:
+ return 24 * time.Hour
+ case Timeframe7D:
+ return 7 * 24 * time.Hour
+ case Timeframe30D:
+ return 30 * 24 * time.Hour
+ default:
+ panic("unsupported timeframe")
+ }
+}
+
+func TestProviderRestoresAttributionAfterUnambiguousAdded(t *testing.T) {
+ t.Parallel()
+ cutoff := time.Date(2026, 8, 19, 10, 0, 0, 0, time.UTC)
+ start := cutoff.Add(-24 * time.Hour)
+ base := func(eventID, eventType string, observedAt time.Time) SandboxEvent {
+ return SandboxEvent{EventID: mustUUID(eventID), Namespace: "ns-a", SandboxName: "sandbox", SandboxUID: "uid", PoolName: "pool-a", Runtime: "kubevirt", VMName: "vm", EventType: eventType, ObservedAt: observedAt}
+ }
+ events := []SandboxEvent{
+ base("00000000-0000-0000-0000-000000000095", "Added", start.Add(-time.Hour)),
+ base("00000000-0000-0000-0000-000000000096", "Unexpected", start.Add(time.Hour)),
+ base("00000000-0000-0000-0000-000000000097", "Added", start.Add(2*time.Hour)),
+ }
+ before := Allocation{Start: start, End: start.Add(time.Hour), Namespace: "ns-a", Pod: "virt-launcher-vm-a", Minutes: 60, CPUUsageAverage: 1, CPURequestAverage: 1, RAMUsageAverageBytes: gibibyte, RAMRequestAverageBytes: gibibyte}
+ after := Allocation{Start: start.Add(3 * time.Hour), End: start.Add(4 * time.Hour), Namespace: "ns-a", Pod: "virt-launcher-vm-a", Minutes: 60, CPUUsageAverage: 1, CPURequestAverage: 1, RAMUsageAverageBytes: gibibyte, RAMRequestAverageBytes: gibibyte}
+ got, err := NewProvider(&fakeEventStore{events: events}, &fakeAllocationClient{asOf: cutoff, allocations: []Allocation{before, after}}, func() time.Time { return cutoff }).Overview(context.Background(), Query{Subject: "alice", Timeframe: Timeframe24H})
+ if err != nil || !got.Partial || len(got.Pools) != 1 || got.Pools[0].CPU.Consumed != 2 {
+ t.Fatalf("overview=%#v err=%v", got, err)
+ }
+}
diff --git a/libs/fleet/backend/usage/safe_error.go b/libs/fleet/backend/usage/safe_error.go
new file mode 100644
index 0000000000..afd7566d00
--- /dev/null
+++ b/libs/fleet/backend/usage/safe_error.go
@@ -0,0 +1,17 @@
+package usage
+
+type sanitizedError struct {
+ message string
+ cause error
+}
+
+func (err *sanitizedError) Error() string { return err.message }
+
+func (err *sanitizedError) Unwrap() error { return err.cause }
+
+func newSanitizedError(message string, cause error) error {
+ if cause == nil {
+ return nil
+ }
+ return &sanitizedError{message: message, cause: cause}
+}
diff --git a/libs/fleet/backend/usage/safe_error_test.go b/libs/fleet/backend/usage/safe_error_test.go
new file mode 100644
index 0000000000..2b944197e2
--- /dev/null
+++ b/libs/fleet/backend/usage/safe_error_test.go
@@ -0,0 +1,17 @@
+package usage
+
+import (
+ "errors"
+ "testing"
+)
+
+func TestNewSanitizedErrorRedactsAndPreservesCause(t *testing.T) {
+ cause := errors.New("secret upstream detail")
+ err := newSanitizedError("invalid OpenCost URL", cause)
+ if err.Error() != "invalid OpenCost URL" {
+ t.Fatalf("Error() = %q", err.Error())
+ }
+ if !errors.Is(err, cause) {
+ t.Fatal("sanitized error lost cause identity")
+ }
+}
diff --git a/libs/fleet/backend/usage/types.go b/libs/fleet/backend/usage/types.go
new file mode 100644
index 0000000000..48f95630a4
--- /dev/null
+++ b/libs/fleet/backend/usage/types.go
@@ -0,0 +1,112 @@
+package usage
+
+import (
+ "context"
+ "time"
+
+ "github.com/google/uuid"
+)
+
+type Timeframe string
+type Interval string
+
+const (
+ Timeframe24H Timeframe = "24h"
+ Timeframe7D Timeframe = "7d"
+ Timeframe30D Timeframe = "30d"
+
+ IntervalHour Interval = "1h"
+ IntervalDay Interval = "1d"
+)
+
+type Query struct {
+ ActorSubject string
+ Subject string
+ Admin bool
+ Timeframe Timeframe
+}
+
+type PoolQuery struct {
+ Query
+ PoolID string
+ Interval Interval
+}
+
+type MetricTotals struct {
+ Consumed float64 `json:"consumed"`
+ Provisioned float64 `json:"provisioned"`
+}
+
+type PoolSummary struct {
+ ID string `json:"id"`
+ Name string `json:"name"`
+ CPU MetricTotals `json:"cpu"`
+ Memory MetricTotals `json:"memory"`
+}
+
+type OverviewResponse struct {
+ DataAsOf time.Time `json:"data_as_of"`
+ Partial bool `json:"partial"`
+ Pools []PoolSummary `json:"pools"`
+}
+
+type PoolIdentity struct {
+ ID string `json:"id"`
+ Name string `json:"name"`
+}
+
+type Bucket struct {
+ Start time.Time `json:"start"`
+ End time.Time `json:"end"`
+ CPUConsumed float64 `json:"cpu_consumed"`
+ CPUProvisioned float64 `json:"cpu_provisioned"`
+ MemoryConsumed float64 `json:"memory_consumed"`
+ MemoryProvisioned float64 `json:"memory_provisioned"`
+}
+
+type PoolDetailResponse struct {
+ DataAsOf time.Time `json:"data_as_of"`
+ Partial bool `json:"partial"`
+ Pool PoolIdentity `json:"pool"`
+ Buckets []Bucket `json:"buckets"`
+}
+
+type Provider interface {
+ Overview(context.Context, Query) (OverviewResponse, error)
+ PoolDetail(context.Context, PoolQuery) (PoolDetailResponse, error)
+}
+
+type SandboxEvent struct {
+ EventID uuid.UUID
+ Namespace string
+ SandboxName string
+ SandboxUID string
+ PoolName string
+ Runtime string
+ VMName string
+ EventType string
+ ObservedAt time.Time
+}
+
+type EventStore interface {
+ // Events returns database event order; equal observed timestamps remain partial.
+ Events(context.Context, string, time.Time, time.Time) ([]SandboxEvent, error)
+}
+
+type Allocation struct {
+ Start time.Time
+ End time.Time
+ Namespace string
+ Pod string
+ Minutes float64
+ CPUUsageAverage float64
+ CPURequestAverage float64
+ RAMUsageAverageBytes float64
+ RAMRequestAverageBytes float64
+}
+
+type AllocationClient interface {
+ Allocations(context.Context, time.Time, time.Time, time.Duration, []string) ([]Allocation, time.Time, bool, error)
+}
+
+const gibibyte = float64(1 << 30)
diff --git a/libs/fleet/e2e/fixtures/mock-api.ts b/libs/fleet/e2e/fixtures/mock-api.ts
index 3e5f6da7a1..1429e922c2 100644
--- a/libs/fleet/e2e/fixtures/mock-api.ts
+++ b/libs/fleet/e2e/fixtures/mock-api.ts
@@ -55,6 +55,7 @@ export interface MockFeatureFlags {
admin?: boolean
billing?: boolean
chat?: boolean
+ usage?: boolean
}
export interface MockAuthOptions {
@@ -166,6 +167,7 @@ export async function mockAuth(
admin: flags.admin ?? false,
billing: flags.billing ?? false,
chat: flags.chat ?? false,
+ usage: flags.usage ?? false,
}),
})
})
diff --git a/libs/fleet/e2e/usage.spec.ts b/libs/fleet/e2e/usage.spec.ts
new file mode 100644
index 0000000000..b6231430e8
--- /dev/null
+++ b/libs/fleet/e2e/usage.spec.ts
@@ -0,0 +1,115 @@
+import { expect, test, type Page } from "@playwright/test"
+import { mockAuth, type MockFeatureFlags } from "./fixtures/mock-api"
+import { expectSharedPageShell } from "./fixtures/shell-geometry"
+const overview = {
+ data_as_of: "2026-08-13T10:00:00Z",
+ partial: true,
+ pools: [
+ {
+ id: "ns-a:pool-a",
+ name: "Pool A",
+ cpu: { consumed: 12, provisioned: 24 },
+ memory: { consumed: 48, provisioned: 96 },
+ },
+ {
+ id: "ns-b:pool-b",
+ name: "Pool B",
+ cpu: { consumed: 6, provisioned: 12 },
+ memory: { consumed: 20, provisioned: 40 },
+ },
+ ],
+}
+const detail = {
+ data_as_of: "2026-08-13T10:00:00Z",
+ partial: false,
+ pool: { id: "ns-b:pool-b", name: "Pool B" },
+ buckets: [
+ {
+ start: "2026-08-13T08:00:00Z",
+ end: "2026-08-13T09:00:00Z",
+ cpu_consumed: 0.5,
+ cpu_provisioned: 1,
+ memory_consumed: 2,
+ memory_provisioned: 4,
+ },
+ ],
+}
+async function mockUsage(
+ p: Page,
+ flags: MockFeatureFlags = { admin: false, usage: true },
+) {
+ await mockAuth(p, flags)
+ await p.route("**/api/usage/overview**", (r) => r.fulfill({ json: overview }))
+ await p.route("**/api/usage/pool**", (r) => r.fulfill({ json: detail }))
+}
+test("usage navigation is feature flagged", async ({ page }) => {
+ await mockUsage(page, { admin: false, usage: false })
+ await page.goto("/pools")
+ await expect(page.getByRole("link", { name: "Usage" })).toHaveCount(0)
+ await page.goto("/usage")
+ await expect(page).toHaveURL(/\/pools$/)
+})
+test("renders usage totals and forwards opaque pool IDs to drilldown", async ({
+ page,
+}) => {
+ await mockUsage(page)
+ await page.goto("/usage")
+ await expect(page).toHaveTitle("Usage · Cua")
+ await expectSharedPageShell(page)
+ await expect(
+ page.getByRole("heading", { name: "Usage preview" }),
+ ).toBeVisible()
+ await expect(
+ page.getByText("Pool A: 12 consumed, 24 provisioned, 50% utilization"),
+ ).toBeVisible()
+ await expect(
+ page.getByText(
+ "Consumed values use measured usage; provisioned values use Kubernetes requests observed by OpenCost, grouped by pool for the selected timeframe.",
+ ),
+ ).toBeVisible()
+ await page.getByRole("button", { name: "Memory" }).click()
+ await page.getByLabel("Pool drilldown").click()
+ const poolRequest = page.waitForRequest((request) => {
+ const url = new URL(request.url())
+ return (
+ url.pathname === "/api/usage/pool" &&
+ url.searchParams.get("pool") === "ns-b:pool-b"
+ )
+ })
+ await page.getByRole("option", { name: "Pool B" }).click()
+ expect((await poolRequest).url()).toContain("pool=ns-b%3Apool-b")
+ await expect(
+ page.getByRole("heading", { name: "CPU core-hours per bucket" }),
+ ).toBeVisible()
+ await expect(
+ page.getByRole("heading", { name: "Memory GiB-hours per bucket" }),
+ ).toBeVisible()
+})
+test("admin view-as persists", async ({ page }) => {
+ await mockUsage(page, { admin: true, usage: true })
+ await page.goto("/usage")
+ await page.getByLabel("View usage for subject").fill("customer")
+ await page.getByRole("button", { name: "View usage" }).click()
+ await expect(page).toHaveURL(/subject=customer/)
+ await expect(page.getByText("Viewing usage for customer")).toBeVisible()
+})
+test("shows loading empty error and stale states", async ({ page }) => {
+ await mockAuth(page, { admin: false, usage: true })
+ let releaseOverview!: () => void
+ const overviewBlocked = new Promise<void>((resolve) => {
+ releaseOverview = resolve
+ })
+ await page.route("**/api/usage/overview**", async (r) => {
+ await overviewBlocked
+ await r.fulfill({
+ json: { data_as_of: "2026-08-10T00:00:00Z", partial: false, pools: [] },
+ })
+ })
+ await page.goto("/usage")
+ await expect(page.getByText("Loading usage data")).toBeVisible()
+ releaseOverview()
+ await expect(
+ page.getByText("No usage data is available for this timeframe."),
+ ).toBeVisible()
+ await expect(page.getByText("Usage data may be stale")).toBeVisible()
+})
diff --git a/libs/fleet/nginx.conf b/libs/fleet/nginx.conf
index ebc52bcbc1..a2aa347e65 100644
--- a/libs/fleet/nginx.conf
+++ b/libs/fleet/nginx.conf
@@ -150,7 +150,7 @@ server {
proxy_set_header X-Forwarded-Proto $scheme;
}
- location ~ ^/api/(keys|user-keys|github-trust-policies|gateway|k8s|swagger|batch|label|namespaces|config|chat|billing|state)(/|$) {
+ location ~ ^/api/(keys|user-keys|github-trust-policies|gateway|k8s|swagger|batch|label|namespaces|config|chat|billing|state|usage)(/|$) {
proxy_pass ${CYCLOPS_CS_BACKEND};
proxy_http_version 1.1;
proxy_set_header Host $host;
diff --git a/libs/fleet/src/App.tsx b/libs/fleet/src/App.tsx
index e0a1332bf9..02e5a02f6a 100644
--- a/libs/fleet/src/App.tsx
+++ b/libs/fleet/src/App.tsx
@@ -22,6 +22,7 @@ import { PoolNew } from "./pages/PoolNew"
import { UserApiKeys } from "./pages/UserApiKeys"
import { Settings } from "./pages/Settings"
import { AgentChat } from "./pages/AgentChat"
+import { Usage } from "./pages/Usage"
import { PageShell } from "./components/PageShell"
import { FeatureFlagProvider, useFeatureFlags } from "./components/FeatureFlagContext"
import { FlashContext, type FlashMsg } from "./components/FlashContext"
@@ -108,11 +109,13 @@ function Shell() {
setNavigationOpen(tabletOrWider)
}, [tabletOrWider])
const user = userInfo()
- const { chat } = useFeatureFlags()
+ const { chat, usage } = useFeatureFlags()
useEffect(() => {
const path = location.pathname
- const pageTitle = path === "/agent"
- ? "Chat"
+ const pageTitle = path === "/usage"
+ ? "Usage"
+ : path === "/agent"
+ ? "Chat"
: path === "/user-keys"
? "User API keys"
: path === "/settings"
@@ -194,6 +197,9 @@ function Shell() {
}}
items={[
{ type: "link", text: "Pools", href: "#/pools" },
+ ...(usage
+ ? [{ type: "link" as const, text: "Usage", href: "#/usage" }]
+ : []),
...(chat
? [{ type: "link" as const, text: "Chat", href: "#/agent" }]
: []),
@@ -252,6 +258,7 @@ export function App() {
<Route path="/pools/:namespace/:name" element={<PoolDetail />} />
<Route path="/user-keys" element={<UserApiKeys />} />
<Route path="/settings" element={<Settings />} />
+ <Route path="/usage" element={<UsageRoute />} />
<Route path="/agent" element={<ChatRoute />} />
<Route path="/billing" element={<Navigate to="/settings" replace />} />
<Route
@@ -288,3 +295,15 @@ function ChatRoute() {
}
return chat ? <AgentChat /> : <Navigate to="/pools" replace />
}
+
+function UsageRoute() {
+ const { usage, resolved } = useFeatureFlags()
+ if (!resolved) {
+ return (
+ <PageShell eyebrow="Resources" title="Usage preview">
+ <div />
+ </PageShell>
+ )
+ }
+ return usage ? <Usage /> : <Navigate to="/pools" replace />
+}
diff --git a/libs/fleet/src/components/FeatureFlagContext.tsx b/libs/fleet/src/components/FeatureFlagContext.tsx
index d297abe487..874f8e96a9 100644
--- a/libs/fleet/src/components/FeatureFlagContext.tsx
+++ b/libs/fleet/src/components/FeatureFlagContext.tsx
@@ -2,7 +2,7 @@ import { createContext, useContext, useEffect, useState, type ReactNode } from "
import { fetchFeatureFlags, type FeatureFlags } from "../sdk/featureFlags"
import { isLocalVisualPreview } from "../local-visual-preview"
-const DEFAULT_FLAGS: FeatureFlags = { admin: false, billing: false, chat: false }
+const DEFAULT_FLAGS: FeatureFlags = { admin: false, billing: false, chat: false, usage: false }
interface FeatureFlagContextValue extends FeatureFlags {
resolved: boolean
diff --git a/libs/fleet/src/pages/Usage.tsx b/libs/fleet/src/pages/Usage.tsx
new file mode 100644
index 0000000000..be14c0b2ef
--- /dev/null
+++ b/libs/fleet/src/pages/Usage.tsx
@@ -0,0 +1,352 @@
+import Alert from "@cloudscape-design/components/alert"
+import BarChart from "@cloudscape-design/components/bar-chart"
+import Box from "@cloudscape-design/components/box"
+import Button from "@cloudscape-design/components/button"
+import Container from "@cloudscape-design/components/container"
+import FormField from "@cloudscape-design/components/form-field"
+import Header from "@cloudscape-design/components/header"
+import Input from "@cloudscape-design/components/input"
+import LineChart from "@cloudscape-design/components/line-chart"
+import SegmentedControl from "@cloudscape-design/components/segmented-control"
+import Select from "@cloudscape-design/components/select"
+import SpaceBetween from "@cloudscape-design/components/space-between"
+import Spinner from "@cloudscape-design/components/spinner"
+import StatusIndicator from "@cloudscape-design/components/status-indicator"
+import { useEffect, useMemo, useState } from "react"
+import { useSearchParams } from "react-router-dom"
+import { useFeatureFlags } from "../components/FeatureFlagContext"
+import { PageShell } from "../components/PageShell"
+import {
+ usageApi,
+ type UsageOverviewResponse,
+ type UsagePoolDetailResponse,
+ type UsageTimeframe,
+} from "../sdk/usage"
+type Metric = "cpu" | "memory"
+const opts = [
+ { id: "24h", text: "24 hours" },
+ { id: "7d", text: "7 days" },
+ { id: "30d", text: "30 days" },
+]
+const i18n = {
+ filterLabel: "Filter displayed data",
+ filterPlaceholder: "Filter data",
+ filterSelectedAriaLabel: "selected",
+ detailPopoverDismissAriaLabel: "Dismiss",
+ legendAriaLabel: "Legend",
+ chartAriaRoleDescription: "chart",
+}
+const util = (c: number, p: number) => (p > 0 ? Math.round((c / p) * 100) : 0)
+const stale = (d: string, t: UsageTimeframe) =>
+ Date.now() - new Date(d).getTime() > (t === "24h" ? 3 : 30) * 3600000
+export function Usage() {
+ const { admin } = useFeatureFlags()
+ const [sp, setSp] = useSearchParams()
+ const raw = sp.get("timeframe")
+ const timeframe: UsageTimeframe = raw === "7d" || raw === "30d" ? raw : "24h"
+ const subject = sp.get("subject") ?? ""
+ const [input, setInput] = useState(subject)
+ const [metric, setMetric] = useState<Metric>("cpu")
+ const [overview, setOverview] = useState<UsageOverviewResponse | null>(null)
+ const [detail, setDetail] = useState<UsagePoolDetailResponse | null>(null)
+ const [pool, setPool] = useState<string | null>(null)
+ const [loading, setLoading] = useState(true)
+ const [detailLoading, setDetailLoading] = useState(false)
+ const [error, setError] = useState<string | null>(null)
+ useEffect(() => {
+ let active = true
+ setLoading(true)
+ setError(null)
+ usageApi
+ .overview(timeframe, subject || undefined)
+ .then((v) => {
+ if (active) {
+ setOverview(v)
+ setPool((p) =>
+ v.pools.some((x) => x.id === p) ? p : (v.pools[0]?.id ?? null),
+ )
+ }
+ })
+ .catch((e) => {
+ if (active) {
+ setOverview(null)
+ setPool(null)
+ setError(e instanceof Error ? e.message : "Usage data is unavailable")
+ }
+ })
+ .finally(() => {
+ if (active) setLoading(false)
+ })
+ return () => {
+ active = false
+ }
+ }, [timeframe, subject])
+ useEffect(() => {
+ if (!pool) {
+ setDetail(null)
+ return
+ }
+ let active = true
+ setDetailLoading(true)
+ usageApi
+ .pool(timeframe, pool, subject || undefined)
+ .then((v) => {
+ if (active) setDetail(v)
+ })
+ .catch((e) => {
+ if (active)
+ setError(e instanceof Error ? e.message : "Pool usage is unavailable")
+ })
+ .finally(() => {
+ if (active) setDetailLoading(false)
+ })
+ return () => {
+ active = false
+ }
+ }, [timeframe, subject, pool])
+ const series = useMemo(
+ () => [
+ {
+ title: "Consumed",
+ type: "bar" as const,
+ color: "#0972d3",
+ data: (overview?.pools ?? []).map((p) => ({
+ x: p.name,
+ y: p[metric].consumed,
+ })),
+ },
+ {
+ title: "Provisioned capacity",
+ type: "bar" as const,
+ color: "#9dc7ea",
+ data: (overview?.pools ?? []).map((p) => ({
+ x: p.name,
+ y: p[metric].provisioned,
+ })),
+ },
+ ],
+ [overview, metric],
+ )
+ const selected = overview?.pools.find((p) => p.id === pool)
+ const unit = metric === "cpu" ? "CPU core-hours" : "Memory GiB-hours"
+ const changeTime = (v: UsageTimeframe) => {
+ const n = new URLSearchParams(sp)
+ n.set("timeframe", v)
+ setSp(n)
+ }
+ const view = () => {
+ const n = new URLSearchParams(sp),
+ v = input.trim()
+ v ? n.set("subject", v) : n.delete("subject")
+ setSp(n)
+ }
+ return (
+ <PageShell
+ eyebrow="Resources"
+ title="Usage preview"
+ description="Preview resource consumption and provisioned capacity. No pricing or payment data is shown."
+ actions={
+ <SegmentedControl
+ selectedId={timeframe}
+ onChange={(e) => changeTime(e.detail.selectedId as UsageTimeframe)}
+ options={opts}
+ label="Usage timeframe"
+ />
+ }
+ >
+ <SpaceBetween size="l">
+ {admin && (
+ <Container header={<Header variant="h2">Administrator view</Header>}>
+ <SpaceBetween size="s">
+ <FormField
+ label="View usage for subject"
+ description="The signed-in administrator remains the real actor; this selection only scopes usage reads."
+ >
+ <SpaceBetween direction="horizontal" size="xs">
+ <Input
+ value={input}
+ onChange={(e) => setInput(e.detail.value)}
+ />
+ <Button onClick={view}>View usage</Button>
+ </SpaceBetween>
+ </FormField>
+ {subject && (
+ <Alert type="info">Viewing usage for {subject}</Alert>
+ )}
+ </SpaceBetween>
+ </Container>
+ )}
+ {loading && (
+ <Box textAlign="center">
+ <Spinner /> Loading usage data
+ </Box>
+ )}
+ {error && (
+ <Alert type="error" header="Usage data is unavailable">
+ {error}
+ </Alert>
+ )}
+ {!loading && overview && (
+ <SpaceBetween size="l">
+ <Container
+ header={
+ <Header
+ variant="h2"
+ description="Consumed values use measured usage; provisioned values use Kubernetes requests observed by OpenCost, grouped by pool for the selected timeframe."
+ >
+ Overview
+ </Header>
+ }
+ >
+ <SpaceBetween size="m">
+ <SegmentedControl
+ selectedId={metric}
+ onChange={(e) => setMetric(e.detail.selectedId as Metric)}
+ options={[
+ { id: "cpu", text: "CPU" },
+ { id: "memory", text: "Memory" },
+ ]}
+ label="Usage metric"
+ />
+ <Box variant="h3">{unit}</Box>
+ {overview.partial && (
+ <StatusIndicator type="warning">
+ Data is partial
+ </StatusIndicator>
+ )}
+ {stale(overview.data_as_of, timeframe) && (
+ <StatusIndicator type="warning">
+ Usage data may be stale
+ </StatusIndicator>
+ )}
+ <Box color="text-body-secondary">
+ Data as of {new Date(overview.data_as_of).toLocaleString()}
+ </Box>
+ {overview.pools.length === 0 ? (
+ <Box textAlign="center" color="text-body-secondary">
+ No usage data is available for this timeframe.
+ </Box>
+ ) : (
+ <>
+ <BarChart
+ series={series}
+ xScaleType="categorical"
+ xDomain={overview.pools.map((p) => p.name)}
+ yTitle={unit}
+ ariaLabel={`Usage overview in ${unit}`}
+ ariaDescription="Each pool has separately labeled consumed and provisioned capacity bars."
+ i18nStrings={i18n}
+ hideFilter
+ />
+ {overview.pools.map((p) => {
+ const v = p[metric]
+ return (
+ <Box key={p.id} color="text-body-secondary">
+ {p.name}: {v.consumed} consumed, {v.provisioned}{" "}
+ provisioned, {util(v.consumed, v.provisioned)}%
+ utilization
+ </Box>
+ )
+ })}
+ </>
+ )}
+ </SpaceBetween>
+ </Container>
+ {overview.pools.length > 0 && (
+ <Container
+ header={
+ <Header variant="h2">
+ {selected?.name ?? "Pool"} drilldown
+ </Header>
+ }
+ >
+ <SpaceBetween size="l">
+ <FormField label="Pool drilldown">
+ <Select
+ selectedOption={
+ selected
+ ? { label: selected.name, value: selected.id }
+ : null
+ }
+ onChange={(e) =>
+ setPool(e.detail.selectedOption.value ?? null)
+ }
+ options={overview.pools.map((p) => ({
+ label: p.name,
+ value: p.id,
+ }))}
+ />
+ </FormField>
+ {detailLoading && (
+ <Box>
+ <Spinner /> Loading pool usage
+ </Box>
+ )}
+ {detail && !detailLoading && (
+ <>
+ <UsageLine
+ title="CPU core-hours per bucket"
+ consumed={detail.buckets.map((b) => ({
+ x: new Date(b.start),
+ y: b.cpu_consumed,
+ }))}
+ provisioned={detail.buckets.map((b) => ({
+ x: new Date(b.start),
+ y: b.cpu_provisioned,
+ }))}
+ />
+ <UsageLine
+ title="Memory GiB-hours per bucket"
+ consumed={detail.buckets.map((b) => ({
+ x: new Date(b.start),
+ y: b.memory_consumed,
+ }))}
+ provisioned={detail.buckets.map((b) => ({
+ x: new Date(b.start),
+ y: b.memory_provisioned,
+ }))}
+ />
+ </>
+ )}
+ </SpaceBetween>
+ </Container>
+ )}
+ </SpaceBetween>
+ )}
+ </SpaceBetween>
+ </PageShell>
+ )
+}
+function UsageLine({
+ title,
+ consumed,
+ provisioned,
+}: {
+ title: string
+ consumed: { x: Date; y: number }[]
+ provisioned: { x: Date; y: number }[]
+}) {
+ return (
+ <SpaceBetween size="s">
+ <Box variant="h3">{title}</Box>
+ <LineChart
+ series={[
+ { title: "Consumed", type: "line", color: "#0972d3", data: consumed },
+ {
+ title: "Provisioned capacity",
+ type: "line",
+ color: "#9dc7ea",
+ data: provisioned,
+ },
+ ]}
+ xScaleType="time"
+ xTitle="Bucket start"
+ yTitle={title}
+ ariaLabel={title}
+ ariaDescription="Consumed values use measured usage; provisioned values use Kubernetes requests observed by OpenCost."
+ i18nStrings={i18n}
+ hideFilter
+ />
+ </SpaceBetween>
+ )
+}
diff --git a/libs/fleet/src/sdk/featureFlags.ts b/libs/fleet/src/sdk/featureFlags.ts
index 57911d2368..697d21479c 100644
--- a/libs/fleet/src/sdk/featureFlags.ts
+++ b/libs/fleet/src/sdk/featureFlags.ts
@@ -14,12 +14,15 @@ export interface FeatureFlags {
billing: boolean
/** Chat users can access persisted browser-bash conversations. */
chat: boolean
+ /** Internal users can access the preview usage dashboard. */
+ usage: boolean
}
const DEFAULT_FLAGS: FeatureFlags = {
admin: false,
billing: false,
chat: false,
+ usage: false,
}
let _cache: FeatureFlags | null = null
@@ -44,6 +47,7 @@ export async function fetchFeatureFlags(): Promise<FeatureFlags> {
admin: data.admin ?? false,
billing: data.billing ?? false,
chat: data.chat ?? false,
+ usage: data.usage ?? false,
}
return _cache
} catch {
diff --git a/libs/fleet/src/sdk/usage.ts b/libs/fleet/src/sdk/usage.ts
new file mode 100644
index 0000000000..b1c12d40fd
--- /dev/null
+++ b/libs/fleet/src/sdk/usage.ts
@@ -0,0 +1,10 @@
+import { getToken } from "../auth/keycloak"
+export type UsageTimeframe="24h"|"7d"|"30d"
+export interface UsageMetricTotals{consumed:number;provisioned:number}
+export interface UsagePoolSummary{id:string;name:string;cpu:UsageMetricTotals;memory:UsageMetricTotals}
+export interface UsageOverviewResponse{data_as_of:string;partial:boolean;pools:UsagePoolSummary[]}
+export interface UsageBucket{start:string;end:string;cpu_consumed:number;cpu_provisioned:number;memory_consumed:number;memory_provisioned:number}
+export interface UsagePoolDetailResponse{data_as_of:string;partial:boolean;pool:{id:string;name:string};buckets:UsageBucket[]}
+async function request<T>(path:string,p:URLSearchParams):Promise<T>{const token=await getToken();const r=await fetch(`${path}?${p}`,{headers:{Authorization:token?`Bearer ${token}`:""}});if(!r.ok){const b=await r.json().catch(()=>null) as {error?:string}|null;throw new Error(b?.error??`usage request failed: ${r.status}`)}return r.json() as Promise<T>}
+function params(timeframe:UsageTimeframe,subject?:string){const p=new URLSearchParams({timeframe});if(subject)p.set("subject",subject);return p}
+export const usageApi={overview:(t:UsageTimeframe,s?:string)=>request<UsageOverviewResponse>("/api/usage/overview",params(t,s)),pool:(t:UsageTimeframe,poolId:string,s?:string)=>{const p=params(t,s);p.set("pool",poolId);return request<UsagePoolDetailResponse>("/api/usage/pool",p)}}
diff --git a/libs/fleet/tests/nginx-config.test.mjs b/libs/fleet/tests/nginx-config.test.mjs
index 0f654636fe..0ba691aa2e 100644
--- a/libs/fleet/tests/nginx-config.test.mjs
+++ b/libs/fleet/tests/nginx-config.test.mjs
@@ -29,6 +29,11 @@ test("backend API nginx route includes GitHub trust policy endpoints", async ()
/\bstate\b/,
"expected /api/state/query to proxy to cyclops-cs-backend",
)
+ assert.match(
+ backendRoute[1],
+ /\busage\b/,
+ "expected /api/usage to proxy to cyclops-cs-backend",
+ )
})
test("oauth2-proxy accepts Fleets GitHub WIF bearer tokens", async () => {