Backstage Terraform Environments Plugin

This plugin allows managing ephemeral Terraform environments using GitHub Issues and Actions.

Features

• List all Terraform environments
• View environment details and status
• Destroy environments that are no longer needed
• Integration with GitHub Issues for tracking
• Integration with GitHub Actions for provisioning and destruction

Installation

1. Install the plugin in your Backstage app:

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

2. Configure the plugin in your app-config.yaml:

terraformenvironments:
  defaultowner: your-github-org-name
  defaultrepo: your-repo-name

3. Add the plugin API factory to your packages/app/src/apis.ts:

import { 
  createApiFactory,
  configApiRef,
} from '@backstage/core-plugin-api';
import { scmAuthApiRef } from '@backstage/integration-react';
import { 
  terraformEnvironmentsApiRef,
  createTerraformEnvironmentsApi 
} from '@invincible/backstage-plugin-terraform-environments';

export const apis = [
  // ... existing API factories
  
  // Add the Terraform Environments API
  createApiFactory({
    api: terraformEnvironmentsApiRef,
    deps: { scmAuthApi: scmAuthApiRef },
    factory: ({ scmAuthApi }) => createTerraformEnvironmentsApi(scmAuthApi),
  }),
];

4. Add the plugin page to your packages/app/src/App.tsx:

import { TerraformEnvironmentsPage } from '@invincible/backstage-plugin-terraform-environments';

// In your routes:
<Route path="/terraform-environments" element={<TerraformEnvironmentsPage />} />

GitHub Configuration

The plugin requires GitHub authentication to be set up in your Backstage instance:

1. Create a GitHub App or Personal Access Token with the following permissions:

   • repo (full access to repositories)
   • workflow (ability to trigger workflows)

2. Configure GitHub authentication in your app-config.yaml:

integrations:
  github:
    - host: github.com
      token: ${GITHUB_TOKEN}

GitHub Action Workflows

The plugin works with two GitHub Action workflows:

1. terraform-pr.yml: Creates environments when PR is opened
2. destroy-environment.yml: Destroys environments when requested

These workflows should be placed in .github/workflows/ in your infrastructure repository.

Troubleshooting

If you encounter any issues with the plugin:

1. Check your browser console for error messages
2. Verify that the GitHub token has the required permissions
3. Make sure your app-config.yaml has the correct configuration
4. Check that the GitHub repository exists and is accessible

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.