@intentius/chant-lexicon-grafana 0.105.1 → 0.106.3

package/src/import/operator.test.ts

@@ -0,0 +1,235 @@
+import { describe, expect, test } from "vitest";
+import type { EmbeddedContent } from "@intentius/chant/import/embedded";
+import { grafanaPlugin } from "../plugin";
+import { operatorContactPoint, operatorPolicyRoute, operatorRouteSpec, operatorRule } from "../k8s";
+import { operatorImporter, provisionedReceivers, provisionedRoute, provisionedRule } from "./operator";
+
+const site = (hostType: string, select: string, spec: Record<string, unknown>): EmbeddedContent => ({
+  host: "k8s",
+  hostType,
+  location: `${hostType.split("::").pop()} x spec.${select}`,
+  directory: "x",
+  document: spec,
+  select,
+  labels: {},
+});
+
+const SELECTOR = { matchLabels: { dashboards: "grafana" } };
+
+describe("Grafana Operator alerting embedded in a k8s manifest (#3538)", () => {
+  test("the plugin registers the importer", () => {
+    expect(grafanaPlugin.embeddedImporters?.()).toContain(operatorImporter);
+  });
+
+  test("matches the five kinds at their own field, and nothing else", () => {
+    expect(operatorImporter.matches(site("K8s::Grafana::GrafanaAlertRuleGroup", "rules", { rules: [] }))).toBe(true);
+    expect(operatorImporter.matches(site("K8s::Grafana::GrafanaContactPoint", "receivers", { receivers: [] }))).toBe(true);
+    expect(operatorImporter.matches(site("K8s::Grafana::GrafanaNotificationPolicy", "route", { route: {} }))).toBe(true);
+    expect(operatorImporter.matches(site("K8s::Grafana::GrafanaNotificationPolicyRoute", "route", { route: { receiver: "r" } }))).toBe(true);
+    expect(operatorImporter.matches(site("K8s::Grafana::GrafanaMuteTiming", "time_intervals", { time_intervals: [] }))).toBe(true);
+    expect(operatorImporter.matches(site("K8s::Grafana::GrafanaNotificationTemplate", "template", { template: "x" }))).toBe(true);
+    expect(operatorImporter.matches(site("K8s::Grafana::GrafanaAlertRuleGroup", "receivers", {}))).toBe(false);
+    expect(operatorImporter.matches(site("K8s::Core::ConfigMap", "rules", { rules: [] }))).toBe(false);
+  });
+
+  describe("a rule", () => {
+    test("goes back to the file's spelling, without the values the CRD requires and Grafana defaults", () => {
+      expect(
+        provisionedRule({
+          uid: "r",
+          title: "R",
+          condition: "A",
+          data: [],
+          for: "0s",
+          noDataState: "NoData",
+          execErrState: "Alerting",
+          missingSeriesEvalsToResolve: 3,
+          notificationSettings: { receiver: "oncall", group_by: ["a"] },
+          annotations: { __dashboardUid__: "dash", __panelId__: "2", summary: "s" },
+        }),
+      ).toEqual({
+        uid: "r",
+        title: "R",
+        condition: "A",
+        data: [],
+        missing_series_evals_to_resolve: 3,
+        notification_settings: { receiver: "oncall", group_by: ["a"] },
+        dashboardUid: "dash",
+        panelId: 2,
+        annotations: { summary: "s" },
+      });
+    });
+
+    test("keeps values that are not the defaults, and a record rule's condition is the rule's own", () => {
+      const back = provisionedRule({ uid: "r", title: "R", condition: "B", data: [], for: "5m", noDataState: "Alerting", execErrState: "Error" });
+      expect(back).toMatchObject({ for: "5m", noDataState: "Alerting", execErrState: "Error", condition: "B" });
+      expect(provisionedRule({ uid: "r", title: "R", condition: "A", data: [], record: { metric: "m", from: "A" } })).not.toHaveProperty("condition");
+    });
+
+    test("is the inverse of operatorRule", () => {
+      const rule = {
+        uid: "r",
+        title: "R",
+        condition: "A",
+        data: [],
+        for: "5m",
+        labels: { severity: "page" },
+        dashboardUid: "dash",
+        panelId: 4,
+        annotations: { summary: "s" },
+        missing_series_evals_to_resolve: 2,
+        notification_settings: { receiver: "oncall" },
+      };
+      expect(provisionedRule(operatorRule(rule))).toEqual(rule);
+    });
+  });
+
+  describe("a receiver", () => {
+    test("reads each valuesFrom entry back as ${NAME} at its path, and names the Secret", () => {
+      const forward = operatorContactPoint(
+        { name: "oncall", receivers: [{ uid: "u", type: "slack", settings: { title: "t", url: "${SLACK_URL}", tlsConfig: { clientKey: "$KEY" } } }] },
+        "grafana-secrets",
+      );
+      const back = provisionedReceivers(forward.receivers as unknown[], "contact point");
+      expect(back.secretName).toBe("grafana-secrets");
+      expect(back.receivers).toEqual([{ uid: "u", type: "slack", settings: { title: "t", url: "${SLACK_URL}", tlsConfig: { clientKey: "${KEY}" } } }]);
+    });
+
+    test("without valuesFrom there is no Secret", () => {
+      expect(provisionedReceivers([{ uid: "m", type: "email", settings: { addresses: "a@example.com" } }], "cp")).toEqual({
+        receivers: [{ uid: "m", type: "email", settings: { addresses: "a@example.com" } }],
+      });
+    });
+
+    test("refuses what a ${NAME} reference cannot say", () => {
+      const from = (valueFrom: unknown, name = "s") => [{ type: "x", settings: {}, valuesFrom: [{ targetPath: "url", valueFrom }, { targetPath: "b", valueFrom: { secretKeyRef: { name, key: "B" } } }] }];
+      expect(() => provisionedReceivers(from({ configMapKeyRef: { name: "c", key: "K" } }), "cp")).toThrow(/secretKeyRef/);
+      expect(() => provisionedReceivers(from({ secretKeyRef: { name: "s", key: "not-a-name" } }), "cp")).toThrow(/secretKeyRef/);
+      expect(() => provisionedReceivers(from({ secretKeyRef: { name: "one", key: "A" } }, "two"), "cp")).toThrow(/one secretName/);
+    });
+  });
+
+  describe("the policy tree", () => {
+    test("object_matchers go back to matchers in every nested route", () => {
+      const route = operatorPolicyRoute({
+        receiver: "oncall",
+        routes: [{ receiver: "tickets", matchers: ['severity="ticket"', "team=~a|b"], routes: [{ matchers: ["env!=dev"] }] }],
+      });
+      expect(provisionedRoute(route)).toEqual({
+        receiver: "oncall",
+        routes: [{ receiver: "tickets", matchers: ['severity="ticket"', 'team=~"a|b"'], routes: [{ matchers: ['env!="dev"'] }] }],
+      });
+    });
+
+    test("a matcher that cannot be written as a string keeps them all as objects", () => {
+      const objects = [
+        ["a", "=", "x"],
+        ["b", "=", 'say "hi"'],
+      ];
+      expect(provisionedRoute({ receiver: "r", object_matchers: objects })).toEqual({ receiver: "r", object_matchers: objects });
+    });
+  });
+
+  describe("import", () => {
+    test("a rule group becomes an AlertRuleGroup, read through operatorRules, with a warning about its folder", () => {
+      const spec = {
+        instanceSelector: SELECTOR,
+        name: "errors",
+        folderRef: "grafana-folder-alerts",
+        interval: "30s",
+        rules: [
+          {
+            uid: "high-errors",
+            title: "High errors",
+            condition: "A",
+            for: "5m",
+            noDataState: "NoData",
+            execErrState: "Alerting",
+            data: [{ refId: "A", relativeTimeRange: { from: 600, to: 0 }, datasourceUid: "prom", model: { refId: "A", expr: "up", datasource: { type: "prometheus", uid: "prom" } } }],
+          },
+        ],
+      };
+      const out = operatorImporter.import(site("K8s::Grafana::GrafanaAlertRuleGroup", "rules", spec));
+      expect(out.value.shape).toBe("single");
+      expect(out.value.through).toEqual({ from: "@intentius/chant-lexicon-grafana/k8s", name: "operatorRules" });
+      const [binding] = out.value.bindings;
+      expect(out.files.find((f) => f.path === binding.from)?.content).toContain(`const ${binding.name} = new AlertRuleGroup(`);
+      const text = out.files.map((f) => f.content).join("\n");
+      expect(text).toContain('folder: "grafana-folder-alerts"');
+      expect(text).toContain("new AlertRule(");
+      expect(out.warnings?.join("\n")).toContain('rule group "errors": a declaration\'s folder is a title');
+    });
+
+    test("a contact point that reads a Secret gets a module naming it", () => {
+      const spec = {
+        instanceSelector: SELECTOR,
+        name: "oncall",
+        receivers: [
+          {
+            uid: "oncall-slack",
+            type: "slack",
+            settings: { title: "chant" },
+            valuesFrom: [{ targetPath: "url", valueFrom: { secretKeyRef: { name: "grafana-secrets", key: "SLACK_URL" } } }],
+          },
+        ],
+      };
+      const out = operatorImporter.import(site("K8s::Grafana::GrafanaContactPoint", "receivers", spec));
+      expect(out.value.through).toBeUndefined();
+      const [binding] = out.value.bindings;
+      expect(binding).toEqual({ from: "receivers.ts", name: "receivers" });
+      const module = out.files.find((f) => f.path === "receivers.ts")!.content;
+      expect(module).toContain('import { operatorReceivers } from "@intentius/chant-lexicon-grafana/k8s";');
+      expect(module).toContain('"grafana-secrets"');
+      expect(out.files.map((f) => f.content).join("\n")).toContain("${SLACK_URL}");
+    });
+
+    test("a contact point with no Secret is read through operatorReceivers alone", () => {
+      const spec = { name: "mail", receivers: [{ uid: "m", type: "email", settings: { addresses: "a@example.com" } }] };
+      const out = operatorImporter.import(site("K8s::Grafana::GrafanaContactPoint", "receivers", spec));
+      expect(out.value.through).toEqual({ from: "@intentius/chant-lexicon-grafana/k8s", name: "operatorReceivers" });
+      expect(out.files.some((f) => f.path === "receivers.ts")).toBe(false);
+    });
+
+    test("a policy, a mute timing and a template", () => {
+      const policy = operatorImporter.import(site("K8s::Grafana::GrafanaNotificationPolicy", "route", { route: { receiver: "oncall", routes: [{ object_matchers: [["severity", "=", "page"]] }] } }));
+      expect(policy.value.through?.name).toBe("operatorPolicy");
+      const text = policy.files.map((f) => f.content).join("\n");
+      expect(text).toContain("new NotificationPolicy(");
+      expect(text).toContain('severity="page"');
+
+      const mute = operatorImporter.import(site("K8s::Grafana::GrafanaMuteTiming", "time_intervals", { name: "weekends", time_intervals: [{ weekdays: ["saturday", "sunday"] }] }));
+      expect(mute.value.through?.name).toBe("operatorTimeIntervals");
+      expect(mute.files.map((f) => f.content).join("\n")).toContain("new MuteTiming(");
+
+      const template = operatorImporter.import(site("K8s::Grafana::GrafanaNotificationTemplate", "template", { name: "t", template: '{{ define "t" }}x{{ end }}' }));
+      expect(template.value.through?.name).toBe("operatorTemplate");
+      expect(template.files.map((f) => f.content).join("\n")).toContain("new NotificationTemplate(");
+    });
+
+    test("a policy route is read as the child of a policy and written back through operatorRouteSpec", () => {
+      const spec = { receiver: "tickets", object_matchers: [["severity", "=", "ticket"]], mute_time_intervals: ["weekends"], routes: [{ object_matchers: [["team", "=", "a"]] }] };
+      const out = operatorImporter.import(site("K8s::Grafana::GrafanaNotificationPolicyRoute", "route", { route: spec }));
+      expect(out.value.through).toEqual({ from: "@intentius/chant-lexicon-grafana/k8s", name: "operatorRouteSpec" });
+      const text = out.files.map((f) => f.content).join("\n");
+      expect(text).toContain("new NotificationPolicy(");
+      expect(text).toContain('severity="ticket"');
+      expect(text).toContain('team="a"');
+    });
+
+    test("a policy route's routeSelector is left out with a warning, and a route with no receiver throws", () => {
+      const out = operatorImporter.import(site("K8s::Grafana::GrafanaNotificationPolicyRoute", "route", { route: { receiver: "r", routeSelector: { matchLabels: { a: "b" } } } }));
+      expect((out.warnings ?? []).join("\n")).toContain("routeSelector");
+      expect(() => operatorImporter.import(site("K8s::Grafana::GrafanaNotificationPolicyRoute", "route", { route: { matchers: [] } }))).toThrow(/spec.receiver/);
+    });
+
+    test("a policy that selects routes by label throws so the host keeps it as written", () => {
+      const route = { receiver: "oncall", routeSelector: { matchLabels: { a: "b" } } };
+      expect(() => operatorImporter.import(site("K8s::Grafana::GrafanaNotificationPolicy", "route", { route }))).toThrow(/routeSelector/);
+    });
+
+    test("a policy with no receiver, and a group with no folder, throw so the host keeps them as written", () => {
+      expect(() => operatorImporter.import(site("K8s::Grafana::GrafanaNotificationPolicy", "route", { route: { group_by: ["a"] } }))).toThrow();
+      expect(() => operatorImporter.import(site("K8s::Grafana::GrafanaAlertRuleGroup", "rules", { name: "g", rules: [] }))).toThrow(/names no folder/);
+    });
+  });
+});

package/src/import/operator.ts

@@ -0,0 +1,243 @@
+/**
+ * Grafana Operator alerting resources embedded in a k8s manifest, for
+ * `chant import` (#3538).
+ *
+ * `GrafanaOperatorResources` (#3156) writes `GrafanaAlertRuleGroup`,
+ * `GrafanaContactPoint`, `GrafanaNotificationPolicy` (with, for
+ * `policyRoutes`, a `GrafanaNotificationPolicyRoute` per child route),
+ * `GrafanaMuteTiming` and
+ * `GrafanaNotificationTemplate` from grafana alerting declarations. The k8s
+ * parser offers the one field of each that holds the alerting content
+ * (`spec.rules`, `spec.receivers`, `spec.route`, `spec.time_intervals`,
+ * `spec.template`) with the whole `spec` as the document. This importer
+ * reads that spec back into the provisioning-file shape, which the alerting
+ * importer turns into declarations, and the k8s value becomes a call of the
+ * matching function in `@intentius/chant-lexicon-grafana/k8s` over the
+ * declaration, so a build gives the same field again.
+ *
+ * The reverse of what `GrafanaOperatorResources` writes:
+ *
+ * - a rule: the CRD's camel case (`missingSeriesEvalsToResolve`,
+ *   `notificationSettings`) goes back to the file's snake case, the
+ *   `__dashboardUid__` and `__panelId__` annotations go back to
+ *   `dashboardUid` and `panelId`, and the values the CRD requires and the
+ *   file leaves to Grafana's defaults (`for: 0s`, `noDataState: NoData`,
+ *   `execErrState: Alerting`) are left out;
+ * - a receiver: each `valuesFrom` entry becomes `${NAME}` at its
+ *   `targetPath` in the settings, `NAME` being the Secret key. The Secret's
+ *   name is not part of a declaration, so a contact point that reads a
+ *   Secret is written with a small module holding
+ *   `operatorReceivers(contactPoint, "<secret>")`;
+ * - a `GrafanaNotificationPolicyRoute`: its whole `spec` is the route, read
+ *   as the one child of a policy that has its receiver, and written back by
+ *   `operatorRouteSpec`;
+ * - the policy tree: `object_matchers` go back to Alertmanager `matchers`
+ *   strings where each can be written as one.
+ *
+ * A rule group's folder is a title in a declaration and a `GrafanaFolder`
+ * name (`folderRef`) in the resource, and the resource does not hold the
+ * title, so the declaration's `folder` is the reference, with a warning.
+ */
+
+import type { EmbeddedContent, EmbeddedContentImporter, EmbeddedImport } from "@intentius/chant/import/embedded";
+import { planAlertingProvisioning } from "./alerting";
+import { generatePlanModules } from "./generator";
+import { isObject } from "./normalize";
+
+type Json = Record<string, unknown>;
+
+const K8S_ENTRY = "@intentius/chant-lexicon-grafana/k8s";
+
+/** The resource types this importer reads, the spec field the k8s parser offers for each, the class it becomes and the function that writes the field back. */
+const KINDS: Record<string, { select: string; className: string; through: string }> = {
+  "K8s::Grafana::GrafanaAlertRuleGroup": { select: "rules", className: "AlertRuleGroup", through: "operatorRules" },
+  "K8s::Grafana::GrafanaContactPoint": { select: "receivers", className: "ContactPoint", through: "operatorReceivers" },
+  "K8s::Grafana::GrafanaNotificationPolicy": { select: "route", className: "NotificationPolicy", through: "operatorPolicy" },
+  "K8s::Grafana::GrafanaNotificationPolicyRoute": { select: "route", className: "NotificationPolicy", through: "operatorRouteSpec" },
+  "K8s::Grafana::GrafanaMuteTiming": { select: "time_intervals", className: "MuteTiming", through: "operatorTimeIntervals" },
+  "K8s::Grafana::GrafanaNotificationTemplate": { select: "template", className: "NotificationTemplate", through: "operatorTemplate" },
+};
+
+/** A Secret key a `${NAME}` reference can name. */
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+// ── the reverse mapping ──────────────────────────────────────────────
+
+/** One entry of `GrafanaAlertRuleGroup.spec.rules` as a rule of the provisioning file. */
+export function provisionedRule(rule: Json): Json {
+  const { missingSeriesEvalsToResolve, notificationSettings, annotations, for: forDuration, noDataState, execErrState, condition, ...rest } = rule;
+  const out: Json = { ...rest };
+
+  const record = isObject(rule.record) ? rule.record : undefined;
+  if (condition !== undefined && !(record && condition === record.from)) out.condition = condition;
+  if (forDuration !== undefined && forDuration !== "0s") out.for = forDuration;
+  if (noDataState !== undefined && noDataState !== "NoData") out.noDataState = noDataState;
+  if (execErrState !== undefined && execErrState !== "Alerting") out.execErrState = execErrState;
+  if (missingSeriesEvalsToResolve !== undefined) out.missing_series_evals_to_resolve = missingSeriesEvalsToResolve;
+  if (notificationSettings !== undefined) out.notification_settings = notificationSettings;
+
+  if (isObject(annotations)) {
+    const { __dashboardUid__, __panelId__, ...notes } = annotations;
+    const kept: Json = { ...notes };
+    if (typeof __dashboardUid__ === "string") out.dashboardUid = __dashboardUid__;
+    else if (__dashboardUid__ !== undefined) kept.__dashboardUid__ = __dashboardUid__;
+    if (typeof __panelId__ === "string" && /^\d+$/.test(__panelId__)) out.panelId = Number(__panelId__);
+    else if (__panelId__ !== undefined) kept.__panelId__ = __panelId__;
+    if (Object.keys(kept).length > 0) out.annotations = kept;
+  } else if (annotations !== undefined) {
+    out.annotations = annotations;
+  }
+  return out;
+}
+
+function setPath(settings: Json, path: string[], value: string, where: string): void {
+  let node = settings;
+  for (const seg of path.slice(0, -1)) {
+    if (node[seg] === undefined) node[seg] = {};
+    if (!isObject(node[seg])) throw new Error(`${where}: valuesFrom targetPath ${path.join(".")} goes through ${seg}, which is not an object`);
+    node = node[seg] as Json;
+  }
+  node[path[path.length - 1]] = value;
+}
+
+/**
+ * `GrafanaContactPoint.spec.receivers` as the provisioning file's receivers,
+ * each `valuesFrom` entry put back as `${NAME}` in the settings, and the name
+ * of the Secret they read (one Secret, as `GrafanaOperatorResources` writes).
+ */
+export function provisionedReceivers(receivers: unknown[], where: string): { receivers: Json[]; secretName?: string } {
+  const secrets = new Set<string>();
+  const out = receivers.map((r, i) => {
+    if (!isObject(r)) throw new Error(`${where}: receivers[${i}] is not an object`);
+    const { valuesFrom, ...rest } = r;
+    const settings: Json = isObject(rest.settings) ? structuredClone(rest.settings) : {};
+    for (const entry of Array.isArray(valuesFrom) ? valuesFrom : []) {
+      const ref = isObject(entry) && isObject(entry.valueFrom) && isObject(entry.valueFrom.secretKeyRef) ? entry.valueFrom.secretKeyRef : undefined;
+      if (!isObject(entry) || typeof entry.targetPath !== "string" || !ref || typeof ref.name !== "string" || typeof ref.key !== "string" || !ENV_NAME.test(ref.key)) {
+        throw new Error(`${where}: receivers[${i}] has a valuesFrom entry that is not a secretKeyRef to a key a \${NAME} reference can name`);
+      }
+      secrets.add(ref.name);
+      setPath(settings, entry.targetPath.split("."), `\${${ref.key}}`, where);
+    }
+    return { ...rest, settings };
+  });
+  if (secrets.size > 1) {
+    throw new Error(`${where}: the receivers read ${[...secrets].map((s) => `"${s}"`).join(" and ")}, and GrafanaOperatorResources takes one secretName`);
+  }
+  return { receivers: out, ...(secrets.size === 1 ? { secretName: [...secrets][0] } : {}) };
+}
+
+/** An `object_matchers` entry as an Alertmanager matcher string, when it can be written as one and read back the same. */
+function matcherText(m: unknown): string | undefined {
+  if (!Array.isArray(m) || m.length !== 3 || !m.every((x) => typeof x === "string")) return undefined;
+  const [label, op, value] = m as [string, string, string];
+  if (!/^[^\s=!~]+$/.test(label) || !["=", "!=", "=~", "!~"].includes(op)) return undefined;
+  if (value.includes('"') || value.includes("\\")) return undefined;
+  return `${label}${op}"${value}"`;
+}
+
+/** A route of the policy tree as the provisioning file holds it: `object_matchers` as `matchers` strings, in every nested route. */
+export function provisionedRoute(route: Json): Json {
+  const { object_matchers, routes, ...rest } = route;
+  const out: Json = { ...rest };
+  if (Array.isArray(object_matchers) && object_matchers.length > 0) {
+    const texts = object_matchers.map(matcherText);
+    // Every matcher or none: the build writes object matchers before matchers, so a mix would reorder.
+    if (texts.every((t): t is string => t !== undefined)) out.matchers = [...texts, ...(Array.isArray(rest.matchers) ? (rest.matchers as unknown[]) : [])];
+    else out.object_matchers = object_matchers;
+  }
+  if (Array.isArray(routes)) out.routes = routes.map((r) => (isObject(r) ? provisionedRoute(r) : r));
+  return out;
+}
+
+// ── the importer ─────────────────────────────────────────────────────
+
+function provisioningFile(type: string, spec: Json, warnings: string[]): { file: Json; secretName?: string } {
+  const where = `${type.split("::").pop()}`;
+  const name = spec.name;
+  switch (type) {
+    case "K8s::Grafana::GrafanaAlertRuleGroup": {
+      if (typeof name !== "string") throw new Error(`${where} has no spec.name`);
+      if (!Array.isArray(spec.rules)) throw new Error(`${where} has no spec.rules`);
+      const folder = typeof spec.folderRef === "string" ? spec.folderRef : typeof spec.folderUID === "string" ? spec.folderUID : undefined;
+      if (folder === undefined) throw new Error(`${where} names no folder (folderRef or folderUID)`);
+      warnings.push(
+        `rule group "${name}": a declaration's folder is a title, and the resource holds only ${typeof spec.folderRef === "string" ? `the GrafanaFolder name "${folder}" (folderRef)` : `the folder uid "${folder}" (folderUID)`}, so folder is set to that; change it to the folder's title`,
+      );
+      const group: Json = { name, folder, ...(typeof spec.interval === "string" ? { interval: spec.interval } : {}), rules: spec.rules.map((r) => (isObject(r) ? provisionedRule(r) : r)) };
+      return { file: { apiVersion: 1, groups: [group] } };
+    }
+    case "K8s::Grafana::GrafanaContactPoint": {
+      if (typeof name !== "string") throw new Error(`${where} has no spec.name`);
+      if (!Array.isArray(spec.receivers)) throw new Error(`${where} has no spec.receivers`);
+      const { receivers, secretName } = provisionedReceivers(spec.receivers, `contact point "${name}"`);
+      return { file: { apiVersion: 1, contactPoints: [{ name, receivers }] }, secretName };
+    }
+    case "K8s::Grafana::GrafanaNotificationPolicy": {
+      if (!isObject(spec.route)) throw new Error(`${where} has no spec.route`);
+      // The routes it selects are their own resources, and a declaration cannot hold the selector: keep it as written.
+      if (spec.route.routeSelector !== undefined) throw new Error(`${where} merges routes in with spec.route.routeSelector, which a NotificationPolicy cannot hold`);
+      return { file: { apiVersion: 1, policies: [provisionedRoute(spec.route)] } };
+    }
+    case "K8s::Grafana::GrafanaNotificationPolicyRoute": {
+      // The k8s parser offers the whole spec as `route`. A route has no declaration of its own, so it is read as the one child of a policy with its receiver.
+      if (!isObject(spec.route) || typeof spec.route.receiver !== "string") throw new Error(`${where} has no spec.receiver`);
+      const { routeSelector: _selector, ...route } = spec.route;
+      if (_selector !== undefined) warnings.push("the route's routeSelector (routes merged in by label) is not part of a declaration, so it is left out; import the selected routes on their own");
+      return { file: { apiVersion: 1, policies: [{ receiver: route.receiver, routes: [provisionedRoute(route)] }] } };
+    }
+    case "K8s::Grafana::GrafanaMuteTiming": {
+      if (typeof name !== "string") throw new Error(`${where} has no spec.name`);
+      return { file: { apiVersion: 1, muteTimes: [{ name, time_intervals: spec.time_intervals }] } };
+    }
+    default: {
+      if (typeof name !== "string" || typeof spec.template !== "string") throw new Error(`${where} has no spec.name or spec.template`);
+      return { file: { apiVersion: 1, templates: [{ name, template: spec.template }] } };
+    }
+  }
+}
+
+export const operatorImporter: EmbeddedContentImporter = {
+  what: "Grafana Operator alerting",
+
+  matches(content: EmbeddedContent) {
+    const kind = KINDS[content.hostType];
+    return kind !== undefined && content.select === kind.select && isObject(content.document);
+  },
+
+  import(content: EmbeddedContent): EmbeddedImport {
+    const kind = KINDS[content.hostType];
+    const warnings: string[] = [];
+    const { file, secretName } = provisioningFile(content.hostType, content.document as Json, warnings);
+    const planned = planAlertingProvisioning(file);
+    warnings.push(...planned.warnings);
+
+    const declaration = planned.plan.declarations.find((d) => d.className === kind.className);
+    const { files, exported } = generatePlanModules(planned.plan);
+    const binding = declaration ? exported.get(declaration.id) : undefined;
+    if (!binding) throw new Error(`no ${kind.className} was read from ${content.location}: ${planned.warnings.join(" ") || "the alerting importer dropped it"}`);
+
+    if (secretName === undefined) {
+      return {
+        files,
+        value: { bindings: [{ from: binding.path, name: binding.name }], shape: "single", through: { from: K8S_ENTRY, name: kind.through } },
+        warnings,
+      };
+    }
+    // A declaration does not know the Secret its settings were read from, so a module of its own names it.
+    const module = {
+      path: "receivers.ts",
+      content: [
+        "/** The receivers of the contact point, with its secrets read from the Secret they were in. */",
+        `import { operatorReceivers } from "${K8S_ENTRY}";`,
+        `import { ${binding.name} } from "./${binding.path.replace(/\.ts$/, "")}";`,
+        "",
+        `const receivers = operatorReceivers(${binding.name}, ${JSON.stringify(secretName)});`,
+        "",
+        "export { receivers };",
+        "",
+      ].join("\n"),
+    };
+    return { files: [...files, module], value: { bindings: [{ from: module.path, name: "receivers" }], shape: "single" }, warnings };
+  },
+};