@backstage/plugin-catalog-backend-module-puppetdb 0.0.0-nightly-20230304023150

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# @backstage/plugin-catalog-backend-module-puppetdb
+
+## 0.0.0-nightly-20230304023150
+
+### Minor Changes
+
+- a1efcf9a658: Initial version of the plugin.
+
+### Patch Changes
+
+- Updated dependencies
+  - @backstage/plugin-catalog-backend@0.0.0-nightly-20230304023150
+  - @backstage/errors@0.0.0-nightly-20230304023150
+  - @backstage/backend-tasks@0.0.0-nightly-20230304023150
+  - @backstage/backend-common@0.0.0-nightly-20230304023150
+  - @backstage/catalog-model@0.0.0-nightly-20230304023150
+  - @backstage/config@0.0.0-nightly-20230304023150
+  - @backstage/types@1.0.2

package/README.md

@@ -0,0 +1,90 @@
+# Catalog Backend Module for Puppet
+
+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.
+
+## Installation
+
+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:
+
+```bash
+# From your Backstage root directory
+yarn add --cwd packages/backend @backstage/plugin-catalog-backend-module-puppetdb
+```
+
+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:
+    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"]'
+```
+
+## 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:
+
+```ts
+export const customResourceTransformer: ResourceTransformer = async (
+  node,
+  config,
+): Promise<GroupEntity | 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:
+
+```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,
+});
+```

package/config.d.ts

@@ -0,0 +1,68 @@
+/*
+ * Copyright 2020 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { TaskScheduleDefinition } from '@backstage/backend-tasks';
+
+/**
+ * Represents the configuration for the Backstage.
+ */
+export interface Config {
+  /**
+   * Configuration for the catalog.
+   */
+  catalog?: {
+    /**
+     * Configuration for the providers.
+     */
+    providers?: {
+      /**
+       * PuppetDB Entity Provider configuration. Uses "default" as default ID for the single config variant.
+       */
+      puppetdb?:
+        | {
+            /**
+             * (Required) The base URL of PuppetDB API instance.
+             */
+            baseUrl: string;
+            /**
+             * (Optional) PQL query to filter PuppetDB nodes.
+             */
+            query?: string;
+            /**
+             * (Optional) Task schedule definition for the refresh.
+             */
+            schedule?: TaskScheduleDefinition;
+          }
+        | Record<
+            string,
+            {
+              /**
+               * (Required) The base URL of PuppetDB API instance.
+               */
+              baseUrl: string;
+              /**
+               * (Optional) PQL query to filter PuppetDB nodes.
+               */
+              query?: string;
+              /**
+               * (Optional) Task schedule definition for the refresh.
+               */
+              schedule?: TaskScheduleDefinition;
+            }
+          >;
+    };
+  };
+}

package/dist/index.cjs.js

@@ -0,0 +1,275 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var backendTasks = require('@backstage/backend-tasks');
+var uuid = require('uuid');
+var catalogModel = require('@backstage/catalog-model');
+var _ = require('@backstage/catalog-model/');
+var lodash = require('lodash');
+var fetch = require('node-fetch');
+var errors = require('@backstage/errors');
+
+function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
+
+function _interopNamespace(e) {
+  if (e && e.__esModule) return e;
+  var n = Object.create(null);
+  if (e) {
+    Object.keys(e).forEach(function (k) {
+      if (k !== 'default') {
+        var d = Object.getOwnPropertyDescriptor(e, k);
+        Object.defineProperty(n, k, d.get ? d : {
+          enumerable: true,
+          get: function () { return e[k]; }
+        });
+      }
+    });
+  }
+  n["default"] = e;
+  return Object.freeze(n);
+}
+
+var uuid__namespace = /*#__PURE__*/_interopNamespace(uuid);
+var fetch__default = /*#__PURE__*/_interopDefaultLegacy(fetch);
+
+const DEFAULT_PROVIDER_ID = "default";
+
+function readProviderConfigs(config) {
+  const providersConfig = config.getOptionalConfig(
+    "catalog.providers.puppetdb"
+  );
+  if (!providersConfig) {
+    return [];
+  }
+  if (providersConfig.has("baseUrl")) {
+    return [readProviderConfig(DEFAULT_PROVIDER_ID, providersConfig)];
+  }
+  return providersConfig.keys().map((id) => {
+    return readProviderConfig(id, providersConfig.getConfig(id));
+  });
+}
+function readProviderConfig(id, config) {
+  const baseUrl = config.getString("baseUrl").replace(/\/+$/, "");
+  const query = config.getOptionalString("query");
+  const schedule = config.has("schedule") ? backendTasks.readTaskScheduleDefinitionFromConfig(config.getConfig("schedule")) : void 0;
+  return {
+    id,
+    baseUrl,
+    query,
+    schedule
+  };
+}
+
+const ANNOTATION_PUPPET_CERTNAME = "puppet.com/certname";
+const ENDPOINT_FACTSETS = "pdb/query/v4/factsets";
+const ENDPOINT_NODES = "pdb/query/v4/nodes";
+const DEFAULT_ENTITY_OWNER = "unknown";
+
+const defaultResourceTransformer = async (node, _config) => {
+  var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j;
+  const certName = node.certname.toLocaleLowerCase("en-US");
+  const type = ((_c = (_b = (_a = node.facts) == null ? void 0 : _a.data) == null ? void 0 : _b.find((e) => e.name === "is_virtual")) == null ? void 0 : _c.value) ? "virtual-machine" : "physical-server";
+  const kernel = (_f = (_e = (_d = node.facts) == null ? void 0 : _d.data) == null ? void 0 : _e.find((e) => e.name === "kernel")) == null ? void 0 : _f.value;
+  return {
+    apiVersion: "backstage.io/v1beta1",
+    kind: "Resource",
+    metadata: {
+      name: certName,
+      annotations: {
+        [ANNOTATION_PUPPET_CERTNAME]: certName
+      },
+      namespace: catalogModel.DEFAULT_NAMESPACE,
+      description: (_j = (_i = (_h = (_g = node.facts) == null ? void 0 : _g.data) == null ? void 0 : _h.find((e) => e.name === "ipaddress")) == null ? void 0 : _i.value) == null ? void 0 : _j.toString(),
+      tags: kernel ? [kernel.toString().toLocaleLowerCase("en-US")] : []
+    },
+    spec: {
+      type,
+      owner: DEFAULT_ENTITY_OWNER,
+      dependsOn: [],
+      dependencyOf: []
+    }
+  };
+};
+
+async function readPuppetNodes(config, opts) {
+  var _a;
+  const transformFn = (_a = opts == null ? void 0 : opts.transformer) != null ? _a : defaultResourceTransformer;
+  const url = new URL(ENDPOINT_FACTSETS, config.baseUrl);
+  if (config.query) {
+    url.searchParams.set("query", config.query);
+  }
+  if (opts == null ? void 0 : opts.logger) {
+    opts.logger.debug("Reading nodes from PuppetDB", { url: url.toString() });
+  }
+  const response = await fetch__default["default"](url.toString(), {
+    method: "GET",
+    headers: {
+      "Content-Type": "application/json",
+      Accept: "application/json"
+    }
+  });
+  if (!response.ok) {
+    throw await errors.ResponseError.fromResponse(response);
+  }
+  const nodes = await response.json();
+  const entities = [];
+  for (const node of nodes) {
+    const entity = await transformFn(node, config);
+    if (entity) {
+      entities.push(entity);
+    }
+  }
+  return entities;
+}
+
+class PuppetDbEntityProvider {
+  /**
+   * Creates instances of {@link PuppetDbEntityProvider} from a configuration.
+   *
+   * @param config - The configuration to read provider information from.
+   * @param deps - The dependencies for  {@link PuppetDbEntityProvider}.
+   *
+   * @returns A list of {@link PuppetDbEntityProvider} instances.
+   */
+  static fromConfig(config, deps) {
+    if (!deps.schedule && !deps.scheduler) {
+      throw new Error("Either schedule or scheduler must be provided.");
+    }
+    return readProviderConfigs(config).map((providerConfig) => {
+      var _a, _b;
+      if (!deps.schedule && !providerConfig.schedule) {
+        throw new Error(
+          `No schedule provided neither via code nor config for puppet-provider:${providerConfig.id}.`
+        );
+      }
+      const taskRunner = (_a = deps.schedule) != null ? _a : deps.scheduler.createScheduledTaskRunner(providerConfig.schedule);
+      const transformer = (_b = deps.transformer) != null ? _b : defaultResourceTransformer;
+      return new PuppetDbEntityProvider(
+        providerConfig,
+        deps.logger,
+        taskRunner,
+        transformer
+      );
+    });
+  }
+  /**
+   * Creates an instance of {@link PuppetDbEntityProvider}.
+   *
+   * @param config - Configuration of the provider.
+   * @param logger - The instance of a {@link Logger}.
+   * @param taskRunner - The instance of {@link TaskRunner}.
+   * @param transformer - A {@link ResourceTransformer} function.
+   *
+   * @private
+   */
+  constructor(config, logger, taskRunner, transformer) {
+    this.config = config;
+    this.logger = logger.child({
+      target: this.getProviderName()
+    });
+    this.scheduleFn = this.createScheduleFn(taskRunner);
+    this.transformer = transformer;
+  }
+  /** {@inheritdoc @backstage/plugin-catalog-backend#EntityProvider.connect} */
+  async connect(connection) {
+    this.connection = connection;
+    await this.scheduleFn();
+  }
+  /** {@inheritdoc @backstage/plugin-catalog-backend#EntityProvider.getProviderName} */
+  getProviderName() {
+    return `puppetdb-provider:${this.config.id}`;
+  }
+  /**
+   * Creates a function that can be used to schedule a refresh of the catalog.
+   *
+   * @param taskRunner - The instance of {@link TaskRunner}.
+   *
+   * @private
+   */
+  createScheduleFn(taskRunner) {
+    return async () => {
+      const taskId = `${this.getProviderName()}:refresh`;
+      return taskRunner.run({
+        id: taskId,
+        fn: async () => {
+          const logger = this.logger.child({
+            class: PuppetDbEntityProvider.prototype.constructor.name,
+            taskId,
+            taskInstanceId: uuid__namespace.v4()
+          });
+          try {
+            await this.refresh(logger);
+          } catch (error) {
+            logger.error(`${this.getProviderName()} refresh failed`, error);
+          }
+        }
+      });
+    };
+  }
+  /**
+   * Refreshes the catalog by reading nodes from PuppetDB and registering them as Resource Entities.
+   *
+   * @param logger - The instance of a Logger.
+   */
+  async refresh(logger) {
+    if (!this.connection) {
+      throw new Error("Not initialized");
+    }
+    const { markReadComplete } = trackProgress(logger);
+    const entities = await readPuppetNodes(this.config, {
+      logger,
+      transformer: this.transformer
+    });
+    const { markCommitComplete } = markReadComplete(entities);
+    await this.connection.applyMutation({
+      type: "full",
+      entities: [...entities].map((entity) => ({
+        locationKey: this.getProviderName(),
+        entity: withLocations(this.config.baseUrl, entity)
+      }))
+    });
+    markCommitComplete(entities);
+  }
+}
+function withLocations(baseUrl, entity) {
+  var _a;
+  const location = `${baseUrl}/${ENDPOINT_NODES}/${(_a = entity.metadata) == null ? void 0 : _a.name}`;
+  return lodash.merge(
+    {
+      metadata: {
+        annotations: {
+          [_.ANNOTATION_LOCATION]: `url:${location}`,
+          [_.ANNOTATION_ORIGIN_LOCATION]: `url:${location}`
+        }
+      }
+    },
+    entity
+  );
+}
+function trackProgress(logger) {
+  let timestamp = Date.now();
+  function markReadComplete(entities) {
+    var _a;
+    const readDuration = ((Date.now() - timestamp) / 1e3).toFixed(1);
+    timestamp = Date.now();
+    logger.info(
+      `Read ${(_a = entities == null ? void 0 : entities.length) != null ? _a : 0} in ${readDuration} seconds. Committing...`
+    );
+    return { markCommitComplete };
+  }
+  function markCommitComplete(entities) {
+    var _a;
+    const commitDuration = ((Date.now() - timestamp) / 1e3).toFixed(1);
+    logger.info(
+      `Committed ${(_a = entities == null ? void 0 : entities.length) != null ? _a : 0} in ${commitDuration} seconds.`
+    );
+  }
+  return { markReadComplete };
+}
+
+exports.ANNOTATION_PUPPET_CERTNAME = ANNOTATION_PUPPET_CERTNAME;
+exports.DEFAULT_PROVIDER_ID = DEFAULT_PROVIDER_ID;
+exports.PuppetDbEntityProvider = PuppetDbEntityProvider;
+exports.defaultResourceTransformer = defaultResourceTransformer;
+//# sourceMappingURL=index.cjs.js.map

package/dist/index.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs.js","sources":["../src/providers/constants.ts","../src/providers/PuppetDbEntityProviderConfig.ts","../src/puppet/constants.ts","../src/puppet/transformers.ts","../src/puppet/read.ts","../src/providers/PuppetDbEntityProvider.ts"],"sourcesContent":["/*\n * Copyright 2020 The Backstage Authors\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\n/**\n * Name of the default provider when a using a simple configuration.\n *\n * @public\n */\nexport const DEFAULT_PROVIDER_ID = 'default';\n","/*\n * Copyright 2021 The Backstage Authors\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  readTaskScheduleDefinitionFromConfig,\n  TaskScheduleDefinition,\n} from '@backstage/backend-tasks';\nimport { Config } from '@backstage/config';\nimport { DEFAULT_PROVIDER_ID } from './constants';\n\n/**\n * Configuration of {@link PuppetDbEntityProvider}.\n *\n * @public\n */\nexport type PuppetDbEntityProviderConfig = {\n  /**\n   * ID of the provider.\n   */\n  id: string;\n  /**\n   * (Required) The base URL of PuppetDB API instance.\n   */\n  baseUrl: string;\n  /**\n   * (Optional) PQL query to filter PuppetDB nodes.\n   */\n  query?: string;\n  /**\n   * (Optional) Task schedule definition for the refresh.\n   */\n  schedule?: TaskScheduleDefinition;\n};\n\n/**\n * Reads the configuration of the PuppetDB Entity Providers.\n *\n * @param config - The application configuration.\n *\n * @returns PuppetDB Entity Provider configurations list.\n */\nexport function readProviderConfigs(\n  config: Config,\n): PuppetDbEntityProviderConfig[] {\n  const providersConfig = config.getOptionalConfig(\n    'catalog.providers.puppetdb',\n  );\n  if (!providersConfig) {\n    return [];\n  }\n\n  if (providersConfig.has('baseUrl')) {\n    return [readProviderConfig(DEFAULT_PROVIDER_ID, providersConfig)];\n  }\n\n  return providersConfig.keys().map(id => {\n    return readProviderConfig(id, providersConfig.getConfig(id));\n  });\n}\n\n/**\n * Reads the configuration for the PuppetDB Entity Provider.\n *\n * @param id - ID of the provider.\n * @param config - The application configuration.\n *\n * @returns The PuppetDB Entity Provider configuration.\n */\nfunction readProviderConfig(\n  id: string,\n  config: Config,\n): PuppetDbEntityProviderConfig {\n  const baseUrl = config.getString('baseUrl').replace(/\\/+$/, '');\n  const query = config.getOptionalString('query');\n\n  const schedule = config.has('schedule')\n    ? readTaskScheduleDefinitionFromConfig(config.getConfig('schedule'))\n    : undefined;\n\n  return {\n    id,\n    baseUrl,\n    query,\n    schedule,\n  };\n}\n","/*\n * Copyright 2020 The Backstage Authors\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\n/**\n * Annotation for specifying the certificate name of a node in PuppetDB.\n *\n * @public\n */\nexport const ANNOTATION_PUPPET_CERTNAME = 'puppet.com/certname';\n\n/**\n * Path of PuppetDB FactSets endpoint.\n */\nexport const ENDPOINT_FACTSETS = 'pdb/query/v4/factsets';\n\n/**\n * Path of PuppetDB Nodes endpoint.\n */\nexport const ENDPOINT_NODES = 'pdb/query/v4/nodes';\n\n/**\n * Default owner for entities created by the PuppetDB provider.\n *\n * @public\n */\nexport const DEFAULT_ENTITY_OWNER = 'unknown';\n","/*\n * Copyright 2020 The Backstage Authors\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 { ResourceTransformer } from './types';\nimport { DEFAULT_NAMESPACE, ResourceEntity } from '@backstage/catalog-model';\nimport { ANNOTATION_PUPPET_CERTNAME, DEFAULT_ENTITY_OWNER } from './constants';\n\n/**\n * A default implementation of the {@link ResourceTransformer}.\n *\n * @param node - The found PuppetDB node entry in its source format. This is the entry that you want to transform.\n * @param _config - The configuration for the entity provider.\n *\n * @returns A `ResourceEntity`.\n *\n * @public\n */\nexport const defaultResourceTransformer: ResourceTransformer = async (\n  node,\n  _config,\n): Promise<ResourceEntity | undefined> => {\n  const certName = node.certname.toLocaleLowerCase('en-US');\n  const type = node.facts?.data?.find(e => e.name === 'is_virtual')?.value\n    ? 'virtual-machine'\n    : 'physical-server';\n  const kernel = node.facts?.data?.find(e => e.name === 'kernel')?.value;\n\n  return {\n    apiVersion: 'backstage.io/v1beta1',\n    kind: 'Resource',\n    metadata: {\n      name: certName,\n      annotations: {\n        [ANNOTATION_PUPPET_CERTNAME]: certName,\n      },\n      namespace: DEFAULT_NAMESPACE,\n      description: node.facts?.data\n        ?.find(e => e.name === 'ipaddress')\n        ?.value?.toString(),\n      tags: kernel ? [kernel.toString().toLocaleLowerCase('en-US')] : [],\n    },\n    spec: {\n      type: type,\n      owner: DEFAULT_ENTITY_OWNER,\n      dependsOn: [],\n      dependencyOf: [],\n    },\n  };\n};\n","/*\n * Copyright 2020 The Backstage Authors\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 { PuppetDbEntityProviderConfig } from '../providers';\nimport { PuppetNode, ResourceTransformer } from './types';\nimport { ResourceEntity } from '@backstage/catalog-model/';\nimport { defaultResourceTransformer } from './transformers';\nimport fetch from 'node-fetch';\nimport { ResponseError } from '@backstage/errors';\nimport { ENDPOINT_FACTSETS } from './constants';\nimport { Logger } from 'winston';\n\n/**\n * Reads nodes and their facts from PuppetDB.\n *\n * @param config - The provider configuration.\n * @param opts - Additional options.\n */\nexport async function readPuppetNodes(\n  config: PuppetDbEntityProviderConfig,\n  opts?: {\n    transformer?: ResourceTransformer;\n    logger?: Logger;\n  },\n): Promise<ResourceEntity[]> {\n  const transformFn = opts?.transformer ?? defaultResourceTransformer;\n  const url = new URL(ENDPOINT_FACTSETS, config.baseUrl);\n\n  if (config.query) {\n    url.searchParams.set('query', config.query);\n  }\n\n  if (opts?.logger) {\n    opts.logger.debug('Reading nodes from PuppetDB', { url: url.toString() });\n  }\n\n  const response = await fetch(url.toString(), {\n    method: 'GET',\n    headers: {\n      'Content-Type': 'application/json',\n      Accept: 'application/json',\n    },\n  });\n\n  if (!response.ok) {\n    throw await ResponseError.fromResponse(response);\n  }\n\n  const nodes = (await response.json()) as PuppetNode[];\n  const entities: ResourceEntity[] = [];\n\n  for (const node of nodes) {\n    const entity = await transformFn(node, config);\n    if (entity) {\n      entities.push(entity);\n    }\n  }\n\n  return entities;\n}\n","/*\n * Copyright 2021 The Backstage Authors\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  EntityProvider,\n  EntityProviderConnection,\n} from '@backstage/plugin-catalog-backend';\nimport { Logger } from 'winston';\nimport {\n  PuppetDbEntityProviderConfig,\n  readProviderConfigs,\n} from './PuppetDbEntityProviderConfig';\nimport { Config } from '@backstage/config';\nimport { PluginTaskScheduler, TaskRunner } from '@backstage/backend-tasks';\nimport * as uuid from 'uuid';\nimport { ResourceTransformer, defaultResourceTransformer } from '../puppet';\nimport {\n  ANNOTATION_LOCATION,\n  ANNOTATION_ORIGIN_LOCATION,\n  Entity,\n} from '@backstage/catalog-model/';\nimport { merge } from 'lodash';\nimport { readPuppetNodes } from '../puppet/read';\nimport { ENDPOINT_NODES } from '../puppet/constants';\n\n/**\n * Reads nodes from [PuppetDB](https://www.puppet.com/docs/puppet/6/puppetdb_overview.html)\n * based on the provided query and registers them as Resource entities in the catalog.\n *\n * @public\n */\nexport class PuppetDbEntityProvider implements EntityProvider {\n  private readonly config: PuppetDbEntityProviderConfig;\n  private readonly logger: Logger;\n  private readonly scheduleFn: () => Promise<void>;\n  private readonly transformer: ResourceTransformer;\n  private connection?: EntityProviderConnection;\n\n  /**\n   * Creates instances of {@link PuppetDbEntityProvider} from a configuration.\n   *\n   * @param config - The configuration to read provider information from.\n   * @param deps - The dependencies for  {@link PuppetDbEntityProvider}.\n   *\n   * @returns A list of {@link PuppetDbEntityProvider} instances.\n   */\n  static fromConfig(\n    config: Config,\n    deps: {\n      logger: Logger;\n      schedule?: TaskRunner;\n      scheduler?: PluginTaskScheduler;\n      transformer?: ResourceTransformer;\n    },\n  ): PuppetDbEntityProvider[] {\n    if (!deps.schedule && !deps.scheduler) {\n      throw new Error('Either schedule or scheduler must be provided.');\n    }\n\n    return readProviderConfigs(config).map(providerConfig => {\n      if (!deps.schedule && !providerConfig.schedule) {\n        throw new Error(\n          `No schedule provided neither via code nor config for puppet-provider:${providerConfig.id}.`,\n        );\n      }\n\n      const taskRunner =\n        deps.schedule ??\n        deps.scheduler!.createScheduledTaskRunner(providerConfig.schedule!);\n\n      const transformer = deps.transformer ?? defaultResourceTransformer;\n\n      return new PuppetDbEntityProvider(\n        providerConfig,\n        deps.logger,\n        taskRunner,\n        transformer,\n      );\n    });\n  }\n\n  /**\n   * Creates an instance of {@link PuppetDbEntityProvider}.\n   *\n   * @param config - Configuration of the provider.\n   * @param logger - The instance of a {@link Logger}.\n   * @param taskRunner - The instance of {@link TaskRunner}.\n   * @param transformer - A {@link ResourceTransformer} function.\n   *\n   * @private\n   */\n  private constructor(\n    config: PuppetDbEntityProviderConfig,\n    logger: Logger,\n    taskRunner: TaskRunner,\n    transformer: ResourceTransformer,\n  ) {\n    this.config = config;\n    this.logger = logger.child({\n      target: this.getProviderName(),\n    });\n    this.scheduleFn = this.createScheduleFn(taskRunner);\n    this.transformer = transformer;\n  }\n\n  /** {@inheritdoc @backstage/plugin-catalog-backend#EntityProvider.connect} */\n  async connect(connection: EntityProviderConnection): Promise<void> {\n    this.connection = connection;\n    await this.scheduleFn();\n  }\n\n  /** {@inheritdoc @backstage/plugin-catalog-backend#EntityProvider.getProviderName} */\n  getProviderName(): string {\n    return `puppetdb-provider:${this.config.id}`;\n  }\n\n  /**\n   * Creates a function that can be used to schedule a refresh of the catalog.\n   *\n   * @param taskRunner - The instance of {@link TaskRunner}.\n   *\n   * @private\n   */\n  private createScheduleFn(taskRunner: TaskRunner): () => Promise<void> {\n    return async () => {\n      const taskId = `${this.getProviderName()}:refresh`;\n      return taskRunner.run({\n        id: taskId,\n        fn: async () => {\n          const logger = this.logger.child({\n            class: PuppetDbEntityProvider.prototype.constructor.name,\n            taskId,\n            taskInstanceId: uuid.v4(),\n          });\n          try {\n            await this.refresh(logger);\n          } catch (error) {\n            logger.error(`${this.getProviderName()} refresh failed`, error);\n          }\n        },\n      });\n    };\n  }\n\n  /**\n   * Refreshes the catalog by reading nodes from PuppetDB and registering them as Resource Entities.\n   *\n   * @param logger - The instance of a Logger.\n   */\n  async refresh(logger: Logger) {\n    if (!this.connection) {\n      throw new Error('Not initialized');\n    }\n\n    const { markReadComplete } = trackProgress(logger);\n    const entities = await readPuppetNodes(this.config, {\n      logger,\n      transformer: this.transformer,\n    });\n    const { markCommitComplete } = markReadComplete(entities);\n\n    await this.connection.applyMutation({\n      type: 'full',\n      entities: [...entities].map(entity => ({\n        locationKey: this.getProviderName(),\n        entity: withLocations(this.config.baseUrl, entity),\n      })),\n    });\n    markCommitComplete(entities);\n  }\n}\n\n/**\n * Ensures the entities have required annotation data.\n *\n * @param baseUrl - The base URL of the PuppetDB instance.\n * @param entity - The entity to add the annotations to.\n *\n * @returns Entity with @{@link ANNOTATION_LOCATION} and @{@link ANNOTATION_ORIGIN_LOCATION} annotations.\n */\nfunction withLocations(baseUrl: string, entity: Entity): Entity {\n  const location = `${baseUrl}/${ENDPOINT_NODES}/${entity.metadata?.name}`;\n\n  return merge(\n    {\n      metadata: {\n        annotations: {\n          [ANNOTATION_LOCATION]: `url:${location}`,\n          [ANNOTATION_ORIGIN_LOCATION]: `url:${location}`,\n        },\n      },\n    },\n    entity,\n  ) as Entity;\n}\n\n/**\n * Tracks the progress of the PuppetDB read and commit operations.\n *\n * @param logger - The instance of a {@link Logger}.\n */\nfunction trackProgress(logger: Logger) {\n  let timestamp = Date.now();\n\n  function markReadComplete(entities: Entity[]) {\n    const readDuration = ((Date.now() - timestamp) / 1000).toFixed(1);\n    timestamp = Date.now();\n    logger.info(\n      `Read ${entities?.length ?? 0} in ${readDuration} seconds. Committing...`,\n    );\n    return { markCommitComplete };\n  }\n\n  function markCommitComplete(entities: Entity[]) {\n    const commitDuration = ((Date.now() - timestamp) / 1000).toFixed(1);\n    logger.info(\n      `Committed ${entities?.length ?? 0} in ${commitDuration} seconds.`,\n    );\n  }\n\n  return { markReadComplete };\n}\n"],"names":["readTaskScheduleDefinitionFromConfig","DEFAULT_NAMESPACE","fetch","ResponseError","uuid","merge","ANNOTATION_LOCATION","ANNOTATION_ORIGIN_LOCATION"],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,192 @@
+import { EntityProvider, EntityProviderConnection } from '@backstage/plugin-catalog-backend';
+import { Logger } from 'winston';
+import { Config } from '@backstage/config';
+import { TaskScheduleDefinition, TaskRunner, PluginTaskScheduler } from '@backstage/backend-tasks';
+import { ResourceEntity } from '@backstage/catalog-model';
+import { JsonValue } from '@backstage/types';
+
+/**
+ * Annotation for specifying the certificate name of a node in PuppetDB.
+ *
+ * @public
+ */
+declare const ANNOTATION_PUPPET_CERTNAME = "puppet.com/certname";
+
+/**
+ * Configuration of {@link PuppetDbEntityProvider}.
+ *
+ * @public
+ */
+declare type PuppetDbEntityProviderConfig = {
+    /**
+     * ID of the provider.
+     */
+    id: string;
+    /**
+     * (Required) The base URL of PuppetDB API instance.
+     */
+    baseUrl: string;
+    /**
+     * (Optional) PQL query to filter PuppetDB nodes.
+     */
+    query?: string;
+    /**
+     * (Optional) Task schedule definition for the refresh.
+     */
+    schedule?: TaskScheduleDefinition;
+};
+
+/**
+ * Customize the ingested Resource entity.
+ *
+ * @param node - The found PuppetDB node entry in its source format. This is the entry that you want to transform.
+ * @param config - The configuration for the entity provider.
+ *
+ * @returns A `ResourceEntity` or `undefined` if you want to ignore the found group for being ingested by the catalog.
+ *
+ * @public
+ */
+declare type ResourceTransformer = (node: PuppetNode, config: PuppetDbEntityProviderConfig) => Promise<ResourceEntity | undefined>;
+/**
+ * A node in PuppetDB.
+ *
+ * @public
+ */
+declare type PuppetNode = {
+    /**
+     * The most recent time of fact submission from the associated certname.
+     */
+    timestamp: string;
+    /**
+     * The certname associated with the factset.
+     */
+    certname: string;
+    /**
+     * A hash of the factset's certname, environment, timestamp, facts, and producer_timestamp.
+     */
+    hash: string;
+    /**
+     *  The most recent time of fact submission for the relevant certname from the Puppet Server.
+     */
+    producer_timestamp: string;
+    /**
+     * The certname of the Puppet Server that sent the factset to PuppetDB.
+     */
+    producer: string;
+    /**
+     * The environment associated with the fact.
+     */
+    environment: string;
+    /**
+     * The facts associated with the factset.
+     */
+    facts: PuppetFactSet;
+};
+/**
+ * The set of all facts for a single certname in PuppetDB.
+ *
+ * @public
+ */
+declare type PuppetFactSet = {
+    /**
+     * The array of facts.
+     */
+    data: PuppetFact[];
+    /**
+     * The URL to retrieve more information about the facts.
+     */
+    href: string;
+};
+/**
+ * A fact in PuppetDB.
+ *
+ * @public
+ */
+declare type PuppetFact = {
+    /**
+     * The name of the fact.
+     */
+    name: string;
+    /**
+     * The value of the fact.
+     */
+    value: JsonValue;
+};
+
+/**
+ * A default implementation of the {@link ResourceTransformer}.
+ *
+ * @param node - The found PuppetDB node entry in its source format. This is the entry that you want to transform.
+ * @param _config - The configuration for the entity provider.
+ *
+ * @returns A `ResourceEntity`.
+ *
+ * @public
+ */
+declare const defaultResourceTransformer: ResourceTransformer;
+
+/**
+ * Reads nodes from [PuppetDB](https://www.puppet.com/docs/puppet/6/puppetdb_overview.html)
+ * based on the provided query and registers them as Resource entities in the catalog.
+ *
+ * @public
+ */
+declare class PuppetDbEntityProvider implements EntityProvider {
+    private readonly config;
+    private readonly logger;
+    private readonly scheduleFn;
+    private readonly transformer;
+    private connection?;
+    /**
+     * Creates instances of {@link PuppetDbEntityProvider} from a configuration.
+     *
+     * @param config - The configuration to read provider information from.
+     * @param deps - The dependencies for  {@link PuppetDbEntityProvider}.
+     *
+     * @returns A list of {@link PuppetDbEntityProvider} instances.
+     */
+    static fromConfig(config: Config, deps: {
+        logger: Logger;
+        schedule?: TaskRunner;
+        scheduler?: PluginTaskScheduler;
+        transformer?: ResourceTransformer;
+    }): PuppetDbEntityProvider[];
+    /**
+     * Creates an instance of {@link PuppetDbEntityProvider}.
+     *
+     * @param config - Configuration of the provider.
+     * @param logger - The instance of a {@link Logger}.
+     * @param taskRunner - The instance of {@link TaskRunner}.
+     * @param transformer - A {@link ResourceTransformer} function.
+     *
+     * @private
+     */
+    private constructor();
+    /** {@inheritdoc @backstage/plugin-catalog-backend#EntityProvider.connect} */
+    connect(connection: EntityProviderConnection): Promise<void>;
+    /** {@inheritdoc @backstage/plugin-catalog-backend#EntityProvider.getProviderName} */
+    getProviderName(): string;
+    /**
+     * Creates a function that can be used to schedule a refresh of the catalog.
+     *
+     * @param taskRunner - The instance of {@link TaskRunner}.
+     *
+     * @private
+     */
+    private createScheduleFn;
+    /**
+     * Refreshes the catalog by reading nodes from PuppetDB and registering them as Resource Entities.
+     *
+     * @param logger - The instance of a Logger.
+     */
+    refresh(logger: Logger): Promise<void>;
+}
+
+/**
+ * Name of the default provider when a using a simple configuration.
+ *
+ * @public
+ */
+declare const DEFAULT_PROVIDER_ID = "default";
+
+export { ANNOTATION_PUPPET_CERTNAME, DEFAULT_PROVIDER_ID, PuppetDbEntityProvider, PuppetDbEntityProviderConfig, PuppetFact, PuppetFactSet, PuppetNode, ResourceTransformer, defaultResourceTransformer };

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@backstage/plugin-catalog-backend-module-puppetdb",
+  "description": "A Backstage catalog backend module that helps integrate towards PuppetDB",
+  "version": "0.0.0-nightly-20230304023150",
+  "main": "dist/index.cjs.js",
+  "types": "dist/index.d.ts",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public",
+    "main": "dist/index.cjs.js",
+    "types": "dist/index.d.ts"
+  },
+  "backstage": {
+    "role": "backend-plugin-module"
+  },
+  "homepage": "https://backstage.io",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/backstage/backstage",
+    "directory": "plugins/catalog-backend-module-puppetdb"
+  },
+  "keywords": [
+    "backstage",
+    "puppetdb",
+    "puppet"
+  ],
+  "scripts": {
+    "start": "backstage-cli package start",
+    "build": "backstage-cli package build",
+    "lint": "backstage-cli package lint",
+    "test": "backstage-cli package test",
+    "clean": "backstage-cli package clean",
+    "prepack": "backstage-cli package prepack",
+    "postpack": "backstage-cli package postpack"
+  },
+  "dependencies": {
+    "@backstage/backend-common": "^0.0.0-nightly-20230304023150",
+    "@backstage/backend-tasks": "^0.0.0-nightly-20230304023150",
+    "@backstage/catalog-model": "^0.0.0-nightly-20230304023150",
+    "@backstage/config": "^0.0.0-nightly-20230304023150",
+    "@backstage/errors": "^0.0.0-nightly-20230304023150",
+    "@backstage/plugin-catalog-backend": "^0.0.0-nightly-20230304023150",
+    "@backstage/types": "^1.0.2",
+    "lodash": "^4.17.21",
+    "luxon": "^3.0.0",
+    "node-fetch": "^2.6.7",
+    "uuid": "^8.0.0",
+    "winston": "^3.2.1"
+  },
+  "devDependencies": {
+    "@backstage/backend-test-utils": "^0.0.0-nightly-20230304023150",
+    "@backstage/cli": "^0.0.0-nightly-20230304023150",
+    "@types/lodash": "^4.14.151",
+    "msw": "^0.49.0"
+  },
+  "files": [
+    "dist",
+    "config.d.ts"
+  ],
+  "configSchema": "config.d.ts"
+}