What you need

Kumo.io signs in to Google Cloud with a service-account key: the JSON key file you download for a service account. You need:

• a service account with read access to the project, such as the Viewer role (roles/viewer),
• the Cloud Asset API (cloudasset.googleapis.com) enabled on the service account's own project,
• a JSON key for the service account.

Viewer already includes the Cloud Asset read permission Kumo.io uses. If you give the service account a custom role instead, also grant it Cloud Asset Viewer (roles/cloudasset.viewer).

A service-account key is the only way to connect Google Cloud today. Workload identity federation and Application Default Credentials aren't supported yet, on kumo.io or on self-hosted Kumo.io.

Some organizations block service-account key creation with the iam.disableServiceAccountKeyCreation organization policy. If yours does, you can't create a key for Kumo.io until an administrator makes an exception for the project.

Create the service account and key

With the Google Cloud CLI (replace <project> with your project ID):

gcloud services enable cloudasset.googleapis.com --project <project>
gcloud iam service-accounts create kumo-reader --project <project>
gcloud projects add-iam-policy-binding <project> \
  --member serviceAccount:kumo-reader@<project>.iam.gserviceaccount.com \
  --role roles/viewer
gcloud iam service-accounts keys create kumo-key.json \
  --iam-account kumo-reader@<project>.iam.gserviceaccount.com

Keep kumo-key.json safe. Once Kumo.io has it, delete your local copy.

Connect it to Kumo.io

1. Open Cloud Connections and select Add a Source, or select Add Source on a workspace's Connections tab.
2. Under 1 · Choose a Provider, pick Google Cloud.
3. Under 2 · Enter the Credential, paste the whole key file into Service-account key JSON, or select Upload Key File and choose kumo-key.json. The file is read in your browser and sent only with the connect request. Kumo.io checks it is a service-account key (valid JSON with type, project_id, client_email and private_key) before sending it; a gcloud auth user credential is flagged on the field.
4. Pick the Workspace it syncs into.
5. If the service account can see more than one project, open Advanced Options and enter the one to read in Project ID. Otherwise Kumo.io uses the first project it finds. A Name for the source is there too.
6. Select Test Connection to check the key, then Connect Source.

Kumo.io stores the credential, finds the project, creates the source and starts the first sync.

To connect more projects, add a source for each one. They can share a service account: grant it Viewer on each project, then either paste the same key with a different Project ID each time, or pick Use an Existing Credential and enter the project (see Reuse a credential).

How Kumo.io reads your project

Kumo.io normally reads the whole project through Cloud Asset Inventory, which covers every resource type Kumo.io recognises: currently 91 types across 29 services. See GCP coverage for the full list.

At the start of every sync, Kumo.io checks whether Cloud Asset Inventory is available to the key. If the API is disabled, the permission is missing, or an organization policy forbids it, Kumo.io reads through the individual service APIs instead. That path covers Compute Engine, Google Kubernetes Engine, Cloud SQL, Cloud Storage, Cloud DNS, Pub/Sub, Cloud Run, Memorystore for Redis and IAM. Other resource types show as unknown until Cloud Asset is available.

When this happens, the source page shows a notice explaining why and what to do. It goes away by itself after a later check finds Cloud Asset available, and the next sync reads through Cloud Asset again. You don't need to reconnect.

Kumo.io reads one project per source. It doesn't yet sweep whole folders or organizations, so connect each project separately.

Connect from the CLI

kumo source connect runs the same flow as Add a Source. The key file is the credential. Because the CLI reads one line from standard input, compact the key to a single line first:

jq -c . kumo-key.json | \
  kumo source connect --provider gcp --credential-kind gcp.service_account \
    --display-name "prod project" --secret-material-stdin --scope <project>

Add --no-sync to skip the first sync. See the CLI reference.

If the connection fails

Test Connection, the source's credential health panel and the sync's diagnostics report what went wrong. Common Google Cloud problems and their fixes: