Backstage GCP Entity Providers Plugin

Install the backend module

yarn add --cwd packages/backend @backtostage/plugin-catalog-backend-module-gcp

Set up credentials

Create a Google service account with access to list the resources you want to ingest. Store its JSON key file on disk. Point the backend to it with this env var.

export GOOGLE_APPLICATION_CREDENTIALS=/absolute/path/to/service-account.json

You can also use impersonated credentials if that fits your setup.

Wire it into the new backend system

Add the module to your backend entry file. Put these imports and backend.add calls in packages/backend/src/index.ts where you create and configure the backend.

// packages/backend/src/index.ts
import {
  catalogModuleGoogleSQLDatabaseEntityProvider,
  catalogModuleGoogleRedisDatabaseEntityProvider,
  catalogModuleGoogleOrganizationProjectEntityProvider,
} from '@backtostage/plugin-catalog-backend-module-gcp';

// Add one or more providers
backend.add(catalogModuleGoogleSQLDatabaseEntityProvider);
backend.add(catalogModuleGoogleRedisDatabaseEntityProvider);
backend.add(catalogModuleGoogleOrganizationProjectEntityProvider);

You can add only the providers you need. For example only SQL or only Redis.

// Only Cloud SQL
backend.add(catalogModuleGoogleSQLDatabaseEntityProvider);

// Only Redis
backend.add(catalogModuleGoogleRedisDatabaseEntityProvider);

// Only Projects from an organization
backend.add(catalogModuleGoogleOrganizationProjectEntityProvider);

Configure catalog providers

Use the gcpResources key to avoid conflicts with other GCP catalog modules. The old gcp key still works but is deprecated.

Example with a single project and both SQL and Redis. This also sets labels for owner component and system.

# app-config.yaml
catalog:
  providers:
    gcpResources:
      - project: my-gcp-project-id
        ownerLabel: team
        componentLabel: app
        systemLabel: system
        cloudsql:
          resourceType: CloudSQL
          suffix: cloudsql
          disabled: false
          namespaceByProject: false
        redis:
          resourceType: Memorystore Redis
          location: us-central1
          suffix: redis
          disabled: false
          namespaceByProject: false
        schedule:
          frequency: { minutes: 30 }
          timeout: { minutes: 3 }

Example that loads projects from an organization. The project list step runs through the Google API query. Then resources can be ingested based on those projects.

# app-config.yaml
catalog:
  providers:
    gcpResources:
      - organization:
          query: parent:organizations/1234567890
          resourceType: Project
        schedule:
          frequency: { minutes: 30 }
          timeout: { minutes: 3 }

Optional settings you can use in the entries above

• ownerLabel default is owner
• componentLabel default is component
• systemLabel default is system
• cloudsql suffix default is cloudsql
• redis suffix default is redis
• redis location can be a region or left empty to scan all regions
• disabled default is false for each provider
• namespaceByProject default is false for each provider

When you enable namespaceByProject the plugin does not remove resources that already exist in the default namespace. Clean those if you want to avoid duplicates.

You can also fine tune the schedule with initialDelay and scope. These use the same shapes as the Backstage task schedule.

schedule:
  frequency: { minutes: 30 }
  timeout: { minutes: 3 }
  initialDelay: { seconds: 10 }
  scope: global

If you must use the deprecated key this is the equivalent shape. Prefer gcpResources.

catalog:
  providers:
    gcp:
      - project: my-gcp-project-id
        schedule:
          frequency: { minutes: 30 }
          timeout: { minutes: 3 }

What appears in the catalog

This module creates Resource entities for Cloud SQL and Redis. It can also create Project entities from your organization search. The owner field can come from your chosen label. The dependency and system fields can come from the component and system labels.

Frontend changes

No frontend additions are needed. The entities will show up in the Catalog pages once the backend ingests them.

Old backend system

This package is built as a backend module for the new backend system. It does not document a legacy CatalogBuilder integration. If your app still uses the old backend, move the catalog to the new backend module loader then add the providers as shown earlier.