@intentius/chant-lexicon-grafana 0.97.0 → 0.99.0

package/src/import.e2e.test.ts

@@ -1,24 +1,22 @@
 /**
  * "A dashboard builds to JSON that Grafana imports without edits", against
- * Grafana itself.
+ * Grafana itself, on every release in `GRAFANA_IMAGES` (12.4 and 13.2).
  *
  * Builds each example (getting-started, and dashboards-from-declarations,
  * whose dashboards the RED, SLO and agent composites build), mounts its
  * provisioning files and dashboards into a pinned `grafana/grafana`
- * container, and asserts that
- * Grafana provisioned every datasource and dashboard and hands each
- * dashboard back with the panels that were built. It then imports the same
- * JSON a second time through `POST /api/dashboards/db`, the path the UI's
- * import uses, under another uid.
+ * container, and asserts that Grafana provisioned every datasource and
+ * dashboard, and that each stored dashboard model is the built JSON, key
+ * for key, once the keys Grafana adds (`GRAFANA_INJECTED`: `id` and
+ * `version`) are taken out. It then imports the same JSON a second time
+ * through `POST /api/dashboards/db`, the path the UI's import uses, under
+ * another uid, and compares that stored model the same way.
  *
  * Skipped, with the reason in the test name, when Docker is not running.
- * On demand: `npx vitest run --project e2e lexicons/grafana`.
+ * On demand: `npx vitest run --project e2e lexicons/grafana/src/import.e2e.test.ts`.
  */
-import { execSync } from "node:child_process";
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
+import { mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
 import { afterAll, describe, expect, it } from "vitest";
 import { build } from "@intentius/chant/build";
 import type { SerializerResult } from "@intentius/chant/serializer";
@@ -26,23 +24,12 @@ import type { Serializer } from "@intentius/chant/serializer";
 import { otelSerializer } from "@intentius/chant-lexicon-otel/serializer";
 import { prometheusSerializer } from "@intentius/chant-lexicon-prometheus/serializer";
 import { grafanaSerializer } from "./serializer";
+import { DockerScope, GRAFANA_IMAGES, dockerAvailable, waitFor } from "../test/e2e/containers";
+import { withoutInjected } from "../test/e2e/stored-model";
 
-/** The Grafana release the import test runs against; `CHANT_GRAFANA_IMAGE` overrides it. */
-export const GRAFANA_IMAGE = process.env.CHANT_GRAFANA_IMAGE ?? "grafana/grafana:12.4.11";
-
-function available(cmd: string): boolean {
-  try {
-    execSync(cmd, { stdio: "ignore" });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-const hasDocker = available("docker info");
+const hasDocker = dockerAvailable();
 const skipReason = hasDocker ? "" : "Docker is not running";
-const AUTH = `Basic ${Buffer.from("admin:admin").toString("base64")}`;
-const examples = join(dirname(dirname(fileURLToPath(import.meta.url))), "examples");
+const examples = join(import.meta.dirname, "..", "examples");
 
 /** Each example, and the serializers its build root needs. */
 const EXAMPLES: Array<{ name: string; serializers: Serializer[] }> = [
@@ -50,98 +37,58 @@ const EXAMPLES: Array<{ name: string; serializers: Serializer[] }> = [
   { name: "dashboards-from-declarations", serializers: [otelSerializer, prometheusSerializer, grafanaSerializer] },
 ];
 
-async function waitFor<T>(what: string, fn: () => Promise<T | undefined>, timeoutMs = 120_000): Promise<T> {
-  const deadline = Date.now() + timeoutMs;
-  let last: unknown;
-  while (Date.now() < deadline) {
-    try {
-      const v = await fn();
-      if (v !== undefined) return v;
-    } catch (err) {
-      last = err;
-    }
-    await new Promise((r) => setTimeout(r, 1000));
-  }
-  throw new Error(`timed out waiting for ${what}${last ? `: ${String(last)}` : ""}`);
-}
+const MATRIX = GRAFANA_IMAGES.flatMap((image) => EXAMPLES.map((e) => ({ ...e, image })));
 
-describe.skipIf(!hasDocker).each(EXAMPLES)(`Grafana imports the $name dashboards without edits${skipReason ? ` (skipped: ${skipReason})` : ""}`, ({ name, serializers }) => {
-  const CONTAINER = `chant-grafana-import-${name}-${process.pid}`;
-  const dir = mkdtempSync(join(tmpdir(), "chant-grafana-import-"));
+describe.skipIf(!hasDocker).each(MATRIX)(`$image imports the $name dashboards without edits${skipReason ? ` (skipped: ${skipReason})` : ""}`, ({ name, serializers, image }) => {
+  const scope = new DockerScope(`grafana-import-${name}`);
 
-  afterAll(() => {
-    try {
-      execSync(`docker rm -f ${CONTAINER}`, { stdio: "ignore" });
-    } catch {
-      // already gone
-    }
-    rmSync(dir, { recursive: true, force: true });
-  });
+  afterAll(() => scope.cleanup());
 
-  it("provisions every datasource and dashboard, and accepts the JSON through the import API", { timeout: 300_000 }, async () => {
+  it("provisions every datasource and dashboard as built, and accepts the JSON through the import API", { timeout: 300_000 }, async () => {
     const result = await build(join(examples, name, "src"), serializers);
     expect(result.errors).toEqual([]);
     const out = result.outputs.get("grafana") as SerializerResult;
+    const dir = scope.tempDir();
     for (const [file, content] of Object.entries(out.files ?? {})) {
       mkdirSync(dirname(join(dir, file)), { recursive: true });
       writeFileSync(join(dir, file), content);
     }
     const index = JSON.parse(out.primary) as { dashboards: Array<{ uid: string; title: string; folder?: string; file: string }>; datasources: Array<{ uid: string; type: string; name: string }> };
 
-    execSync(
-      [
-        "docker run -d",
-        `--name ${CONTAINER}`,
-        "-p 127.0.0.1::3000",
-        "-e GF_SECURITY_ADMIN_PASSWORD=admin",
-        "-e GF_ANALYTICS_REPORTING_ENABLED=false",
-        "-e GF_ANALYTICS_CHECK_FOR_UPDATES=false",
-        `-v ${join(dir, "provisioning")}:/etc/grafana/provisioning:ro`,
-        `-v ${join(dir, "dashboards")}:/var/lib/grafana/dashboards:ro`,
-        GRAFANA_IMAGE,
-      ].join(" "),
-      { stdio: "ignore" },
-    );
-    const port = execSync(`docker port ${CONTAINER} 3000/tcp`).toString().trim().split("\n")[0].split(":").pop();
-    const base = `http://127.0.0.1:${port}`;
-    const api = async (path: string, init?: RequestInit) => {
-      const res = await fetch(`${base}${path}`, { ...init, headers: { authorization: AUTH, "content-type": "application/json", ...(init?.headers ?? {}) } });
-      return { status: res.status, body: (await res.json()) as Record<string, unknown> & unknown[] };
-    };
-
-    await waitFor("Grafana to answer", async () => ((await fetch(`${base}/api/health`)).ok ? true : undefined));
+    const grafana = await scope.grafana({ image, provisioningDir: join(dir, "provisioning"), dashboardsDir: join(dir, "dashboards") });
+    const { api } = grafana;
 
     // Datasources: every declared one, with the uid and type chant gave it.
     const datasources = await waitFor("datasources", async () => {
       const { status, body } = await api("/api/datasources");
-      return status === 200 && (body as unknown[]).length >= index.datasources.length ? (body as unknown as Array<{ uid: string; type: string; name: string }>) : undefined;
+      return status === 200 && (body as unknown[]).length >= index.datasources.length ? (body as Array<{ uid: string; type: string; name: string }>) : undefined;
     });
     expect(datasources.map((d) => [d.uid, d.type, d.name]).sort()).toEqual(index.datasources.map((d) => [d.uid, d.type, d.name]).sort());
 
-    // Dashboards: provisioned, in their folder, with every panel as built.
+    // Dashboards: provisioned, in their folder, and stored exactly as built.
     for (const d of index.dashboards) {
       const { body } = await waitFor(`dashboard ${d.uid}`, async () => {
         const r = await api(`/api/dashboards/uid/${d.uid}`);
         return r.status === 200 ? r : undefined;
       });
       const meta = body.meta as { provisioned: boolean; folderTitle?: string };
-      const stored = body.dashboard as { title: string; panels: Array<Record<string, unknown>>; templating: { list: unknown[] } };
-      const built = JSON.parse(out.files![d.file]) as typeof stored;
+      const stored = body.dashboard as Record<string, unknown>;
+      const built = JSON.parse(out.files![d.file]) as Record<string, unknown>;
       expect(meta.provisioned).toBe(true);
       if (d.folder) expect(meta.folderTitle).toBe(d.folder);
-      expect(stored.title).toBe(d.title);
-      const shape = (panels: Array<Record<string, unknown>>) => panels.map((p) => [p.id, p.type, p.title, p.gridPos]);
-      expect(shape(stored.panels)).toEqual(shape(built.panels));
-      expect(stored.templating.list.length).toBe(built.templating.list.length);
+      expect(typeof stored.id, `${d.uid}: Grafana assigns the id`).toBe("number");
+      expect(stored.version, `${d.uid}: Grafana's first version`).toBe(1);
+      expect(withoutInjected(stored), `${image} stored ${d.uid} differently from the build`).toStrictEqual(built);
     }
 
     // The same JSON through the import API, under a new uid.
     const first = index.dashboards[0];
-    const copy = { ...JSON.parse(out.files![first.file]), uid: `${first.uid}-api`, title: `${first.title} (API import)` };
+    const copy = { ...(JSON.parse(out.files![first.file]) as Record<string, unknown>), uid: `${first.uid}-api`, title: `${first.title} (API import)` };
     const imported = await api("/api/dashboards/db", { method: "POST", body: JSON.stringify({ dashboard: copy, overwrite: false }) });
     expect(imported.status).toBe(200);
     expect(imported.body.status).toBe("success");
     const back = await api(`/api/dashboards/uid/${first.uid}-api`);
-    expect((back.body.dashboard as { panels: unknown[] }).panels.length).toBe(copy.panels.length);
+    expect(back.status).toBe(200);
+    expect(withoutInjected(back.body.dashboard as Record<string, unknown>), `${image} stored the API import differently from the JSON sent`).toStrictEqual(copy);
   });
 });

package/src/import.test.ts

@@ -3,7 +3,7 @@
  *
  * Builds every example and validates each dashboard against Grafana's
  * dashboard schema at `GRAFANA_SCHEMA_PIN`, each panel's options and each
- * query against their plugin's schema, and runs GRAF101-GRAF107 over the
+ * query against their plugin's schema, and runs the GRAF1xx checks over the
  * output. `import.e2e.test.ts` does the same against a real Grafana when
  * Docker is available.
  */
@@ -18,6 +18,7 @@ import { grafanaSerializer } from "./serializer";
 import { validateDashboardSchema } from "./schema-validate";
 import { validateGrafanaOutput } from "./validate-output";
 import type { ProvisionedDatasource } from "./build";
+import { ALERTING_FILE } from "./alerting-build";
 
 const examplesDir = join(dirname(dirname(fileURLToPath(import.meta.url))), "examples");
 const examples = readdirSync(examplesDir).filter((e) => {
@@ -34,12 +35,17 @@ describe.each(examples)("example %s", (example) => {
     expect(result.errors).toEqual([]);
     const out = result.outputs.get("grafana") as SerializerResult;
     const dashboards = Object.entries(out.files ?? {}).filter(([f]) => f.startsWith("dashboards/"));
-    expect(dashboards.length).toBeGreaterThan(0);
+    const alerting = out.files?.[ALERTING_FILE];
+    expect(dashboards.length + (alerting ? 1 : 0)).toBeGreaterThan(0);
     for (const [file, text] of dashboards) {
       expect({ file, problems: validateDashboardSchema(JSON.parse(text)) }).toEqual({ file, problems: [] });
     }
     const ds = load(out.files?.["provisioning/datasources/chant.yaml"] ?? "datasources: []") as { datasources: ProvisionedDatasource[] };
-    const issues = validateGrafanaOutput({ dashboards: dashboards.map(([source, t]) => ({ source, json: JSON.parse(t) })), datasources: ds.datasources });
+    const issues = validateGrafanaOutput({
+      dashboards: dashboards.map(([source, t]) => ({ source, json: JSON.parse(t) })),
+      datasources: ds.datasources,
+      alerting: alerting ? [{ source: ALERTING_FILE, json: load(alerting) as Record<string, unknown> }] : [],
+    });
     expect(issues).toEqual([]);
   });
 });

package/src/index.ts

@@ -8,8 +8,15 @@ export { grafanaSerializer } from "./serializer";
 export {
   Datasource,
   DATASOURCE_TYPE,
+  ExternalDatasource,
+  EXTERNAL_DATASOURCE_TYPE,
   BUILTIN_DATASOURCE_UIDS,
   isDatasourceEntity,
+  isExternalDatasource,
+  isDatasourceDeclaration,
+  type ExternalDatasourceProps,
+  type ExternalDatasourceEntity,
+  type ExternalDatasourceConstructor,
   type DatasourceProps,
   type DatasourceEntity,
   type DatasourceConstructor,
@@ -34,6 +41,98 @@ export {
   type DashboardProviderEntity,
 } from "./dashboard";
 
+// Grafana-managed alerting
+export {
+  AlertRuleGroup,
+  AlertRule,
+  AlertQuery,
+  ReduceExpression,
+  MathExpression,
+  ThresholdExpression,
+  ResampleExpression,
+  ClassicConditionsExpression,
+  SqlExpression,
+  ContactPoint,
+  NotificationPolicy,
+  MuteTiming,
+  NotificationTemplate,
+  ALERT_RULE_GROUP_TYPE,
+  ALERT_RULE_TYPE,
+  ALERT_QUERY_TYPE,
+  EXPRESSION_TYPE_PREFIX,
+  EXPRESSION_DATASOURCE_UID,
+  CONTACT_POINT_TYPE,
+  NOTIFICATION_POLICY_TYPE,
+  MUTE_TIMING_TYPE,
+  NOTIFICATION_TEMPLATE_TYPE,
+  isAlertRuleGroupEntity,
+  isAlertRuleEntity,
+  isAlertQueryEntity,
+  isExpressionEntity,
+  isContactPointEntity,
+  isNotificationPolicyEntity,
+  isMuteTimingEntity,
+  isNotificationTemplateEntity,
+  type AlertRuleGroupProps,
+  type AlertRuleGroupEntity,
+  type AlertRuleProps,
+  type AlertRuleEntity,
+  type AlertRuleData,
+  type AlertRuleNotificationSettings,
+  type AlertRuleRecord,
+  type AlertQueryProps,
+  type AlertQueryEntity,
+  type AlertDuration,
+  type RelativeTimeRange,
+  type ExpressionEntity,
+  type ExpressionKind,
+  type ReduceExpressionProps,
+  type MathExpressionProps,
+  type ThresholdExpressionProps,
+  type ResampleExpressionProps,
+  type ClassicConditionsExpressionProps,
+  type SqlExpressionProps,
+  type NoDataState,
+  type ExecErrState,
+  type ContactPointProps,
+  type ContactPointEntity,
+  type ContactPointReceiver,
+  type ContactPointIntegrationType,
+  type NotificationPolicyProps,
+  type NotificationPolicyEntity,
+  type PolicyRoute,
+  type ObjectMatcher,
+  type MuteTimingProps,
+  type MuteTimingEntity,
+  type NotificationTemplateProps,
+  type NotificationTemplateEntity,
+} from "./alerting";
+export {
+  buildAlerting,
+  alertingYaml,
+  alertRuleJson,
+  alertQueryJson,
+  ruleGroupJson,
+  contactPointJson,
+  notificationPolicyJson,
+  muteTimingJson,
+  notificationTemplateJson,
+  durationSeconds,
+  ALERTING_FILE,
+  ALERTING_FILE_KEYS,
+  DEFAULT_RELATIVE_TIME_RANGE,
+  DEFAULT_GROUP_INTERVAL,
+  type AlertingFile,
+  type AlertingIndex,
+  type ProvisionedRuleGroup,
+  type ProvisionedAlertRule,
+  type ProvisionedAlertQuery,
+  type ProvisionedContactPoint,
+  type ProvisionedMuteTiming,
+  type ProvisionedTemplate,
+} from "./alerting-build";
+export { CONTACT_POINT_SECRET_SETTINGS } from "./contact-point-secrets";
+
 // Panels and rows, and the extension point for other panel plugins
 export {
   TimeSeriesPanel,
@@ -44,6 +143,19 @@ export {
   TracesPanel,
   HeatmapPanel,
   TextPanel,
+  BarChartPanel,
+  BarGaugePanel,
+  PieChartPanel,
+  StateTimelinePanel,
+  StatusHistoryPanel,
+  HistogramPanel,
+  NodeGraphPanel,
+  XYChartPanel,
+  TrendPanel,
+  CanvasPanel,
+  GeomapPanel,
+  FlameGraphPanel,
+  AlertListPanel,
   Row,
   definePanel,
   registeredPanels,
@@ -112,7 +224,32 @@ export {
 // The generated schema types and their pin
 export * as schema from "./schema";
 export { DASHBOARD_SCHEMA_VERSION } from "./schema";
-export { GRAFANA_SCHEMA_PIN, SCHEMA_NAMES, type GrafanaSchemaPin, type SchemaName } from "./pin";
+export {
+  GRAFANA_SCHEMA_PIN,
+  SCHEMA_NAMES,
+  IMPORT_ONLY_SCHEMA_NAMES,
+  VENDORED_SCHEMA_NAMES,
+  type GrafanaSchemaPin,
+  type SchemaName,
+  type ImportOnlySchemaName,
+  type VendoredSchemaName,
+} from "./pin";
+// Hand-written options for the built-in panels with no schema
+export type { AlertListOptions, AlertListSortOrder, AlertListStateFilter, FlameGraphOptions } from "./panel-options";
+
+// Panel transformations, typed per transformer (Grafana v13.2.2)
+export {
+  transformation,
+  customTransformation,
+  TRANSFORMATION_IDS,
+  type Transformation,
+  type KnownTransformation,
+  type CustomTransformation,
+  type TransformationCommon,
+  type TransformationId,
+  type TransformationOptionsById,
+  type ReducerId,
+} from "./transformations";
 
 // Plain-data API: render, check and detect without a build
 export {
@@ -124,8 +261,10 @@ export {
   panelsJson,
   targetJson,
   variableModel,
+  customVariableOptions,
   datasourceRef,
   provisionedDatasource,
+  externalDatasourceRecord,
   provisionedProvider,
   datasourcesYaml,
   dashboardProvidersYaml,
@@ -137,6 +276,7 @@ export {
   type BuiltDashboard,
   type GrafanaIndex,
   type ProvisionedDatasource,
+  type ExternalDatasourceRecord,
   type ProvisionedProvider,
   type DashboardJson,
   type PanelJson,
@@ -147,20 +287,31 @@ export {
 export {
   validateGrafanaOutput,
   issuesFor,
+  knownDatasourcesOf,
   variableReferences,
   type GrafanaIssue,
   type GrafanaIssueCode,
   type GrafanaArtifacts,
   type DashboardDoc,
 } from "./validate-output";
-export { validateDashboardSchema, type SchemaProblem } from "./schema-validate";
-export { looksLikeDashboard, looksLikeDatasourceProvisioning, looksLikeDashboardProvisioning } from "./detect";
-export { slugUid, isValidUid, UID_PATTERN, type DeepPartial } from "./util";
+export {
+  datasourceUses,
+  resolveDatasourceRef,
+  knownDatasources,
+  type DatasourceUse,
+  type ResolvedDatasource,
+  type KnownDatasource,
+  type DatasourceRefJson,
+} from "./datasource-refs";
+export { validateDashboardSchema, validateExpressionSchema, type SchemaProblem } from "./schema-validate";
+export { looksLikeDashboard, looksLikeDatasourceProvisioning, looksLikeDashboardProvisioning, looksLikeAlertingProvisioning } from "./detect";
+export { slugUid, isValidUid, UID_PATTERN, type DeepPartial, type PropsOf } from "./util";
 
-// Composites: dashboards built from a spanmetrics connector, an Slo and the GenAI preset
+// Composites: dashboards built from a spanmetrics connector, an Slo and the GenAI preset, and an Slo's burn-rate alerts as Grafana rules
 export {
   RedDashboard,
   redQueries,
+  RED_DEFAULT_SPAN_KINDS,
   SloDashboard,
   sloQueries,
   AgentDashboard,
@@ -168,6 +319,7 @@ export {
   type RedDashboardProps,
   type RedDashboardMembers,
   type RedDashboardInstance,
+  type SpanKind,
   type SloDashboardProps,
   type SloDashboardMembers,
   type SloDashboardInstance,
@@ -175,4 +327,37 @@ export {
   type AgentDashboardMembers,
   type AgentDashboardInstance,
   type DashboardOptions,
+  SloAlertRules,
+  sloAlertQueries,
+  type SloAlertRulesProps,
+  type SloAlertRulesMembers,
+  type SloAlertRulesInstance,
 } from "./composites";
+
+// Config namespace (#2946): `grafana.profiles.<env>` in chant.config.ts, the
+// Grafana each environment is observed in and exported from.
+export { grafanaConfigSchema, resolveGrafanaTarget } from "./config";
+export type { GrafanaConfig, GrafanaProfile } from "./config";
+
+// Ownership (#2946): chant's marker on a dashboard.grafana.app resource.
+export {
+  GRAFANA_OWNERSHIP_KEYS,
+  DEFAULT_PROVIDER_NAME,
+  grafanaOwnershipLabels,
+  dashboardOwnership,
+} from "./ownership";
+
+// The HTTP client observe and export share, for the API applier (#2948).
+export { GrafanaClient, GrafanaApiError, grafanaHttp, namespaceOf, statusVerdict } from "./api/client";
+export type { GrafanaAuth, GrafanaHttp, GrafanaResponse, GrafanaTarget, StatusVerdict } from "./api/client";
+export { bindGrafana, classifyGrafanaFailure, GrafanaBindingError } from "./api/bind";
+
+// The API applier (#2948): the typed Op step, and the pieces an embedding
+// caller composes (the activity itself is `./op/activities`).
+export { grafanaApply } from "./op/builders";
+export { applyGrafana, planFromDashboards, GRAFANA_APPLY_KINDS } from "./api/apply";
+export type { GrafanaApplyPlan, GrafanaApplyOutcome, DashboardPlan, BuiltDashboardInput } from "./api/apply";
+export { folderUidFor, foldersForDashboards, type FolderPlan } from "./api/folders";
+
+// The Grafana RBAC actions a service account needs to observe, apply and prune.
+export { GrafanaActions, grafanaActionsFor, type GrafanaAccessLevel } from "./actions/index";

package/src/k8s.test.ts

@@ -0,0 +1,98 @@
+import { describe, expect, test } from "vitest";
+import { expandComposite } from "@intentius/chant/composite";
+import { k8sSerializer } from "@intentius/chant-lexicon-k8s";
+import { loadAll } from "js-yaml";
+import { Dashboard } from "./dashboard";
+import { Datasource } from "./datasource";
+import { StatPanel } from "./panels";
+import { PromQuery } from "./query";
+import { dashboardJson } from "./build";
+import { GrafanaConfigMaps, grafanaConfigMapLayout, grafanaVolumes } from "./k8s";
+
+const prometheus = new Datasource({ name: "Prometheus", type: "prometheus", url: "http://prometheus:9090" });
+const stat = () => new StatPanel({ title: "Up", datasource: prometheus, targets: [new PromQuery({ expr: "sum(up)" })] });
+const top = new Dashboard({ title: "Top", uid: "Top_Level", panels: [stat()] });
+const red = new Dashboard({ title: "RED", uid: "red", folder: "Services", panels: [stat()] });
+const slo = new Dashboard({ title: "SLO", uid: "slo", folder: "Services", panels: [stat()] });
+const entities = [prometheus, top, red, slo];
+
+type Manifest = { kind: string; metadata: { name: string; namespace?: string; labels?: Record<string, string>; annotations?: Record<string, string> }; data: Record<string, string> };
+
+function manifests(instance: ReturnType<typeof GrafanaConfigMaps>): Manifest[] {
+  const out = k8sSerializer.serialize(expandComposite("grafana", instance));
+  return (loadAll(typeof out === "string" ? out : out.primary) as Manifest[]).filter(Boolean);
+}
+
+describe("GrafanaConfigMaps", () => {
+  test("one ConfigMap per dashboard, labelled for the sidecar, holding dashboardJson(dashboard)", () => {
+    const docs = manifests(GrafanaConfigMaps({ entities, namespace: "obs", labels: { team: "sre" } }));
+    expect(docs.map((d) => d.metadata.name)).toEqual([
+      "grafana-dashboard-top-level",
+      "grafana-dashboard-red",
+      "grafana-dashboard-slo",
+      "grafana-datasources",
+      "grafana-dashboard-providers",
+    ]);
+    const [topCm, redCm] = docs;
+    expect(topCm.metadata).toEqual({ name: "grafana-dashboard-top-level", namespace: "obs", labels: { team: "sre", grafana_dashboard: "1" } });
+    expect(topCm.data).toEqual({ "Top_Level.json": dashboardJson(top) });
+    expect(redCm.metadata.annotations).toEqual({ "k8s-sidecar-target-directory": "Services" });
+    expect(docs[3].metadata.labels).toEqual({ team: "sre", grafana_datasource: "1" });
+    expect(Object.keys(docs[3].data)).toEqual(["chant.yaml"]);
+    expect(docs[3].data["chant.yaml"]).toContain("url: http://prometheus:9090");
+    expect(docs[4].metadata.labels).toEqual({ team: "sre" });
+  });
+
+  test("labels and the folder annotation can be changed or left off", () => {
+    const docs = manifests(GrafanaConfigMaps({ entities: [red], name: "Obs", dashboardLabel: ["dashboards", "obs"], folderAnnotation: false }));
+    expect(docs[0].metadata).toEqual({ name: "obs-dashboard-red", labels: { dashboards: "obs" } });
+    const bare = manifests(GrafanaConfigMaps({ entities: [prometheus], datasourceLabel: false }));
+    expect(bare.map((d) => [d.metadata.name, d.metadata.labels])).toEqual([["grafana-datasources", {}]]);
+  });
+
+  test("names stay unique and DNS-1123 when uids collide after lower-casing", () => {
+    const a = new Dashboard({ title: "A", uid: "Same" });
+    const b = new Dashboard({ title: "B", uid: "same" });
+    expect(grafanaConfigMapLayout({ entities: [a, b] }).dashboards.map((d) => d.configMap)).toEqual(["grafana-dashboard-same", "grafana-dashboard-same-2"]);
+  });
+});
+
+describe("grafanaVolumes", () => {
+  test("provisioning under /etc/grafana/provisioning, each dashboard folder a projected volume of its own", () => {
+    const { volumes, volumeMounts } = grafanaVolumes({ entities });
+    expect(volumeMounts).toEqual([
+      { name: "grafana-provisioning", mountPath: "/etc/grafana/provisioning", readOnly: true },
+      { name: "grafana-dashboards-0", mountPath: "/var/lib/grafana/dashboards", readOnly: true },
+      { name: "grafana-dashboards-1", mountPath: "/var/lib/grafana/dashboards/Services", readOnly: true },
+    ]);
+    expect(volumes).toEqual([
+      {
+        name: "grafana-provisioning",
+        projected: {
+          sources: [
+            { configMap: { name: "grafana-datasources", items: [{ key: "chant.yaml", path: "datasources/chant.yaml" }] } },
+            { configMap: { name: "grafana-dashboard-providers", items: [{ key: "chant.yaml", path: "dashboards/chant.yaml" }] } },
+          ],
+        },
+      },
+      { name: "grafana-dashboards-0", projected: { sources: [{ configMap: { name: "grafana-dashboard-top-level", items: [{ key: "Top_Level.json", path: "Top_Level.json" }] } }] } },
+      {
+        name: "grafana-dashboards-1",
+        projected: {
+          sources: [
+            { configMap: { name: "grafana-dashboard-red", items: [{ key: "red.json", path: "red.json" }] } },
+            { configMap: { name: "grafana-dashboard-slo", items: [{ key: "slo.json", path: "slo.json" }] } },
+          ],
+        },
+      },
+    ]);
+  });
+
+  test("a different dashboards path or volume name", () => {
+    const { volumeMounts } = grafanaVolumes({ entities: [red] }, { dashboardsPath: "/dash/", volumeName: "g" });
+    expect(volumeMounts.map((m) => [m.name, m.mountPath])).toEqual([
+      ["g-provisioning", "/etc/grafana/provisioning"],
+      ["g-dashboards-0", "/dash/Services"],
+    ]);
+  });
+});