From 92f582349847800e31763548ef6c40086a1fbd11 Mon Sep 17 00:00:00 2001
From: aramissennyeydd <aramis.sennyey@doordash.com>
Date: Mon, 29 Sep 2025 10:19:47 -0400
Subject: [PATCH] add docs

Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com>
---
 .../core-services/instance-metadata.md        | 44 +++++++++++++++++++
 1 file changed, 44 insertions(+)
 create mode 100644 docs/backend-system/core-services/instance-metadata.md

diff --git a/docs/backend-system/core-services/instance-metadata.md b/docs/backend-system/core-services/instance-metadata.md
new file mode 100644
index 0000000000..8a5818e2bc
--- /dev/null
+++ b/docs/backend-system/core-services/instance-metadata.md
@@ -0,0 +1,44 @@
+---
+id: instance-metadata
+title: Instance Metadata Service
+sidebar_label: Instance Metadata
+description: Documentation for the Instance Metadata service
+---
+
+The instance metadata service provides information about the running Backstage backend instance. Currently, it provides a list of all installed backend plugins.
+
+:::note Note
+
+The instance metadata service only provides information about the specific Backstage instance you're running on. In more complex deployments with multiple Backstage instances, this service will not provide a complete list of all plugins across all instances.
+
+:::
+
+## Using the service
+
+The following example shows how to use the instance metadata service in your `example` backend plugin to access the list of installed backend plugins.
+
+```ts
+import {
+  coreServices,
+  createBackendPlugin,
+} from '@backstage/backend-plugin-api';
+
+createBackendPlugin({
+  pluginId: 'example',
+  register(env) {
+    env.registerInit({
+      deps: {
+        instanceMetadata: coreServices.instanceMetadata,
+      },
+      async init({ instanceMetadata }) {
+        const plugins = instanceMetadata.getInstalledPlugins();
+        console.log('Installed plugins:', plugins);
+      },
+    });
+  },
+});
+```
+
+## Dynamic plugin registration
+
+The instance metadata service picks up plugins that are registered at start time through a `backend.start()` call. You need to restart the running backend instance to pick up newly installed plugins.