Backstage PuppetDB Entity Provider Plugin

PuppetDB Entity Provider brings your PuppetDB inventory into Backstage. It reads nodes from PuppetDB using a query. Then it registers them as Resource entities in the catalog. The provider runs on the backend and can refresh on a schedule so your catalog stays in step with PuppetDB.

The provider focuses on turning nodes and their facts into useful catalog records. You can shape the imported data to match your model. Set owner and system. Adjust names. Add labels and annotations. This comes through a transformer hook so you can keep the catalog clean and consistent with your standards.Common use cases are straightforward. Show your server or VM fleet in Backstage without writing lots of YAML by hand. Let teams discover resources and see who owns them. Connect resources to systems, docs, and runbooks that already live in your portal. If you want visibility into Puppet activity from the catalog, you can pair it with the community PuppetDB frontend plugin to view reports and events for the same resources. This gives engineers a single place to look when they need context during changes or incidents.

Installation Instructions

These instructions apply to self-hosted Backstage only.

What this plugin does

It pulls nodes from PuppetDB into the Backstage catalog as Resource entities. It runs in the backend. There is no frontend component to add.

Install on a classic backend

Add the backend module

Copy

cd packages/backend
yarn add @backstage/plugin-catalog-backend-module-puppetdb

Wire the provider into the catalog backend

Edit packages backend src plugins catalog.ts

Copy

import { Router } from 'express';
import { CatalogBuilder } from '@backstage/plugin-catalog-backend';
import { PluginEnvironment } from '../types';

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 },
      }),
    }),
  );

  const { processingEngine, router } = await builder.build();
  await processingEngine.start();
  return router;
}

Configure the provider

Add a provider entry in your app config. Put this in app-config.yaml

Copy

catalog:
  providers:
    puppetdb:
      default:
        baseUrl: https://puppetdb.example.com
        #query: '["=","certname","example.com"]'

baseUrl must point to your PuppetDB API
query is optional. Use it to filter nodes

Optional customize the resource transformer

You can override the default entity mapping. Create a transformer. Then pass it to the provider.

Example transformer file packages backend src puppetdbTransformer.ts

Copy

import type { ResourceEntity } from '@backstage/catalog-model';
import type { ResourceTransformer } from '@backstage/plugin-catalog-backend-module-puppetdb';
import { defaultResourceTransformer } from '@backstage/plugin-catalog-backend-module-puppetdb';

export const customResourceTransformer: ResourceTransformer = async (
  node,
  config,
): Promise<ResourceEntity | undefined> => {
  // You can change namespace owner name labels annotations and more
  // Example wraps the default transformer
  return defaultResourceTransformer(node, config);
};

Wire it in packages backend src plugins catalog.ts

Copy

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

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

Where the data shows up

There is no UI plugin to add. Imported Resource entities appear in the Catalog in your Backstage frontend.

Changelog

This changelog is produced from commits made to the PuppetDB Entity Provider plugin since a year ago, and based on the code located here. It may not contain information about all commits. Releases and version bumps are intentionally omitted. This changelog is generated by AI.

Breaking changes

None

Features

None

Bug fixes

Fix API report path so warnings show up #27116 merged 11 months ago
Fix knip reports when the workspace path has spaces #31045 merged 20 days ago

Maintenance

Upgrade to uuid v11 with built in types #27649 merged 11 months ago
Remove node fetch usage #27950 merged 10 months ago
Improve knip reports with a single workspace config #28491 merged 8 months ago
Clean circular import issues #30387 merged 3 months ago
Remove last remnant of old system structure #31051 merged 1 month ago

Notes

No user facing changes in this set
These updates improve build and code health

Set up Backstage in minutes with Roadie

Focus on using Backstage, rather than building and maintaining it.

Get a demo