GCP

Teleskope supports two GCP enrollment paths:

• Organization discovery: Configure one connector service account and grant its IAM roles on the organization. Teleskope traverses the organization and its folders to discover projects automatically.

• Manual project enrollment: Add projects individually and grant the connector roles on each project.

Organization discovery is optional and disabled by default. It does not replace manual project enrollment. When organization discovery is enabled, inherited organization-level permissions mean discovered projects do not need to be enrolled or assigned to connectors individually.

Organization reconciliation runs on a five-field cron schedule in UTC. During reconciliation, Teleskope:

1. Discovers projects in the organization and its folders.

2. Determines which supported GCP resources exist in each project.

3. Verifies the connector service account's effective access.

4. Enables each connector independently for the projects where it is applicable and accessible.

A project does not need every connector. If a project has no resources for a connector, that connector is marked not applicable. A permission failure for one connector does not prevent another accessible connector from running in the same project.

The organization reconciliation cron controls project discovery and access verification. Each connector has a separate scan cron that controls when eligible resources are added to and refreshed in the Data Catalog.

Configure organization discovery

Use the following sections for organization discovery. To enroll one project without scheduled organization traversal, see Enroll a project manually.

Runtime IAM requirements

Grant the shared dispatch permissions and the permissions for every connector you enable. The table lists the Google API calls used by the current connector paths and whether organization readiness explicitly verifies the permission. A No means the permission is not in the preflight's declared required-permission check; resource-discovery calls can still fail before that check runs. It does not mean the permission is optional at runtime.

Scope	Google API methods	Required permission	Readiness preflight
Shared dispatch	Resource Manager Projects.Get and Projects.GetAncestry	resourcemanager.projects.get	No
Shared dispatch	Compute Engine Regions.List	compute.regions.list	No
BigQuery	BigQuery Datasets.List and Datasets.Get	bigquery.datasets.get	No
BigQuery	BigQuery Tables.List and Tables.Get	bigquery.tables.get, bigquery.tables.list	bigquery.tables.get only
BigQuery	BigQuery query jobs for column discovery and scanning	bigquery.jobs.create, bigquery.tables.getData	Yes
Cloud SQL	Cloud SQL Admin Instances.List	cloudsql.instances.list	No
Cloud SQL	Cloud SQL Auth Proxy connection	cloudsql.instances.get, cloudsql.instances.connect	Yes
Cloud SQL	Cloud SQL Admin SslCerts.Insert, when Teleskope generates a client certificate	cloudsql.sslCerts.create	No
Cloud Storage	Cloud Storage Buckets.List	storage.buckets.list	No
Cloud Storage	Cloud Storage Buckets.GetIamPolicy for each discovered bucket	storage.buckets.getIamPolicy	No
Cloud Storage	Cloud Storage Objects.List and object reads during scanning	storage.objects.list, storage.objects.get	Yes
Cloud Logging	GKE Projects.Locations.Clusters.List	container.clusters.list	Yes
Cloud Logging	Cloud Logging Entries.List	logging.logEntries.list	Yes

The preflight does not explicitly test the shared dispatch permissions, Cloud SQL certificate creation, or the Cloud Storage bucket enumeration and IAM-policy reads. Grant every permission in this table before enabling a connector; a successful readiness result is not an assertion that those permissions were tested.

Cloud SQL database permissions are separate from Google Cloud IAM. The database user still needs the read-only grants in Cloud SQL.

Create the connector service account

Create one service account for Teleskope in a GCP project that belongs to the organization. The service account can be used across all projects because its discovery and connector roles are granted on the organization.

resource "google_service_account" "teleskope" {
  project      = var.service_account_project_id
  account_id   = "teleskope"
  display_name = "Teleskope connector"
}

Grant organization discovery permissions

Create a custom role on the organization with these permissions:

• resourcemanager.organizations.get

• resourcemanager.folders.get

• resourcemanager.folders.list

• resourcemanager.projects.get

• resourcemanager.projects.list

• compute.regions.list

Grant the custom role to the connector service account on the organization.

resource "google_organization_iam_custom_role" "teleskope_discovery" {
  org_id      = var.organization_id
  role_id     = "teleskope_org_discovery"
  title       = "Teleskope organization discovery"
  description = "Read-only organization, folder, project, and region discovery"

  permissions = [
    "resourcemanager.organizations.get",
    "resourcemanager.folders.get",
    "resourcemanager.folders.list",
    "resourcemanager.projects.get",
    "resourcemanager.projects.list",
    "compute.regions.list",
  ]
}

resource "google_organization_iam_member" "teleskope_discovery" {
  org_id = var.organization_id
  role   = google_organization_iam_custom_role.teleskope_discovery.name
  member = "serviceAccount:${google_service_account.teleskope.email}"
}

The organization role above includes the two shared dispatch permissions. They are required even when you enable only one connector because dispatch looks up the enrolled project and its regions before connector-specific work starts.

Grant connector permissions on the organization

Grant the roles for every connector that you enable in Teleskope. Apply these roles to the connector service account at the organization level, not separately in each project.

BigQuery

• roles/bigquery.jobUser

• roles/bigquery.metadataViewer

• roles/bigquery.dataViewer

For BigQuery deletion or masking workflows, also grant roles/bigquery.dataEditor.

• roles/bigquery.metadataViewer supplies bigquery.datasets.get, bigquery.tables.get, and bigquery.tables.list.

• roles/bigquery.dataViewer supplies bigquery.tables.getData.

• roles/bigquery.jobUser supplies bigquery.jobs.create at the project where a BigQuery job runs.

Cloud SQL

• roles/cloudsql.client

• roles/cloudsql.viewer

• roles/cloudsql.admin

• roles/cloudsql.viewer supplies cloudsql.instances.get and cloudsql.instances.list.

• roles/cloudsql.client supplies cloudsql.instances.connect for the Cloud SQL Auth Proxy.

• roles/cloudsql.admin is used only because it includes cloudsql.sslCerts.create, which Teleskope uses when it generates a client SSL certificate.

Database credentials and read-only database grants are still configured per Cloud SQL instance; see Cloud SQL.

Cloud Storage

• roles/storage.bucketViewer

• roles/storage.objectViewer

• roles/pubsub.viewer

• roles/pubsub.subscriber

roles/storage.bucketViewer supplies storage.buckets.get and storage.buckets.list, while roles/storage.objectViewer supplies storage.objects.get and storage.objects.list. Neither role grants storage.buckets.getIamPolicy; grant the custom role below as well. In particular, roles/storage.objectViewer does not grant bucket enumeration or bucket IAM-policy reads.

The Pub/Sub roles are required when Cloud Storage notifications are used for incremental discovery. They do not replace the Cloud Storage permissions above. Topics, subscriptions, and bucket notifications remain project- or bucket-specific resources; see Cloud Storage.

resource "google_organization_iam_custom_role" "teleskope_storage_iam_policy_reader" {
  org_id      = var.organization_id
  role_id     = "teleskope_storage_iam_policy_reader"
  title       = "Teleskope Cloud Storage IAM policy reader"
  description = "Read bucket IAM policies for Teleskope Cloud Storage discovery"

  permissions = ["storage.buckets.getIamPolicy"]
}

resource "google_organization_iam_member" "teleskope_storage_iam_policy_reader" {
  org_id = var.organization_id
  role   = google_organization_iam_custom_role.teleskope_storage_iam_policy_reader.name
  member = "serviceAccount:${google_service_account.teleskope.email}"
}

Cloud Logging

• roles/logging.privateLogViewer

• roles/container.clusterViewer

roles/container.clusterViewer includes container.clusters.list, and roles/logging.privateLogViewer includes logging.logEntries.list for private log entries.

Terraform example

The following example grants all supported connector roles. Remove roles for connectors you do not enable.

locals {
  teleskope_connector_roles = toset([
    # BigQuery
    "roles/bigquery.jobUser",
    "roles/bigquery.metadataViewer",
    "roles/bigquery.dataViewer",
    # Optional: deletion and masking
    "roles/bigquery.dataEditor",

    # Cloud SQL
    "roles/cloudsql.client",
    "roles/cloudsql.viewer",
    "roles/cloudsql.admin",

    # Cloud Storage
    "roles/storage.bucketViewer",
    "roles/storage.objectViewer",
    "roles/pubsub.viewer",
    "roles/pubsub.subscriber",

    # Cloud Logging
    "roles/logging.privateLogViewer",
    "roles/container.clusterViewer",
  ])
}

resource "google_organization_iam_member" "teleskope_connectors" {
  for_each = local.teleskope_connector_roles

  org_id = var.organization_id
  role   = each.value
  member = "serviceAccount:${google_service_account.teleskope.email}"
}

Allow Teleskope to use the service account

Teleskope does not require a downloaded service-account key. Configure one of the following identity methods for your deployment.

Teleskope SaaS

Your Teleskope account team provides the exact Workload Identity Federation principal for your environment. Grant that principal roles/iam.workloadIdentityUser on the connector service account.

gcloud iam service-accounts add-iam-policy-binding \
  teleskope@SERVICE_ACCOUNT_PROJECT_ID.iam.gserviceaccount.com \
  --member="principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT" \
  --role="roles/iam.workloadIdentityUser"

Use the principal exactly as provided. This binding is made on the service account because it controls impersonation; the discovery and connector roles remain organization-level grants.

Teleskope-managed GCP deployment

Grant the Teleskope application service account permission to impersonate the connector service account. Your Teleskope account team provides the application service-account email.

gcloud iam service-accounts add-iam-policy-binding \
  teleskope@SERVICE_ACCOUNT_PROJECT_ID.iam.gserviceaccount.com \
  --member="serviceAccount:teleskope-CUSTOMER-app@DEPLOYMENT_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/iam.serviceAccountTokenCreator"

Configure organization discovery in Teleskope

In Teleskope, go to Settings > Connectors > GCP and configure:

• GCP organization ID

• Connector service-account email

• Workload Identity Federation project number, pool, and provider for SaaS deployments

• Reconciliation cron expression in UTC

• Scheduled discovery

The default reconciliation schedule is 0 0 * * *, once per day at 00:00 UTC. Run a dry run first, review the discovered project counts, then enable scheduled discovery.

Organization discovery automatically uses the GCP connectors enrolled in the environment. It does not require a per-project connector mapping. Connector scan schedules are configured separately on their individual settings pages.

Enroll a project manually

In Teleskope, go to Settings > Connectors > GCP and select Enroll. The Enroll page first shows Terraform to apply in the project being enrolled: it creates the connector service account, a Workload Identity pool, and an AWS provider trusting an AWS account, and grants the service account roles/iam.workloadIdentityUser. It also creates a one-time, org-level custom role and binding for discovery permissions — apply that part once per organization, not per project.

Before applying: set the AWS provider's account to the AWS account ID of your Teleskope environment, provided by your account team — the pre-filled value is not an AWS account ID. Use your project number, not your project ID, in the principalSet:// member — GCP requires the numeric project number there.

Then fill in the form with the organization ID, project ID, project number, service account name and email, and the pool ID and provider ID just created: GCP Organization ID, GCP Project ID, GCP Project Number, Service Account Name, Service Account Email, Workload Federation Pool ID, Workload Federation Pool Provider ID. Select Enroll.

Grant the shared dispatch role and the connector roles only on that project. The project is stored and enabled independently of any organization enrollment profile, so scheduled organization discovery does not need to be enabled.

resource "google_project_iam_custom_role" "teleskope_gcp_dispatch" {
  project_id  = var.project_id
  role_id     = "teleskope_gcp_dispatch"
  title       = "Teleskope GCP dispatch"
  description = "Read the enrolled project and its regions before connector dispatch"

  permissions = [
    "resourcemanager.projects.get",
    "compute.regions.list",
  ]
}

resource "google_project_iam_member" "teleskope_gcp_dispatch" {
  project = var.project_id
  role    = google_project_iam_custom_role.teleskope_gcp_dispatch.name
  member  = "serviceAccount:${google_service_account.teleskope.email}"
}

For manual Cloud Storage enrollment, also grant this project-scoped custom role in addition to roles/storage.bucketViewer and roles/storage.objectViewer:

resource "google_project_iam_custom_role" "teleskope_storage_iam_policy_reader" {
  project_id  = var.project_id
  role_id     = "teleskope_storage_iam_policy_reader"
  title       = "Teleskope Cloud Storage IAM policy reader"
  description = "Read bucket IAM policies for Teleskope Cloud Storage discovery"

  permissions = ["storage.buckets.getIamPolicy"]
}

resource "google_project_iam_member" "teleskope_storage_iam_policy_reader" {
  project = var.project_id
  role    = google_project_iam_custom_role.teleskope_storage_iam_policy_reader.name
  member  = "serviceAccount:${google_service_account.teleskope.email}"
}