Connect Google Cloud

Zaysa connects to a Google Cloud project, folder or organization without a service account or key. You run one Cloud Shell script to set up Workload Identity Federation. For each scan, Google issues a token that lasts about one hour. Zaysa stores no long-lived cloud credential for this connection.

Choose how to connect

For keyless access, choose One project, A folder, or Whole organization. Enter a project ID, folders/123, or organizations/456. The Workload Identity pool can live in a different project. Zaysa reads only the scope you select.

Before you start

• A Zaysa account. New here? Start with Getting started.
• Enough IAM rights to enable APIs, create a Workload Identity pool, and grant read roles at the scope you choose.
• Google Cloud Shell, opened from the Google Cloud console. Select the project that holds the identity pool. If needed, run gcloud config set project YOUR_POOL_PROJECT_ID.

What Zaysa gets

See the Permissions reference for each feature's exact grants and what happens without them.

Read roles by scope

Cloud Map reads all projects in the selected folder or organization. Costs, scans, billing and Cloud History keep reading the single Cloud Shell project. The setup script grants only Cloud Map roles at folder or organization level and grants the other read roles on that project. Cloud Map needs these roles:

For an organization, the setup script grants these Cloud Map roles: Cloud Asset Viewer, Compute Viewer, Browser.

Connect with keyless access

Option A: Cloud Shell script

1. Open the connection window

   In Zaysa, open Resources → Cloud Accounts and click Connect account (1).

   

2. Choose Google Cloud and name the connection

   (1) Choose Google Cloud Platform as the Cloud Provider. (2) Name the connection, for example Production GCP. (3) Leave Keyless selected. Choose the project, folder or organization Zaysa should read. All Regions (Recommended) is right for most connections.

   

3. Run the script in Google Cloud Shell

   Scroll to Run this once in Google Cloud Shell. Click Open Cloud Shell (1). Check that the project shown at the top of the shell is the one that holds the identity pool. Click Copy (2), paste the whole block into Cloud Shell and press Enter.

   

   The script reads the selected project and its number, enables the APIs, sets up the pool and provider, grants the roles and prints the project number. It takes about 30 seconds and ends like this:

   Google Cloud Shell

   → Setting up keyless access for project my-project (123456789012)…
   Operation "operations/acat.p2-123456789012-a43e04eb-…" finished successfully.
   Updated IAM policy for project [my-project].
   Updated IAM policy for project [my-project].
   Updated IAM policy for project [my-project].
   Updated IAM policy for project [my-project].
   Updated IAM policy for project [my-project].
   Updated IAM policy for project [my-project].
   Updated IAM policy for project [my-project].
   Updated IAM policy for project [my-project].
   
   ✅ Done! Type this PROJECT NUMBER into Zaysa:
      123456789012

   Prefer the console?

   Choose Console, click by click next to Cloud Shell script. It lists the console screens and values to copy.

4. Enter the project number

   Type the number the script printed into GCP project number (1). Zaysa shows the full provider path under Zaysa will connect to:. If you used custom pool or provider names, choose Used custom pool / provider names? Paste the full path instead.

   

5. Click Connect Account

   Scroll to the bottom and click Connect Account (1). The optional BigQuery billing export section above the button can be set up later.

   

   Asked to sign in again?

   Connecting a cloud account is a sensitive action. If you signed in more than 30 minutes ago, Zaysa asks you to sign in again with your email and password (and your authenticator code, if you use one), then brings you back to Cloud accounts. Open Connect account again and repeat the last two steps: the pool and provider in Google Cloud are already there.

6. Wait for trust verification

   Zaysa first says Cloud account connected — verifying the cloud trust…. It then says Cloud trust verified — scans & deploys will authenticate and shows Verify again.

   

Option B: Console, click by click

Choose Console, click by click (1) in Zaysa. Its New principals value is personalised for your Zaysa user and project number. Copy it from the guide.

1. Create the identity pool and OIDC provider

   Open IAM & Admin → Workload Identity Federation → Create pool. Under Create an identity pool, set Name to zaysa-pool and click Continue. Under Add a provider to pool, choose Select a provider → OpenID Connect (OIDC). Set Provider name to zaysa-oidc, Issuer (URL) to https://zaysa.io, and Audiences to Default audience. Do not add an allowed audience. Click Continue.

2. Configure provider attributes

   Under Configure provider attributes, set Google 1 (google.subject) to assertion.sub, and Attribute Conditions to assertion.sub.startsWith('zaysa:deploy:'). Click Save.

3. Grant read-only access

   Open IAM & Admin → IAM and click Grant access. Copy the generated New principals value from Zaysa. Your project number is the digits on the console home Project info card. Add these Role values, using + Add another role between them: Cloud Asset Viewer, Compute Viewer, Monitoring Viewer, Recommender Viewer, Logs Viewer, Browser, BigQuery Job User, BigQuery Data Viewer, Kubernetes Engine Viewer, Cloud SQL Viewer, Storage Bucket Viewer, Cloud Run Viewer, Cloud Functions Viewer, Pub/Sub Viewer, Artifact Registry Reader, Redis Viewer, Filestore Viewer. Click Save.

4. Enable the APIs

   Open APIs & Services → Library. Enable Cloud Asset API, Compute Engine API, Cloud Monitoring API, Recommender API, Cloud Logging API, Cloud Resource Manager API, Identity and Access Management (IAM) API, and Security Token Service API. Enter your project number in GCP project number in Zaysa and click Connect Account.

Beam also needs

For just-in-time human access, Beam must act as the connected deploy service account. That account needs roles/iam.serviceAccountAdmin to create and disable each grant's service account and roles/resourcemanager.projectIamAdmin to bind and remove its roles. Beam › Connections › Check readiness checks these permissions and gives the exact fix.

Connect with a service-account key

Choose Access Keys / Secret (1) when keyless is unavailable. Zaysa stores the JSON key encrypted, but the long-lived key never expires on its own. Some organizations block key creation.

Option A: Cloud Shell script

1. Create the service account and JSON key

   In Zaysa, click Copy on the service-account key guide. Open Google Cloud Shell, select your project, paste the block, and press Enter. The script enables the scan APIs, creates or reuses zaysa-reader, grants the eight read-only roles listed above, and creates one JSON key. Copy everything between the lines it prints into Service Account JSON. The guide's Expected identity is zaysa-reader@<your project id>.iam.gserviceaccount.com.

Option B: Google Cloud console

1. Create the service account and roles

   Open IAM & Admin → Service Accounts → + Create service account. Set Service account name to zaysa-reader, then click Create and continue. Under Select a role, add Cloud Asset Viewer, Compute Viewer, Monitoring Viewer, Recommender Viewer, Logs Viewer, Browser, BigQuery Job User, BigQuery Data Viewer, Kubernetes Engine Viewer, Cloud SQL Viewer, Storage Bucket Viewer, Cloud Run Viewer, Cloud Functions Viewer, Pub/Sub Viewer, Artifact Registry Reader, Redis Viewer, Filestore Viewer, using + Add another role. Click Continue → Done.

2. Download the JSON key and enable APIs

   Open the account's Keys tab → Add key → Create new key. Set Key type to JSON, click Create, then open the downloaded file and paste its whole contents into Service Account JSON. In APIs & Services → Library, enable Cloud Asset API, Compute Engine API, Cloud Monitoring API, Recommender API, Cloud Logging API, Cloud Resource Manager API, and Identity and Access Management (IAM) API. Click Test Connection, then Connect Account.

Rotate a key

Go to FinOps → Optimization. Under Connected cloud accounts, open the account's ⋮ menu, click Edit account & billing, paste the new JSON key, and click Save Credentials. Remove the old key in Google Cloud.

Add the billing export (optional)

A BigQuery billing export gives Zaysa real invoiced cost. Set it up while connecting or through Edit account & billing.

1. Create the dataset and find your billing account ID

   Enter the export project in BigQuery Project ID and dataset in BigQuery Dataset, normally billing_export. Click Open Cloud Shell (1) and Copy in the billing guide. Paste the personalised block into Cloud Shell and press Enter. It creates the dataset and prints the billing account ID. The verified run printed:

   Google Cloud Shell

   Dataset 'my-project:billing_export' successfully created.
   
   ✅ Billing account id (type it into Zaysa):  XXXXXX-XXXXXX-XXXXXX
      Dataset created: billing_export
      Now enable the export in the console (step 2) — Google has no command for that step.

   For the console path, open BigQuery Studio. In Explorer, click ⋮ next to your project → Create dataset. Set Dataset ID to billing_export, Location type to Multi-region → US, then click Create dataset. Find the billing account ID on Cloud Billing.

2. Enable the export in Cloud Billing

   Click Open Cloud Billing (2), or open Cloud Billing. Select the billing account → Billing export → BigQuery export tab. Under Detailed usage cost, click Edit settings. Set Project to your export project and Dataset to billing_export, then click Save. Google starts sending data within 24 hours, with no backfill of earlier months.

3. Enter the billing account ID

   Type the billing account ID into the billing guide. Zaysa fills BigQuery Table with gcp_billing_export_resource_v1_<billing account id with underscores>. You can also copy the exact table name from BigQuery after the first export arrives.

4. Check permissions and save

   If the export is in the connected project and you used the setup script, the BigQuery roles are already granted. Click Save & Continue, or Skip for now. For an existing account, click Save Billing Config. If the export is in another project, grant the connected identity roles/bigquery.dataViewer and roles/bigquery.jobUser there. Use the personalised grant script in Zaysa with Cloud Shell, or open IAM & Admin → IAM → Grant access. Paste the generated New principals value, add BigQuery Data Viewer and BigQuery Job User, and click Save.

Check it worked

Click Check permissions on the card to see which features are ready in this connection; the Check permissions guide explains the results.

The account card shows Keyless, Connected (1), the region and the project number.

Run scan on the card takes you to the Cost Optimizer, where you scan the project to see what it costs and where the waste is. The first scan guide walks through it.

If something goes wrong

“No GCP project is selected in this Cloud Shell”

Run gcloud projects list, then gcloud config set project YOUR_PROJECT_ID. Paste the whole script again.

“Cannot read project”

Either the wrong project is selected or your Google account is not an Owner of it. Switch to a project you own with gcloud config set project YOUR_PROJECT_ID, then paste the script again.

“Trust not confirmed yet”

A new trust can take a minute to propagate. Wait and click Verify again. Check that you typed the project number, which contains only digits, rather than the project ID.

“Cloud Logging access denied — grant roles/logging.viewer”

Existing keyless connections need this read-only role once. Replace PROJECT_ID, PROJECT_NUMBER, and YOUR_USER_ID with the values for your connection; the subject has the same form as the setup script. Then run:

gcloud projects add-iam-policy-binding PROJECT_ID --member="principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/zaysa-pool/subject/zaysa:deploy:YOUR_USER_ID:gcp:PROJECT_NUMBER" --role="roles/logging.viewer" --condition=None

The new role can take about a minute to apply. Then reload Cloud History.

“organization policy blocks service-account keys”

Use Keyless if your organization enforces iam.disableServiceAccountKeyCreation.

“has no billing account linked”

Check that the selected project has a billing account and that you have billing.resourceAssociations.list.

Remove access

• In Google Cloud, open IAM & Admin → IAM. Remove the principal whose name contains zaysa-pool/subject/zaysa:deploy: from the eight roles listed above.
• If nothing else uses the provider and pool, delete them in the Google Cloud console or run these commands in Cloud Shell with the project selected:

gcloud iam workload-identity-pools providers delete zaysa-oidc --workload-identity-pool=zaysa-pool --location=global
gcloud iam workload-identity-pools delete zaysa-pool --location=global

For a service-account key connection, delete its key or the zaysa-reader service account. To remove the account from Zaysa, click the bin icon on its card.

Next steps