Backstage FireHydrant Plugin

FireHydrant is an incident management platform that helps teams respond faster, follow a clear process, and learn from every incident. It connects with tools you already use and tracks your services and environments so responders have context when it matters. The FireHydrant plugin brings that context into Backstage so you can see incident information where your engineers already work.

Inside Backstage, the plugin surfaces the current state of a service. You can see active incidents and jump to the most recent ones. You can start or review an incident in FireHydrant without switching tabs. The plugin also shows a snapshot from the last 30 days with service health, total time impacted, incident count, and MTTD MTTA MTTM MTTR. This gives you a quick pulse on reliability for each component in your catalog.

Common use cases are simple. An on call engineer opens a service page and checks if there is an ongoing incident before digging into logs. An SRE scans incident trends to spot risky services and plan follow up work. A platform team reduces context switching by showing incident status next to docs and deployments. FireHydrant also ingests Backstage service definitions into its own catalog which helps keep ownership and inventory in sync across both systems.

Installation Instructions

These instructions apply to self-hosted Backstage only. To use this plugin on Roadie, visit the docs.

Install the package

Copy

yarn --cwd packages/app add @backstage-community/plugin-firehydrant

Add the FireHydrant card to the entity page

Place the card on your catalog entity page so users can see it.

Edit packages/app/src/components/catalog/EntityPage.tsx

Copy

import React from 'react';
import Grid from '@material-ui/core/Grid';
import { useEntity } from '@backstage/plugin-catalog-react';
import { FirehydrantCard, isFireHydrantAvailable } from '@backstage-community/plugin-firehydrant';

export const EntityOverviewContent = () => {
  const { entity } = useEntity();

  return (
    <Grid container spacing={3}>
      <Grid item md={6} xs={12}>
        {isFireHydrantAvailable(entity) ? <FirehydrantCard /> : null}
      </Grid>
      {/* keep your other overview cards here */}
    </Grid>
  );
};

If your app uses a different component name for the overview content, add the card inside that component within the Grid.

Configure the proxy

Add a proxy entry so the frontend can call the FireHydrant API. Edit app-config.yaml at the root of your repo.

Use an environment variable for the token

Copy

proxy:
  '/firehydrant/api':
    target: 'https://api.firehydrant.io/v1/'
    changeOrigin: true
    headers:
      Authorization: Bearer ${FIREHYDRANT_BOT_TOKEN}

Or hardcode the token

Copy

proxy:
  '/firehydrant/api':
    target: 'https://api.firehydrant.io/v1/'
    changeOrigin: true
    headers:
      Authorization: Bearer fhb-your-bot-token-here

You can create a bot token in FireHydrant in the bots page in the organization settings.

Optional service annotation

Add this annotation if your Backstage entity name does not match the service name in FireHydrant. Put it in the entity yaml in your catalog.

Copy

metadata:
  annotations:
    firehydrant.com/service-name: your-firehydrant-service-name

What the plugin exports and how to import

You can import these from the package

Copy

import {
  FirehydrantCard,
  isFireHydrantAvailable,
  firehydrantPlugin,
} from '@backstage-community/plugin-firehydrant';

Use FirehydrantCard on the entity page as shown above.

Use isFireHydrantAvailable to show the card only when the entity has the right metadata.

firehydrantPlugin is the plugin instance. You usually do not need to reference it directly for this setup.

Backend notes for both systems

This plugin does not ship a backend part. No backend module install is needed in the old or the new backend system.

The only backend requirement is the proxy config shown above. The card reads data through that proxy path.

Things to Know

Typically, Backstage components are linked to external services like FireHydrant.io by adding annotations to the component’s catalog-info.yaml. The FireHydrant plugin does not require an annotation. Instead, the Backstage component is added to the FireHydrant.io service catalog following a very specific naming convention: component-type:namespace/component-name.

For example, a component of type Component, in the default namespace, named backstage-sample-service would need to be added to the FireHydrant.io service catalog as Component:default/backstage-sample-service. Here is what that component would loook like in the Backstage catalog:

Sample component in Backstage

And here is what the Matching component would look like in the FireHydrant.io service catalog:

Matching component in FireHydrant.io

Obtaining a FireHydrant Authorization Token

Backstage needs an authorization token to authenticate to the FireHydrant.io API. This token is obtained by created a new bot configuration on FireHydrant.io:

Create bot on FireHydrant.io, step 1

Add the authorization token directly to app-config.yaml or refer to it from an environment variable.

Changelog

This changelog is produced from commits made to the FireHydrant 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
Reduce false positives in knip reports by using a single workspace config Update Backstage repo tools to 0.13.0 #3018 merged 7 months ago

Set up Backstage in minutes with Roadie

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

Get a demo