@intentius/chant-lexicon-grafana 0.97.0 → 0.99.0

package/src/describe-resources.test.ts

@@ -0,0 +1,255 @@
+/**
+ * The thin read (#2946) against an in-memory Grafana, and the shared
+ * observation conformance suite over the same fake.
+ */
+
+import { describe, expect, it } from "vitest";
+import { describeObservationConformance } from "@intentius/chant-test-utils";
+import { normalizeObservation } from "@intentius/chant/observation";
+import { describeResources, type GrafanaObserveOptions } from "./describe-resources";
+import { fakeGrafana, liveDatasource, type FakeGrafanaState } from "./api/fake-grafana";
+import { grafanaPlugin } from "./plugin";
+import { Dashboard, DashboardProvider } from "./dashboard";
+import { Datasource, ExternalDatasource } from "./datasource";
+import { StatPanel, Row } from "./panels";
+import { PromQuery } from "./query";
+import { CustomVariable } from "./variables";
+
+type Entities = GrafanaObserveOptions["entities"];
+
+const CONFIG = { grafana: { profiles: { prod: { url: "http://grafana.test", token: { env: "GRAFANA_TEST_TOKEN" } } } } };
+const ENV = { GRAFANA_TEST_TOKEN: "glsa_test" };
+
+const prometheus = new Datasource({ name: "Prometheus", type: "prometheus", url: "http://prometheus:9090" });
+const loki = new ExternalDatasource({ type: "loki", uid: "shared-loki" });
+const up = new PromQuery({ expr: "up", datasource: prometheus });
+const upPanel = new StatPanel({ title: "Up", targets: [up] });
+const row = new Row({ title: "Health", panels: [upPanel] });
+const env = new CustomVariable({ name: "env", values: ["prod", "staging"] });
+const overview = new Dashboard({ title: "Overview", variables: [env], panels: [row] });
+const legacy = new Dashboard({ title: "Legacy", uid: "legacy-board" });
+const lonely = new StatPanel({ title: "On no dashboard" });
+const provider = new DashboardProvider({ name: "ops" });
+
+function entities(pairs: Record<string, { entityType: string; props: unknown }>): Entities {
+  return new Map(Object.entries(pairs).map(([n, e]) => [n, { entityType: e.entityType, props: e.props as Record<string, unknown> }]));
+}
+
+const ALL = entities({ overview, legacy, prometheus, loki, upPanel, up, row, env, provider });
+
+function state(overrides: Partial<FakeGrafanaState> = {}): FakeGrafanaState {
+  return {
+    api: "v1",
+    dashboards: {
+      overview: { spec: { title: "Overview", panels: [] }, annotations: { "grafana.app/managedBy": "classic-file-provisioning", "grafana.app/managerId": "ops" } },
+      "legacy-board": { spec: { title: "Legacy", panels: [] }, labels: { "app.kubernetes.io/managed-by": "chant", "chant.intentius.io/stack": "shop", "chant.intentius.io/env": "prod" } },
+    },
+    datasources: { prometheus: liveDatasource({ name: "Prometheus", type: "prometheus", uid: "prometheus" }) },
+    ...overrides,
+  };
+}
+
+function run(s: FakeGrafanaState, opts: Partial<GrafanaObserveOptions> = {}, calls?: string[]) {
+  return describeResources({
+    environment: "prod",
+    entityNames: [...ALL.keys()],
+    entities: ALL,
+    config: CONFIG,
+    env: ENV,
+    http: fakeGrafana(s, calls),
+    ...opts,
+  });
+}
+
+describe("describeResources", () => {
+  it("reads each dashboard and datasource by the uid the build gives it, and says where it looked", async () => {
+    const { resources, queried } = normalizeObservation(await run(state()));
+    expect(resources.overview).toMatchObject({ type: "Grafana::Dashboard", physicalId: "overview", status: "PRESENT", ownership: "owned" });
+    expect(resources.prometheus).toMatchObject({ physicalId: "prometheus", ownership: "unknown" });
+    expect(queried.overview).toBe("/apis/dashboard.grafana.app/v1/namespaces/default/dashboards/overview");
+    expect(queried.prometheus).toBe("/api/datasources/uid/prometheus");
+  });
+
+  it("uses v1beta1 on a 12.x server and /api/dashboards/uid on one without the dashboard API", async () => {
+    expect(normalizeObservation(await run(state({ api: "v1beta1" }))).queried.overview).toContain("/v1beta1/");
+    const legacyRead = normalizeObservation(await run(state({ api: "legacy" })));
+    expect(legacyRead.queried.overview).toBe("/api/dashboards/uid/overview");
+    expect(legacyRead.resources.overview.ownership).toBe("unknown");
+  });
+
+  it("a 404 is absent; an external datasource that is not there is absent too", async () => {
+    const { resources, unobserved } = normalizeObservation(await run(state()));
+    expect(resources.loki).toBeUndefined();
+    expect(unobserved.loki).toBeUndefined();
+  });
+
+  it("a panel, row, query or variable takes its dashboard's verdict, with one read of the dashboard", async () => {
+    const calls: string[] = [];
+    const { resources } = normalizeObservation(await run(state(), {}, calls));
+    for (const name of ["upPanel", "up", "row", "env"]) {
+      expect(resources[name], name).toMatchObject({ physicalId: "overview", ownership: "owned", attributes: { dashboard: "overview" } });
+    }
+    expect(calls.filter((c) => c.endsWith("/dashboards/overview"))).toHaveLength(1);
+  });
+
+  it("a part of a dashboard that is absent is absent", async () => {
+    const s = state();
+    delete s.dashboards.overview;
+    const { resources, unobserved } = normalizeObservation(await run(s));
+    for (const name of ["overview", "upPanel", "up", "row", "env"]) {
+      expect(resources[name], name).toBeUndefined();
+      expect(unobserved[name], name).toBeUndefined();
+    }
+  });
+
+  it("reads chant's marker, stack and env included, from the labels of a dashboard written through the API", async () => {
+    const { resources } = normalizeObservation(await run(state()));
+    expect(resources.legacy).toMatchObject({ ownership: "owned", marker: { stack: "shop", env: "prod" } });
+  });
+
+  it("a dashboard another provider loads is foreign", async () => {
+    const s = state();
+    s.dashboards.overview.annotations = { "grafana.app/managedBy": "classic-file-provisioning", "grafana.app/managerId": "other" };
+    expect(normalizeObservation(await run(s)).resources.overview.ownership).toBe("foreign");
+  });
+});
+
+describeObservationConformance({
+  lexicon: "grafana",
+  ownershipChannel: grafanaPlugin.ownershipChannel,
+  scenarios: [
+    {
+      name: "a provisioned estate on Grafana 13",
+      declared: [...ALL.keys()],
+      run: () => run(state()),
+      expectPresent: ["overview", "legacy", "prometheus", "upPanel", "up", "row", "env"],
+      expectAbsent: ["loki"],
+      expectUnobserved: ["provider"],
+      expectMarker: { legacy: { stack: "shop", env: "prod" } },
+      expectNoMarker: ["overview"],
+    },
+    {
+      name: "owned: true keeps chant's dashboards and withholds what it cannot show is chant's",
+      declared: [...ALL.keys()],
+      owned: true,
+      run: () => run(state(), { owned: true }),
+      expectPresent: ["overview", "legacy"],
+      expectUnobserved: ["prometheus", "provider"],
+    },
+    {
+      name: "owned: true on Grafana 11, where no dashboard's ownership can be read",
+      declared: ["overview", "legacy"],
+      owned: true,
+      run: () => run(state({ api: "legacy" }), { owned: true, entityNames: ["overview", "legacy"] }),
+      expectUnobserved: ["overview", "legacy"],
+    },
+    {
+      name: "a refused token",
+      declared: [...ALL.keys()],
+      run: () => run(state({ status: 401 })),
+      expectUnobserved: [...ALL.keys()],
+    },
+    {
+      name: "no Grafana bound to the environment",
+      declared: ["overview"],
+      run: () => describeResources({ environment: "staging", entityNames: ["overview"], entities: ALL, config: CONFIG, env: {} }),
+      expectUnobserved: ["overview"],
+    },
+    {
+      name: "a profile naming a token variable that is not set",
+      declared: ["overview"],
+      run: () => describeResources({ environment: "prod", entityNames: ["overview"], entities: ALL, config: CONFIG, env: {} }),
+      expectUnobserved: ["overview"],
+    },
+    {
+      name: "a dashboard stored as v2 that the server does not serve at v2",
+      declared: ["overview"],
+      run: () => {
+        const s = state();
+        s.dashboards.overview.storedVersion = "v2beta1";
+        return run(s, { entityNames: ["overview"] });
+      },
+      expectUnobserved: ["overview"],
+    },
+    {
+      name: "a panel on no dashboard",
+      declared: ["lonely"],
+      run: () => run(state(), { entityNames: ["lonely"], entities: new Map([...ALL, ["lonely", { entityType: lonely.entityType, props: lonely.props as unknown as Record<string, unknown> }]]) }),
+      expectUnobserved: ["lonely"],
+    },
+  ],
+});
+
+/** A small v2 spec of the "Overview" dashboard: one stat panel in a tab. */
+const OVERVIEW_V2 = {
+  title: "Overview",
+  annotations: [],
+  cursorSync: "Off",
+  links: [],
+  preload: false,
+  tags: [],
+  variables: [],
+  timeSettings: { from: "now-6h", to: "now", autoRefresh: "", autoRefreshIntervals: [], hideTimepicker: false, fiscalYearStartMonth: 0 },
+  elements: {
+    "panel-1": {
+      kind: "Panel",
+      spec: { id: 1, title: "Up", description: "", links: [], data: { kind: "QueryGroup", spec: { queries: [], transformations: [], queryOptions: {} } }, vizConfig: { kind: "VizConfig", group: "stat", version: "", spec: { options: {}, fieldConfig: { defaults: {}, overrides: [] } } } },
+    },
+  },
+  layout: {
+    kind: "TabsLayout",
+    spec: { tabs: [{ kind: "TabsLayoutTab", spec: { title: "Health", layout: { kind: "GridLayout", spec: { items: [{ kind: "GridLayoutItem", spec: { x: 0, y: 0, width: 12, height: 8, element: { kind: "ElementReference", name: "panel-1" } } }] } } } }] },
+  },
+};
+
+describe("a dashboard Grafana stores as v2 (#2947)", () => {
+  for (const [api, version] of [["v1", "v2"], ["v1beta1", "v2beta1"]] as const) {
+    it(`is read again at ${version} on a ${api} server, and says it was v2 and what the classic form cannot hold`, async () => {
+      const s = state({ api });
+      s.dashboards.overview = { ...s.dashboards.overview, storedVersion: version, v2: OVERVIEW_V2 };
+      const calls: string[] = [];
+      const obs = normalizeObservation(await run(s, { entityNames: ["overview"] }, calls));
+      expect(obs.unobserved).toEqual({});
+      // Ownership comes from the v2 resource's metadata, as from the classic one: the declared ops provider loads it.
+      expect(obs.resources.overview).toMatchObject({ status: "PRESENT", ownership: "owned" });
+      expect(obs.resources.overview.attributes).toMatchObject({ title: "Overview", schema: "v2", v2Lossy: [expect.stringMatching(/tabs "Health" become expanded rows/)] });
+      expect(calls).toContain(`GET /apis/dashboard.grafana.app/${version}/namespaces/default/dashboards/overview`);
+    });
+  }
+
+  it("a classic dashboard is read once, at the classic version, with no schema attribute", async () => {
+    const calls: string[] = [];
+    const obs = normalizeObservation(await run(state(), { entityNames: ["overview"] }, calls));
+    expect(obs.resources.overview.attributes).not.toHaveProperty("schema");
+    expect(calls.filter((c) => c.includes("/dashboards/overview"))).toEqual(["GET /apis/dashboard.grafana.app/v1/namespaces/default/dashboards/overview"]);
+  });
+
+  it("one the server does not serve at v2 is unsupported-kind, not the lossy classic read", async () => {
+    const s = state();
+    s.dashboards.overview.storedVersion = "v2";
+    const obs = normalizeObservation(await run(s, { entityNames: ["overview"] }));
+    expect(obs.unobserved.overview).toMatchObject({ reason: "unsupported-kind", detail: expect.stringMatching(/stored as a v2 dashboard .* lossy down-conversion/) });
+  });
+
+  it("a failed v2 read is read-failed", async () => {
+    const s = state();
+    s.dashboards.overview = { ...s.dashboards.overview, storedVersion: "v2", v2: OVERVIEW_V2 };
+    const base = fakeGrafana(s);
+    const http: typeof base = async (method, path, body) => (path.includes("/v2/") ? { status: 500, json: { message: "boom" } } : base(method, path, body));
+    const obs = normalizeObservation(await describeResources({ environment: "prod", entityNames: ["overview"], entities: ALL, config: CONFIG, env: ENV, http }));
+    expect(obs.unobserved.overview.reason).toBe("read-failed");
+  });
+});
+
+describe("unobserved reasons", () => {
+  it("names the reason each hole has", async () => {
+    const refused = normalizeObservation(await run(state({ status: 401 })));
+    expect(refused.unobserved.overview.reason).toBe("no-credentials");
+    const unbound = normalizeObservation(await describeResources({ environment: "staging", entityNames: ["overview"], entities: ALL, config: CONFIG, env: {} }));
+    expect(unbound.unobserved.overview).toMatchObject({ reason: "no-binding", detail: expect.stringContaining("GRAFANA_URL") });
+    const noToken = normalizeObservation(await describeResources({ environment: "prod", entityNames: ["overview"], entities: ALL, config: CONFIG, env: {} }));
+    expect(noToken.unobserved.overview).toMatchObject({ reason: "no-credentials", detail: expect.stringContaining("GRAFANA_TEST_TOKEN") });
+    const failing = normalizeObservation(await run(state({ status: 500 })));
+    expect(failing.unobserved.overview.reason).toBe("read-failed");
+  });
+});

package/src/describe-resources.ts

@@ -0,0 +1,209 @@
+/**
+ * `describeResources()` for grafana (#2946): does each declared dashboard
+ * and datasource exist in the environment's Grafana, and whose is it.
+ *
+ * Runs on core's observer harness. `bind()` resolves the environment's
+ * Grafana (`grafana.profiles.<env>`, else `GRAFANA_URL`) and discovers which
+ * dashboard API it serves; each entity is one GET, by the uid the build gives
+ * it. Verdicts:
+ *
+ * | Entity | Read | 404 | Not readable |
+ * |---|---|---|---|
+ * | `Dashboard` | `/apis/dashboard.grafana.app/<v>/.../dashboards/<uid>` (Grafana 11: `/api/dashboards/uid/<uid>`) | absent | a v2-stored dashboard the server does not serve at v2: `unsupported-kind` |
+ * | `Datasource`, `ExternalDatasource` | `/api/datasources/uid/<uid>` | absent | |
+ * | a panel, row, query or variable | its dashboard's read (./members.ts) | its dashboard's | its dashboard's |
+ * | `DashboardProvider` | none: a provisioning-file setting Grafana serves no API for | | `unsupported-kind` |
+ *
+ * A dashboard Grafana stores as v2 is read at v2 and converted (#2947);
+ * its metadata says `schema: "v2"` and lists what the classic form cannot
+ * hold under `v2Lossy`.
+ *
+ * A refused token is `no-credentials` for every entity, a missing binding
+ * `no-binding`, anything else `read-failed`, never absent.
+ *
+ * Ownership is read where Grafana has a channel (./ownership.ts): a
+ * dashboard over `/apis` resolves `owned` or `foreign`; a dashboard over the
+ * legacy API and every datasource say `unknown`, and an `owned: true` read
+ * withholds them as `filtered`, since it cannot show they are chant's.
+ */
+
+import type { ResourceMetadata } from "@intentius/chant/lexicon";
+import {
+  observeEntities,
+  type DeclaredEntity,
+  type DescribeResourcesResult,
+  type EntityObservation,
+  type ObserverAdapter,
+} from "@intentius/chant/observation";
+import { bindGrafana, classifyGrafanaFailure, type BindOptions } from "./api/bind";
+import { GrafanaApiError, type GrafanaClient } from "./api/client";
+import { classicDashboardOf, dashboardApi, readDashboard } from "./api/dashboards";
+import { readDatasource } from "./api/datasources";
+import { DASHBOARD_PROVIDER_TYPE, DASHBOARD_TYPE } from "./dashboard";
+import { DATASOURCE_TYPE, EXTERNAL_DATASOURCE_TYPE } from "./datasource";
+import { dashboardMembers, isDashboardPart } from "./members";
+import { chantProviderNames, dashboardOwnership, ownershipGap } from "./ownership";
+import { slugUid } from "./util";
+
+export interface GrafanaObserveOptions extends Omit<BindOptions, "environment"> {
+  environment: string;
+  buildOutput?: string;
+  entityNames: string[];
+  entities: Map<string, { entityType: string; props: Record<string, unknown> }>;
+  owned?: boolean;
+}
+
+/** The uid a declared dashboard or datasource has in Grafana: the one the build gives it. */
+export function declaredUid(name: string, entityType: string, props: Record<string, unknown>): string | undefined {
+  if (typeof props.uid === "string" && props.uid !== "") return props.uid;
+  if (entityType === DASHBOARD_TYPE) return slugUid(name || String(props.title ?? ""));
+  if (entityType === DATASOURCE_TYPE && typeof props.name === "string") return slugUid(props.name);
+  return undefined;
+}
+
+/** What `unsupported-kind` says about a provider. */
+export const PROVIDER_NOT_OBSERVABLE =
+  "a dashboard provider is a setting in Grafana's provisioning file, which Grafana serves no API for; its dashboards are observed instead";
+
+/** What `unsupported-kind` says about a panel, row, query or variable that no declared dashboard holds. */
+export const ORPHAN_PART =
+  "panels, rows, queries and variables exist in Grafana only inside a dashboard, and no declared dashboard holds this one";
+
+/** A GrafanaApiError as the harness's per-entity verdict; anything else is rethrown for the harness to record. */
+function unobservedFrom(err: unknown): EntityObservation {
+  if (err instanceof GrafanaApiError) return { unobserved: classifyGrafanaFailure(err) };
+  throw err;
+}
+
+async function observeDashboard(client: GrafanaClient, uid: string, providers: ReadonlySet<string>, owned: boolean | undefined): Promise<EntityObservation> {
+  let read;
+  try {
+    read = await readDashboard(client, uid);
+  } catch (err) {
+    return unobservedFrom(err);
+  }
+  if ("absent" in read) return { absent: true, queried: read.address };
+  const live = read.present;
+  const classic = classicDashboardOf(live);
+  if ("unsupported" in classic) {
+    return { unobserved: { reason: "unsupported-kind", detail: `dashboard "${uid}" is not readable: ${classic.unsupported}` }, queried: live.address };
+  }
+  const { ownership, marker } = dashboardOwnership(live, providers);
+  if (owned && ownership !== "owned") {
+    return {
+      unobserved: {
+        reason: "filtered",
+        detail: `dashboard "${uid}" exists but ${ownership === "unknown" ? "its ownership cannot be read" : "is not chant's"}: ${ownershipGap(live)}`,
+      },
+      queried: live.address,
+    };
+  }
+  const metadata = (live.raw.metadata ?? {}) as { generation?: unknown };
+  const legacyVersion = (live.raw.meta as { version?: unknown } | undefined)?.version;
+  const managerId = live.annotations["grafana.app/managerId"];
+  const meta: ResourceMetadata = {
+    type: DASHBOARD_TYPE,
+    physicalId: uid,
+    status: "PRESENT",
+    ownership,
+    ...(marker ? { marker } : {}),
+    attributes: {
+      title: classic.json.title,
+      via: live.via,
+      ...(live.folderUid ? { folderUid: live.folderUid } : {}),
+      // Grafana's save counter: a UI save moves it, so a snapshot diff sees the edit too.
+      ...(typeof metadata.generation === "number" ? { generation: metadata.generation } : {}),
+      ...(typeof legacyVersion === "number" ? { version: legacyVersion } : {}),
+      ...(managerId ? { managerId } : {}),
+      ...(classic.warnings !== undefined ? { schema: "v2", ...(classic.warnings.length > 0 ? { v2Lossy: classic.warnings } : {}) } : {}),
+    },
+  };
+  return { present: meta, queried: live.address };
+}
+
+async function observeDatasource(client: GrafanaClient, entity: DeclaredEntity, uid: string, owned: boolean | undefined): Promise<EntityObservation> {
+  let read;
+  try {
+    read = await readDatasource(client, uid);
+  } catch (err) {
+    return unobservedFrom(err);
+  }
+  if ("absent" in read) return { absent: true, queried: read.address };
+  if (owned) {
+    return {
+      unobserved: { reason: "filtered", detail: `datasource "${uid}" exists but its ownership cannot be read: Grafana's datasource API returns no labels or annotations` },
+      queried: read.address,
+    };
+  }
+  const ds = read.present;
+  return {
+    present: {
+      type: entity.type,
+      physicalId: uid,
+      status: "PRESENT",
+      ownership: "unknown",
+      attributes: {
+        name: ds.name,
+        type: ds.type,
+        ...(typeof ds.readOnly === "boolean" ? { readOnly: ds.readOnly } : {}),
+        ...(typeof ds.version === "number" ? { version: ds.version } : {}),
+      },
+    },
+    queried: read.address,
+  };
+}
+
+function adapter(options: GrafanaObserveOptions): ObserverAdapter<GrafanaClient> {
+  const providers = chantProviderNames(options.entities.values());
+  const members = dashboardMembers(options.entities);
+  // One read per dashboard, however many of its members are asked about.
+  const dashboardOnce = (client: GrafanaClient, uid: string) => client.once(`observe:${uid}`, () => observeDashboard(client, uid, providers, options.owned));
+
+  return {
+    async bind() {
+      const client = await bindGrafana({ ...options });
+      // Discovery is the first request, so a refused token or an unreachable
+      // server fails the bind: every entity NOT-OBSERVED with one reason.
+      await dashboardApi(client);
+      return client;
+    },
+    classifyBindFailure: (err) => classifyGrafanaFailure(err),
+    async read(client, entity): Promise<EntityObservation> {
+      if (entity.type === DASHBOARD_PROVIDER_TYPE) {
+        return { unobserved: { reason: "unsupported-kind", detail: PROVIDER_NOT_OBSERVABLE } };
+      }
+      if (isDashboardPart(entity.type)) {
+        const holder = members.get(entity.name);
+        const dashboard = holder !== undefined ? options.entities.get(holder) : undefined;
+        const uid = holder !== undefined && dashboard ? declaredUid(holder, DASHBOARD_TYPE, dashboard.props) : undefined;
+        if (!uid) return { unobserved: { reason: "unsupported-kind", detail: ORPHAN_PART } };
+        const verdict = await dashboardOnce(client, uid);
+        if (!("present" in verdict)) return verdict;
+        const { ownership, marker } = verdict.present;
+        return {
+          present: { type: entity.type, physicalId: uid, status: "PRESENT", ...(ownership ? { ownership } : {}), ...(marker ? { marker } : {}), attributes: { dashboard: uid } },
+          ...(verdict.queried ? { queried: verdict.queried } : {}),
+        };
+      }
+      const uid = declaredUid(entity.name, entity.type, entity.props);
+      if (entity.type === DASHBOARD_TYPE) {
+        return uid ? dashboardOnce(client, uid) : { unobserved: { reason: "read-failed", detail: `"${entity.name}" does not resolve to a uid` } };
+      }
+      if (entity.type === DATASOURCE_TYPE || entity.type === EXTERNAL_DATASOURCE_TYPE) {
+        return uid ? observeDatasource(client, entity, uid, options.owned) : { unobserved: { reason: "read-failed", detail: `"${entity.name}" does not resolve to a uid` } };
+      }
+      return { unobserved: { reason: "unsupported-kind", detail: `no grafana reader for ${entity.type}` } };
+    },
+  };
+}
+
+/** Observe every declared grafana entity against the environment's Grafana. */
+export async function describeResources(options: GrafanaObserveOptions): Promise<DescribeResourcesResult> {
+  const declared: DeclaredEntity[] = [];
+  for (const name of options.entityNames) {
+    const entity = options.entities.get(name);
+    if (!entity) continue;
+    declared.push({ name, type: entity.entityType, props: entity.props });
+  }
+  return observeEntities(declared, adapter(options));
+}

package/src/detect.ts

@@ -14,6 +14,33 @@ export function looksLikeDashboard(data: unknown): data is Record<string, unknow
   return Array.isArray(data.panels) && (typeof data.schemaVersion === "number" || isObject(data.templating));
 }
 
+/** A dashboard saved before Grafana 5.0: panels inside a top-level `rows` list. */
+export function looksLikeLegacyRowsDashboard(data: unknown): data is Record<string, unknown> {
+  return isObject(data) && !Array.isArray(data.panels) && Array.isArray(data.rows) && typeof data.schemaVersion === "number";
+}
+
+/** A dashboard as the `dashboard.grafana.app` API serves it: `apiVersion`, `kind: Dashboard` and a `spec`. */
+export function looksLikeDashboardResource(data: unknown): data is { apiVersion: string; kind: "Dashboard"; spec: Record<string, unknown> } {
+  return (
+    isObject(data) &&
+    data.kind === "Dashboard" &&
+    typeof data.apiVersion === "string" &&
+    data.apiVersion.startsWith("dashboard.grafana.app/") &&
+    isObject(data.spec)
+  );
+}
+
+/** A v2 dashboard: a `dashboard.grafana.app/v2*` resource, or a bare v2 spec (`elements` and `layout`). */
+export function looksLikeV2Dashboard(data: unknown): boolean {
+  if (looksLikeDashboardResource(data)) return /^dashboard\.grafana\.app\/v2/.test(data.apiVersion);
+  return isObject(data) && isObject(data.elements) && isObject(data.layout);
+}
+
+/** What `GET /api/dashboards/uid/<uid>` returns: `{ dashboard, meta }`. */
+export function looksLikeDashboardApiResponse(data: unknown): data is { dashboard: Record<string, unknown>; meta: unknown } {
+  return isObject(data) && isObject(data.meta) && (looksLikeDashboard(data.dashboard) || looksLikeLegacyRowsDashboard(data.dashboard));
+}
+
 /** A datasource provisioning file: `apiVersion` and a `datasources` list. */
 export function looksLikeDatasourceProvisioning(data: unknown): data is { apiVersion: unknown; datasources: unknown[] } {
   return isObject(data) && data.apiVersion !== undefined && Array.isArray(data.datasources);
@@ -24,7 +51,57 @@ export function looksLikeDashboardProvisioning(data: unknown): data is { apiVers
   return isObject(data) && data.apiVersion !== undefined && Array.isArray(data.providers);
 }
 
-/** Template detection for `chant import` and friends: any of the three. */
+/** The lists an alerting provisioning file holds (Grafana's `AlertingFileV1`). */
+const ALERTING_LISTS = [
+  "groups",
+  "deleteRules",
+  "contactPoints",
+  "deleteContactPoints",
+  "policies",
+  "resetPolicies",
+  "muteTimes",
+  "deleteMuteTimes",
+  "templates",
+  "deleteTemplates",
+] as const;
+
+/** A Grafana-managed rule group: a `folder`, or rules with `data` (queries), which a Prometheus rule group never has. */
+function looksLikeGrafanaRuleGroup(g: unknown): boolean {
+  if (!isObject(g)) return false;
+  if (typeof g.folder === "string") return true;
+  return Array.isArray(g.rules) && g.rules.some((r) => isObject(r) && Array.isArray(r.data));
+}
+
+/**
+ * An alerting provisioning file (`provisioning/alerting/*.yaml`, or what
+ * `/api/v1/provisioning/*\/export` writes): at least one of the alerting
+ * lists at the top level and nothing but those and `apiVersion`. A `groups`
+ * list must hold Grafana rule groups, so a Prometheus rule file (`groups:`
+ * of `name` and `rules` with `expr`) is not mistaken for one.
+ */
+export function looksLikeAlertingProvisioning(data: unknown): data is Record<string, unknown> {
+  if (!isObject(data)) return false;
+  const keys = Object.keys(data);
+  if (!keys.some((k) => (ALERTING_LISTS as readonly string[]).includes(k) && Array.isArray(data[k]))) return false;
+  if (!keys.every((k) => k === "apiVersion" || (ALERTING_LISTS as readonly string[]).includes(k))) return false;
+  if (Array.isArray(data.groups) && data.groups.length > 0 && !data.groups.every(looksLikeGrafanaRuleGroup)) return false;
+  return data.apiVersion !== undefined || Array.isArray(data.groups);
+}
+
+/**
+ * Template detection for `chant import` and friends: dashboard JSON in any
+ * of the shapes above (v2 included, #2947), or a datasource, dashboard or
+ * alerting provisioning file.
+ */
 export function detectTemplate(data: unknown): boolean {
-  return looksLikeDashboard(data) || looksLikeDatasourceProvisioning(data) || looksLikeDashboardProvisioning(data);
+  return (
+    looksLikeDashboard(data) ||
+    looksLikeLegacyRowsDashboard(data) ||
+    looksLikeDashboardResource(data) ||
+    looksLikeV2Dashboard(data) ||
+    looksLikeDashboardApiResponse(data) ||
+    looksLikeDatasourceProvisioning(data) ||
+    looksLikeDashboardProvisioning(data) ||
+    looksLikeAlertingProvisioning(data)
+  );
 }