Get Roadie in your IDE with our new MCP Servers
Roadie
← Backstage Plugins Guides
PuppetDB logo

Backstage PuppetDB Plugin

Created by TDabasinskas

PuppetDB stores facts, catalogs, and reports from your Puppet managed nodes. It gives you a single source of truth for what each node looks like and what happened during the last runs. If you already rely on Puppet for config management, you likely use PuppetDB to answer questions about state and drift.

The PuppetDB plugin brings that context into Backstage. It adds a page where engineers can browse Puppet reports for resources that exist in the Backstage catalog. You can see logs and events from runs. You can jump from a service in the catalog to recent configuration activity. When paired with the catalog backend module for PuppetDB, nodes from PuppetDB can appear in Backstage as Resource entities, with links back to their reports.

Common use cases are simple. Troubleshoot failed runs without leaving your portal. Check what changed on a host before a deployment. Give service owners lightweight visibility into their infrastructure. Provide audit friendly views of configuration history tied to the software catalog. Keep resource metadata in one place so on call engineers are not switching tools during incidents.

Installation Instructions

These instructions apply to self-hosted Backstage only.

Install the frontend package

  1. Add the plugin to your app package
Copy 
yarn --cwd packages/app add @backstage-community/plugin-puppetdb
  1. Register the page route in packages/app/src/App.tsx
Copy 
// packages/app/src/App.tsx
import React from 'react';
import { FlatRoutes } from '@backstage/core-app-api';
import { Route } from 'react-router';
import { PuppetDbPage } from '@backstage-community/plugin-puppetdb';

export const AppRoutes = () => (
  <FlatRoutes>
    {/* other routes */}
    <Route path="/puppetdb" element={<PuppetDbPage />} />
  </FlatRoutes>
);
  1. Add a sidebar link so people can find the page
Copy 
// packages/app/src/components/Root/Root.tsx
import React from 'react';
import { SidebarItem } from '@backstage/core-components';

// inside your Sidebar component
<SidebarItem to="/puppetdb" text="PuppetDB" />

Configure the proxy to reach PuppetDB

  1. Add a proxy entry in app-config.yaml
Copy 
proxy:
  '/puppetdb':
    target: https://your.puppetdb.instance.com

The plugin calls the Backstage proxy under the path shown. Point target at your PuppetDB base URL.

Provide the PuppetDB certname on your Resource entities

The page needs the certname of each node. You can set it yourself with an annotation on Resource entities. Example entity

Copy 
apiVersion: backstage.io/v1alpha1
kind: Resource
metadata:
  name: example-node
  annotations:
    puppet.com/certname: node01.example.com
spec:
  type: compute
  owner: team-a

About backend usage

This plugin is frontend only. You do not need to install a backend service for it.

If you want the certname to be filled by the catalog backend instead of setting it by hand, install the catalog backend module for PuppetDB in your backend. Use the new backend system or the old backend as your app requires. Register the module with your catalog backend in the usual way for your setup.

Changelog

This changelog is produced from commits made to the PuppetDB 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.

Maintenance

  • Remove unused dev dependency canvas #3565 Merged 6 months ago
  • Update repo tools config to reduce knip false positives #3018 Merged 7 months ago

Breaking changes

None

Set up Backstage in minutes with Roadie

Get a demo