{"id":15679273,"url":"https://github.com/joatmon08/backstage-plugin-terraform","last_synced_at":"2025-07-04T11:01:42.536Z","repository":{"id":158355060,"uuid":"633982378","full_name":"joatmon08/backstage-plugin-terraform","owner":"joatmon08","description":"Experimental Terraform Cloud Plugin for Backstage","archived":false,"fork":false,"pushed_at":"2023-12-06T15:48:30.000Z","size":2076,"stargazers_count":17,"open_issues_count":2,"forks_count":14,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-04-19T20:53:58.711Z","etag":null,"topics":["backstage","terraform"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/joatmon08.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2023-04-28T18:26:02.000Z","updated_at":"2024-06-27T01:41:28.000Z","dependencies_parsed_at":"2023-12-06T16:40:31.967Z","dependency_job_id":null,"html_url":"https://github.com/joatmon08/backstage-plugin-terraform","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joatmon08%2Fbackstage-plugin-terraform","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joatmon08%2Fbackstage-plugin-terraform/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joatmon08%2Fbackstage-plugin-terraform/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joatmon08%2Fbackstage-plugin-terraform/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/joatmon08","download_url":"https://codeload.github.com/joatmon08/backstage-plugin-terraform/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252852607,"owners_count":21814386,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["backstage","terraform"],"created_at":"2024-10-03T16:28:07.314Z","updated_at":"2025-05-07T09:43:06.545Z","avatar_url":"https://github.com/joatmon08.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# [Backstage](https://backstage.io)\n\nThis is an example Backstage app that includes two Terraform plugins:\n\n1. Scaffolder Action - creates Terraform Cloud/Enterprise resources using scaffolder\n1. Terraform frontend plugin - retrieves information for an entity based on an organization and workspace\n\n## Prerequisites\n\nInstall [Backstage prerequisites](https://backstage.io/docs/getting-started/#prerequisites).\n\n## Install\n\nIn your terminal, set the Terraform Cloud token and GitHub token\n\n```sh\nexport GITHUB_TOKEN=\"\"\nexport TF_TOKEN=\"\"\n```\n\nTo start the app, run:\n\n```sh\nyarn install\n\nyarn dev\n```\n\n## Using the Scaffolder Action\n\nThis repository includes an example template for the Scaffolder to use\nunder `examples/terraform`.\n\nReview `template.yaml` for the series of custom actions specific\nto Terraform. You can...\n\n- Create projects\n- Create workspaces\n- Create runs\n\nHowever, you will encounter a few caveats:\n\n- Scaffolder is *not* intended to be idempotent. If you have an\n  existing project, you must remove the \"Create Project\" step\n  from the template.\n\n- Variables must be passed through scaffolder. Secrets should\n  not be passed directly through scaffolder, consider setting them\n  separately using variable sets or using dynamic credentials\n  from Vault.\n\n- Workspaces use VCS connections. This ensures that you can\n  manage your infrastructure on Day 2.\n  - If you do not specific a `vcsAuthUser`, the VCS connection will\n    default to the first OAuth client returned by the Terraform API.\n  - If you specify a `vcsAuthUser`, the action will return\n    the first VCS OAuth token associated with that user. **Note that\n    `vcsAuthUser` must have sufficient permissions to access\n    the `vcsRepo` you are connecting.**\n\n\n## Using Scaffolder with HashiCorp Vault \u0026 GitHub\n\nIdeally, you'll want to scope your Terraform token to\nthe workspace and projects specific to a group. One approach\nis to use HashiCorp Vault to generate the Terraform tokens.\n\nIn order to allow Backstage to access Vault, you need to configure\nan authentication provider for Backstage using an SCM tool (GitHub, GitLab, etc.).\n\nThis is because Scaffolder has a\n[built-in action](https://backstage.io/docs/features/software-templates/writing-templates/#using-the-users-oauth-token)\nthat allows you to retrieve a user OAuth token from the SCM tool for use in subsequent actions.\n\n```text\n             ┌─────────────► SCM Provider ◄─────────────────────┐\n             │                 (GitHub)                         │\n             │                                                  │\n             │                                                  │\n             │                                             ┌────┴────┬──────────────────┐\n             │                                             │         │ Vault            │\n┌────────────┴──────────────┐Auth with OAuth user token    │         │                  │\n│                           ├──────────────────────────────►  GitHub │                  │\n│        Backstage          │  Return Vault token          │   Auth  │ Terraform Cloud  │\n│   (GitHub Auth Provider)  ◄──────────────────────────────┤  Method │  Secrets Engine  │\n│                           │                              │         │                  │\n└────────────▲───┬──────────┘                              └─────────┴────▲──┬──────────┘\n             │   │             Use Vault token to get TFC token           │  │\n             │   └────────────────────────────────────────────────────────┘  │\n             │                    Return TFC Token                           │\n             └───────────────────────────────────────────────────────────────┘\n```\n\n### Set up GitHub\n\n1. Create a [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)\n   with read-only access to your organization.\n\n1. Set the personal access token as an environment variable for Backstage.\n   This allows Backstage to read repositories and register entities into catalog.\n   ```shell\n   export GITHUB_TOKEN=\"\"\n   ```\n\n1. Create an OAuth App for Backstage in GitHub under **your organization**.\n\n1. Set the client ID and secret as environment variables for Backstage.\n   ```shell\n   export AUTH_GITHUB_CLIENT_ID=\"\"\n   export AUTH_GITHUB_CLIENT_SECRET=\"\"\n   ```\n\n1. Sign into Backstage using your GitHub user and make sure\n   you grant a user access to the organization.\n\n### Set up Terraform Cloud\n\n1. Set a read-only Terraform Cloud token that allows\n   Backstage frontend components to retrieve information\n   about workspaces, runs, and outputs.\n   ```shell\n   export TF_TOKEN=\"\"\n   ```\n\n1. In your Terraform Cloud organization, add a VCS provider.\n\n1. Create an OAuth App for Terraform Cloud in GitHub under **your organization**.\n\n### Set up Vault\n\n1. Using Docker, create a development Vault server.\n   ```shell\n   cd vault \u0026\u0026 docker-compose up -d \u0026\u0026 cd ..\n   ```\n\n1. Set environment variables to configure Vault Github auth method,\n   using organization, organization ID, and a sample user.\n   ```shell\n   export VAULT_GITHUB_ORG=\"\"\n   export VAULT_GITHUB_ORG_ID=\"\"\n   export VAULT_GITHUB_USER=\"\"\n   ```\n\n1. Set environment variables for Terraform Cloud secrets engine,\n   including organization token and team ID specific to backstage.\n   ```shell\n   export TERRAFORM_CLOUD_ORGANIZATION_TOKEN=\"\"\n   export TERRAFORM_CLOUD_TEAM_ID=\"\"\n   ```\n\n1. Run `bash vault/setup.sh`. This sets up the auth method, policies,\n   and secrets engines for Backstage to authenticate and retrieve secrets\n   from Vault.\n\n### Run the Scaffolder Template\n\nStart Backstage. Choose the Terraform template and enter the form values.\nThe Vault defaults are already set. When you create the repository,\nBackstage authenticates to Vault with its GitHub OAuth user access token,\ngets a Vault token, and uses that to retrieve the Terraform Cloud token.\n\nThe Terraform Cloud token in this example is a team token, which has sufficient\npermission to create workspaces and projects in Terraform Cloud.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoatmon08%2Fbackstage-plugin-terraform","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjoatmon08%2Fbackstage-plugin-terraform","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoatmon08%2Fbackstage-plugin-terraform/lists"}