GCP Projects ☁️

Komodor's GCP integration discovers your GKE clusters and pulls read-only metadata so you can view workload health, costs, and right-sizing recommendations without granting write access.

How it works

You create an Azure App Registration (service principal) with the built-in Reader role on your subscription, then hand the credentials to Komodor. Komodor stores the client secret encrypted and uses it only to list and describe your AKS resources.

Prerequisites

- Google Cloud SDK installed — `gcloud --version`

- Owner or IAM Admin on the target project

- Active `gcloud` login — `gcloud auth login`

- A Komodor API key (find it under Settings → API Keys)

Setup

Option 1 — Automated setup script

Download and run the script. It creates the service account, assigns the Viewer role, and registers the integration in one step.

bash
bash setup-gcp-integration.sh \
  --project-id <your-project-id> \
  --komodor-api-key <your-api-key>

For multiple projects, need to run it separately for each project.

Optional flags:

Flag	Description	Default
--project-id	GCP Project ID	required
--komodor-api-key	Komodor API key	required
--account-name	Display name in Komodor	Project ID

The script deletes the local key file automatically on exit.

Option 2 — Manual Setup

Create the service account

bash
gcloud iam service-accounts create komodor \
  --display-name "Komodor" \
  --project <your-project-id>

The service account email will be:

`komodor@<your-project-id>.iam.gserviceaccount.com`

Assign the Viewer role

bash
gcloud projects add-iam-policy-binding <your-project-id> \
  --member="serviceAccount:komodor@<your-project-id>.iam.gserviceaccount.com" \
  --role="roles/viewer"

Generate a JSON key

bash
gcloud iam service-accounts keys create /tmp/komodor-key.json \
  --iam-account="komodor@<your-project-id>.iam.gserviceaccount.com" \
  --project <your-project-id>

Register the integration

Pass the JSON key file contents directly in the `serviceAccountJsonKey` field:

`bash
curl -X POST https://api.komodor.com/api/v2/integrations/gcp \
  -H "X-API-KEY: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d "{
    \"accountName\": \"<display-name>\",
    \"projectId\": \"<your-project-id>\",
    \"serviceAccountEmail\": \"komodor@<your-project-id>.iam.gserviceaccount.com\",
    \"serviceAccountJsonKey\": $(cat /tmp/komodor-key.json | python3 -c 'import sys,json; print(json.dumps(sys.stdin.read()))')
  }"

Clean up the key file

bash
rm /tmp/komodor-key.json

Verify the connection

A successful `POST` returns `HTTP 201` with an integration ID and initial status:

{
"id": "...",
"status": "connected",
"verificationStatus": "pending"
}

`verificationStatus` transitions to `verified` within 2–3 minutes. Poll with:

bash
curl https://api.komodor.com/api/v2/integrations/gcp/<integration-id> \
  -H "X-API-KEY: <your-api-key>" \
  | python3 -m json.tool

Required permissions

The built-in Viewer role covers everything Komodor needs. If your security policy requires a custom role, the minimum permissions are:

Permission	Purpose
resourcemanager.projects.get	Read project metadata
container.clusters.list	Discover GKE clusters
container.clusters.get	Read GKE cluster details
iam.serviceAccounts.get	Validate service account configuration

Troubleshooting

`verificationStatus` stays `pending` after 5 minutes

IAM policy changes can take a few minutes to propagate. If it remains `pending` past 10 minutes, check that the Viewer role binding was applied to the correct project.

`HTTP 401 Unauthorized`

The `X-API-KEY` header is missing or the key is invalid. Verify your API key under Settings → API Keys.

`HTTP 422 All checks failed`

The `serviceAccountJsonKey` value is not valid JSON, or the `projectId` in the request does not match the `project_id` inside the key file. Re-export the key and try again.

`HTTP 409 Conflict`

An integration for this project already exists. Remove the existing integration first via `DELETE /api/v2/integrations/gcp/<id>`, then retry.