Skip to main content

Terraform State Backend Plugin

The Terraform State Backend ingests Terraform state from GCS buckets and Terraform Cloud workspaces, creating hierarchical catalog entities in Backstage.

Overview​

PropertyValue
Package@internal/plugin-terraform-state-backend
TypeBackend (Catalog Provider)
Plugin IDterraform-state
IntegrationGCS, Terraform Cloud, Vault

Architecture​

Providers​

GCS State Provider​

Reads Terraform state from Google Cloud Storage.

import { catalogModuleTerraformStateGcsProvider } from "@internal/plugin-terraform-state-backend";

// Register in backend
backend.add(catalogModuleTerraformStateGcsProvider);

Features:

  • Multiple bucket support
  • State file discovery
  • Workspace detection

TFC State Provider​

Reads Terraform state from Terraform Cloud.

import { catalogModuleTerraformStateTfcProvider } from "@internal/plugin-terraform-state-backend";

// Register in backend
backend.add(catalogModuleTerraformStateTfcProvider);

Features:

  • Organization/workspace enumeration
  • State version retrieval
  • Vault token integration

State Processing​

Processing Pipeline​

Resource Filtering​

The ResourceFilter applies whitelists and mappings:

interface ResourceFilter {
  whitelist: string[]; // Resource types to include
  mappings: ResourceMapping[]; // Type to entity mappings
}

Default Whitelist (GCP):

  • google_project
  • google_compute_instance
  • google_storage_bucket
  • google_sql_database_instance
  • google_container_cluster
  • And more...

Hierarchy Builder​

Creates parent-child relationships:

Resource Graph Builder​

Builds resource dependency graph:

Generated Entities​

Entity Kinds​

Resource TypeEntity KindEntity Type
google_projectResourcegcp-project
google_compute_instanceResourcegcp-compute
google_storage_bucketResourcegcp-storage
google_sql_database_instanceResourcegcp-sql
google_container_clusterResourcegcp-gke

Entity Annotations​

apiVersion: backstage.io/v1alpha1
kind: Resource
metadata:
  name: my-vm-instance
  annotations:
    terraform/resource-type: google_compute_instance
    terraform/state-source: gs://my-bucket/terraform.tfstate
    terraform/workspace: production
    gcp/project: my-project-id
    gcp/region: us-central1
    gcp/console-link: https://console.cloud.google.com/compute/instances/...
spec:
  type: gcp-compute
  owner: platform-team
  dependsOn:
    - resource:default/my-vpc
    - resource:default/my-service-account

The plugin generates GCP console links:

interface ConsoleLink {
  resourceType: string;
  urlTemplate: string;
}

// Example mappings
const consoleLinkMappings = {
  google_compute_instance:
    "https://console.cloud.google.com/compute/instancesDetail/zones/{zone}/instances/{name}?project={project}",
  google_storage_bucket:
    "https://console.cloud.google.com/storage/browser/{name}?project={project}",
  google_container_cluster:
    "https://console.cloud.google.com/kubernetes/clusters/details/{location}/{name}/details?project={project}",
};

Configuration​

# app-config.yaml
catalog:
  providers:
    terraformStateGcs:
      buckets:
        - name: my-terraform-state
          prefix: environments/
        - name: my-other-state

    terraformStateTfc:
      organizations:
        - acme-corp
        - staging-org

Services​

StateProcessingService​

Core service for state file processing.

interface StateProcessingService {
  processState(state: TerraformState): ProcessedState;
  extractResources(state: TerraformState): Resource[];
  buildEntities(resources: Resource[]): Entity[];
}

VaultTokenService​

Retrieves TFC tokens from Vault.

interface VaultTokenService {
  getToken(organization: string): Promise<string>;
}

Module Exports​

// Main exports
export {
  catalogModuleTerraformStateTfcProvider,
  catalogModuleTerraformStateGcsProvider,
  TfcStateProvider,
  GcsStateProvider,
  StateProcessingService,
  ResourceFilter,
  HierarchyBuilder,
  ResourceGraphBuilder,
  VaultTokenService,
};