This repository contains plugins and modules for Backstage to support Pulumi.

This repository contains the following Backstage plugins and modules:

• Pulumi Scaffolder Backend Module
• Pulumi Plugin
• Catalog Backend Module for Pulumi

You need to have the Pulumi CLI installed on the Backstage server.

If you use the Backstage Dockerfile, add following lines before the USER node line:

RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
    --mount=type=cache,target=/var/lib/apt,sharing=locked \
    apt-get update && \
    apt-get install -y --no-install-recommends curl ca-certificates

and add following lines after the USER node line:

RUN <<EOF
## Install pulumi and set to PATH
curl -fsSL https://get.pulumi.com | sh
EOF

ENV PATH="/node/.pulumi/bin:${PATH}"

This will install the latest Pulumi CLI to your Backstage container.

To authenticate to the Pulumi cloud service, you need to provide additionally the Pulumi Personal Access Token via the environment variable `PULUMI_ACCESS_TOKEN``

If you're not going to use the Pulumi Deployment service, you need to be sure that all the programming language runtimes are installed on your Backstage service

You need to configure the action in your backend:

# From your Backstage root directory
yarn add --cwd packages/backend @pulumi/backstage-scaffolder-backend-pulumi

Configure the action (you can check the docs to see all options):

// packages/backend/src/index.ts
const backend = createBackend();
backend.add(import('@pulumi/backstage-scaffolder-backend-pulumi'));

You need to set the PULUMI_ACCESS_TOKEN environment variable to be able to use the Pulumi action.

The Pulumi New Action is a custom action that allows you to create a new Pulumi project from a template.

pulumi:new

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: kubernetes-template
  title: Kubernetes Cluster
  description: |
    A template for creating a new Kubernetes Cluster.
  tags:
  - pulumi
  - kubernetes
spec:
  steps:
  - id: pulumi-new-component
    name: Cookie cut the component Pulumi project
    action: pulumi:new
    input:
      name: "${{ parameters.component_id }}-infrastructure"
      description: ${{ parameters.description | dump }}
      organization: ediri
      stack: ${{ parameters.stack }}
      template: "https://github.com/my-silly-organisation/microservice-civo/tree/main/infrastructure-${{ parameters.cloud }}-${{ parameters.language }}"
      config:
        "node:node_count": "${{ parameters.nodeCount }}"
      folder: .

The Pulumi Up Action is a custom action that allows you to run the pulumi up command.

pulumi:up

The action offers also Pulumi deployment support, to use it you need to set the deployment input to true. If you did not set any config or secretConfig, during the pulumi:new action, you need to set them here. If you have any provider related credentials, you need to set the providerCredentialsFromEnv input.

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: kubernetes-template
  title: Kubernetes Cluster
  description: |
    A template for creating a new Kubernetes Cluster.
  tags:
  - pulumi
  - kubernetes
spec:
  steps:
  - id: pulumi-deploy-infrastructure
    name: Deploy the infrastructure using Pulumi CLI
    action: pulumi:up
    input:
      deployment: false
      name: "${{ parameters.component_id }}-infrastructure"
      repoUrl: "https://github.com/${{ (parameters.repoUrl | parseRepoUrl)['owner'] }}/${{ (parameters.repoUrl | parseRepoUrl)['repo'] }}"
      repoProjectPath: .
      organization: ediri
      outputs:
      - kubeconfig
      - ClusterId
      stack: ${{ parameters.stack }}

The Pulumi Preview Action allows you to preview changes without deploying.

pulumi:preview

Output: changeSummary - Summary of proposed changes by operation type.

steps:
  - id: pulumi-preview
    name: Preview infrastructure changes
    action: pulumi:preview
    input:
      name: my-infrastructure
      organization: my-org
      stack: dev
      repoProjectPath: .
      environments:
        - my-org/my-esc-env

The Pulumi Destroy Action allows you to destroy stack resources. Requires explicit confirmation.

pulumi:destroy

Output: summary - Summary of destroyed resources by operation type.

steps:
  - id: pulumi-destroy
    name: Destroy infrastructure
    action: pulumi:destroy
    input:
      name: my-infrastructure
      organization: my-org
      stack: dev
      confirm: true  # Required safety flag
      removeStack: true  # Optionally remove the stack after destroy

The Pulumi Deployment Config Action configures Pulumi Deployments settings via the Pulumi Cloud REST API.

pulumi:deployment:config

Outputs:

• settingsUrl - URL to view deployment settings in Pulumi Cloud
• configured - Whether settings were successfully configured

steps:
  - id: configure-deployment
    name: Configure Pulumi Deployments
    action: pulumi:deployment:config
    input:
      organization: my-org
      project: my-project
      stack: dev
      sourceContext:
        git:
          repoUrl: https://github.com/my-org/my-repo
          branch: main
          repoDir: infrastructure
      operationContext:
        preRunCommands:
          - npm install
        oidc:
          aws:
            roleArn: arn:aws:iam::123456789:role/pulumi-deploy
      github:
        repository: my-org/my-repo
        deployCommits: true
        previewPullRequests: true

The Pulumi Deployment Run Action triggers a Pulumi Deployment via the Pulumi Cloud REST API.

pulumi:deployment:run

Outputs:

• deploymentId - The ID of the triggered deployment
• deploymentUrl - URL to view the deployment in Pulumi Cloud
• version - The deployment version number

steps:
  - id: trigger-deployment
    name: Trigger Pulumi Deployment
    action: pulumi:deployment:run
    input:
      organization: my-org
      project: my-project
      stack: prod
      operation: update
      inheritSettings: true

• Display relevant Pulumi information about an entity within Backstage, such as the Pulumi stack, organization, project name, and project description.
• Show stack outputs directly in the Pulumi card (e.g., URLs, resource IDs, connection strings).
• Show the Pulumi activity view for an entity within Backstage.
• Support for multiple stacks and organizations with tabbed UI.
• Pulumi Dashboard: A standalone dashboard page showing organization-wide metrics, recent stack updates, deployments, and resource trends.

• Setup of the Pulumi plugin for Backstage requires a Pulumi Organization admin to generate a Pulumi access token for the Backstage application.

When an entity has multiple stacks configured, they are displayed as tabs in the UI:

The Pulumi Dashboard provides an organization-wide view of your Pulumi infrastructure:

• Organization Selector: Switch between Pulumi organizations you have access to
• Stats Cards: View counts for Members, Stacks, ESC Environments, and Resources
• Latest Stack Updates: See recent stack activity with status, timing, and resource changes
• Latest Deployments: Monitor recent Pulumi Deployments with status and links
• Resource Trends: Interactive chart showing resource count over time with configurable time ranges and CSV export

If you need any help with this plugin, feel free to reach out to me!

The file paths mentioned in the following steps are relative to your app's root directory — for example, the directory created by following the Getting Started guide and creating your app with npx @backstage/create-app.

First, install the Pulumi plugin via a CLI:

# From your Backstage root directory
yarn add --cwd packages/app @pulumi/backstage-plugin-pulumi

Next, add the plugin to EntityPage.tsx in packages/app/src/components/catalog by adding the following code snippets.

Add the following imports to the top of the file:

import {
    isPulumiAvailable,
    EntityPulumiCard,
    EntityPulumiMetdataCard,
    PulumiComponent,
    PulumiDashboardPage,
} from '@pulumi/backstage-plugin-pulumi';

Then create a new constant for the Pulumi Component:

const pulumiContent = (
    <EntitySwitch>
        <EntitySwitch.Case if={isPulumiAvailable}>
            <PulumiComponent/>
        </EntitySwitch.Case>
    </EntitySwitch>
);

Find const overviewContent in EntityPage.tsx, and add the following snippet inside the outermost Grid defined there, just before the closing </Grid> tag:

<EntitySwitch>
    <EntitySwitch.Case if={isPulumiAvailable}>
        <Grid item md={6}>
            <EntityPulumiCard variant="gridItem"/>
        </Grid>
    </EntitySwitch.Case>
</EntitySwitch>

Now find the serviceEntityPage constant in EntityPage.tsx, and add the following snippet inside:

<EntityLayout.Route path="/pulumi" title="Pulumi" if={isPulumiAvailable}>
    {pulumiContent}
</EntityLayout.Route>

To add the standalone Pulumi Dashboard page, add a route in your App.tsx:

import { PulumiDashboardPage } from '@pulumi/backstage-plugin-pulumi';

// In your routes
<Route path="/pulumi" element={<PulumiDashboardPage />} />

You can also add a sidebar navigation item in your Root.tsx:

<SidebarItem icon={YourIcon} to="pulumi" text="Pulumi" />

Lastly, find the systemPage constant in EntityPage.tsx, and add the following snippet inside after the closing </Grid> tag of the <EntityAboutCard variant="gridItem" />:

  <EntitySwitch>
    <EntitySwitch.Case if={isPulumiAvailable}>
        <Grid item md={6}>
            <EntityPulumiMetdataCard/>
        </Grid>
    </EntitySwitch.Case>
</EntitySwitch>

First, annotate your component/resource entity with the following:

annotations:
  pulumi.com/project-slug: <org/project/stack>

You can also specify multiple stacks using comma-separated values:

annotations:
  # Multiple stacks - displays as tabs in the UI
  pulumi.com/project-slug: acme/web-app/prod,acme/web-app/staging,acme/api/prod

And your system entity with the following:

annotations:
  pulumi.com/orga-slug: <org>

You can also specify multiple organizations using comma-separated values:

annotations:
  # Multiple organizations - displays as tabs in the UI
  pulumi.com/orga-slug: acme,widgets-inc

Next, provide the API token that the client will use to make requests to the Pulumi Cloud API.

Add the proxy configuration in app-config.yaml:

proxy:
  '/pulumi':
    target: 'https://api.pulumi.com/api'
    changeOrigin: true
    headers:
      Authorization: token ${PULUMI_ACCESS_TOKEN}
      Accept: application/vnd.pulumi+8
      Content-Type: application/json

Then, start the backend, passing the Pulumi Access Token as an environment variable:

export PULUMI_ACCESS_TOKEN='<PULUMI_ACCESS_TOKEN>' 
yarn start

This will proxy the request by adding an Authorization header with the provided token.

1. Remove any configuration added in Backstage yaml files, such as the proxy configuration in app-config.yaml and the integration key in an entity's annotations.
2. Remove the added code snippets from EntityPage.tsx
3. Remove the plugin package:

# From your Backstage root directory
yarn remove --cwd packages/app @pulumi/backstage-plugin-pulumi

This plugin supports the new Backstage frontend system. Follow these steps to use it in an application that supports the new frontend system.

Once you install the @pulumi/backstage-plugin-pulumi package, you can choose how the package should be detected by the app. The package can be automatically discovered when the feature discovery config is set, or it can be manually enabled via code.

# app-config.yaml
app:
  # Enable package discovery for all plugins
  packages: 'all'
---
app:
  # Enable package discovery only for Pulumi
  packages:
    include:
      - '@pulumi/backstage-plugin-pulumi'
      

// packages/app/src/App.tsx
import { createApp } from '@backstage/frontend-defaults';
import pulumiPlugin from '@pulumi/backstage-plugin-pulumi/alpha';
const app = createApp({
features: [
// ...other plugins
pulumiPlugin,
],
});

The plugin installs the following extensions:

You can configure these extensions in your app-config.yaml:

# app-config.yaml
app:
  extensions:
    # Disable the Pulumi stack card
    - entity-card:pulumi/stack: false

    # Disable the Pulumi metadata card
    - entity-card:pulumi/metadata: false

    # Disable the Pulumi entity content tab
    - entity-content:pulumi/activity: false

    # Customize the Pulumi entity content path and title
    - entity-content:pulumi/activity:
        config:
          path: '/infrastructure'
          title: 'Infrastructure'

    # Customize the Pulumi dashboard page path
    - page:pulumi:
        config:
          path: '/infrastructure-dashboard'

This is an extension module to the plugin-catalog-backend plugin, providing an PulumiEntityProvider that can be used to ingest Resource entities from the Pulumi Cloud. This provider is useful if you want to import Pulumi stacks into Backstage.

The provider is not installed by default, therefore you have to add a dependency to @pulumi/plugin-catalog-backend-module-pulumi to your backend package:

# From your Backstage root directory
yarn add --cwd packages/backend @pulumi/plugin-catalog-backend-module-pulumi

Update the catalog plugin initialization in your backend to add the provider and schedule it:

//packages/backend/src/index.ts
backend.add(import('@pulumi/plugin-catalog-backend-module-pulumi/alpha'));

After this, you also have to add some configuration in your app-config that describes what you want to import for that target.

The following configuration is an example of how a setup could look for importing stacks from Pulumi Cloud:

catalog:
  providers:
    pulumi:
      default:
        api: https://api.pulumi.com
        organization: <your organization>
        pulumiAccessToken: ${PULUMI_ACCESS_TOKEN}
        schedule:
          frequency: PT10M
          timeout: PT50M