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.
The Pub/Sub push subscription for logs (step 5). Pub/Sub signs in to the Collector as this account when it pushes logs.

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
Pub/Sub API (`pubsub.googleapis.com`)	Receive logs (topic and push subscription). Needed only for logs.
Cloud Logging API (`logging.googleapis.com`)	Create the log sink that sends logs to Pub/Sub. Needed only for logs.

In every monitored project that is not the deployment project, also enable the Cloud Monitoring API, and the Cloud Logging API if you want logs.

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 \
  pubsub.googleapis.com \
  logging.googleapis.com \
  --project=<deployment-project-id>

For each additional monitored project:

gcloud services enable \
  monitoring.googleapis.com \
  logging.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. The Pub/Sub push subscription for logs uses it too.

In your deployment project, go to IAM & Admin > Service Accounts > + Create service account.
Set Service account name to signoz-integration-collector. GCP generates the email signoz-integration-collector@<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-collector \
  --display-name="SigNoz telemetry collector" \
  --project=<deployment-project-id>

This creates signoz-integration-collector@<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-collector@<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-collector@<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.

Log delivery identities (reference)

Logs use two more identities. You set them up later in Collect logs. Nothing to do now.

Log sink writer identity: GCP creates a service account for each log sink. You give it roles/pubsub.publisher on the Pub/Sub topic so the sink can send logs.
Push sign-in account: the push subscription signs in to the Collector as signoz-integration-collector. You give it roles/run.invoker on the Cloud Run service.

Permission summary

After this guide, signoz-integration-collector holds:

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

These roles are granted later:

Identity	Role	Scope	Purpose
`signoz-integration-collector` service account	`roles/secretmanager.secretAccessor`	The Collector config secret	Read the Collector config at startup (Deploy the Collector)
`signoz-integration-collector` service account	`roles/run.invoker`	The Collector's Cloud Run service	Let Pub/Sub push logs to the Collector (Collect logs)
Pub/Sub service agent	`roles/iam.serviceAccountTokenCreator`	The `signoz-integration-collector` service account	Create sign-in tokens for push requests (Collect logs)
Log sink writer identity (auto-created)	`roles/pubsub.publisher`	The Pub/Sub topic	Send logs to the topic (Collect logs)

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.