> For the complete documentation index, see [llms.txt](https://docs.nullify.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nullify.ai/connectors/gcp/configuration.md).

# Configuration

## Requirements

* An active Nullify tenant.
* A GCP project with permissions to create workload identity pools and service accounts.
* Terraform >= 1.3 (recommended) or `gcloud` CLI.
* For organization or folder scope: org admin access.

## Setup Overview

Nullify uses Workload Identity Federation (WIF) with OIDC to access your GCP environment. The Terraform module creates a workload identity pool, a read-only service account, and the minimum IAM bindings needed for cloud scanning.

## Parameters Supplied by Nullify

Available in the Nullify console under **Configure > Connectors > GCP**:

* **OIDC Issuer URI** — `https://gcp.nullify.ai` (production)
* **Tenant ID** — Your Nullify tenant identifier

## Information You Provide

After deploying the Terraform module:

* **Workload Identity Provider** — The full resource path from the Terraform output
* **Service Account Email** — The impersonated service account email from the Terraform output
* **Project IDs** — The GCP projects Nullify should scan

## Setup Steps

1. **Clone the Terraform module**:

   ```bash
   git clone https://github.com/Nullify-Platform/nullify-cloud-connector.git
   cd nullify-cloud-connector/gcp-integration-setup/terraform
   ```
2. **Configure variables**:

   ```bash
   cp terraform.tfvars.example terraform.tfvars
   ```

   Fill in:

   * `gcp_project_id` — Your GCP project
   * `nullify_oidc_issuer_uri` — From the Nullify console
   * `nullify_tenant_id` — From the Nullify console
   * `scope` — `"organization"`, `"folder"`, or `"projects"`
   * `organization_id` — Required for org or folder scope
3. **Deploy**:

   ```bash
   terraform init
   terraform plan
   terraform apply
   ```
4. **Configure in Nullify console**:
   * Go to **Configure > Connectors > GCP**
   * Paste the `workload_identity_provider` output
   * Paste the `service_account_email` output
   * Add your GCP project IDs
   * Click **Save** — Nullify auto-verifies the credentials

## Scope Options

| Scope          | Use When                          | Requires                        |
| -------------- | --------------------------------- | ------------------------------- |
| `organization` | Scan all projects in your GCP org | `organization_id`               |
| `folder`       | Scan all projects in a folder     | `organization_id` + `folder_id` |
| `projects`     | Scan specific projects only       | `project_ids` list              |

## Permissions

Nullify requests **read-only** access. No write, no data-plane, no code execution permissions.

**Predefined roles**: `cloudasset.viewer`, `iam.securityReviewer`, `compute.viewer`, `container.clusterViewer`, `cloudsql.viewer`, `spanner.viewer`, `cloudkms.viewer`, `logging.viewer`, `run.viewer`, `cloudfunctions.viewer`, `appengine.appViewer`, `dataproc.viewer`, `dataflow.viewer`, `pubsub.viewer`

**Custom role** (`nullifyCloudConnector`): Read-only permissions for Cloud Armor, VPC Service Controls, org policies, AlloyDB, Filestore, Memorystore, Artifact Registry, Cloud DNS, and API Gateway.

Full permission justification: [permissions.md](https://github.com/Nullify-Platform/nullify-cloud-connector/blob/main/gcp-integration-setup/docs/permissions.md)

## Revoking Access

```bash
terraform destroy
```

This deletes the workload identity pool, service account, and all IAM bindings.

***

## Kubernetes Collector (GKE)

Deploy the Nullify k8s-collector to GKE clusters for workload-level visibility.

### Prerequisites

* Any GKE cluster (Standard, Autopilot, private, or public)
* Kubernetes 1.22+
* Helm v3
* No special GKE configuration required

### Setup

1. **Get your cluster's OIDC issuer URL**:

   ```bash
   gcloud container clusters describe CLUSTER --zone ZONE \
     --format='value(selfLink)'
   ```
2. **Register in Nullify console**:
   * Go to **Configure > Connectors > GCP > GKE Clusters**
   * Add the OIDC issuer URL
   * Click **Save**
   * Copy the **K8s Collector Role ARN** displayed on the card
3. **Deploy the Helm chart**:

   ```bash
   helm repo add nullify https://nullify-platform.github.io/nullify-cloud-connector/
   helm repo update

   helm install nullify-collector nullify/nullify-k8s-collector \
     --namespace nullify --create-namespace \
     --set cloudProvider=gcp \
     --set collector.clusterName=my-gke-cluster \
     --set collector.aws.region=us-east-1 \
     --set collector.s3.bucket=your-nullify-bucket \
     --set collector.kms.keyArn=arn:aws:kms:us-east-1:123456789012:key/... \
     --set collector.gke.awsRoleArn=arn:aws:iam::123456789012:role/...
   ```

   The `collector.aws.region`, `collector.s3.bucket`, `collector.kms.keyArn`, and role ARN values all come from the Nullify **Configure → Connectors** page. The collector runs on a schedule (daily by default); adjust `collector.schedule` if you need a different cadence.

### What the Collector Gathers

* Cluster metadata (version, node pools)
* Namespaces, pods, deployments, statefulsets, daemonsets
* Services, ingresses, endpoints
* RBAC (roles, role bindings, service accounts)
* Network policies
* Persistent volumes and claims

Data is uploaded to Nullify's S3 bucket encrypted in transit. No cluster modifications are made.

## Troubleshooting

| Symptom                                                    | Likely Cause                                                                             |
| ---------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| Verify returns red with `permission denied`                | The Nullify SA is missing IAM bindings. Re-run `terraform apply`.                        |
| Verify returns red with `invalid token`                    | `nullify_oidc_issuer_uri` doesn't match. Use `https://gcp.nullify.ai` for production.    |
| k8s-collector fails with `AssumeRoleWithWebIdentity` error | The cluster OIDC URL wasn't registered in the Nullify console, or the role ARN is wrong. |
| k8s-collector pod stuck in `Pending`                       | Insufficient CPU/memory on the node. Reduce resource requests in Helm values.            |
| Connector shows `Not Verified`                             | Click Verify in the console, or re-save the settings to trigger auto-verify.             |