Skip to content

Installing the Terraform Scaffolder Plugin#

This guide will help you install and set up the Terraform Scaffolder plugin in your Backstage instance.

Prerequisites#

  • Backstage application
  • Node.js and npm/yarn
  • Access to Terraform modules (e.g., GitHub repositories, Terraform Registry)
  • GitHub token (if using private repositories)

Installation Steps#

  1. Install the plugin package:
# Using yarn
yarn --cwd packages/app add @backstage/plugin-terraform-scaffolder
  1. Register the plugin in your Backstage app:
// packages/app/src/apis.ts
import { terraformScaffolderPlugin } from '@backstage/plugin-terraform-scaffolder';

export const apis = [
  // ... other APIs
  terraformScaffolderPlugin,
];
  1. Configure the plugin in your app-config.yaml:
terraformScaffolder:
  # Enable proxy support for private GitHub repositories
  useProxyForGitHub: true

  # Registry module configuration (optional)
  registryReferences:
    returnAllVersions: true
    namespaces:
      - terraform-aws-modules
      - vmware

  # Direct module references
  moduleReferences:
    - name: 'AWS ECR Module'
      url: 'https://github.com/terraform-aws-modules/terraform-aws-ecr'
      refs:
        - 'v3.1.0'
      description: 'AWS ECR Module'
  1. If using private GitHub repositories, configure the proxy:
proxy:
  endpoints:
    '/github-raw':
      target: 'https://raw.githubusercontent.com'
      changeOrigin: true
      headers:
        Authorization: 'Token ${GITHUB_TOKEN}'
  1. Add the field extension to your template:
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: terraform-infrastructure
  title: Create Infrastructure
spec:
  parameters:
    - title: Infrastructure
      properties:
        infrastructure:
          title: Terraform Module
          type: string
          ui:field: TerraformModule

Verification#

To verify the installation:

  1. Navigate to your software templates
  2. Create a new component using a template with the TerraformModule field
  3. Verify that you can:
  4. Select from available modules
  5. Choose module versions
  6. Configure module variables
  7. See validation messages
  8. Submit the form successfully
  9. Access private repositories (if configured)

Troubleshooting#

Common issues and solutions:

  1. Module Not Found
  2. Check module URL in app-config.yaml
  3. Verify GitHub access permissions
  4. Check module ref/branch exists

  5. Verify registry namespace configuration

  6. Private Repository Access

  7. Check GitHub token permissions
  8. Verify proxy configuration
  9. Ensure useProxyForGitHub is enabled

  10. Check proxy endpoint headers

  11. Type Errors

  12. Ensure all required API dependencies are installed
  13. Check for version mismatches

  14. Verify type definitions in variables.tf

  15. Form Validation Errors

  16. Verify variables.tf exists in module
  17. Check variable type definitions
  18. Ensure version references are correct

Next Steps#

After installation:

  1. Configure your module sources:
  2. Add configuration-based modules
  3. Set up catalog-based modules

  4. Configure registry integration

  5. Set up security:

  6. Configure private repository access
  7. Set up proxy settings

  8. Manage GitHub tokens

  9. Create and test templates:

  10. Create templates using the TerraformModule field
  11. Test with different module versions

  12. Verify variable handling

  13. Plan for production:

  14. Set up CI/CD for your Terraform deployments
  15. Document module usage
  16. Plan version management strategy

For detailed configuration options, see the Configuration guide.