@marble-sh/backstage-plugin-catalog-backend-module-grafana 0.2.0

package/README.md

@@ -0,0 +1,151 @@
+# @marble-sh/backstage-plugin-catalog-backend-module-grafana
+
+A catalog backend module that **auto-discovers Grafana instances and dashboards
+as catalog entities**, so your Grafana estate shows up in the Software Catalog
+and can participate in relations.
+
+It registers an `EntityProvider` that periodically reads every configured
+Grafana instance and emits:
+
+- one **`Resource`** (`spec.type: grafana-instance`) per Grafana instance, and
+- one **`Resource`** (`spec.type: grafana-dashboard`) per discovered dashboard,
+
+with each dashboard declaring `spec.dependsOn` on its instance Resource. That
+produces `dependsOn` / `dependencyOf` relations, so an instance's entity page
+lists all of its dashboards, and each dashboard links back to its instance.
+
+Every generated entity carries the required
+`backstage.io/managed-by-location` and
+`backstage.io/managed-by-origin-location` annotations and a `grafana/instance`
+annotation (dashboards also get a `grafana/dashboard-selector`), so the
+[frontend plugin](../grafana/README.md) tabs light up on the generated entities
+automatically.
+
+Discovery is resilient to outages: when reading an instance fails, its
+previously discovered entities are re-emitted (a full refresh replaces the
+provider's entire entity set, so skipping the instance would delete them); if
+an instance fails before any successful read, the refresh is aborted and
+retried on the next scheduled run, leaving the catalog untouched. Entity names
+are sanitized to satisfy catalog validation — names that would exceed 63
+characters, and dashboard uids containing uppercase characters, get a short
+stable hash appended to stay unique.
+
+## Installation
+
+```sh
+yarn --cwd packages/backend add @marble-sh/backstage-plugin-catalog-backend-module-grafana
+```
+
+```ts
+// packages/backend/src/index.ts
+backend.add(import('@backstage/plugin-catalog-backend'));
+backend.add(
+  import('@marble-sh/backstage-plugin-catalog-backend-module-grafana'),
+);
+```
+
+## Configuration
+
+Connection details are read from the shared `grafana.instances` config (the
+same block the [backend plugin](../grafana-backend/README.md) uses). Discovery
+behavior is configured under `grafana.catalog`:
+
+```yaml
+grafana:
+  instances:
+    - name: production
+      baseUrl: https://grafana.internal.example.com
+      token: ${GRAFANA_PROD_TOKEN}
+
+  catalog:
+    # How often discovery runs (defaults to every 30 minutes / 3-minute timeout).
+    schedule:
+      frequency: { minutes: 30 }
+      timeout: { minutes: 3 }
+    # Owner assigned to every generated entity (defaults to group:default/grafana).
+    defaultOwner: group:default/observability
+    # Optional system for every generated entity.
+    system: observability
+    # Catalog namespace for the generated entities (defaults to "default").
+    namespace: monitoring
+    # Only discover these instances (defaults to all under grafana.instances).
+    instances: [production]
+    # Only ingest a subset of dashboards (defaults to everything).
+    filter:
+      tags: [team-a]
+      query: payments, checkout
+    # Toggle what is emitted (all default to true).
+    emitInstances: true
+    emitDashboards: true
+    emitTags: true
+```
+
+Every option and its states:
+
+| Option           | Unset / default                            | When set                                                                                                                                |
+| ---------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `schedule`       | Every 30 minutes, 3-minute timeout.        | Discovery runs on your schedule.                                                                                                        |
+| `defaultOwner`   | `group:default/grafana`.                   | Every generated entity gets this `spec.owner`.                                                                                          |
+| `system`         | No `spec.system` on generated entities.    | Every generated entity gets this `spec.system`.                                                                                         |
+| `namespace`      | Entities live in the `default` namespace.  | Entities — and the `dependsOn` references between them — use this namespace.                                                            |
+| `instances`      | Every instance under `grafana.instances`.  | Only the listed instances are discovered. A name that doesn't exist under `grafana.instances` fails startup with a configuration error. |
+| `filter.tags`    | No tag filtering.                          | Only dashboards carrying **all** listed tags are ingested.                                                                              |
+| `filter.query`   | No title filtering.                        | Only dashboards whose title contains **any** of the comma-separated values (case-insensitive) are ingested.                             |
+| `emitInstances`  | `true`: one `Resource` per instance.       | `false`: no instance entities, and dashboard entities carry no `dependsOn` (there is nothing to point at).                              |
+| `emitDashboards` | `true`: one `Resource` per dashboard.      | `false`: no dashboard entities, and Grafana is not queried for dashboards during discovery at all.                                      |
+| `emitTags`       | `true`: dashboard tags become entity tags. | `false`: generated entities carry no tags (`filter.tags` still works — it filters what is ingested, not what the entities carry).       |
+
+An instance with `apis.dashboards: none` (see the
+[backend README](../grafana-backend/README.md#api-selection)) contributes its
+instance `Resource` but no dashboards.
+
+See [`config.d.ts`](./config.d.ts) for the full, documented schema.
+
+## Generated entity shape
+
+```yaml
+# Instance
+apiVersion: backstage.io/v1alpha1
+kind: Resource
+metadata:
+  name: grafana-instance-production
+  title: Production Grafana
+  annotations:
+    backstage.io/managed-by-location: grafana:production
+    grafana/instance: production
+  links:
+    - url: https://grafana.internal.example.com
+      title: Open Grafana
+spec:
+  type: grafana-instance
+  owner: group:default/observability
+---
+# Dashboard
+apiVersion: backstage.io/v1alpha1
+kind: Resource
+metadata:
+  name: grafana-dashboard-production-abc123
+  title: My Service
+  annotations:
+    backstage.io/managed-by-location: grafana:production
+    grafana/instance: production
+    grafana/dashboard-selector: My Service
+  links:
+    - url: https://grafana.internal.example.com/d/abc123/my-service
+      title: Open dashboard
+spec:
+  type: grafana-dashboard
+  owner: group:default/observability
+  dependsOn:
+    - resource:default/grafana-instance-production
+```
+
+## Testing
+
+```sh
+yarn workspace @marble-sh/backstage-plugin-catalog-backend-module-grafana test
+```
+
+The entity-building logic is unit-tested in isolation; the provider is tested
+with a fake task runner and a mocked catalog connection; and the module is
+verified to register its provider via `startTestBackend`.

package/config.schema.json

@@ -0,0 +1,180 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "grafana": {
+      "type": "object",
+      "properties": {
+        "catalog": {
+          "type": "object",
+          "properties": {
+            "schedule": {
+              "type": "object",
+              "properties": {
+                "frequency": {
+                  "anyOf": [
+                    {
+                      "type": "object",
+                      "properties": {
+                        "years": {
+                          "type": "number"
+                        },
+                        "months": {
+                          "type": "number"
+                        },
+                        "weeks": {
+                          "type": "number"
+                        },
+                        "days": {
+                          "type": "number"
+                        },
+                        "hours": {
+                          "type": "number"
+                        },
+                        "minutes": {
+                          "type": "number"
+                        },
+                        "seconds": {
+                          "type": "number"
+                        },
+                        "milliseconds": {
+                          "type": "number"
+                        }
+                      },
+                      "description": "Human friendly durations object."
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "cron": {
+                          "type": "string"
+                        }
+                      },
+                      "required": [
+                        "cron"
+                      ]
+                    }
+                  ]
+                },
+                "timeout": {
+                  "type": "object",
+                  "properties": {
+                    "years": {
+                      "type": "number"
+                    },
+                    "months": {
+                      "type": "number"
+                    },
+                    "weeks": {
+                      "type": "number"
+                    },
+                    "days": {
+                      "type": "number"
+                    },
+                    "hours": {
+                      "type": "number"
+                    },
+                    "minutes": {
+                      "type": "number"
+                    },
+                    "seconds": {
+                      "type": "number"
+                    },
+                    "milliseconds": {
+                      "type": "number"
+                    }
+                  },
+                  "description": "Human friendly durations object."
+                },
+                "initialDelay": {
+                  "type": "object",
+                  "properties": {
+                    "years": {
+                      "type": "number"
+                    },
+                    "months": {
+                      "type": "number"
+                    },
+                    "weeks": {
+                      "type": "number"
+                    },
+                    "days": {
+                      "type": "number"
+                    },
+                    "hours": {
+                      "type": "number"
+                    },
+                    "minutes": {
+                      "type": "number"
+                    },
+                    "seconds": {
+                      "type": "number"
+                    },
+                    "milliseconds": {
+                      "type": "number"
+                    }
+                  },
+                  "description": "Human friendly durations object."
+                }
+              },
+              "required": [
+                "frequency",
+                "timeout"
+              ],
+              "description": "How often discovery runs, and how long a single run may take. Defaults to every 30 minutes with a 3-minute timeout."
+            },
+            "defaultOwner": {
+              "type": "string",
+              "description": "The `spec.owner` assigned to every generated entity. Defaults to `group:default/grafana`. Set this to a team that owns the Grafana estate, for example `group:default/observability`."
+            },
+            "system": {
+              "type": "string",
+              "description": "An optional `spec.system` assigned to every generated entity, for example `observability`."
+            },
+            "namespace": {
+              "type": "string",
+              "description": "The catalog namespace the generated entities are created in.\n\n - unset (default): entities live in the `default` namespace.  - set: entities (and the `dependsOn` references between them) use the    given namespace."
+            },
+            "instances": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Which configured Grafana instances discovery reads.\n\n - unset (default): every instance under `grafana.instances`.  - a list of instance names: only those instances are discovered.    Startup fails with a configuration error if a listed name does not    exist under `grafana.instances`."
+            },
+            "filter": {
+              "type": "object",
+              "properties": {
+                "tags": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  },
+                  "description": "Only discover dashboards carrying **all** of these tags. Unset (default) means no tag filtering."
+                },
+                "query": {
+                  "type": "string",
+                  "description": "Only discover dashboards whose title contains one of these comma-separated values (case-insensitive). Unset (default) means no title filtering."
+                }
+              },
+              "description": "Narrows which dashboards are ingested. Both conditions must hold when both are set. Instance entities are unaffected."
+            },
+            "emitInstances": {
+              "type": "boolean",
+              "description": "Whether to emit a `Resource` for each Grafana instance.\n\n - `true` (default): one `Resource` (`spec.type: grafana-instance`)    per instance; dashboards declare `dependsOn` on it.  - `false`: no instance entities, and dashboard entities carry no    `dependsOn` (there is nothing to point at)."
+            },
+            "emitDashboards": {
+              "type": "boolean",
+              "description": "Whether to emit a `Resource` for each discovered dashboard.\n\n - `true` (default): one `Resource` (`spec.type: grafana-dashboard`)    per dashboard that passes `filter`.  - `false`: no dashboard entities, and Grafana is not queried for    dashboards during discovery at all."
+            },
+            "emitTags": {
+              "type": "boolean",
+              "description": "Whether dashboard tags are copied onto the generated entities.\n\n - `true` (default): sanitized dashboard tags become    `metadata.tags` on the dashboard entities.  - `false`: generated entities carry no tags. Tag-based `filter`    settings still work — this only affects the emitted entities."
+            }
+          },
+          "description": "Configuration for the Grafana catalog discovery module.\n\nThe module reads the instances from `grafana.instances` (shared with the Grafana backend plugin) and periodically emits a `Resource` entity for each Grafana instance and each dashboard it discovers, linking every dashboard to its instance via `spec.dependsOn`."
+        }
+      }
+    }
+  }
+}

package/dist/GrafanaEntityProvider.cjs.js

@@ -0,0 +1,121 @@
+'use strict';
+
+var errors = require('@backstage/errors');
+var backstagePluginGrafanaNode = require('@marble-sh/backstage-plugin-grafana-node');
+var buildEntities = require('./buildEntities.cjs.js');
+var config = require('./config.cjs.js');
+
+class GrafanaEntityProvider {
+  instances;
+  discovery;
+  logger;
+  taskRunner;
+  clientFactory;
+  connection;
+  // The most recent successfully built entities per instance. A full mutation
+  // replaces everything this provider ever emitted, so a transiently failing
+  // instance must not simply be skipped — that would delete its entities.
+  lastGoodEntities = /* @__PURE__ */ new Map();
+  /**
+   * Builds a provider from the root config and the logger/scheduler services.
+   *
+   * Throws if `grafana.catalog.instances` names an instance that is not
+   * configured under `grafana.instances`.
+   */
+  static fromConfig(rootConfig, options) {
+    const discovery = config.readGrafanaDiscoveryConfig(rootConfig);
+    let instances = backstagePluginGrafanaNode.readGrafanaInstances(rootConfig);
+    if (discovery.instances) {
+      const known = new Set(instances.map((instance) => instance.name));
+      const unknown = discovery.instances.filter((name) => !known.has(name));
+      if (unknown.length > 0) {
+        throw new errors.InputError(
+          `grafana.catalog.instances names unknown instance(s) '${unknown.join(
+            "', '"
+          )}'; configured instances are: ${[...known].join(", ")}`
+        );
+      }
+      const allowed = new Set(discovery.instances);
+      instances = instances.filter((instance) => allowed.has(instance.name));
+    }
+    return new GrafanaEntityProvider({
+      instances,
+      discovery,
+      logger: options.logger,
+      taskRunner: options.scheduler.createScheduledTaskRunner(
+        discovery.schedule
+      )
+    });
+  }
+  constructor(options) {
+    this.instances = options.instances;
+    this.discovery = options.discovery;
+    this.logger = options.logger;
+    this.taskRunner = options.taskRunner;
+    this.clientFactory = options.clientFactory ?? ((instance) => new backstagePluginGrafanaNode.GrafanaHttpClient({ instance }));
+  }
+  /** The unique, stable name identifying this provider's entity bucket. */
+  getProviderName() {
+    return "GrafanaEntityProvider";
+  }
+  /** Stores the connection and schedules the recurring discovery task. */
+  async connect(connection) {
+    this.connection = connection;
+    await this.taskRunner.run({
+      id: `${this.getProviderName()}:refresh`,
+      fn: async () => {
+        await this.refresh();
+      }
+    });
+  }
+  /**
+   * Reads every configured instance and replaces the provider's entities.
+   *
+   * When an instance fails transiently, its previously discovered entities are
+   * re-emitted so the full mutation does not remove them from the catalog. If
+   * an instance fails before any successful read, the whole refresh is aborted
+   * (leaving the catalog untouched) and retried on the next scheduled run.
+   */
+  async refresh() {
+    if (!this.connection) {
+      throw new Error("GrafanaEntityProvider is not connected");
+    }
+    const entities = [];
+    for (const instance of this.instances) {
+      let built;
+      try {
+        const client = this.clientFactory(instance);
+        const dashboards = this.discovery.emitDashboards ? await client.listDashboards(this.discovery.filter) : [];
+        built = buildEntities.buildGrafanaEntities(instance, dashboards, this.discovery);
+        this.lastGoodEntities.set(instance.name, built);
+      } catch (error) {
+        const previous = this.lastGoodEntities.get(instance.name);
+        if (!previous) {
+          this.logger.error(
+            `Failed to read Grafana instance '${instance.name}' for catalog discovery and no previous result is available; aborting this refresh`,
+            error
+          );
+          throw error;
+        }
+        this.logger.warn(
+          `Failed to read Grafana instance '${instance.name}' for catalog discovery; keeping its ${previous.length} previously discovered entities`,
+          error
+        );
+        built = previous;
+      }
+      entities.push(
+        ...built.map((entity) => ({
+          entity,
+          locationKey: `grafana:${instance.name}`
+        }))
+      );
+    }
+    await this.connection.applyMutation({ type: "full", entities });
+    this.logger.info(
+      `Grafana catalog discovery emitted ${entities.length} entities`
+    );
+  }
+}
+
+exports.GrafanaEntityProvider = GrafanaEntityProvider;
+//# sourceMappingURL=GrafanaEntityProvider.cjs.js.map

package/dist/GrafanaEntityProvider.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GrafanaEntityProvider.cjs.js","sources":["../src/GrafanaEntityProvider.ts"],"sourcesContent":["/*\n * Copyright 2026 Cassidy Marble\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  LoggerService,\n  SchedulerService,\n  SchedulerServiceTaskRunner,\n} from '@backstage/backend-plugin-api';\nimport { Config } from '@backstage/config';\nimport { InputError } from '@backstage/errors';\nimport { ResourceEntity } from '@backstage/catalog-model';\nimport {\n  DeferredEntity,\n  EntityProvider,\n  EntityProviderConnection,\n} from '@backstage/plugin-catalog-node';\nimport {\n  GrafanaClient,\n  GrafanaHttpClient,\n  GrafanaInstanceConfig,\n  readGrafanaInstances,\n} from '@marble-sh/backstage-plugin-grafana-node';\nimport { buildGrafanaEntities } from './buildEntities';\nimport { GrafanaDiscoveryConfig, readGrafanaDiscoveryConfig } from './config';\n\n/**\n * A catalog `EntityProvider` that discovers Grafana instances and their\n * dashboards, emitting a `Resource` for each and linking every dashboard to its\n * instance via `spec.dependsOn`.\n *\n * @public\n */\nexport class GrafanaEntityProvider implements EntityProvider {\n  private readonly instances: GrafanaInstanceConfig[];\n  private readonly discovery: GrafanaDiscoveryConfig;\n  private readonly logger: LoggerService;\n  private readonly taskRunner: SchedulerServiceTaskRunner;\n  private readonly clientFactory: (\n    instance: GrafanaInstanceConfig,\n  ) => GrafanaClient;\n  private connection?: EntityProviderConnection;\n  // The most recent successfully built entities per instance. A full mutation\n  // replaces everything this provider ever emitted, so a transiently failing\n  // instance must not simply be skipped — that would delete its entities.\n  private readonly lastGoodEntities = new Map<string, ResourceEntity[]>();\n\n  /**\n   * Builds a provider from the root config and the logger/scheduler services.\n   *\n   * Throws if `grafana.catalog.instances` names an instance that is not\n   * configured under `grafana.instances`.\n   */\n  static fromConfig(\n    rootConfig: Config,\n    options: { logger: LoggerService; scheduler: SchedulerService },\n  ): GrafanaEntityProvider {\n    const discovery = readGrafanaDiscoveryConfig(rootConfig);\n    let instances = readGrafanaInstances(rootConfig);\n\n    if (discovery.instances) {\n      const known = new Set(instances.map(instance => instance.name));\n      const unknown = discovery.instances.filter(name => !known.has(name));\n      if (unknown.length > 0) {\n        throw new InputError(\n          `grafana.catalog.instances names unknown instance(s) '${unknown.join(\n            \"', '\",\n          )}'; configured instances are: ${[...known].join(', ')}`,\n        );\n      }\n      const allowed = new Set(discovery.instances);\n      instances = instances.filter(instance => allowed.has(instance.name));\n    }\n\n    return new GrafanaEntityProvider({\n      instances,\n      discovery,\n      logger: options.logger,\n      taskRunner: options.scheduler.createScheduledTaskRunner(\n        discovery.schedule,\n      ),\n    });\n  }\n\n  constructor(options: {\n    instances: GrafanaInstanceConfig[];\n    discovery: GrafanaDiscoveryConfig;\n    logger: LoggerService;\n    taskRunner: SchedulerServiceTaskRunner;\n    clientFactory?: (instance: GrafanaInstanceConfig) => GrafanaClient;\n  }) {\n    this.instances = options.instances;\n    this.discovery = options.discovery;\n    this.logger = options.logger;\n    this.taskRunner = options.taskRunner;\n    this.clientFactory =\n      options.clientFactory ??\n      (instance => new GrafanaHttpClient({ instance }));\n  }\n\n  /** The unique, stable name identifying this provider's entity bucket. */\n  getProviderName(): string {\n    return 'GrafanaEntityProvider';\n  }\n\n  /** Stores the connection and schedules the recurring discovery task. */\n  async connect(connection: EntityProviderConnection): Promise<void> {\n    this.connection = connection;\n    await this.taskRunner.run({\n      id: `${this.getProviderName()}:refresh`,\n      fn: async () => {\n        await this.refresh();\n      },\n    });\n  }\n\n  /**\n   * Reads every configured instance and replaces the provider's entities.\n   *\n   * When an instance fails transiently, its previously discovered entities are\n   * re-emitted so the full mutation does not remove them from the catalog. If\n   * an instance fails before any successful read, the whole refresh is aborted\n   * (leaving the catalog untouched) and retried on the next scheduled run.\n   */\n  async refresh(): Promise<void> {\n    if (!this.connection) {\n      throw new Error('GrafanaEntityProvider is not connected');\n    }\n\n    const entities: DeferredEntity[] = [];\n    for (const instance of this.instances) {\n      let built: ResourceEntity[];\n      try {\n        const client = this.clientFactory(instance);\n        const dashboards = this.discovery.emitDashboards\n          ? await client.listDashboards(this.discovery.filter)\n          : [];\n        built = buildGrafanaEntities(instance, dashboards, this.discovery);\n        this.lastGoodEntities.set(instance.name, built);\n      } catch (error) {\n        const previous = this.lastGoodEntities.get(instance.name);\n        if (!previous) {\n          this.logger.error(\n            `Failed to read Grafana instance '${instance.name}' for catalog discovery and no previous result is available; aborting this refresh`,\n            error as Error,\n          );\n          throw error;\n        }\n        this.logger.warn(\n          `Failed to read Grafana instance '${instance.name}' for catalog discovery; keeping its ${previous.length} previously discovered entities`,\n          error as Error,\n        );\n        built = previous;\n      }\n      entities.push(\n        ...built.map(entity => ({\n          entity,\n          locationKey: `grafana:${instance.name}`,\n        })),\n      );\n    }\n\n    await this.connection.applyMutation({ type: 'full', entities });\n    this.logger.info(\n      `Grafana catalog discovery emitted ${entities.length} entities`,\n    );\n  }\n}\n"],"names":["readGrafanaDiscoveryConfig","readGrafanaInstances","InputError","GrafanaHttpClient","buildGrafanaEntities"],"mappings":"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"}

package/dist/buildEntities.cjs.js

@@ -0,0 +1,96 @@
+'use strict';
+
+var crypto = require('crypto');
+var catalogModel = require('@backstage/catalog-model');
+var backstagePluginGrafanaCommon = require('@marble-sh/backstage-plugin-grafana-common');
+
+const RESOURCE_TYPE_INSTANCE = "grafana-instance";
+const RESOURCE_TYPE_DASHBOARD = "grafana-dashboard";
+const shortHash = (value) => crypto.createHash("sha256").update(value).digest("hex").slice(0, 8);
+const sanitizeName = (value) => {
+  const sanitized = value.toLocaleLowerCase("en-US").replace(/[^a-z0-9\-_.]+/g, "-").replace(/^[^a-z0-9]+/, "").replace(/[^a-z0-9]+$/, "");
+  if (sanitized.length <= 63) {
+    return sanitized;
+  }
+  const head = sanitized.slice(0, 54).replace(/[^a-z0-9]+$/, "");
+  return `${head}-${shortHash(value)}`;
+};
+const sanitizeTags = (tags) => {
+  const seen = /* @__PURE__ */ new Set();
+  for (const tag of tags) {
+    const sanitized = tag.toLocaleLowerCase("en-US").replace(/[^a-z0-9:+#]+/g, "-").replace(/^-+/, "").replace(/-+$/, "").slice(0, 63);
+    if (sanitized) {
+      seen.add(sanitized);
+    }
+  }
+  return [...seen];
+};
+const instanceEntityName = (instance) => sanitizeName(`grafana-instance-${instance.name}`);
+const dashboardEntityName = (instance, dashboard) => {
+  const caseSafeUid = dashboard.uid === dashboard.uid.toLocaleLowerCase("en-US") ? dashboard.uid : `${dashboard.uid}-${shortHash(dashboard.uid)}`;
+  return sanitizeName(`grafana-dashboard-${instance.name}-${caseSafeUid}`);
+};
+function buildGrafanaEntities(instance, dashboards, options) {
+  const locationRef = `grafana:${instance.name}`;
+  const commonAnnotations = {
+    [catalogModel.ANNOTATION_LOCATION]: locationRef,
+    [catalogModel.ANNOTATION_ORIGIN_LOCATION]: locationRef,
+    [backstagePluginGrafanaCommon.GRAFANA_ANNOTATION_INSTANCE]: instance.name
+  };
+  const systemSpec = options.system ? { system: options.system } : {};
+  const entities = [];
+  if (options.emitInstances) {
+    entities.push({
+      apiVersion: "backstage.io/v1alpha1",
+      kind: "Resource",
+      metadata: {
+        name: instanceEntityName(instance),
+        namespace: options.namespace,
+        title: instance.title,
+        annotations: { ...commonAnnotations },
+        links: [{ url: instance.baseUrl, title: "Open Grafana" }]
+      },
+      spec: {
+        type: RESOURCE_TYPE_INSTANCE,
+        owner: options.defaultOwner,
+        ...systemSpec
+      }
+    });
+  }
+  if (options.emitDashboards) {
+    for (const dashboard of dashboards) {
+      const tags = options.emitTags ? sanitizeTags(dashboard.tags) : [];
+      entities.push({
+        apiVersion: "backstage.io/v1alpha1",
+        kind: "Resource",
+        metadata: {
+          name: dashboardEntityName(instance, dashboard),
+          namespace: options.namespace,
+          title: dashboard.title,
+          annotations: {
+            ...commonAnnotations,
+            [backstagePluginGrafanaCommon.GRAFANA_ANNOTATION_DASHBOARD_SELECTOR]: dashboard.title
+          },
+          links: [{ url: dashboard.url, title: "Open dashboard" }],
+          ...tags.length ? { tags } : {}
+        },
+        spec: {
+          type: RESOURCE_TYPE_DASHBOARD,
+          owner: options.defaultOwner,
+          ...options.emitInstances ? {
+            dependsOn: [
+              `resource:${options.namespace}/${instanceEntityName(
+                instance
+              )}`
+            ]
+          } : {},
+          ...systemSpec
+        }
+      });
+    }
+  }
+  return entities;
+}
+
+exports.buildGrafanaEntities = buildGrafanaEntities;
+//# sourceMappingURL=buildEntities.cjs.js.map

package/dist/buildEntities.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildEntities.cjs.js","sources":["../src/buildEntities.ts"],"sourcesContent":["/*\n * Copyright 2026 Cassidy Marble\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { createHash } from 'crypto';\nimport {\n  ANNOTATION_LOCATION,\n  ANNOTATION_ORIGIN_LOCATION,\n  ResourceEntity,\n} from '@backstage/catalog-model';\nimport {\n  GRAFANA_ANNOTATION_DASHBOARD_SELECTOR,\n  GRAFANA_ANNOTATION_INSTANCE,\n  GrafanaDashboard,\n} from '@marble-sh/backstage-plugin-grafana-common';\nimport { GrafanaInstanceConfig } from '@marble-sh/backstage-plugin-grafana-node';\n\n/**\n * Options controlling how Grafana data is turned into catalog entities.\n *\n * @public\n */\nexport type GrafanaEntityOptions = {\n  /** The `spec.owner` assigned to every generated entity. */\n  defaultOwner: string;\n  /** An optional `spec.system` assigned to every generated entity. */\n  system?: string;\n  /** The catalog namespace the generated entities live in. */\n  namespace: string;\n  /** Whether to emit a Resource for the Grafana instance. */\n  emitInstances: boolean;\n  /** Whether to emit a Resource for each dashboard. */\n  emitDashboards: boolean;\n  /** Whether dashboard tags are copied onto the generated entities. */\n  emitTags: boolean;\n};\n\nconst RESOURCE_TYPE_INSTANCE = 'grafana-instance';\nconst RESOURCE_TYPE_DASHBOARD = 'grafana-dashboard';\n\nconst shortHash = (value: string): string =>\n  createHash('sha256').update(value).digest('hex').slice(0, 8);\n\nconst sanitizeName = (value: string): string => {\n  const sanitized = value\n    .toLocaleLowerCase('en-US')\n    .replace(/[^a-z0-9\\-_.]+/g, '-')\n    .replace(/^[^a-z0-9]+/, '')\n    .replace(/[^a-z0-9]+$/, '');\n  if (sanitized.length <= 63) {\n    return sanitized;\n  }\n  // Entity names are capped at 63 characters and must end alphanumeric. A\n  // plain cut could end on a separator and could collide with another long\n  // name, so truncated names get a stable hash of the full value appended.\n  const head = sanitized.slice(0, 54).replace(/[^a-z0-9]+$/, '');\n  return `${head}-${shortHash(value)}`;\n};\n\nconst sanitizeTags = (tags: string[]): string[] => {\n  const seen = new Set<string>();\n  for (const tag of tags) {\n    const sanitized = tag\n      .toLocaleLowerCase('en-US')\n      .replace(/[^a-z0-9:+#]+/g, '-')\n      .replace(/^-+/, '')\n      .replace(/-+$/, '')\n      .slice(0, 63);\n    if (sanitized) {\n      seen.add(sanitized);\n    }\n  }\n  return [...seen];\n};\n\nconst instanceEntityName = (instance: GrafanaInstanceConfig): string =>\n  sanitizeName(`grafana-instance-${instance.name}`);\n\nconst dashboardEntityName = (\n  instance: GrafanaInstanceConfig,\n  dashboard: GrafanaDashboard,\n): string => {\n  // Grafana uids are case-sensitive, but entity names are lowercased. When a\n  // uid contains uppercase characters, a stable hash of the original uid is\n  // appended so that uids differing only in case cannot collide.\n  const caseSafeUid =\n    dashboard.uid === dashboard.uid.toLocaleLowerCase('en-US')\n      ? dashboard.uid\n      : `${dashboard.uid}-${shortHash(dashboard.uid)}`;\n  return sanitizeName(`grafana-dashboard-${instance.name}-${caseSafeUid}`);\n};\n\n/**\n * Builds the catalog entities for a single Grafana instance and its dashboards.\n *\n * Every entity carries `backstage.io/managed-by-location` and\n * `backstage.io/managed-by-origin-location` annotations so the catalog accepts\n * them. Dashboards declare a `spec.dependsOn` on their instance Resource, which\n * produces `dependsOn`/`dependencyOf` relations between them.\n *\n * @public\n */\nexport function buildGrafanaEntities(\n  instance: GrafanaInstanceConfig,\n  dashboards: GrafanaDashboard[],\n  options: GrafanaEntityOptions,\n): ResourceEntity[] {\n  const locationRef = `grafana:${instance.name}`;\n  const commonAnnotations: Record<string, string> = {\n    [ANNOTATION_LOCATION]: locationRef,\n    [ANNOTATION_ORIGIN_LOCATION]: locationRef,\n    [GRAFANA_ANNOTATION_INSTANCE]: instance.name,\n  };\n  const systemSpec = options.system ? { system: options.system } : {};\n\n  const entities: ResourceEntity[] = [];\n\n  if (options.emitInstances) {\n    entities.push({\n      apiVersion: 'backstage.io/v1alpha1',\n      kind: 'Resource',\n      metadata: {\n        name: instanceEntityName(instance),\n        namespace: options.namespace,\n        title: instance.title,\n        annotations: { ...commonAnnotations },\n        links: [{ url: instance.baseUrl, title: 'Open Grafana' }],\n      },\n      spec: {\n        type: RESOURCE_TYPE_INSTANCE,\n        owner: options.defaultOwner,\n        ...systemSpec,\n      },\n    });\n  }\n\n  if (options.emitDashboards) {\n    for (const dashboard of dashboards) {\n      const tags = options.emitTags ? sanitizeTags(dashboard.tags) : [];\n      entities.push({\n        apiVersion: 'backstage.io/v1alpha1',\n        kind: 'Resource',\n        metadata: {\n          name: dashboardEntityName(instance, dashboard),\n          namespace: options.namespace,\n          title: dashboard.title,\n          annotations: {\n            ...commonAnnotations,\n            [GRAFANA_ANNOTATION_DASHBOARD_SELECTOR]: dashboard.title,\n          },\n          links: [{ url: dashboard.url, title: 'Open dashboard' }],\n          ...(tags.length ? { tags } : {}),\n        },\n        spec: {\n          type: RESOURCE_TYPE_DASHBOARD,\n          owner: options.defaultOwner,\n          ...(options.emitInstances\n            ? {\n                dependsOn: [\n                  `resource:${options.namespace}/${instanceEntityName(\n                    instance,\n                  )}`,\n                ],\n              }\n            : {}),\n          ...systemSpec,\n        },\n      });\n    }\n  }\n\n  return entities;\n}\n"],"names":["createHash","ANNOTATION_LOCATION","ANNOTATION_ORIGIN_LOCATION","GRAFANA_ANNOTATION_INSTANCE","GRAFANA_ANNOTATION_DASHBOARD_SELECTOR"],"mappings":"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"}

package/dist/config.cjs.js

@@ -0,0 +1,30 @@
+'use strict';
+
+var backendPluginApi = require('@backstage/backend-plugin-api');
+
+const DEFAULT_SCHEDULE = {
+  frequency: { minutes: 30 },
+  timeout: { minutes: 3 }
+};
+const DEFAULT_OWNER = "group:default/grafana";
+function readGrafanaDiscoveryConfig(rootConfig) {
+  const config = rootConfig.getOptionalConfig("grafana.catalog");
+  const scheduleConfig = config?.getOptionalConfig("schedule");
+  return {
+    schedule: scheduleConfig ? backendPluginApi.readSchedulerServiceTaskScheduleDefinitionFromConfig(scheduleConfig) : DEFAULT_SCHEDULE,
+    defaultOwner: config?.getOptionalString("defaultOwner") ?? DEFAULT_OWNER,
+    system: config?.getOptionalString("system"),
+    namespace: config?.getOptionalString("namespace") ?? "default",
+    emitInstances: config?.getOptionalBoolean("emitInstances") ?? true,
+    emitDashboards: config?.getOptionalBoolean("emitDashboards") ?? true,
+    emitTags: config?.getOptionalBoolean("emitTags") ?? true,
+    instances: config?.getOptionalStringArray("instances"),
+    filter: {
+      tags: config?.getOptionalStringArray("filter.tags"),
+      query: config?.getOptionalString("filter.query")
+    }
+  };
+}
+
+exports.readGrafanaDiscoveryConfig = readGrafanaDiscoveryConfig;
+//# sourceMappingURL=config.cjs.js.map

package/dist/config.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.cjs.js","sources":["../src/config.ts"],"sourcesContent":["/*\n * Copyright 2026 Cassidy Marble\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { Config } from '@backstage/config';\nimport {\n  readSchedulerServiceTaskScheduleDefinitionFromConfig,\n  SchedulerServiceTaskScheduleDefinition,\n} from '@backstage/backend-plugin-api';\nimport { GrafanaEntityOptions } from './buildEntities';\n\n/**\n * Filters narrowing which dashboards discovery ingests.\n *\n * @public\n */\nexport type GrafanaDiscoveryFilter = {\n  /** Only discover dashboards carrying all of these tags. */\n  tags?: string[];\n  /** Comma-separated title substrings; dashboards matching any are discovered. */\n  query?: string;\n};\n\n/**\n * The fully-resolved configuration for the Grafana catalog discovery module.\n *\n * @public\n */\nexport type GrafanaDiscoveryConfig = GrafanaEntityOptions & {\n  schedule: SchedulerServiceTaskScheduleDefinition;\n  /** Instance names to discover; `undefined` means every configured instance. */\n  instances?: string[];\n  /** Dashboard filter applied during discovery. */\n  filter: GrafanaDiscoveryFilter;\n};\n\nconst DEFAULT_SCHEDULE: SchedulerServiceTaskScheduleDefinition = {\n  frequency: { minutes: 30 },\n  timeout: { minutes: 3 },\n};\n\nconst DEFAULT_OWNER = 'group:default/grafana';\n\n/**\n * Reads the `grafana.catalog` configuration into a resolved\n * {@link GrafanaDiscoveryConfig}, applying defaults.\n *\n * @public\n */\nexport function readGrafanaDiscoveryConfig(\n  rootConfig: Config,\n): GrafanaDiscoveryConfig {\n  const config = rootConfig.getOptionalConfig('grafana.catalog');\n\n  const scheduleConfig = config?.getOptionalConfig('schedule');\n\n  return {\n    schedule: scheduleConfig\n      ? readSchedulerServiceTaskScheduleDefinitionFromConfig(scheduleConfig)\n      : DEFAULT_SCHEDULE,\n    defaultOwner: config?.getOptionalString('defaultOwner') ?? DEFAULT_OWNER,\n    system: config?.getOptionalString('system'),\n    namespace: config?.getOptionalString('namespace') ?? 'default',\n    emitInstances: config?.getOptionalBoolean('emitInstances') ?? true,\n    emitDashboards: config?.getOptionalBoolean('emitDashboards') ?? true,\n    emitTags: config?.getOptionalBoolean('emitTags') ?? true,\n    instances: config?.getOptionalStringArray('instances'),\n    filter: {\n      tags: config?.getOptionalStringArray('filter.tags'),\n      query: config?.getOptionalString('filter.query'),\n    },\n  };\n}\n"],"names":["readSchedulerServiceTaskScheduleDefinitionFromConfig"],"mappings":";;;;AAgDA,MAAM,gBAAA,GAA2D;AAAA,EAC/D,SAAA,EAAW,EAAE,OAAA,EAAS,EAAA,EAAG;AAAA,EACzB,OAAA,EAAS,EAAE,OAAA,EAAS,CAAA;AACtB,CAAA;AAEA,MAAM,aAAA,GAAgB,uBAAA;AAQf,SAAS,2BACd,UAAA,EACwB;AACxB,EAAA,MAAM,MAAA,GAAS,UAAA,CAAW,iBAAA,CAAkB,iBAAiB,CAAA;AAE7D,EAAA,MAAM,cAAA,GAAiB,MAAA,EAAQ,iBAAA,CAAkB,UAAU,CAAA;AAE3D,EAAA,OAAO;AAAA,IACL,QAAA,EAAU,cAAA,GACNA,qEAAA,CAAqD,cAAc,CAAA,GACnE,gBAAA;AAAA,IACJ,YAAA,EAAc,MAAA,EAAQ,iBAAA,CAAkB,cAAc,CAAA,IAAK,aAAA;AAAA,IAC3D,MAAA,EAAQ,MAAA,EAAQ,iBAAA,CAAkB,QAAQ,CAAA;AAAA,IAC1C,SAAA,EAAW,MAAA,EAAQ,iBAAA,CAAkB,WAAW,CAAA,IAAK,SAAA;AAAA,IACrD,aAAA,EAAe,MAAA,EAAQ,kBAAA,CAAmB,eAAe,CAAA,IAAK,IAAA;AAAA,IAC9D,cAAA,EAAgB,MAAA,EAAQ,kBAAA,CAAmB,gBAAgB,CAAA,IAAK,IAAA;AAAA,IAChE,QAAA,EAAU,MAAA,EAAQ,kBAAA,CAAmB,UAAU,CAAA,IAAK,IAAA;AAAA,IACpD,SAAA,EAAW,MAAA,EAAQ,sBAAA,CAAuB,WAAW,CAAA;AAAA,IACrD,MAAA,EAAQ;AAAA,MACN,IAAA,EAAM,MAAA,EAAQ,sBAAA,CAAuB,aAAa,CAAA;AAAA,MAClD,KAAA,EAAO,MAAA,EAAQ,iBAAA,CAAkB,cAAc;AAAA;AACjD,GACF;AACF;;"}

package/dist/index.cjs.js

@@ -0,0 +1,16 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var module$1 = require('./module.cjs.js');
+var GrafanaEntityProvider = require('./GrafanaEntityProvider.cjs.js');
+var buildEntities = require('./buildEntities.cjs.js');
+var config = require('./config.cjs.js');
+
+
+
+exports.default = module$1.catalogModuleGrafana;
+exports.GrafanaEntityProvider = GrafanaEntityProvider.GrafanaEntityProvider;
+exports.buildGrafanaEntities = buildEntities.buildGrafanaEntities;
+exports.readGrafanaDiscoveryConfig = config.readGrafanaDiscoveryConfig;
+//# sourceMappingURL=index.cjs.js.map

package/dist/index.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;"}

package/dist/index.d.ts

@@ -0,0 +1,127 @@
+import * as _backstage_backend_plugin_api from '@backstage/backend-plugin-api';
+import { SchedulerServiceTaskScheduleDefinition, LoggerService, SchedulerService, SchedulerServiceTaskRunner } from '@backstage/backend-plugin-api';
+import { Config } from '@backstage/config';
+import { EntityProvider, EntityProviderConnection } from '@backstage/plugin-catalog-node';
+import { GrafanaInstanceConfig, GrafanaClient } from '@marble-sh/backstage-plugin-grafana-node';
+import { ResourceEntity } from '@backstage/catalog-model';
+import { GrafanaDashboard } from '@marble-sh/backstage-plugin-grafana-common';
+
+/**
+ * Catalog backend module that discovers Grafana instances and dashboards as
+ * catalog `Resource` entities.
+ *
+ * @public
+ */
+declare const catalogModuleGrafana: _backstage_backend_plugin_api.BackendFeature;
+
+/**
+ * Options controlling how Grafana data is turned into catalog entities.
+ *
+ * @public
+ */
+type GrafanaEntityOptions = {
+    /** The `spec.owner` assigned to every generated entity. */
+    defaultOwner: string;
+    /** An optional `spec.system` assigned to every generated entity. */
+    system?: string;
+    /** The catalog namespace the generated entities live in. */
+    namespace: string;
+    /** Whether to emit a Resource for the Grafana instance. */
+    emitInstances: boolean;
+    /** Whether to emit a Resource for each dashboard. */
+    emitDashboards: boolean;
+    /** Whether dashboard tags are copied onto the generated entities. */
+    emitTags: boolean;
+};
+/**
+ * Builds the catalog entities for a single Grafana instance and its dashboards.
+ *
+ * Every entity carries `backstage.io/managed-by-location` and
+ * `backstage.io/managed-by-origin-location` annotations so the catalog accepts
+ * them. Dashboards declare a `spec.dependsOn` on their instance Resource, which
+ * produces `dependsOn`/`dependencyOf` relations between them.
+ *
+ * @public
+ */
+declare function buildGrafanaEntities(instance: GrafanaInstanceConfig, dashboards: GrafanaDashboard[], options: GrafanaEntityOptions): ResourceEntity[];
+
+/**
+ * Filters narrowing which dashboards discovery ingests.
+ *
+ * @public
+ */
+type GrafanaDiscoveryFilter = {
+    /** Only discover dashboards carrying all of these tags. */
+    tags?: string[];
+    /** Comma-separated title substrings; dashboards matching any are discovered. */
+    query?: string;
+};
+/**
+ * The fully-resolved configuration for the Grafana catalog discovery module.
+ *
+ * @public
+ */
+type GrafanaDiscoveryConfig = GrafanaEntityOptions & {
+    schedule: SchedulerServiceTaskScheduleDefinition;
+    /** Instance names to discover; `undefined` means every configured instance. */
+    instances?: string[];
+    /** Dashboard filter applied during discovery. */
+    filter: GrafanaDiscoveryFilter;
+};
+/**
+ * Reads the `grafana.catalog` configuration into a resolved
+ * {@link GrafanaDiscoveryConfig}, applying defaults.
+ *
+ * @public
+ */
+declare function readGrafanaDiscoveryConfig(rootConfig: Config): GrafanaDiscoveryConfig;
+
+/**
+ * A catalog `EntityProvider` that discovers Grafana instances and their
+ * dashboards, emitting a `Resource` for each and linking every dashboard to its
+ * instance via `spec.dependsOn`.
+ *
+ * @public
+ */
+declare class GrafanaEntityProvider implements EntityProvider {
+    private readonly instances;
+    private readonly discovery;
+    private readonly logger;
+    private readonly taskRunner;
+    private readonly clientFactory;
+    private connection?;
+    private readonly lastGoodEntities;
+    /**
+     * Builds a provider from the root config and the logger/scheduler services.
+     *
+     * Throws if `grafana.catalog.instances` names an instance that is not
+     * configured under `grafana.instances`.
+     */
+    static fromConfig(rootConfig: Config, options: {
+        logger: LoggerService;
+        scheduler: SchedulerService;
+    }): GrafanaEntityProvider;
+    constructor(options: {
+        instances: GrafanaInstanceConfig[];
+        discovery: GrafanaDiscoveryConfig;
+        logger: LoggerService;
+        taskRunner: SchedulerServiceTaskRunner;
+        clientFactory?: (instance: GrafanaInstanceConfig) => GrafanaClient;
+    });
+    /** The unique, stable name identifying this provider's entity bucket. */
+    getProviderName(): string;
+    /** Stores the connection and schedules the recurring discovery task. */
+    connect(connection: EntityProviderConnection): Promise<void>;
+    /**
+     * Reads every configured instance and replaces the provider's entities.
+     *
+     * When an instance fails transiently, its previously discovered entities are
+     * re-emitted so the full mutation does not remove them from the catalog. If
+     * an instance fails before any successful read, the whole refresh is aborted
+     * (leaving the catalog untouched) and retried on the next scheduled run.
+     */
+    refresh(): Promise<void>;
+}
+
+export { GrafanaEntityProvider, buildGrafanaEntities, catalogModuleGrafana as default, readGrafanaDiscoveryConfig };
+export type { GrafanaDiscoveryConfig, GrafanaDiscoveryFilter, GrafanaEntityOptions };

package/dist/module.cjs.js

@@ -0,0 +1,28 @@
+'use strict';
+
+var backendPluginApi = require('@backstage/backend-plugin-api');
+var pluginCatalogNode = require('@backstage/plugin-catalog-node');
+var GrafanaEntityProvider = require('./GrafanaEntityProvider.cjs.js');
+
+const catalogModuleGrafana = backendPluginApi.createBackendModule({
+  pluginId: "catalog",
+  moduleId: "grafana",
+  register(env) {
+    env.registerInit({
+      deps: {
+        logger: backendPluginApi.coreServices.logger,
+        config: backendPluginApi.coreServices.rootConfig,
+        scheduler: backendPluginApi.coreServices.scheduler,
+        catalog: pluginCatalogNode.catalogProcessingExtensionPoint
+      },
+      async init({ logger, config, scheduler, catalog }) {
+        catalog.addEntityProvider(
+          GrafanaEntityProvider.GrafanaEntityProvider.fromConfig(config, { logger, scheduler })
+        );
+      }
+    });
+  }
+});
+
+exports.catalogModuleGrafana = catalogModuleGrafana;
+//# sourceMappingURL=module.cjs.js.map

package/dist/module.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"module.cjs.js","sources":["../src/module.ts"],"sourcesContent":["/*\n * Copyright 2026 Cassidy Marble\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  coreServices,\n  createBackendModule,\n} from '@backstage/backend-plugin-api';\nimport { catalogProcessingExtensionPoint } from '@backstage/plugin-catalog-node';\nimport { GrafanaEntityProvider } from './GrafanaEntityProvider';\n\n/**\n * Catalog backend module that discovers Grafana instances and dashboards as\n * catalog `Resource` entities.\n *\n * @public\n */\nexport const catalogModuleGrafana = createBackendModule({\n  pluginId: 'catalog',\n  moduleId: 'grafana',\n  register(env) {\n    env.registerInit({\n      deps: {\n        logger: coreServices.logger,\n        config: coreServices.rootConfig,\n        scheduler: coreServices.scheduler,\n        catalog: catalogProcessingExtensionPoint,\n      },\n      async init({ logger, config, scheduler, catalog }) {\n        catalog.addEntityProvider(\n          GrafanaEntityProvider.fromConfig(config, { logger, scheduler }),\n        );\n      },\n    });\n  },\n});\n"],"names":["createBackendModule","coreServices","catalogProcessingExtensionPoint","GrafanaEntityProvider"],"mappings":";;;;;;AA6BO,MAAM,uBAAuBA,oCAAA,CAAoB;AAAA,EACtD,QAAA,EAAU,SAAA;AAAA,EACV,QAAA,EAAU,SAAA;AAAA,EACV,SAAS,GAAA,EAAK;AACZ,IAAA,GAAA,CAAI,YAAA,CAAa;AAAA,MACf,IAAA,EAAM;AAAA,QACJ,QAAQC,6BAAA,CAAa,MAAA;AAAA,QACrB,QAAQA,6BAAA,CAAa,UAAA;AAAA,QACrB,WAAWA,6BAAA,CAAa,SAAA;AAAA,QACxB,OAAA,EAASC;AAAA,OACX;AAAA,MACA,MAAM,IAAA,CAAK,EAAE,QAAQ,MAAA,EAAQ,SAAA,EAAW,SAAQ,EAAG;AACjD,QAAA,OAAA,CAAQ,iBAAA;AAAA,UACNC,4CAAsB,UAAA,CAAW,MAAA,EAAQ,EAAE,MAAA,EAAQ,WAAW;AAAA,SAChE;AAAA,MACF;AAAA,KACD,CAAA;AAAA,EACH;AACF,CAAC;;"}

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@marble-sh/backstage-plugin-catalog-backend-module-grafana",
+  "version": "0.2.0",
+  "description": "Catalog backend module that discovers Grafana instances and dashboards as catalog entities",
+  "main": "./dist/index.cjs.js",
+  "types": "./dist/index.d.ts",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "backstage": {
+    "role": "backend-plugin-module",
+    "pluginId": "catalog",
+    "pluginPackage": "@backstage/plugin-catalog-backend",
+    "features": {
+      ".": "@backstage/BackendFeature"
+    }
+  },
+  "sideEffects": false,
+  "configSchema": "config.schema.json",
+  "scripts": {
+    "start": "backstage-cli package start",
+    "build": "backstage-cli package build",
+    "clean": "backstage-cli package clean",
+    "lint": "backstage-cli package lint",
+    "prepack": "backstage-cli package prepack",
+    "postpack": "backstage-cli package postpack",
+    "test": "backstage-cli package test"
+  },
+  "dependencies": {
+    "@backstage/backend-plugin-api": "backstage:^",
+    "@backstage/catalog-model": "backstage:^",
+    "@backstage/config": "backstage:^",
+    "@backstage/errors": "backstage:^",
+    "@backstage/plugin-catalog-node": "backstage:^",
+    "@marble-sh/backstage-plugin-grafana-common": "workspace:^",
+    "@marble-sh/backstage-plugin-grafana-node": "workspace:^"
+  },
+  "devDependencies": {
+    "@backstage/backend-test-utils": "backstage:^",
+    "@backstage/cli": "backstage:^",
+    "@backstage/types": "backstage:^"
+  },
+  "files": [
+    "dist",
+    "config.schema.json"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/marble-sh/backstage-plugins-grafana",
+    "directory": "plugins/catalog-backend-module-grafana"
+  },
+  "keywords": [
+    "backstage",
+    "plugin",
+    "grafana",
+    "catalog"
+  ],
+  "author": "Cassidy Marble",
+  "homepage": "https://github.com/marble-sh/backstage-plugins-grafana/tree/main/plugins/catalog-backend-module-grafana",
+  "bugs": "https://github.com/marble-sh/backstage-plugins-grafana/issues",
+  "exports": {
+    ".": {
+      "backstage": "@backstage/BackendFeature",
+      "require": "./dist/index.cjs.js",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.cjs.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {
+      "package.json": [
+        "package.json"
+      ]
+    }
+  }
+}