Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions .chloggen/380-dashboards-upsert-by-origin.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
change_type: enhancement
component: dashboards, apply
note: "Dashboards upsert by the `dash0.com/origin` label, so a dashboard kept as a Kubernetes custom resource no longer becomes a new dashboard on every apply."
issues: [380]
subtext: |
The CLI reads the identifier from `dash0.com/origin`, then `metadata.dash0Extensions.id`, then `dash0.com/id`.
A file exported with `dashboards get -o yaml` updates the dashboard it came from, also after you add a `dash0.com/origin` label to it.
A file whose `dash0.com/origin` and `dash0Extensions.id` differ fails validation before anything is written.
The API already rejected such a file, so no file that worked before fails now.
A file with only the `dash0.com/id` label updates that dashboard instead of creating a new one.
Commands that use an OAuth profile now resolve the access token when they start, so a rejected refresh shows the `dash0 login` hint before any request, as before v1.34.0 of the API client.
change_logs: []
2 changes: 1 addition & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ Detailed guidelines are split into focused documents:
- Check rules: top-level `id` field (`PrometheusAlertRule.Id`)
- Views: `metadata.labels["dash0.com/id"]` (`ViewLabels.Dash0Comid`)
- Synthetic checks: `metadata.labels["dash0.com/id"]`
- Dashboards: `metadata.dash0Extensions.id` (`DashboardMetadataExtensions.Id`)
- Dashboards: `metadata.labels["dash0.com/origin"]`, then `metadata.dash0Extensions.id`, then `metadata.labels["dash0.com/id"]` (the server UUID). `asset.DashboardKeys` sets this order, because the client's `GetID` reads `dash0.com/id` before `dash0Extensions.id`. Read the key before `StripDashboardServerFields`, which clears `dash0.com/id`. An origin that differs from `dash0Extensions.id` fails validation. When the origin is not found and the `dash0.com/id` label is, the CLI updates the dashboard at the id, like teams; `asset.DashboardAlias` returns that label, and `apply --since` treats it as the same dashboard.
- PersesDashboard CRD: `metadata.labels["dash0.com/id"]`
- PrometheusRule CRD (alerting and recording rules): `metadata.labels["dash0.com/id"]`
- Spam filters (v1alpha1 and v1alpha2): `metadata.labels["dash0.com/id"]`, but `metadata.labels["dash0.com/origin"]` takes precedence as the upsert key when both are present
Expand Down
2 changes: 1 addition & 1 deletion cmd/dash0/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -258,7 +258,7 @@ func skillHintSuppressed() bool {
// This approach avoids the need to predict which command will run — something
// that cobra's Traverse cannot reliably do when persistent flags like -X
// precede the subcommand name.
func loadConfig() *profiles.Configuration {
func loadConfig() *profiles.ResolvedConfiguration {
cfg, err := profiles.ResolveConfiguration("", "")
if err != nil {
return nil
Expand Down
6 changes: 3 additions & 3 deletions cmd/dash0/updatekey_characterization_integration_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -183,10 +183,10 @@ func runUpdateAgainstNotFound(t *testing.T, command updateCommand, v updateIdent
func TestUpdateKey_Characterization(t *testing.T) {
want := map[string]map[updateIdentifiers]string{
"dashboards": {
updateWithNeither: "error: no dashboard id given: pass one as an argument, or set the id in the file",
updateWithOrigin: "error: no dashboard id given: pass one as an argument, or set the id in the file",
updateWithNeither: `error: no dashboard origin or id given: pass one as an argument, or set metadata.labels["dash0.com/origin"] in the file`,
updateWithOrigin: "GET /api/dashboards/o",
updateWithID: "GET /api/dashboards/" + characterizationID,
updateWithBoth: "GET /api/dashboards/" + characterizationID,
updateWithBoth: `error: metadata.labels["dash0.com/origin"] ("o") and metadata.dash0Extensions.id ("` + characterizationID + `") must be equal; set only metadata.labels["dash0.com/origin"], and move "` + characterizationID + `" to metadata.labels["dash0.com/id"] if it is the id of an existing dashboard`,
},
"check-rules": {
updateWithNeither: "error: no check rule id given: pass one as an argument, or set the id in the file",
Expand Down
15 changes: 8 additions & 7 deletions docs/commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -834,7 +834,7 @@ The identifier field location varies by asset kind:

| Kind | Identifier field | Notes |
|------|------------------|-------|
| `Dashboard` | `metadata.dash0Extensions.id` | |
| `Dashboard` | `metadata.labels["dash0.com/origin"]`, then `metadata.dash0Extensions.id`, then `metadata.labels["dash0.com/id"]` | `dash0.com/origin` is the recommended key, and a Kubernetes custom resource keeps it, while Kubernetes drops the unknown `dash0Extensions` field. When both `dash0.com/origin` and `dash0Extensions.id` are set, they must be equal, or the document fails validation before anything is written. `dash0.com/id` is the server UUID that `get -o yaml` exports, so an exported file updates the dashboard it came from. When the document carries both `dash0.com/origin` and `dash0.com/id` and the origin is not found, the CLI updates the dashboard at the id, which then gets the origin, and `apply --since` does not delete it |
| `PersesDashboard` | `metadata.labels["dash0.com/id"]` | |
| `CheckRule` | top-level `id` | |
| `PrometheusRule` (alerting rules) | `metadata.labels["dash0.com/id"]` | For a single-alert CRD, this label is the alert's check-rule id directly. For a CRD with two or more alerting rules, each alert gets its own derived id (the CRD's label plus a slug of the alert's own composed name) instead of sharing the CRD's label directly — see [Multi-alert PrometheusRule CRDs](#multi-alert-prometheusrule-crds) |
Expand All @@ -861,7 +861,8 @@ Notification channels have no user-settable ID field at all, and for SLOs origin

For the remaining kinds — views, check rules, recording rules, and synthetic checks — the server treats origin as provenance only, so the CLI strips `dash0.com/origin` from outbound payloads and upserts against `dash0.com/id` (or the kind's equivalent ID field) instead.
Stripping origin keeps an `apply` from claiming ownership of an asset that Terraform or the Kubernetes operator manages.
Dashboards are a third case: they use `metadata.dash0Extensions.id`, and the sibling `metadata.dash0Extensions.origin` field is deprecated in favor of it, so never use origin as a dashboard upsert key.
Dashboards upsert by `dash0.com/origin` too, and also accept `metadata.dash0Extensions.id`, which names the same identifier.
The deprecated `metadata.dash0Extensions.origin` field is never used as a key.

When `list -o yaml` or `get -o yaml` exports an existing asset, the server-assigned ID is rendered into the correct field, so the export-edit-reapply workflow round-trips through the identifier automatically.

Expand Down Expand Up @@ -1529,19 +1530,19 @@ Dashboard:
apiVersion: dash0.com/v1alpha1
kind: Dashboard
metadata:
name: a1b2c3d4-5678-90ab-cdef-1234567890ab
dash0Extensions:
id: a1b2c3d4-5678-90ab-cdef-1234567890ab
name: production-overview
labels:
dash0.com/origin: dash0-cli_production-overview
spec:
display:
name: Production Overview
```

Pinning `apiVersion` on every user-authored file is a defense against silent migrations: today the server infers the default version when the field is omitted, but the same document with an explicit `apiVersion` will keep the same shape when a future default changes.

The user-defined identifier lives in `metadata.dash0Extensions.id` (see [asset identifiers](#asset-identifiers-and-idempotent-upsert)).
The user-defined identifier lives in `metadata.labels["dash0.com/origin"]`; files that set `metadata.dash0Extensions.id` instead keep working (see [asset identifiers](#asset-identifiers-and-idempotent-upsert)).
`metadata.name` is the CRD-style metadata name and is independent of `spec.display.name`, which is the title shown in the UI.
Omitting `dash0Extensions.id` causes every `create` / `apply` to allocate a new server-assigned ID, breaking idempotency.
A document with no identifier makes every `create` / `apply` allocate a new server-assigned ID, breaking idempotency.

PersesDashboard (Perses CRD, converted to a Dashboard on import):

Expand Down
2 changes: 1 addition & 1 deletion go.mod
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ toolchain go1.27.3

require (
github.com/cli/browser v1.3.0
github.com/dash0hq/dash0-api-client-go v1.33.0
github.com/dash0hq/dash0-api-client-go v1.34.0
github.com/google/uuid v1.6.0
github.com/muesli/termenv v0.16.0
github.com/pmezard/go-difflib v1.0.0
Expand Down
4 changes: 2 additions & 2 deletions go.sum
Original file line number Diff line number Diff line change
Expand Up @@ -31,8 +31,8 @@ github.com/cpuguy83/dockercfg v0.3.2/go.mod h1:sugsbF4//dDlL/i+S+rtpIWp+5h0BHJHf
github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
github.com/creack/pty v1.1.24 h1:bJrF4RRfyJnbTJqzRLHzcGaZK1NeM5kTC9jGgovnR1s=
github.com/creack/pty v1.1.24/go.mod h1:08sCNb52WyoAwi2QDyzUCTgcvVFhUzewun7wtTfvcwE=
github.com/dash0hq/dash0-api-client-go v1.33.0 h1:5z1DT1VLirH+eS0M5efxBxvUPqlRHWC5onmZE9JlFNk=
github.com/dash0hq/dash0-api-client-go v1.33.0/go.mod h1:r0AJKYZy8Y6hmGhsVbHbCEOEH3bIUKcHlg/KeZs6dJo=
github.com/dash0hq/dash0-api-client-go v1.34.0 h1:eU0Ej9mt8NUNBb8JK+HqyKwWrW5Qg3BUiU0W8ssu2dA=
github.com/dash0hq/dash0-api-client-go v1.34.0/go.mod h1:r0AJKYZy8Y6hmGhsVbHbCEOEH3bIUKcHlg/KeZs6dJo=
github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
github.com/distribution/reference v0.6.0 h1:0IXCQ5g4/QMHHkarYzh5l+u8T3t73zM5QvfrDyIgxBk=
Expand Down
234 changes: 234 additions & 0 deletions internal/apply/integration_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -1342,6 +1342,223 @@ spec:
}
}

func TestApply_Dashboard_OriginOnly_UpdatesTheSameDashboardOnEveryApply(t *testing.T) {
testutil.SetupTestEnv(t)

yamlFile := filepath.Join(t.TempDir(), "dashboard.yaml")
require.NoError(t, os.WriteFile(yamlFile, []byte(`kind: Dashboard
metadata:
name: checkout
labels:
dash0.com/origin: dash0-cli_checkout
spec:
display:
name: Checkout
`), 0644))

server := testutil.NewMockServer(t, testutil.FixturesDir())
server.On(http.MethodGet, "/api/dashboards/dash0-cli_checkout", testutil.MockResponse{
StatusCode: http.StatusNotFound,
BodyFile: testutil.FixtureDashboardsNotFound,
Validator: testutil.RequireHeaders,
})
server.WithDashboardsUpdate(testutil.FixtureDashboardsImportSuccess)

for range 2 {
cmd := NewApplyCmd()
cmd.SetArgs([]string{"-f", yamlFile, "--api-url", server.URL, "--auth-token", testAuthToken})
var cmdErr error
testutil.CaptureStdout(t, func() { cmdErr = cmd.Execute() })
require.NoError(t, cmdErr)
}

var puts int
for _, req := range server.Requests() {
assert.NotEqual(t, http.MethodPost, req.Method, "an origin-only dashboard must never be created with POST")
if req.Method == http.MethodPut {
assert.Equal(t, "/api/dashboards/dash0-cli_checkout", req.Path)
puts++
}
}
assert.Equal(t, 2, puts)
}

// The second apply of an origin-only dashboard finds it at the origin and
// reports no changes, instead of creating it again.
func TestApply_Dashboard_OriginOnly_SecondApplyReportsNoChanges(t *testing.T) {
testutil.SetupTestEnv(t)

const originPath = "/api/dashboards/dash0-cli_checkout"
yamlFile := filepath.Join(t.TempDir(), "dashboard.yaml")
require.NoError(t, os.WriteFile(yamlFile, []byte(`kind: Dashboard
metadata:
name: test-dashboard
labels:
dash0.com/origin: dash0-cli_checkout
spec:
display:
name: Test Dashboard
description: Test dashboard for apply command
layouts:
- kind: Grid
spec:
items: []
panels: {}
`), 0644))

server := testutil.NewMockServer(t, testutil.FixturesDir())
server.On(http.MethodGet, originPath, testutil.MockResponse{
StatusCode: http.StatusOK,
BodyFile: testutil.FixtureDashboardsImportSuccess,
Validator: testutil.RequireHeaders,
})
server.WithDashboardsUpdate(testutil.FixtureDashboardsImportSuccess)

cmd := NewApplyCmd()
cmd.SetArgs([]string{"-f", yamlFile, "--api-url", server.URL, "--auth-token", testAuthToken})
var cmdErr error
output := testutil.CaptureStdout(t, func() { cmdErr = cmd.Execute() })

require.NoError(t, cmdErr)
assert.Contains(t, output, "no changes")
assert.NotContains(t, output, "created")
assert.Equal(t, []string{"GET " + originPath, "PUT " + originPath}, methodsAndPaths(server.Requests()))
}

func TestApply_Dashboard_ServerIDLabelOnly_UpdatesThatDashboard(t *testing.T) {
testutil.SetupTestEnv(t)

const serverID = "0b7e5d2a-1c3f-4e8a-9b6d-2f4a8c1e7d90"
yamlFile := filepath.Join(t.TempDir(), "dashboard.yaml")
require.NoError(t, os.WriteFile(yamlFile, []byte(`kind: Dashboard
metadata:
name: checkout
labels:
dash0.com/id: `+serverID+`
spec:
display:
name: Checkout
`), 0644))

server := testutil.NewMockServer(t, testutil.FixturesDir())
server.On(http.MethodGet, "/api/dashboards/"+serverID, testutil.MockResponse{
StatusCode: http.StatusOK,
BodyFile: testutil.FixtureDashboardsImportSuccess,
Validator: testutil.RequireHeaders,
})
server.WithDashboardsUpdate(testutil.FixtureDashboardsImportSuccess)

cmd := NewApplyCmd()
cmd.SetArgs([]string{"-f", yamlFile, "--api-url", server.URL, "--auth-token", testAuthToken})
var cmdErr error
testutil.CaptureStdout(t, func() { cmdErr = cmd.Execute() })
require.NoError(t, cmdErr)

assert.Nil(t, findRequest(server.Requests(), http.MethodPost, apiPathDashboards), "an exported dashboard must not be created a second time")
putReq := findRequest(server.Requests(), http.MethodPut, apiPathDashboards)
require.NotNil(t, putReq)
assert.Equal(t, "/api/dashboards/"+serverID, putReq.Path)
}

func TestApply_Dashboard_OriginAndExtensionsIDDiffer_FailsBeforeAnyWrite(t *testing.T) {
testutil.SetupTestEnv(t)

yamlFile := filepath.Join(t.TempDir(), "dashboard.yaml")
require.NoError(t, os.WriteFile(yamlFile, []byte(`kind: Dashboard
metadata:
name: checkout
labels:
dash0.com/origin: dash0-cli_checkout
dash0Extensions:
id: other-id
spec:
display:
name: Checkout
`), 0644))

server := testutil.NewMockServer(t, testutil.FixturesDir())

cmd := NewApplyCmd()
cmd.SetArgs([]string{"-f", yamlFile, "--api-url", server.URL, "--auth-token", testAuthToken})
var cmdErr error
testutil.CaptureStdout(t, func() { cmdErr = cmd.Execute() })

require.Error(t, cmdErr)
assert.Contains(t, cmdErr.Error(), `metadata.labels["dash0.com/origin"] ("dash0-cli_checkout") and metadata.dash0Extensions.id ("other-id") must be equal; set only metadata.labels["dash0.com/origin"], and move "other-id" to metadata.labels["dash0.com/id"] if it is the id of an existing dashboard`)
assert.Empty(t, server.Requests())
}

const (
exportedDashboardID = "0b7e5d2a-1c3f-4e8a-9b6d-2f4a8c1e7d90"
exportedDashboardOrigin = "dash0-cli_checkout"
)

// applyExportedDashboardWithNewOrigin applies an exported dashboard that has
// gained an origin. The origin is unknown; storedStatus is the answer for the
// exported id.
func applyExportedDashboardWithNewOrigin(t *testing.T, storedStatus int) []testutil.RecordedRequest {
t.Helper()
testutil.SetupTestEnv(t)

yamlFile := filepath.Join(t.TempDir(), "dashboard.yaml")
require.NoError(t, os.WriteFile(yamlFile, []byte(`kind: Dashboard
metadata:
name: checkout
labels:
dash0.com/id: `+exportedDashboardID+`
dash0.com/origin: `+exportedDashboardOrigin+`
spec:
display:
name: Checkout
`), 0644))

server := testutil.NewMockServer(t, testutil.FixturesDir())
server.On(http.MethodGet, "/api/dashboards/"+exportedDashboardOrigin, testutil.MockResponse{
StatusCode: http.StatusNotFound,
BodyFile: testutil.FixtureDashboardsNotFound,
Validator: testutil.RequireHeaders,
})
stored := testutil.MockResponse{StatusCode: storedStatus, BodyFile: testutil.FixtureDashboardsImportSuccess, Validator: testutil.RequireHeaders}
if storedStatus == http.StatusNotFound {
stored.BodyFile = testutil.FixtureDashboardsNotFound
}
server.On(http.MethodGet, "/api/dashboards/"+exportedDashboardID, stored)
server.WithDashboardsUpdate(testutil.FixtureDashboardsImportSuccess)

cmd := NewApplyCmd()
cmd.SetArgs([]string{"-f", yamlFile, "--api-url", server.URL, "--auth-token", testAuthToken})
var cmdErr error
testutil.CaptureStdout(t, func() { cmdErr = cmd.Execute() })
require.NoError(t, cmdErr)
return server.Requests()
}

// Adding an origin to an exported dashboard must update that dashboard, not
// create a second one at the origin.
func TestApply_Dashboard_OriginNotFoundUpdatesAtID(t *testing.T) {
requests := applyExportedDashboardWithNewOrigin(t, http.StatusOK)

assert.Equal(t, []string{
"GET /api/dashboards/" + exportedDashboardOrigin,
"GET /api/dashboards/" + exportedDashboardID,
"PUT /api/dashboards/" + exportedDashboardID,
}, methodsAndPaths(requests))

var body dash0api.DashboardDefinition
require.NoError(t, json.Unmarshal(requests[2].Body, &body))
assert.Equal(t, exportedDashboardOrigin, body.GetOrigin(), "the existing dashboard gets the origin")
}

func TestApply_Dashboard_OriginAndIDNotFoundCreatesAtOrigin(t *testing.T) {
requests := applyExportedDashboardWithNewOrigin(t, http.StatusNotFound)

assert.Equal(t, []string{
"GET /api/dashboards/" + exportedDashboardOrigin,
"GET /api/dashboards/" + exportedDashboardID,
"PUT /api/dashboards/" + exportedDashboardOrigin,
}, methodsAndPaths(requests))
}

func TestApply_Dashboard_RoundTrip(t *testing.T) {
testutil.SetupTestEnv(t)

Expand Down Expand Up @@ -2759,6 +2976,23 @@ spec:
want: `Dashboard "Test Dashboard" (test-dashboard-id) restored`,
wantErr: `Dashboard "Test Dashboard" was saved, but the API still shows it as deleted`,
},
{
name: "dashboard by origin",
yaml: `kind: Dashboard
metadata:
name: test-dashboard
labels:
dash0.com/origin: dash0-cli_checkout
spec:
display:
name: Test Dashboard
`,
path: apiPathDashboards + "/dash0-cli_checkout",
deletedFixture: testutil.FixtureDashboardsGetDeleted,
putFixture: testutil.FixtureDashboardsImportSuccess,
want: `Dashboard "Test Dashboard" (test-dashboard-id) restored`,
wantErr: `Dashboard "Test Dashboard" was saved, but the API still shows it as deleted`,
},
{
name: "view",
yaml: `kind: Dash0View
Expand Down
Loading
Loading