# 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.gke.awsRoleArn=arn:aws:iam::123456789012:role/...
   ```

### 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.             |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.nullify.ai/connectors/gcp/configuration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.