Organization Setup

Before you start

Complete the collection setup first. The Organization path needs all four roles bound at the organization or folder — roles/viewer, roles/monitoring.viewer, roles/browser and roles/serviceusage.serviceUsageConsumer — because GCP IAM inherits down the hierarchy and that binding is what covers every project beneath it, including projects created later.

For one project added by hand, use Single Project Setup instead.

The wizard

Settings → Integrations → GCP → Add New GCP Account → Organization. Four screens — Service Account → Discovery → Review → Enrolled — and nothing is created until you approve the plan on the third.

Screen 1 — Service Account

Four numbered sections, in the order the work happens. They form a chain: the folder list in section 2 only loads once the credentials in section 1 are verified.

1. How KubeSense authenticates. Use workload identity is a switch. Switch it on if you completed the binding in the collection setup — no credential is stored, and there is nothing to verify from here, since the controller holds that identity rather than the dashboard. Leave it off to use a service account key: paste the JSON, then select Verify credentials, which reports which account you signed in as.

2. Scope. Enter your Organization ID, bare (123456789012) or qualified (organizations/123456789012) — both are accepted. Folders is optional and narrows discovery to those folders and everything nested beneath them; leave it empty for the whole organization. Once credentials are verified this becomes a picker listing your real folders by name and ID — use it, because retyping a folder ID is where scope mistakes come from and a wrong ID enrols the wrong tree silently. Under workload identity the picker cannot list, so folder IDs are typed.

3. Project filters. Applied to the discovered projects before anything is enrolled.

sys- projects are created and managed by Google for App Engine, Firebase and Apigee. A large organization can hold hundreds, and each would become an integration that collects nothing. Clear the field to enrol them anyway.

4. What each project collects. A default region for each newly enrolled project — the Cloud Run and Dataproc caveat from the single-project path applies to each — and the resource types to enable. These are applied when a project is first enrolled; changing an individual project's settings afterwards is safe, since enrollment never overwrites per-project choices on a later cycle.

Select Next. That one button saves the configuration and moves on — discovery runs server-side against the saved enrollment, so saving is what unlocks it, and the plan you approve is guaranteed to be the plan you configured. The enrollment is created in preview: nothing is enrolled yet.

Screen 2 — Discovery

Lists every project the service account can see, after your scope filters, and what KubeSense would do with each. Three counters summarise it — Total listed, Would enroll, Skipped — and the table has five columns: Project ID, Name, State, Action and APIs.

APIs is the column that catches people out — it reports the API-enablement problem per project, and this is the only screen where it is visible before committing:

• Ready — every API the selected resource types need is enabled.
• N disabled — hover to see which. That project will enrol and stay empty for the affected types until you enable them.
• Not checked — the check did not run. That is not the same as "fine": it happens under workload identity, where the dashboard cannot use the controller's credential, and on very large organizations where the check is bounded to keep the screen responsive.

Two banners here are worth acting on rather than dismissing. "N projects visible but outside your scope" means the service account holds a binding somewhere broader than you intended. "Only the first N projects were checked for enabled APIs" means the rest show Not checked and can still be enrolled — the check is advisory.

Screen 3 — Review, and enable

The Review screen restates what you configured — authentication mode, service account, organization, scope, include/exclude lists and status — so you approve a plan you can see rather than one you have to remember.

Two choices, and they are two different outcomes rather than one Next: Finish without enrolling keeps it in preview, with nothing created and the plan available for when you come back; Enable Enrollment starts collection.

On enable, KubeSense runs a pass immediately rather than waiting for its 15-minute cycle, and reports how many projects it enrolled. After that the reconcile loop keeps the set current:

Screen 4 — Enrolled

Lists the projects this enrollment created integrations for, each Collecting or Paused — paused meaning it left the configured scope, became inactive, or was excluded, with everything already collected retained and automatic resumption if it returns. Only projects this enrollment created are listed.

An empty list right after enabling is normal if the reconcile cycle has not run yet; projects appear within about 15 minutes. You can return to this view at any time from Settings → Integrations → GCP → Organization.

Operating it

Verify. Verify credentials and then discovery prove the credential. Resources appear within a minute or two as a count per resource type on each integration, and metrics take up to 10 minutes for the first cycle. Under Workload Identity, confirm the pod's identity directly:

kubectl get serviceaccount kubesense-controller -n kubesense \
  -o jsonpath='{.metadata.annotations.iam\.gke\.io/gcp-service-account}'

Adding or removing scope. Edit the enrollment and save; the next cycle reconciles. A new project inside a scope you already cover needs none of this — the binding already reaches it.

Turning it off. Disabling the enrollment stops discovery. Integrations it already created keep collecting, so switching off can never silently stop collection.

Rotating credentials. Nothing to rotate under workload identity. With a key, create a new one, edit the enrollment, paste it, then delete the old key in Google Cloud. The key field is blank when you re-open the enrollment — that is deliberate, and leaving it blank keeps the stored key.

Troubleshooting