# Integrating Backstage

## Overview

Firefly integrates with Backstage to provide comprehensive cloud resource management capabilities directly within your Backstage instance. This integration consists of both frontend and backend plugins that work together to give you visibility and control over your cloud infrastructure.

## Features

### Backend Features

* **Asset Import**: Import Firefly assets as catalog resource entities into Backstage
* **Cloud Account Integration**: Import cloud accounts as system entities into Backstage
* **Relationship Mapping**: Automatically map relationships between:
  * Cloud resources and systems
  * Existing components and cloud resources
  * Dependencies between cloud resources
* **Flexible Filtering**: Filter assets by:
  * Asset types
  * Cloud accounts
* **Automatic Updates**: Periodic checks for new assets (configurable interval)
* **Smart Correlation**: Tag-based and name-based correlation between components and resources

### Frontend Features

* **Dedicated Dashboard**: A Firefly page showing:
  * Cloud resource key metrics
  * Number of cloud resources and systems
  * IaC coverage across infrastructure
  * Top 5 components with unmanaged/drifted and overall resources
* **Component Integration**: Service component pages enhanced with IaC coverage information

## Installation

### Backend Plugin Installation

1. Install the plugin package:

   ```bash
   yarn add @fireflyai/backstage-backend-plugin-firefly
   ```
2. Authenticate with Firefly:

   ```bash
   export FIREFLY_ACCESS_KEY=<your-access-key>
   export FIREFLY_SECRET_KEY=<your-secret-key>
   ```
3. Configure the plugin in your `app-config.yaml`:

   ```yaml
   firefly:
     periodicCheck:
       interval: 3600  # seconds (default: 3600)
       importSystems: true  # import cloud accounts as systems
       correlateByComponentName: true  # if a resource tag value equals the component name, relate the resource to that component
       importResources: true  # import assets as resources
       tagKeysIdentifiers: # Optional: tag keys to use as identifiers for relating resources to components
         - environment
         - component
       filters:
         # Optional filters to apply when fetching assets
         assetTypes:
           - aws_s3_bucket
           - aws_lambda_function
         providerIds:
           - '123456789012'  
           - 'devops-651215'  
   ```
4. Add the plugin to your backend:

   ```typescript
   // In packages/backend/src/index.ts or equivalent
   backend.add(import('@fireflyai/backstage-backend-plugin-firefly'));
   ```

### Frontend Plugin Installation

1. Install the plugin package:

   ```bash
   yarn add @fireflyai/backstage-plugin-firefly
   ```
2. Configure the plugin in your Backstage app:

   ```typescript
   // In packages/app/src/App.tsx
   import { FireflyPage } from '@fireflyai/backstage-plugin-firefly';

   // Add to your app's routes
   <Route path="/firefly" element={<FireflyPage />} />
   ```
3. Add the Firefly icon to your sidebar:

   ```typescript
   // In packages/app/src/components/Root/Root.tsx
   import ExtensionIcon from '@material-ui/icons/Extension';

   // Add to your sidebar items
   <SidebarItem icon={ExtensionIcon} to="firefly" text="Firefly" />
   ```
4. Add the IaC coverage card to entity pages:

   ```typescript
   // In packages/app/src/components/catalog/EntityPage.tsx
   import { EntityDependenciesIaCCoverageCard } from '@fireflyai/backstage-plugin-firefly';

   // Add to your entity page layout
   <Grid item md={4} xs={12}>
     <EntityDependenciesIaCCoverageCard />
   </Grid>
   ```

## How It Works

### Backend Plugin

The backend plugin connects to Firefly's API and imports your cloud resources as Backstage catalog entities. It creates:

* **Resource entities**: Representing individual cloud resources
* **System entities**: Representing cloud accounts

The plugin establishes relationships between these entities, enabling you to visualize dependencies between cloud resources and systems. These relationships help track ownership, dependencies, and provide a comprehensive view of your cloud infrastructure within the Backstage ecosystem.

The plugin automatically relates existing components in your catalog to their corresponding cloud resources using two methods:

1. **Tag-based correlation**: Using the `tagKeysIdentifiers` configuration, the plugin finds components with matching tag key-value pairs.
2. **Name-based correlation**: When `correlateByComponentName` is enabled, the plugin relates resources to components when a resource tag value matches a component name in your catalog.

### Frontend Plugin

The frontend plugin provides:

* A dedicated **Firefly page** (`/firefly`) with:
  * Overview of cloud resources and systems
  * IaC coverage metrics
  * Top components with unmanaged/drifted and overall resources
* **Entity page integration** showing IaC coverage for each component

## Demo

[Video](https://github.com/user-attachments/assets/6e533ca8-964b-49c7-aa7b-5f0d1cc5d23f)

## Best Practices

* Configure appropriate filters to limit the number of imported resources
* Use consistent tagging across your cloud resources to improve correlation
* Set a reasonable interval for periodic checks based on your infrastructure change frequency
* Add the Firefly cards to entity page for maximum visibility

## Troubleshooting

If you encounter issues with the integration:

1. Verify your Firefly API credentials are correct
2. Check the Backstage logs for any error messages
3. Ensure your configuration in `app-config.yaml` is properly formatted
4. Verify network connectivity between your Backstage instance and Firefly

## Read More

* [Firefly Backstage Plugin GitHub Repository](https://github.com/gofireflyio/firefly-backstage-plugin)
* [Firefly Frontend Plugin](https://github.com/gofireflyio/firefly-backstage-plugin/tree/main/plugins/firefly)
* [Firefly Backend Plugin](https://github.com/gofireflyio/firefly-backstage-plugin/tree/main/plugins/firefly-backend)