Create a Least-Privilege GCP Service Account for SigNoz

SigNoz needs a dedicated service account to act as the single identity for the resources the integration runs, so all the access it needs is granted and audited in one place. This guide enables the required APIs and creates that account. It is used by:

The OpenTelemetry Collector (step 3). The Cloud Run service runs as this account, so it authenticates to Google APIs automatically (no key files).
The Cloud Monitoring API. The Collector reads metrics as this account across every project you monitor, which is why it needs roles/monitoring.viewer on each.

Before you start, decide your Deployment Project ID (the project where the Collector will run) and the list of Projects to Monitor. These are two of the four connection fields you enter when you connect your GCP account.

Prerequisites

A GCP account with permission to enable APIs, create service accounts, and grant IAM roles in your deployment project and every project you want to monitor. The Owner or Editor role on those projects is sufficient. If you use custom roles, you need resourcemanager.projects.setIamPolicy, iam.serviceAccounts.create, and serviceusage.services.enable on the project, plus iam.serviceAccounts.actAs on the service account you create here (granted through Service Account User, roles/iam.serviceAccountUser) so you can attach it to the Cloud Run service in step 3.
The gcloud CLI installed and authenticated (gcloud auth login), if you prefer commands over the Console. You can also run every gcloud command from Cloud Shell in the browser.

Throughout this guide, <deployment-project-id> is your Deployment Project ID and <monitored-project-id> is one of the Projects to Monitor. If you monitor only one project, these are the same value.

Step 1: Enable the required APIs

Enable these APIs in your deployment project:

API	Why it's needed
Cloud Run Admin API (`run.googleapis.com`)	Deploy and run the Collector
Secret Manager API (`secretmanager.googleapis.com`)	Store the Collector config the service reads at startup
Cloud Monitoring API (`monitoring.googleapis.com`)	Read metrics into the Collector

In every monitored project that is not the deployment project, also enable the Cloud Monitoring API so its metrics are reachable.

In the Google Cloud Console, select your deployment project in the project picker.
Go to APIs & Services > Enabled APIs & services > + Enable APIs and services.
Search for each API in the table above and click Enable.

See Enabling an API for details.

gcloud services enable \
  run.googleapis.com \
  secretmanager.googleapis.com \
  monitoring.googleapis.com \
  --project=<deployment-project-id>

For each additional monitored project:

gcloud services enable \
  monitoring.googleapis.com \
  --project=<monitored-project-id>

Step 2: Create the integration service account

Create one service account in your deployment project. The Collector runs as this account and authenticates to the Monitoring API with it.

In your deployment project, go to IAM & Admin > Service Accounts > + Create service account.
Set Service account name to signoz-integration. GCP generates the email signoz-integration@<deployment-project-id>.iam.gserviceaccount.com.
Click Create and continue, then Done. You grant roles in the next step.

gcloud iam service-accounts create signoz-integration \
  --display-name="SigNoz Collector" \
  --project=<deployment-project-id>

This creates signoz-integration@<deployment-project-id>.iam.gserviceaccount.com.

You attach this service account to the Cloud Run service in step 3. Because it runs on Cloud Run, the Collector picks up its credentials automatically through Application Default Credentials. You do not create or download a JSON key. Avoid downloading keys unless you have no alternative; a leaked key is a standing credential.

Step 3: Grant metrics permission on each monitored project

To read metrics through the Monitoring API, the service account needs the Monitoring Viewer role (roles/monitoring.viewer) on each project you want to monitor. This role is read-only: it grants monitoring.timeSeries.list and nothing that can modify your resources.

For each monitored project:

Select the monitored project in the project picker.
Go to IAM & Admin > IAM > + Grant access.
In New principals, paste signoz-integration@<deployment-project-id>.iam.gserviceaccount.com.
In Role, select Monitoring > Monitoring Viewer.
Click Save.

Run once per monitored project (including the deployment project if you monitor it):

gcloud projects add-iam-policy-binding <monitored-project-id> \
  --member="serviceAccount:signoz-integration@<deployment-project-id>.iam.gserviceaccount.com" \
  --role="roles/monitoring.viewer"

The service account lives in your deployment project but is granted access on each monitored project. This is expected: one identity reads across every project you monitor. You repeat this binding once per project in Projects to Monitor.

Permission summary

After this guide, signoz-integration holds:

Identity	Role	Scope	Purpose
`signoz-integration` service account	`roles/monitoring.viewer`	Each monitored project	Read metrics via the Monitoring API

One more role is granted later, in step 2 of Deploy the Collector:

Identity	Role	Scope	Purpose
`signoz-integration` service account	`roles/secretmanager.secretAccessor`	The Collector config secret	Read the Collector config at startup

Next step

With APIs enabled and the service account ready, connect your GCP account in SigNoz.

Get Help

If you need help with the steps in this topic, please reach out to us on SigNoz Community Slack. If you are a SigNoz Cloud user, please use in product chat support located at the bottom right corner of your SigNoz instance or contact us at cloud-support@signoz.io.