Single Project Setup
Connect one Google Cloud project to KubeSense for read-only inventory and Cloud Monitoring metrics.
Before you start
Complete the collection setup first: a read-only
service account with roles/viewer and roles/monitoring.viewer on the project, the APIs
enabled for the services you want observed, and the credential available to the controller
— either Workload Identity or a service account key.
Use this path for one project, or a few you would rather add by hand. If your estate spans many projects, Organization Setup enrols them automatically instead.
Connect the project
Settings → Integrations → GCP → Add New GCP Account → Single Project:
| Field | What to enter |
|---|---|
| Name | A friendly label for this project in KubeSense, e.g. gcp-prod. |
| GCP Project ID | The project ID — the alphanumeric ID, not the display name. |
| Default Region | A region slug such as us-central1. See the note below — this is not only a label. |
| Service Account Key (JSON) | The entire contents of the key file from the collection setup, Step 3 Option B. Leave empty for Workload Identity. |
| Collection Settings | Which services to collect, and how deep. |
Select Connect. KubeSense verifies the credential immediately — it calls Compute
Engine's regions.list — and the next screen reports success or the exact error Google
returned.
About Default Region: For most services KubeSense discovers resources across the whole project regardless of this value and uses it only as a label. Two are the exception: Cloud Run and Dataproc are queried in this region only. If your Cloud Run services live in several regions, set this to the one that matters most and connect the project a second time under a different name to cover another.
Every resource type starts disabled: A project connected with nothing selected authenticates correctly and then collects nothing — which reads as broken rather than unconfigured. Choose your resource types on this screen; you can change them at any time from the integration's settings, and a change takes effect on the next collection cycle.
Verify
- The credential resolves. The screen after Connect reports this, and the message on failure is Google's own — it names the missing role or the disabled API.
- Resources appear. Open the integration from Settings → Integrations → GCP. Within a minute or two it shows a count per resource type. A type showing zero either has no resources, or has its API disabled.
- Metrics arrive. Allow up to 10 minutes for the first metric cycle, then open any discovered resource and confirm its charts are populated.
Under Workload Identity you can confirm the pod's identity directly:
kubectl get serviceaccount kubesense-controller -n kubesense \
-o jsonpath='{.metadata.annotations.iam\.gke\.io/gcp-service-account}'This must print the service account email from the collection setup. If it prints nothing, the annotation did not apply.
Troubleshooting
| Symptom | Likely cause | Action |
|---|---|---|
| "Google rejected these credentials" | A missing role binding, a disabled Resource Manager API, or a deleted key | The message shown is Google's own and names the cause. Under Workload Identity the usual cause is that the controller was not restarted after the annotation — re-run the rollout restart |
| A resource type shows nothing at all | Its API is not enabled in the project | gcloud services list --enabled --project=<PROJECT>, then enable it. If you used per-service roles instead of roles/viewer, the missing viewer role produces the same silent empty result |
| Resources appear but their charts are empty | roles/monitoring.viewer missing, or monitoring.googleapis.com not enabled | Both are required for every metric |
| Cloud Run or Dataproc resources are missing | These two are discovered only in the project's Default Region | Set it to where those resources actually run, or connect the project again for another region |
| A GKE cluster appears but has almost no metrics | Expected — cluster-level metrics from Cloud Monitoring are deliberately few | Deploy the KubeSense sensor to that cluster for in-cluster depth |
| The project connects but collects nothing | No resource types selected | Open the integration's settings and enable the types you want |