https://github.com/pulumi/pulumi-backstage-plugin
Pulumi plugin for Backstage
https://github.com/pulumi/pulumi-backstage-plugin
backstage pulumi
Last synced: about 2 months ago
JSON representation
Pulumi plugin for Backstage
- Host: GitHub
- URL: https://github.com/pulumi/pulumi-backstage-plugin
- Owner: pulumi
- License: mpl-2.0
- Created: 2023-08-09T08:29:34.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2025-02-19T11:56:56.000Z (4 months ago)
- Last Synced: 2025-04-14T07:09:46.836Z (about 2 months ago)
- Topics: backstage, pulumi
- Language: TypeScript
- Homepage:
- Size: 2.69 MB
- Stars: 22
- Watchers: 4
- Forks: 3
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Pulumi
This repository contains plugins and modules for [Backstage](https://backstage.io/) to
support [Pulumi](https://www.pulumi.com/).
> [!NOTE]
> This is a work in progress and happy to receive feedback and contributions.
> [!IMPORTANT]
> The Pulumi Scaffolder Backend Module and the Pulumi Catalog Backend Module in version > `v0.6.0` are now supporting
> the new [Backstage Backend System](https://backstage.io/docs/backend-system/building-backends/index).
This repository contains the following Backstage plugins and modules:
- [Pulumi Scaffolder Backend Module](#pulumi-scaffolder-backend-module)
- [Pulumi Plugin](#pulumi-plugin)
- [Catalog Backend Module for Pulumi](#catalog-backend-module-for-pulumi)
## Pulumi Scaffolder Backend Module
### Requirements
#### Pulumi CLI
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:
```Dockerfile
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:
```Dockerfile
RUN < [!NOTE]
> If you run `pulumi:up` via CLI and with a local Pulumi template you may need to install the required dependencies for
> the Pulumi SDK to work. This can now be done via the `preRunCommands` input.
> For example for a node based Pulumi project you need to run `npm install` before running `pulumi up`.
## Pulumi Plugin
- Display relevant Pulumi information about an entity within Backstage, such as the Pulumi stack, organization, project
name, and project description.
- Show the Pulumi activity view for an entity within Backstage.
### Requirements
- Setup of the Pulumi plugin for Backstage requires a Pulumi Organization admin to generate a Pulumi access token for
the Backstage application.
### Feature Overview
#### Pulumi Card (Component Overview)
#### Pulumi Card (System Overview)
#### Pulumi Activity View
### Support
If you need any help with this plugin, feel free to reach out to me!
### Integration Walk-through
#### Install the plugin
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](https://backstage.io/docs/getting-started/) guide and creating your app with
`npx @backstage/create-app`.
First, install the Pulumi plugin via a CLI:
```bash
# 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:
```tsx
import {
isPulumiAvailable,
EntityPulumiCard,
EntityPulumiMetdataCard,
PulumiComponent
} from '@pulumi/backstage-plugin-pulumi';
```
Then create a new constant for the Pulumi Component:
```tsx
const pulumiContent = (
);
```
Find const `overviewContent` in `EntityPage.tsx`, and add the following snippet inside the outermost Grid defined there,
just before the closing `` tag:
```tsx
```
Now find the `serviceEntityPage` constant in `EntityPage.tsx`, and add the following snippet inside:
```tsx
{pulumiContent}
```
Lastly, find the `systemPage` constant in `EntityPage.tsx`, and add the following snippet inside after the
closing `` tag of the ``:
```tsx
```
#### Configure the plugin
First, annotate your component/resource entity with the following:
```yaml
annotations:
pulumi.com/project-slug: [Pulumi Cloud Name: org/stackname/stack]
```
And your system entity with the following:
```yaml
annotations:
pulumi.com/orga-slug: [Pulumi Cloud: org]
```
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`:
```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:
```bash
export PULUMI_ACCESS_TOKEN=''
yarn start
```
This will proxy the request by adding an `Authorization` header with the provided token.
#### How to Uninstall
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.
1. Remove the added code snippets from `EntityPage.tsx`
1. Remove the plugin package:
```bash
# From your Backstage root directory
yarn remove --cwd packages/app @pulumi/backstage-plugin-pulumi
```
## Catalog Backend Module for Pulumi
This is an extension module to the `plugin-catalog-backend` plugin, providing an `PulumiEntityProvider` that can be used to ingest
[Resource entities](https://backstage.io/docs/features/software-catalog/descriptor-format#kind-resource) from the
[Pulumi Cloud](https://app.pulumi.com/). This provider is useful if you want to import Pulumi stacks into Backstage.
### Installation
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:
```bash
# 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:
```typescript
//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.
### Configuration
The following configuration is an example of how a setup could look for importing stacks from Pulumi Cloud:
```yaml
catalog:
providers:
pulumi:
default:
api: https://api.pulumi.com
organization:
pulumiAccessToken: ${PULUMI_ACCESS_TOKEN}
schedule:
frequency: PT10M
timeout: PT50M
```