From d2882d147fc83933b88e2adbac121ea255fffb02 Mon Sep 17 00:00:00 2001
From: Tomas Dabasinskas <tomas@dabasinskas.net>
Date: Sun, 5 Feb 2023 22:26:25 +0200
Subject: [PATCH] Add README

Signed-off-by: Tomas Dabasinskas <tomas@dabasinskas.net>
---
 .../catalog-backend-module-puppetdb/README.md | 95 +++++++++++++++++--
 .../src/puppet/transformers.ts                |  2 +-
 2 files changed, 87 insertions(+), 10 deletions(-)

diff --git a/plugins/catalog-backend-module-puppetdb/README.md b/plugins/catalog-backend-module-puppetdb/README.md
index c66627fa8b..9fea95d61e 100644
--- a/plugins/catalog-backend-module-puppetdb/README.md
+++ b/plugins/catalog-backend-module-puppetdb/README.md
@@ -1,14 +1,91 @@
-# catalog-backend-module-puppetdb
+# Catalog Backend Module for Puppet
 
-Welcome to the catalog-backend-module-puppetdb backend plugin!
+This is an extension module to the `plugin-catalog-backend` plugin, providing an `PuppetDbEntityProvider` that can be used to ingest
+[Resource entities](https://backstage.io/docs/features/software-catalog/descriptor-format#kind-resource) from a
+[PuppetDB](https://www.puppet.com/docs/puppet/6/puppetdb_overview.html) instance(s). This provider is useful if you want to import nodes
+from your PuppetDB into Backstage.
 
-_This plugin was created through the Backstage CLI_
+## Installation
 
-## Getting started
+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:
 
-Your plugin has been added to the example app in this repository, meaning you'll be able to access it by running `yarn
-start` in the root directory, and then navigating to [/catalog-backend-module-puppetdb](http://localhost:3000/catalog-backend-module-puppetdb).
+```bash
+# From your Backstage root directory
+yarn add --cwd packages/backend @backstage/plugin-catalog-backend-module-puppetdb
+```
 
-You can also serve the plugin in isolation by running `yarn start` in the plugin directory.
-This method of serving the plugin provides quicker iteration speed and a faster startup and hot reloads.
-It is only meant for local development, and the setup for it can be found inside the [/dev](/dev) directory.
+Update the catalog plugin initialization in your backend to add the provider and schedule it:
+
+```diff
++ 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.
+
+## Configuration
+
+The following configuration is an example of how a setup could look for importing nodes from an internal PuppetDB instance:
+
+```yaml
+catalog:
+  providers:
+    puppet:
+      default:
+        # (Required) The host of PuppetDB API instance:
+        host: https://puppetdb.example.com
+
+        # (Optional) Query to filter PuppetDB nodes:
+        #query: '["=","certname","example.com"]'
+```
+
+## Customize the Provider
+
+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:
+2.
+
+```ts
+export const customResourceTransformer: ResourceTransformer = async (
+  node,
+  config,
+): Promise<GroupEntity | undefined> => {
+  // Transofrmations 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:
+
+```ts
+const puppetDbEntityProvider = PuppetDbEntityProvider.fromConfig(env.config, {
+  logger: env.logger,
+  schedule: env.scheduler.createScheduledTaskRunner({
+    frequency: { minutes: 10 },
+    timeout: { minutes: 50 },
+    initialDelay: { seconds: 15 },
+  }),
+  transformer: customResourceTransformer,
+});
+```
diff --git a/plugins/catalog-backend-module-puppetdb/src/puppet/transformers.ts b/plugins/catalog-backend-module-puppetdb/src/puppet/transformers.ts
index d99d89b1cf..2062f8e828 100644
--- a/plugins/catalog-backend-module-puppetdb/src/puppet/transformers.ts
+++ b/plugins/catalog-backend-module-puppetdb/src/puppet/transformers.ts
@@ -31,7 +31,7 @@ import { ANNOTATION_PUPPET_CERTNAME, DEFAULT_ENTITY_OWNER } from './constants';
 export const defaultResourceTransformer: ResourceTransformer = async (
   node,
   _config,
-) => {
+): Promise<ResourceEntity | undefined> => {
   const certName = node.certname.toLowerCase();
   const type = node.facts?.data?.find(e => e.name === 'is_virtual')?.value
     ? 'virtual-machine'