This is an extension module to the plugin-catalog-backend plugin, providing an PuppetDbEntityProvider that can be used to ingest Resource entities from a PuppetDB instance(s). This provider is useful if you want to import nodes from your PuppetDB into Backstage.

The provider is not installed by default, therefore you have to add a dependency to @backstage/plugin-catalog-backend-module-puppetdb to your backend package:

# From your Backstage root directory
yarn --cwd packages/backend add @backstage/plugin-catalog-backend-module-puppetdb

Update the catalog plugin initialization in your backend to add the provider and schedule it:

+ import { PuppetDbEntityProvider } from '@backstage/plugin-catalog-backend-module-puppetdb';

 export default async function createPlugin(
   env: PluginEnvironment,
 ): Promise<Router> {
   const builder = await CatalogBuilder.create(env);

+  builder.addEntityProvider(
+    PuppetDbEntityProvider.fromConfig(env.config, {
+      logger: env.logger,
+      schedule: env.scheduler.createScheduledTaskRunner({
+        frequency: { minutes: 10 },
+        timeout: { minutes: 50 },
+        initialDelay: { seconds: 15 }
+      }),
+    })
+  );

After this, you also have to add some configuration in your app-config that describes what you want to import for that target.

The following configuration is an example of how a setup could look for importing nodes from an internal PuppetDB instance:

catalog:
  providers:
    puppetdb:
      default:
        # (Required) The base URL of PuppetDB API instance:
        baseUrl: https://puppetdb.example.com

        # (Optional) Query to filter PuppetDB nodes:
        #query: '["=","certname","example.com"]'

The default ingestion behaviour will likely not work for all use cases - you will want to set proper Owner, System and other fields for the ingested resources. In case you want to customize the ingested entities, the provider allows to pass a transformer for resources. Here we will show an example of overriding the default transformer.

1. Create a transformer:

export const customResourceTransformer: ResourceTransformer = async (
  node,
  config,
): Promise<ResourceEntity | undefined> => {
  // Transformations may change namespace, owner, change entity naming pattern, add labels, annotations, etc.

  // Create the Resource Entity on your own, or wrap the default transformer
  return await defaultResourceTransformer(node, config);
};

2. Configure the provider with the transformer:

  builder.addEntityProvider(
    PuppetDbEntityProvider.fromConfig(env.config, {
      logger: env.logger,
+     transformer: customResourceTransformer,
      schedule: env.scheduler.createScheduledTaskRunner({
        frequency: { minutes: 10 },
        timeout: { minutes: 50 },
        initialDelay: { seconds: 15 }
      }),
    })
  );