Google Cloud

Scope: CLI and API only. This guide covers the gcloud CLI and the Firefly API for onboarding GCP projects without the console wizard. Firefly also ships a Terraform module for Google Cloud onboarding, documented separately.

When to use this

Use this guide to bulk onboard GCP projects, drive onboarding from a CI/CD pipeline, or enable org-level discovery. For a single project, the console wizard (Settings > Integrations > Add New > Google Cloud) is faster.

Prerequisites

• Admin access to the Firefly console

• gcloud CLI, authenticated

• GCP IAM permissions to create service accounts and grant roles

• Org-level IAM permissions if you want folder-tree discovery (optional)

• curl and jq

Pre-flight: can you create service account keys?

Run this before committing to a timeline. This integration depends on a downloadable service account JSON key, and some organizations block key creation with an org policy.

gcloud resource-manager org-policies describe \
  constraints/iam.disableServiceAccountKeyCreation \
  --project="$PROJECT_ID" --effective

If the constraint is enforced, key creation will fail and no amount of IAM permission will fix it. Options, in order of preference:

1. Request a scoped exception for the Firefly project only. Most platform teams will grant this for a single, audited service account — a narrower ask than disabling the policy org-wide.

2. Use a project that's out of scope of the policy, if you have one designated for third-party integrations.

3. Contact your Firefly representative to confirm whether a keyless option (Workload Identity Federation) is currently available for this integration.

Two related constraints worth checking at the same time, since both cause confusing failures later:

gcloud resource-manager org-policies describe \
  constraints/iam.disableServiceAccountKeyUpload \
  --project="$PROJECT_ID" --effective

gcloud resource-manager org-policies describe \
  constraints/iam.allowedPolicyMemberDomains \
  --project="$PROJECT_ID" --effective

The second restricts which identities can be granted roles and is a common cause of "role binding rejected" errors that look like a permissions problem but aren't.

Phase A — Authenticate to Firefly

Create the key pair under Settings > Users > Create Key Pair, then:

FIREFLY_API="https://prodapi.firefly.ai/api"

TOKEN=$(curl -sS -X POST "${FIREFLY_API}/account/access_keys/login" \
  -H "Content-Type: application/json" \
  -d "{\"accessKey\":\"${FIREFLY_ACCESS_KEY}\",\"secretKey\":\"${FIREFLY_SECRET_KEY}\"}" \
  | jq -r '.access_token // .accessToken')

Phase B — Configure Google Cloud

1. Authenticate and set the project

gcloud auth login
gcloud config set project PROJECT_ID

PROJECT_ID=$(gcloud config get-value project)

2. Create the service account

gcloud iam service-accounts create firefly-sa \
  --description="Service Account for Firefly integration" \
  --display-name="Firefly Service Account"

SA_EMAIL="firefly-sa@${PROJECT_ID}.iam.gserviceaccount.com"
echo "$SA_EMAIL"

Use a dedicated service account rather than reusing an existing one — it keeps revocation and audit simple.

3. Grant project-level roles

for ROLE in \
  roles/viewer \
  roles/iam.securityReviewer \
  roles/logging.configWriter \
  roles/storage.bucketViewer
do
  gcloud projects add-iam-policy-binding "$PROJECT_ID" \
    --member="serviceAccount:${SA_EMAIL}" \
    --role="$ROLE" \
    --condition=None
done

Role	Purpose
roles/viewer	Read-only access for inventory discovery
roles/iam.securityReviewer	IAM and security configuration, for compliance scanning
roles/logging.configWriter	Required for event-driven integration (log sinks)
roles/storage.bucketViewer	Bucket metadata for IaC state discovery

4. Grant conditional tfstate access

Object read access is scoped by an IAM condition so Firefly can only read objects whose name ends in tfstate.

gcloud projects add-iam-policy-binding "$PROJECT_ID" \
  --member="serviceAccount:${SA_EMAIL}" \
  --role="roles/storage.objectViewer" \
  --condition='title=TFStateSuffix,description=Limit access to tfstate objects only,expression=resource.name.endsWith("tfstate")'

Use add-iam-policy-binding, never set-iam-policy, for this. set-iam-policy overwrites the project's entire IAM policy document; add-iam-policy-binding is additive and safe.

5. Org-level folder discovery (optional)

Only needed if you want Firefly to discover the folder tree and auto-enroll projects. Requires org admin.

ORG_ID=$(gcloud organizations list --format="value(ID)")
ROLE_ID="fireflyFolderDiscovery"

gcloud iam roles create "$ROLE_ID" \
  --organization="$ORG_ID" \
  --title="Firefly Folder Discovery" \
  --description="Allows Firefly to discover the folder tree" \
  --permissions="resourcemanager.folders.get,resourcemanager.folders.list" \
  --stage="GA"

gcloud organizations add-iam-policy-binding "$ORG_ID" \
  --member="serviceAccount:${SA_EMAIL}" \
  --role="organizations/${ORG_ID}/roles/${ROLE_ID}"

For full org-wide project discovery, also grant roles/viewer at the organization scope. This is the main scale lever on GCP — with org-level viewer and auto-discovery enabled, you onboard one anchor project and Firefly enumerates the rest.

6. Generate the service account key

gcloud iam service-accounts keys create firefly-sa-key.json \
  --iam-account="$SA_EMAIL"

This file is a long-lived credential. Keep it out of version control, delete it from your workstation once uploaded, and agree a rotation schedule up front.

Service account keys don't expire. That's a common finding in security reviews — the key is scoped to a dedicated read-only service account, the tfstate binding is conditioned to a filename suffix, and rotation is a process you control. To rotate, create a second key, update the integration in the Firefly console, then delete the old key:

gcloud iam service-accounts keys list --iam-account="$SA_EMAIL"
gcloud iam service-accounts keys delete KEY_ID --iam-account="$SA_EMAIL"

Agree a rotation interval during onboarding rather than after the first audit.

7. Enable required APIs

gcloud services enable \
  logging.googleapis.com \
  admin.googleapis.com \
  appengine.googleapis.com \
  bigquery.googleapis.com \
  cloudbilling.googleapis.com \
  cloudfunctions.googleapis.com \
  cloudscheduler.googleapis.com \
  dataproc.googleapis.com \
  dns.googleapis.com \
  cloudresourcemanager.googleapis.com \
  sqladmin.googleapis.com \
  compute.googleapis.com \
  iam.googleapis.com \
  container.googleapis.com \
  servicemanagement.googleapis.com \
  serviceusage.googleapis.com \
  cloudasset.googleapis.com \
  redis.googleapis.com \
  storage.googleapis.com \
  groupssettings.googleapis.com \
  spanner.googleapis.com \
  file.googleapis.com \
  recommender.googleapis.com

Takes 2–3 minutes. recommender.googleapis.com powers Google Cloud Insights — leaving it out silently disables that feature.

8. Additional projects (optional)

The same service account can cover multiple projects. For each additional project, repeat steps 3, 4, and 7 with PROJECT_ID set to the new project and SA_EMAIL unchanged:

for P in project-b project-c project-d; do
  for ROLE in roles/viewer roles/iam.securityReviewer roles/logging.configWriter roles/storage.bucketViewer; do
    gcloud projects add-iam-policy-binding "$P" \
      --member="serviceAccount:${SA_EMAIL}" --role="$ROLE" --condition=None
  done
done

Phase C — Register with Firefly

SA_KEY=$(jq -c . firefly-sa-key.json | jq -R .)

PAYLOAD=$(jq -n \
  --arg name "Production GCP" \
  --arg projectId "$PROJECT_ID" \
  --argjson serviceAccountKey "$SA_KEY" \
  '{
    name: $name,
    projectId: $projectId,
    serviceAccountKey: $serviceAccountKey,
    isPrimary: true,
    shouldAutoDiscoverProjects: true,
    isProd: true,
    isEventDrivenDisabled: false,
    isIacAutoDiscoverDisabled: false,
    regexExcludeProjectsDiscovery: []
  }')

curl -sS -X POST "${FIREFLY_API}/integrations/google" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  --data "$PAYLOAD" | jq .

Parameter	Description
name	Display name for the integration
projectId	The GCP project ID being integrated. This is the anchor project used to discover the rest
serviceAccountKey	Full contents of firefly-sa-key.json, as a JSON string
isPrimary	True if this is your primary GCP integration
shouldAutoDiscoverProjects	Discover all accessible projects automatically
isProd	Marks the integration as production
isEventDrivenDisabled	false enables real-time event detection
isIacAutoDiscoverDisabled	false enables automatic IaC discovery
regexExcludeProjectsDiscovery	Regex list of projects to skip, e.g. [".*-test$", "sandbox-.*"]

The initially integrated project is listed first in the console, and every subsequently discovered project hangs off it. Deleting that first project deletes the whole integration — worth planning around before you tidy up unused projects.

This call isn't documented as idempotent. If a registration partially fails, check the console before retrying rather than assuming a second call will update the integration in place.

Verify

1. Firefly console > Settings > Integrations > Google Cloud

2. Confirm the project appears and the status is connected

3. Inventory, filtered to Google Cloud — allow 10–15 minutes for first discovery

Troubleshooting

Symptom	Likely cause
Key creation fails outright	constraints/iam.disableServiceAccountKeyCreation is enforced — see the pre-flight check above
Role binding rejected	Org policy restricting IAM grants (allowedPolicyMemberDomains), or missing resourcemanager.projects.setIamPolicy
API enablement fails	Billing not enabled on the project, or missing serviceusage.services.enable
Registration returns 4xx	Malformed serviceAccountKey (check the jq -c . | jq -R . escaping), or an expired token
Some projects missing from Inventory	APIs not enabled on those projects, or they match an exclusion regex
No IaC state discovered	The tfstate IAM condition wasn't applied, or state objects don't end in tfstate