Customer setup guide

Connect one Google Cloud root.

Create a dedicated customer-owned service account, grant two predefined roles, and let the Sythe Labs platform read one complete Cloud Asset Inventory boundary without changing Google Cloud.

Overview

Two bounded reads through the Google SDK.

The connector authenticates the uploaded service-account JSON in memory, then uses the Google APIs Node.js Client to call Cloud Asset Inventory v1 assets.list. It requests only RESOURCE and IAM_POLICY content and follows pagination until Google returns an empty next-page token.

Google SDK authentication

Client library
googleapis
Token operation
service-account-token-exchange
Authorization scope
https://www.googleapis.com/auth/cloud-platform
CAI read pathRead only
01
RESOURCE snapshot

Cloud Asset Inventory v1 assets.list for the fixed supported asset types.

cloudasset.googleapis.comcloudasset.assets.listResource
02
IAM_POLICY snapshot

Cloud Asset Inventory v1 assets.list for the fixed supported asset types.

cloudasset.googleapis.comcloudasset.assets.listIamPolicy
Before you start

Keep the account, key, and console under customer control.

The customer creates and controls the service account. Do not send its JSON key to Sythe Labs staff, paste it into a support request, or ask staff to enter the Google Cloud console.

  • 01

    One authoritative organization, folder, or project root for the inventory boundary.

  • 02

    A customer-owned project where the dedicated service account and Cloud Asset Inventory API will live.

  • 03

    Permission to create a service account, grant two predefined roles, and create a JSON key when organization policy permits it.

  • 04

    Organization administrator access to the signed-in Sythe Labs platform Integrations page.

Create the connection

Grant two predefined roles, then upload one JSON key.

Steps 3 to 7 are ordinary gcloud commands. Copy the prompt below into a CLI coding agent and it asks you for the two choices in steps 1 and 2, then runs those commands against your own already-authenticated gcloud session. Steps 8 to 10 stay manual: only you upload the JSON key, from the signed-in Integrations page.

Set up a read-only Google Cloud service account so the Sythe Labs platform can read Cloud Asset Inventory for exactly one resource root.

Context:
- I am already signed in to the gcloud CLI with an account that can administer IAM at the root below.
- Use the gcloud CLI only. Do not open the Google Cloud console and do not install anything.

Ask me for these three values first, then echo them back before running anything. The $NAME placeholders below are not set in my shell, so substitute my answers into the commands:
1. ROOT_KIND - organization, folder, or project. This is the highest resource whose descendants Sythe Labs should read.
2. ROOT_ID - the numeric id for an organization or folder, or the project id for a project.
3. SA_PROJECT - the project id that will own the service account and the enabled API. It may be the same project as ROOT_ID.

Run these steps in order. Stop at the first failure and show me the exact gcloud error.

Step 1 - enable Cloud Asset Inventory in the service-account project:
gcloud services enable cloudasset.googleapis.com --project="$SA_PROJECT"

Step 2 - create one dedicated service account. Reuse it if it already exists; never create a second one:
gcloud iam service-accounts create sythe-labs-asset-reader \
  --project="$SA_PROJECT" \
  --display-name="Sythe Labs Cloud Asset Inventory reader"

Its email is sythe-labs-asset-reader@$SA_PROJECT.iam.gserviceaccount.com

Step 3 - grant roles/serviceusage.serviceUsageConsumer on the service-account project:
gcloud projects add-iam-policy-binding "$SA_PROJECT" \
  --member="serviceAccount:sythe-labs-asset-reader@$SA_PROJECT.iam.gserviceaccount.com" \
  --role="roles/serviceusage.serviceUsageConsumer" \
  --condition=None

Step 4 - grant roles/cloudasset.viewer at the root so it inherits to every child resource. Run only the one command that matches ROOT_KIND.

organization:
gcloud organizations add-iam-policy-binding "$ROOT_ID" \
  --member="serviceAccount:sythe-labs-asset-reader@$SA_PROJECT.iam.gserviceaccount.com" \
  --role="roles/cloudasset.viewer" \
  --condition=None

folder:
gcloud resource-manager folders add-iam-policy-binding "$ROOT_ID" \
  --member="serviceAccount:sythe-labs-asset-reader@$SA_PROJECT.iam.gserviceaccount.com" \
  --role="roles/cloudasset.viewer" \
  --condition=None

project:
gcloud projects add-iam-policy-binding "$ROOT_ID" \
  --member="serviceAccount:sythe-labs-asset-reader@$SA_PROJECT.iam.gserviceaccount.com" \
  --role="roles/cloudasset.viewer" \
  --condition=None

Step 5 - create one JSON key:
gcloud iam service-accounts keys create ./sythe-labs-google-cloud.json \
  --iam-account="sythe-labs-asset-reader@$SA_PROJECT.iam.gserviceaccount.com" \
  --project="$SA_PROJECT"

If Step 5 fails because of the constraints/iam.disableServiceAccountKeyCreation organization policy, stop and tell me. This connector requires a user-managed JSON key and has no OAuth or Workload Identity Federation fallback, so the connection cannot proceed until that policy permits a key.

Rules:
- Grant exactly the two roles above. Do not grant Owner, Editor, Viewer, or any other role, do not enable another API, and do not create or change any other resource.
- Never print the contents of the key file and never send it anywhere. Leave it on my machine.

When every step succeeds, print exactly these three lines:
ROOT_TYPE=<organization, folder, or project>
CANONICAL_ROOT=<organizations/ID, folders/ID, or projects/PROJECT_ID>
KEY_FILE=<absolute path to the JSON key file>

I select ROOT_TYPE as the root type, paste CANONICAL_ROOT into the canonical resource name field, and upload KEY_FILE on the Sythe Labs Google Cloud integration page.
  1. 01

    Choose the authoritative organization, folder, or project root and copy its canonical resource name.

  2. 02

    Choose or create the customer-owned project that will own the dedicated service account.

  3. 03

    Enable the Cloud Asset Inventory API in the service-account project.

  4. 04

    Create a dedicated service account for the Sythe Labs platform connection.

  5. 05

    Grant Service Usage Consumer to that service account in the project that owns it.

  6. 06

    Grant Cloud Asset Viewer to that service account at the selected organization, folder, or project root with inherited coverage for every intended child resource.

  7. 07

    Create and download one JSON key for the service account if organization policy permits user-managed keys.

  8. 08

    Open the signed-in Integrations page, choose Google Cloud, enter the canonical root, and select the JSON key file.

  9. 09

    Confirm that the Cloud Asset Viewer assignment covers the selected root and every child resource intended for inventory.

  10. 10

    Connect, then use the status page to confirm the initial complete sync.

Service Usage Consumer

roles/serviceusage.serviceUsageConsumer

Permit the service account to consume the enabled Cloud Asset Inventory API.

Binding location: Service-account project

Permissions
  • serviceusage.services.use

Cloud Asset Viewer

roles/cloudasset.viewer

List RESOURCE and IAM_POLICY assets throughout the confirmed root boundary.

Binding location: Selected organization, folder, or project root

Permissions
  • cloudasset.assets.listResource
  • cloudasset.assets.listIamPolicy
Access and data

Nine RESOURCE types, one IAM_POLICY type, and four checks.

The connector supplies these exact asset-type filters to the two Cloud Asset Inventory reads. It does not request an unbounded asset catalog.

RESOURCE - 9 asset types

  • cloudresourcemanager.googleapis.com/Project
  • compute.googleapis.com/Instance
  • compute.googleapis.com/Disk
  • compute.googleapis.com/Firewall
  • run.googleapis.com/Service
  • container.googleapis.com/Cluster
  • storage.googleapis.com/Bucket
  • sqladmin.googleapis.com/Instance
  • artifactregistry.googleapis.com/Repository

IAM_POLICY - 1 asset type

  • storage.googleapis.com/Bucket

Seven types become inventory

Compute Engine virtual machine

compute.googleapis.com/Instance

compute-instance / iaas

Compute Engine persistent block storage

compute.googleapis.com/Disk

block-storage / iaas

Cloud Run managed application service

run.googleapis.com/Service

serverless-service / paas

Google Kubernetes Engine managed cluster

container.googleapis.com/Cluster

container-orchestration / paas

Cloud Storage object bucket

storage.googleapis.com/Bucket

object-storage / iaas

Cloud SQL managed database instance

sqladmin.googleapis.com/Instance

managed-database / paas

Artifact Registry managed repository

artifactregistry.googleapis.com/Repository

artifact-registry / paas

Supporting configuration checks

  • Public SSH ingress on Compute Engine firewall rules

  • Public Cloud Storage bucket IAM

  • Cloud Storage bucket versioning or retention protection

  • Automated Cloud SQL backups

Project and firewall assets support lookup and checks but do not become inventory rows. The connector does not call Compute Engine, Cloud Storage, Cloud SQL, Resource Manager, export, feed, or search APIs. A failed or incomplete CAI family preserves the prior complete inventory and never produces a false pass.

Key lifecycle

The customer controls replacement and revocation.

The Sythe Labs platform stores the uploaded JSON as an encrypted opaque secret and uses it only for the bounded SDK operations in this guide. Google Cloud remains the source of truth for key status and revocation.

Replace

Create a new JSON key for the same dedicated service account and replace it from the signed-in status page. The Sythe Labs platform validates both CAI reads before switching keys.

Revoke

After replacement succeeds, delete the old key in Google Cloud. To stop access immediately, delete the current key in Google Cloud and then disconnect the integration.

Disconnect

Disconnect from the signed-in status page to delete the encrypted key, stop scheduled synchronization, and remove Google Cloud connector inventory from active inventory.

Clean up

After disconnecting, delete the dedicated service account or remove both role assignments when it is no longer needed. Remove customer-held key copies under your credential-retention process.

Troubleshooting

Resolve the stable reason shown in the signed-in status page.

Match the reason code to the customer-owned action below. Keep a safe request identifier for support, but never copy a service-account key or raw provider response into a message.

The service-account key is invalid

invalid_credential

Create a new JSON key for the dedicated customer-owned service account, then replace the key from the signed-in Integrations page. Do not send the key to Sythe Labs staff or include it in a support request.

The selected root cannot be read

inaccessible_scope

Confirm the canonical organization, folder, or project resource name and grant Cloud Asset Viewer to the dedicated service account at that exact root.

Cloud Asset Inventory is disabled

api_disabled

Enable the Cloud Asset Inventory API in the project that owns the service account, then retry the connection.

Service Usage Consumer is missing

missing_service_usage_consumer

Grant Service Usage Consumer to the dedicated service account in the project that owns it, then retry the connection.

Resource inventory permission is missing

missing_resource_permission

Grant Cloud Asset Viewer to the dedicated service account at the selected root so RESOURCE assets can be listed throughout that boundary.

IAM policy inventory permission is missing

missing_iam_policy_permission

Grant Cloud Asset Viewer to the dedicated service account at the selected root so bucket IAM policies can be listed throughout that boundary.

Google Cloud could not complete the request

transient_failure

Wait for the retry window shown in the signed-in status page, then run the sync again. The prior complete inventory remains unchanged.

The connection configuration is invalid

configuration_error

Review the selected root, service-account project, and both predefined role assignments, then submit the connection again.

Google Cloud returned an unsupported result

provider_schema_drift

Use Sythe Labs support and include only the stable reason code and safe request identifier shown in the signed-in status page. Do not include the key or a raw provider response.

Need platform help?

Use the Sythe Labs support page and include only the stable reason code and safe request identifier shown in the signed-in status page.