GCP Setup¶

Placeholder — awaiting screenshots

This walkthrough is being migrated from an earlier version of the guide. The text is accurate against the current GCP console and gcloud CLI as of May 2026, but the inline screenshots haven't been re-captured yet. The image placeholders below show where they will land. The steps work end-to-end without them — they're a comprehension aid, not a prerequisite. If anything is unclear in the meantime, contact support and we'll talk you through it.

GCP support is in early access

GCP discovery covers 29 services today (Compute Engine VMs, managed instance groups, GKE clusters, Cloud Run, Cloud Functions, Cloud Scheduler, Cloud Tasks, Pub/Sub topics & subscriptions, Cloud Storage, persistent disks, Filestore, Artifact Registry, BigQuery, Bigtable, Firestore, Cloud SQL, Memorystore, VPC networks, subnets, Cloud NAT, firewall rules, load balancers, Cloud DNS, Cloud KMS keyrings, Secret Manager, IAM service accounts, and more). Full parity with the AWS catalogue is on the roadmap.

LightPane connects to your GCP project using Workload Identity Federation (WIF) — the Google-recommended approach for cross-cloud access. No secrets are exchanged or stored. LightPane's AWS Lambda authenticates directly to your GCP project using its own AWS credentials and exchanges them for short-lived (1-hour) GCP access tokens at request time.

A service account key option is available as a fallback for environments where WIF can't be used.

What you'll need¶

A GCP project you can manage (you'll need Owner or Project IAM Admin to create a Workload Identity Pool and grant IAM roles).
5-10 minutes in Cloud Shell.
The ability to copy two values from GCP into your LightPane profile: the Project ID (e.g. my-project-123) and the WIF Credential Configuration JSON the script generates.

If you don't have a GCP project yet, create one at console.cloud.google.com — the GCP Free Tier covers everything LightPane needs to read.

How it works¶

You create a Workload Identity Pool in your GCP project that trusts the LightPane AWS account (236353235295).
You create a service account with the built-in Viewer role.
You allow the AWS-federated identity to impersonate that service account.
LightPane's Lambda uses its AWS credentials to obtain short-lived (1-hour) GCP access tokens via Security Token Service.
No private keys or long-lived credentials are ever exchanged or stored on either side.

What can be accessed¶

The Viewer role provides read-only access to resource configuration in your project:

Compute Engine VMs, instance groups, GKE clusters, Cloud Run services, Cloud Functions
Cloud Storage buckets, persistent disks, Filestore (configuration only — never the objects, blobs, or file contents)
BigQuery datasets, Bigtable instances, Firestore databases, Cloud SQL instances, Memorystore (configuration only — never row contents)
VPC networks, subnets, firewall rules, Cloud NAT, load balancers, Cloud DNS zones
IAM service accounts, Cloud KMS keyrings, Secret Manager metadata
Cloud Scheduler jobs, Cloud Tasks queues, Pub/Sub topics & subscriptions

What CANNOT be accessed¶

Cannot modify, create, or delete any resource
Cannot read storage object data, BigQuery row contents, or Cloud SQL row contents
Cannot read Secret Manager secret values (only that they exist and their metadata)
Cannot decrypt with Cloud KMS keys
Cannot perform any write or management operation
Cannot access resources in any project other than the one you ran the script against

Step 1: Open the setup dialogue in LightPane¶

Sign in to app.lightpane.io.
Go to Cloud accounts in the top nav.
Click the GCP tab, then Link new GCP project.
You'll see a dialogue with the Cloud Shell setup script and two empty fields: Project ID and WIF Credential Configuration. Leave this open in a tab — you'll come back to it in Step 4.

Screenshot placeholder — LightPane Cloud accounts page with the GCP tab selected and the Link new GCP project dialogue open, showing the script and the two empty input fields

Step 2: Open Cloud Shell in your GCP project¶

Sign in to the GCP console.
Make sure the project selector (top of the page, next to the "Google Cloud" logo) shows the project you want LightPane to read. If not, click it and switch to the correct project.

Screenshot placeholder — GCP console with the project selector dropdown highlighted showing the active project

Click the Activate Cloud Shell icon in the top-right toolbar (it looks like a >_ terminal prompt). A Cloud Shell session opens at the bottom of the page.

Screenshot placeholder — GCP console top toolbar with the Activate Cloud Shell terminal icon circled

Why Cloud Shell?

Cloud Shell runs as your user, with gcloud pre-authenticated and the active project pre-selected. The setup script just works without any prior CLI configuration. You can also run the same script from a local terminal if gcloud is installed and logged in (gcloud auth login), but Cloud Shell is the shortest path.

Step 3: Paste and run the setup script¶

Copy the entire script from the LightPane dialogue (Step 1) and paste it into Cloud Shell. The script creates a Workload Identity Pool, an AWS provider on the pool, a service account named lightpane-reader, the IAM bindings, and then prints the credential config JSON you'll need in Step 4.

The script is reproduced here for reference:

# 0. Variables — LIGHTPANE_AWS_ACCOUNT is the LightPane platform's
#    AWS account ID (236353235295). Don't change it unless support
#    has told you to.
export PROJECT_ID=$(gcloud config get-value project)
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')
export LIGHTPANE_AWS_ACCOUNT="236353235295"

# 1. Enable the required APIs
gcloud services enable \
  iamcredentials.googleapis.com \
  iam.googleapis.com \
  cloudresourcemanager.googleapis.com \
  sts.googleapis.com

# 2. Create a Workload Identity Pool
gcloud iam workload-identity-pools create lightpane-pool \
  --location="global" \
  --display-name="LightPane Discovery"

# 3. Add an AWS provider with an EXPLICIT attribute mapping.
#    Two attributes are mapped:
#      * attribute.aws_account = the AWS account the identity came
#        from. Used in step 6 alongside aws_role.
#      * attribute.aws_role    = the IAM role name extracted from the
#        STS ARN (everything between `assumed-role/` and the next `/`).
#        This is what lets step 6 restrict impersonation to specific
#        LightPane Lambda execution roles rather than the whole
#        LightPane platform AWS account.
#    Recent gcloud versions no longer populate a default mapping
#    automatically — without this `--attribute-mapping` arg the
#    pool would accept the AWS identity but no principalSet binding
#    would ever resolve (you'd get `Permission iam.serviceAccounts.
#    getAccessToken denied` from impersonation).
gcloud iam workload-identity-pools providers create-aws lightpane-aws \
  --location="global" \
  --workload-identity-pool="lightpane-pool" \
  --account-id="$LIGHTPANE_AWS_ACCOUNT" \
  --attribute-mapping="google.subject=assertion.arn,attribute.aws_account=assertion.account,attribute.aws_role=assertion.arn.extract('assumed-role/{role}/')"

# 4. Create a service account that LightPane will impersonate
gcloud iam service-accounts create lightpane-reader \
  --display-name="LightPane Reader"

# 5. Grant the SA read-only access on the project
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:lightpane-reader@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/viewer" \
  --condition=None

# 6. Allow ONLY the two LightPane discovery Lambda execution roles to
#    impersonate the SA. Tighter than the previous account-wide
#    binding — any other principal in the LightPane platform AWS
#    account is denied. These two role names are stable LightPane
#    infrastructure; if we ever rename them we'll publish a one-line
#    retrofit command (and the change will be backwards-compatible
#    for one release cycle).
for ROLE in lightpane-service-discovery-role lightpane-service-discovery-refresh-role; do
  gcloud iam service-accounts add-iam-policy-binding \
    lightpane-reader@$PROJECT_ID.iam.gserviceaccount.com \
    --role="roles/iam.workloadIdentityUser" \
    --member="principalSet://iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/lightpane-pool/attribute.aws_role/$ROLE"
done

# 7. Generate the credential config JSON to paste into LightPane
gcloud iam workload-identity-pools create-cred-config \
  projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/lightpane-pool/providers/lightpane-aws \
  --service-account=lightpane-reader@$PROJECT_ID.iam.gserviceaccount.com \
  --aws \
  --output-file=lightpane-config.json

cat lightpane-config.json

Screenshot placeholder — Cloud Shell session showing the script running, with the final cat lightpane-config.json output highlighted

When the script finishes you'll see a JSON block printed in the Cloud Shell window. That's the credential config — the next step is to copy it into LightPane.

First-time Cloud Shell prompts

The first time you run a gcloud command in a new Cloud Shell session you may be asked to confirm "Authorize Cloud Shell" — say Authorize. The script may also prompt to enable APIs ("API [X] not enabled on project. Would you like to enable and retry?") — answer y. After APIs are enabled the rest of the script runs without further prompts.

If you set this up before May 2026

Earlier versions of this script (a) didn't pass --attribute-mapping (so getAccessToken would silently 403), and (b) bound the service-account impersonation at the AWS account level rather than at the IAM role level (so any principal in the LightPane platform AWS account would be accepted). Both are now tightened. Fix in three commands:

export PROJECT_NUMBER=$(gcloud projects describe \
  $(gcloud config get-value project) --format='value(projectNumber)')

# (a) update the attribute mapping to also export aws_role
gcloud iam workload-identity-pools providers update-aws lightpane-aws \
  --location=global \
  --workload-identity-pool=lightpane-pool \
  --attribute-mapping="google.subject=assertion.arn,attribute.aws_account=assertion.account,attribute.aws_role=assertion.arn.extract('assumed-role/{role}/')"

# (b) add the two role-scoped bindings (idempotent — gcloud is
#     a no-op if the binding already exists)
for ROLE in lightpane-service-discovery-role lightpane-service-discovery-refresh-role; do
  gcloud iam service-accounts add-iam-policy-binding \
    lightpane-reader@$(gcloud config get-value project).iam.gserviceaccount.com \
    --role="roles/iam.workloadIdentityUser" \
    --member="principalSet://iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/lightpane-pool/attribute.aws_role/$ROLE"
done

# (c) OPTIONAL — once (b) is in place and you've confirmed
#     panes still work, remove the old account-wide binding:
gcloud iam service-accounts remove-iam-policy-binding \
  lightpane-reader@$(gcloud config get-value project).iam.gserviceaccount.com \
  --role="roles/iam.workloadIdentityUser" \
  --member="principalSet://iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/lightpane-pool/attribute.aws_account/236353235295"

The retrofit can be staged: (a) and (b) are additive and safe at any time, (c) is the cleanup that takes the binding from "either account or role works" to "only the named roles work".

Step 4: Paste the credential config into LightPane¶

In Cloud Shell, the final cat lightpane-config.json printed the credential config JSON. Select the entire JSON block (from the opening { to the closing }) and copy it.
Switch back to the LightPane tab from Step 1.
Paste the JSON into the WIF Credential Configuration field.
Enter your Project ID in the matching field. This is the PROJECT_ID you saw in Cloud Shell — it's also the value shown in the project selector at the top of the GCP console.
(Optional) Enter a Display name if you want to label this project differently from the project ID in the LightPane UI.
Pick a Default region (e.g. europe-west2, us-central1). LightPane will use this as the default for new GCP panes bound to this project.
Click Save.

Screenshot placeholder — LightPane dialogue with Project ID, pasted JSON config, and default region all filled in, Save button highlighted

LightPane performs a quick test call (exchanging the AWS identity for a GCP token and listing service accounts) to confirm the credentials work. If anything's off, you'll see a specific error pointing at which step to re-check.

The credential config file (what's in it)¶

The JSON output contains identifiers and endpoint URLs only — no private keys or secrets:

{
    "type": "external_account",
    "audience": "//iam.googleapis.com/projects/123456789/locations/global/workloadIdentityPools/lightpane-pool/providers/lightpane-aws",
    "subject_token_type": "urn:ietf:params:aws:token-type:aws4_request",
    "service_account_impersonation_url": "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/lightpane-reader@my-project.iam.gserviceaccount.com:generateAccessToken",
    "token_url": "https://sts.googleapis.com/v1/token",
    "credential_source": {
        "environment_id": "aws1",
        "region_url": "http://169.254.169.254/latest/meta-data/placement/availability-zone",
        "url": "http://169.254.169.254/latest/meta-data/iam/security-credentials",
        "regional_cred_verification_url": "https://sts.{region}.amazonaws.com?Action=GetCallerIdentity&Version=2011-06-15"
    }
}

This file is not sensitive

If the credential config is exposed, an attacker would also need valid AWS credentials for the LightPane platform account to use it. The file alone grants no access. The principalSet binding in Step 3 #6 restricts the federated identity to the LightPane AWS account only.

Setup checklist¶

Before you head to the dashboard, confirm:

[ ] You can sign in to the GCP console and see your project
[ ] You ran the setup script in Cloud Shell without errors
[ ] You copied the credential config JSON from the Cloud Shell output
[ ] You added the project to your LightPane profile via app.lightpane.io/accounts.html (Project ID + JSON pasted)
[ ] LightPane's save action returned a success message (not an authentication error)

If all of these are ticked, your GCP project is wired into LightPane and the GCP panes will start showing live data on your next dashboard or Cloud Desktop load.

Fallback: service account key¶

Workload Identity Federation (recommended)Service Account Key (fallback)

No secrets stored. Short-lived tokens. Google's recommended approach and the default in this guide.

If you cannot set up WIF (e.g. the iam.disableServiceAccountKeyCreation org policy blocks it and you can't get an exception), you can create a service account key instead:

In the GCP console, go to IAM & Admin > Service Accounts.
Create a new service account named lightpane-reader.
Grant it the roles/viewer role at the project level.
Open the new service account, go to the Keys tab, click Add Key > Create new key, select JSON, and save the downloaded file.
Paste the JSON content into LightPane's WIF Credential Configuration field (the form accepts either WIF configs or service-account-key JSONs and detects which is which by the type field).

{
    "type": "service_account",
    "project_id": "my-project-123",
    "private_key_id": "key123abc",
    "private_key": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----\n",
    "client_email": "lightpane-reader@my-project-123.iam.gserviceaccount.com",
    ...
}

Service account keys are long-lived secrets

The JSON key file contains a private key that never expires. LightPane stores it encrypted, but WIF avoids this entirely. Use WIF unless you have a specific reason not to.

Note: GCP organisations created after May 2024 block service account key creation by default. You may need an organisation policy administrator to grant an exception to the iam.disableServiceAccountKeyCreation constraint on your project before this fallback works.

Required GCP APIs¶

These APIs must be enabled in your project for WIF discovery to work:

IAM API (iam.googleapis.com)
IAM Credentials API (iamcredentials.googleapis.com)
Security Token Service API (sts.googleapis.com)
Cloud Resource Manager API (cloudresourcemanager.googleapis.com)

The setup script in Step 3 enables all four automatically. Individual panes may also depend on the API for the specific service they discover (e.g. Cloud Tasks needs cloudtasks.googleapis.com); if a required API isn't enabled, the pane renders a friendly empty state with the gcloud services enable … command to fix it, rather than a generic error.

Supported regions¶

LightPane discovers resources in any GCP region. Common regions:

Region	Location
`europe-west2`	London
`europe-west1`	Belgium
`europe-west3`	Frankfurt
`us-central1`	Iowa
`us-east1`	South Carolina
`us-west1`	Oregon
`asia-southeast1`	Singapore
`asia-northeast1`	Tokyo

Some services are global (Cloud DNS zones, IAM service accounts, Cloud Storage at the project level) and ignore the region selector. Others are per-region and respect it. The pane header shows which region the data came from.

Multiple projects¶

LightPane supports more than one GCP project per user account. Each project is registered as its own row in your profile — link each one separately by repeating Steps 1-4 (you can reuse the same setup script in each project's Cloud Shell, since the script uses gcloud config get-value project and runs against whichever project Cloud Shell is currently scoped to).

In the Cloud Desktop and dashboard, every GCP pane shows an account selector chip so you can retarget it at a different project on the fly. Different windows can be bound to different projects simultaneously — useful for side-by-side production vs staging comparison.

Revoking access¶

To remove LightPane's access:

Quickest: Delete the lightpane-reader service account in GCP (IAM & Admin → Service Accounts → lightpane-reader → Delete). LightPane loses access immediately.
Or: Delete the Workload Identity Pool (IAM & Admin → Workload Identity Federation → lightpane-pool → Delete). This revokes the federation in addition to the service account trust.

Or (gcloud):

gcloud iam service-accounts delete \
  lightpane-reader@$PROJECT_ID.iam.gserviceaccount.com

gcloud iam workload-identity-pools delete lightpane-pool \
  --location=global

And: In LightPane, go to Cloud accounts and click Remove on the GCP project row to delete the stored credential config.

Troubleshooting¶

Permission 'iam.serviceAccounts.getAccessToken' denied

Almost always caused by a missing --attribute-mapping on the AWS provider. Recent gcloud versions don't auto-populate a default mapping, so the principalSet binding silently resolves to nothing.

Fix:

gcloud iam workload-identity-pools providers update-aws lightpane-aws \
  --location=global \
  --workload-identity-pool=lightpane-pool \
  --attribute-mapping="google.subject=assertion.arn,attribute.aws_account=assertion.account"

Verify with:

gcloud iam workload-identity-pools providers describe lightpane-aws \
  --location=global \
  --workload-identity-pool=lightpane-pool \
  --format=json

The output should include an attributeMapping field with both keys above populated. If the field is missing or empty, the update command above hasn't taken effect yet.

A pane shows '… API has not been enabled'

Individual GCP services need their own API enabled even after the four WIF APIs are on. LightPane detects this and renders the gcloud services enable command for the specific API. For example, Cloud Tasks panes won't return data until you run:

gcloud services enable cloudtasks.googleapis.com \
  --project=$PROJECT_ID

You can enable several at once if you know which panes you'll use. The full set covering all 29 GCP panes is:

gcloud services enable \
  compute.googleapis.com \
  container.googleapis.com \
  run.googleapis.com \
  cloudfunctions.googleapis.com \
  cloudscheduler.googleapis.com \
  cloudtasks.googleapis.com \
  pubsub.googleapis.com \
  storage.googleapis.com \
  file.googleapis.com \
  artifactregistry.googleapis.com \
  bigquery.googleapis.com \
  bigtableadmin.googleapis.com \
  firestore.googleapis.com \
  sqladmin.googleapis.com \
  redis.googleapis.com \
  dns.googleapis.com \
  cloudkms.googleapis.com \
  secretmanager.googleapis.com \
  --project=$PROJECT_ID

You don't need to enable everything up-front — LightPane will tell you which API is missing the first time you load each pane.

The setup script asks me to authorise Cloud Shell

Normal. Cloud Shell needs explicit consent the first time you use it in a project — accept the prompt and the script continues.

Cannot create a Workload Identity Pool

You need the Workload Identity Pool Admin (roles/iam.workloadIdentityPoolAdmin) or Owner role on the project. Ask whoever administers the project to either run the script themselves or grant you the role.

If you see "Identity Pool Federation API has not been used in project …", run the enable step (1 in the script) first and re-run the create step.

Setup ran but LightPane still shows 'no GCP projects configured'

Check that:

You saved the credential config JSON in the LightPane dialogue (Step 4) — without that, the project record was never created.
The Project ID in LightPane matches the PROJECT_ID the script ran against. They have to be identical strings — the project number (e.g. 472877595413) is not the same as the project ID (e.g. my-project-123).
LightPane returned a success message when you clicked Save (no red error banner). If it errored, the credentials weren't stored.

Service account key creation blocked by org policy

If you're trying the service-account-key fallback and see "Service account key creation is disabled", your org policy blocks it (default for GCP orgs created after May 2024). Options:

Ask an org policy administrator to exclude this project from the iam.disableServiceAccountKeyCreation constraint.
Or — much better — use the WIF path (Steps 1-4 above), which doesn't need keys at all.

Getting help¶

If you hit anything not covered here, email support@lightpane.io — we'll either talk you through it or fix the doc. Open-tickets are easier to chase than email; we'll be opening a support portal shortly.