> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ankra.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Cloud (GCP) Credentials

> Store a GCP service account key in Ankra - read-only for cloud cost estimates and GKE discovery, or with provisioning roles to create GKE clusters.

GCP credentials store a service account key that Ankra uses to estimate the infrastructure cost of your clusters, discover clusters, and provision [Google Kubernetes Engine (GKE)](/guides/gke-clusters). There are two access levels, and you choose which one to grant:

* **Read-only** - cost estimates and cluster discovery only. Ankra never modifies resources.
* **GKE provisioning** - everything read-only does, plus creating and managing GKE clusters.

The key is validated against the GCP Cloud Resource Manager API when you save it, so an invalid key or a project the service account can't read is rejected immediately.

## What Ankra Accesses

For cost estimation and discovery, Ankra calls three Google APIs with the service account, all read-only:

| API                        | Why it's used                                                                   |
| -------------------------- | ------------------------------------------------------------------------------- |
| Cloud Resource Manager API | Verify the service account can read the project (the **Test connection** check) |
| Cloud Billing API          | Read the public Compute Engine price catalog (SKUs) for cost estimates          |
| Compute Engine API         | Read machine-type specs (vCPU and memory) to price your nodes                   |

Provisioning GKE additionally uses:

| API                   | Why it's used                                                  |
| --------------------- | -------------------------------------------------------------- |
| Kubernetes Engine API | Create, upgrade, scale, and delete GKE clusters and node pools |

## Creating a GCP Credential

Pick the tab that matches what you want the credential to do. Each flow is complete - follow one from top to bottom.

<Tabs>
  <Tab title="Read-only (cost and discovery)">
    Grants the **Viewer** role (`roles/viewer`) only. Ankra can price your nodes and discover clusters, but cannot create or change anything.

    <Steps>
      <Step title="Enable the required APIs">
        In the [Google Cloud Console](https://console.cloud.google.com), select your project and enable the **Cloud Resource Manager API**, **Cloud Billing API**, and **Compute Engine API**.

        Or with the `gcloud` CLI:

        ```bash theme={null}
        export PROJECT_ID="your-gcp-project-id"   # replace with your real project ID
        gcloud config set project "$PROJECT_ID"

        gcloud services enable \
          cloudresourcemanager.googleapis.com \
          cloudbilling.googleapis.com \
          compute.googleapis.com
        ```
      </Step>

      <Step title="Create a read-only service account">
        1. Go to **IAM & Admin** → **Service Accounts** → **Create service account**
        2. Give it a name such as `ankra-cost-readonly`
        3. Grant it the **Viewer** role (`roles/viewer`) on the project - or a custom read-only role

        Or with `gcloud` (reusing the `PROJECT_ID` from the previous step):

        ```bash theme={null}
        gcloud iam service-accounts create ankra-cost-readonly \
          --display-name="Ankra cost (read-only)"

        gcloud projects add-iam-policy-binding "$PROJECT_ID" \
          --member="serviceAccount:ankra-cost-readonly@${PROJECT_ID}.iam.gserviceaccount.com" \
          --role="roles/viewer"
        ```

        <Warning>
          If this fails with `does not have permission to access projects instance [...:getIamPolicy] (or it may not exist)`, either `PROJECT_ID` is still set to the placeholder, or your account lacks the `resourcemanager.projects.setIamPolicy` permission. Confirm `echo $PROJECT_ID` shows your real project ID, and that you hold `roles/owner` or `roles/resourcemanager.projectIamAdmin` on it (otherwise ask a project admin to run this one command).
        </Warning>
      </Step>

      <Step title="Create and download a JSON key">
        1. Open the service account → **Keys** → **Add key** → **Create new key**
        2. Choose **JSON** and download the file

        Or with `gcloud`:

        ```bash theme={null}
        gcloud iam service-accounts keys create ankra-key.json \
          --iam-account="ankra-cost-readonly@${PROJECT_ID}.iam.gserviceaccount.com"
        ```

        The downloaded JSON must contain `client_email`, `private_key`, and `token_uri`.
      </Step>

      <Step title="Add to Ankra (UI)">
        Go to **Credentials** → **Add** → **Google Cloud (GCP)**, then provide:

        * **Name**: a unique identifier - lowercase letters and numbers only, cannot start with a hyphen (e.g. `gcp-prod`)
        * **Project ID**: your GCP project ID (e.g. `acme-prod`)
        * **Service Account Key (JSON)**: paste the full contents of the downloaded key file

        Click **Test connection** to verify access, then **Add**.
      </Step>
    </Steps>
  </Tab>

  <Tab title="GKE provisioning">
    Grants the **Kubernetes Engine Admin** (`roles/container.admin`) and **Service Account User** (`roles/iam.serviceAccountUser`) roles so Ankra can create and manage [GKE clusters](/guides/gke-clusters), plus **Viewer** (`roles/viewer`) so the same credential also powers cost estimates and discovery. To also create VPC networks from the cluster wizard, add **Compute Network Admin** (`roles/compute.networkAdmin`).

    <Steps>
      <Step title="Enable the required APIs">
        In the [Google Cloud Console](https://console.cloud.google.com), select your project and enable the **Cloud Resource Manager API**, **Cloud Billing API**, **Compute Engine API**, and **Kubernetes Engine API**.

        Or with the `gcloud` CLI:

        ```bash theme={null}
        export PROJECT_ID="your-gcp-project-id"   # replace with your real project ID
        gcloud config set project "$PROJECT_ID"

        gcloud services enable \
          cloudresourcemanager.googleapis.com \
          cloudbilling.googleapis.com \
          compute.googleapis.com \
          container.googleapis.com
        ```
      </Step>

      <Step title="Create a provisioning service account">
        1. Go to **IAM & Admin** → **Service Accounts** → **Create service account**
        2. Give it a name such as `ankra-gke`
        3. Grant it the **Kubernetes Engine Admin** (`roles/container.admin`), **Service Account User** (`roles/iam.serviceAccountUser`), and **Viewer** (`roles/viewer`) roles on the project
        4. Optional: also grant **Compute Network Admin** (`roles/compute.networkAdmin`) if you want to create VPC networks directly from Ankra's cluster wizard - without it, the wizard can only attach clusters to networks that already exist

        Or with `gcloud` (reusing the `PROJECT_ID` from the previous step):

        ```bash theme={null}
        gcloud iam service-accounts create ankra-gke \
          --display-name="Ankra GKE provisioning"

        gcloud projects add-iam-policy-binding "$PROJECT_ID" \
          --member="serviceAccount:ankra-gke@${PROJECT_ID}.iam.gserviceaccount.com" \
          --role="roles/container.admin"

        gcloud projects add-iam-policy-binding "$PROJECT_ID" \
          --member="serviceAccount:ankra-gke@${PROJECT_ID}.iam.gserviceaccount.com" \
          --role="roles/iam.serviceAccountUser"

        gcloud projects add-iam-policy-binding "$PROJECT_ID" \
          --member="serviceAccount:ankra-gke@${PROJECT_ID}.iam.gserviceaccount.com" \
          --role="roles/viewer"

        # optional - lets the cluster wizard create VPC networks from Ankra
        gcloud projects add-iam-policy-binding "$PROJECT_ID" \
          --member="serviceAccount:ankra-gke@${PROJECT_ID}.iam.gserviceaccount.com" \
          --role="roles/compute.networkAdmin"
        ```

        <Warning>
          If this fails with `does not have permission to access projects instance [...:getIamPolicy] (or it may not exist)`, either `PROJECT_ID` is still set to the placeholder, or your account lacks the `resourcemanager.projects.setIamPolicy` permission. Confirm `echo $PROJECT_ID` shows your real project ID, and that you hold `roles/owner` or `roles/resourcemanager.projectIamAdmin` on it (otherwise ask a project admin to run this one command).
        </Warning>

        `roles/iam.serviceAccountUser` is required because GKE nodes run as the project's default compute service account - Ankra's service account must be allowed to attach it to the node pools it creates.
      </Step>

      <Step title="Create and download a JSON key">
        1. Open the service account → **Keys** → **Add key** → **Create new key**
        2. Choose **JSON** and download the file

        Or with `gcloud`:

        ```bash theme={null}
        gcloud iam service-accounts keys create ankra-key.json \
          --iam-account="ankra-gke@${PROJECT_ID}.iam.gserviceaccount.com"
        ```

        The downloaded JSON must contain `client_email`, `private_key`, and `token_uri`.
      </Step>

      <Step title="Add to Ankra (UI)">
        Go to **Credentials** → **Add** → **Google Cloud (GCP)**, then provide:

        * **Name**: a unique identifier - lowercase letters and numbers only, cannot start with a hyphen (e.g. `gcp-prod`)
        * **Project ID**: your GCP project ID (e.g. `acme-prod`)
        * **Service Account Key (JSON)**: paste the full contents of the downloaded key file

        Click **Test connection** to verify access, then **Add**.
      </Step>

      <Step title="Create your first GKE cluster">
        With the credential saved, follow [Google Kubernetes Engine (GKE)](/guides/gke-clusters) to provision a cluster from the portal, CLI, or API.
      </Step>
    </Steps>
  </Tab>
</Tabs>

<Note>
  Already added a read-only credential and want to provision GKE? Grant the extra roles and enable the Kubernetes Engine API on the **same service account** (run the `add-iam-policy-binding` and `services enable` commands from the **GKE provisioning** tab with your existing account's name) - no need to create a new credential in Ankra.
</Note>

## Troubleshooting GCP Credentials

For `gcloud` setup errors during service-account creation (such as `does not have permission ... (or it may not exist)`), see the warning in the **Create a service account** step above - it's almost always an unsubstituted `PROJECT_ID` placeholder or a missing `setIamPolicy` permission.

The table below covers the **Test connection** result in the Ankra UI:

| Test connection result                                                  | Cause                                   | Solution                                                                                         |
| ----------------------------------------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------ |
| The service account key is not valid JSON or is missing required fields | The pasted key isn't the full JSON file | Paste the entire downloaded JSON; it must include `client_email`, `private_key`, and `token_uri` |
| Google rejected the service account credentials                         | The key is disabled or deleted          | Confirm the key is active, or create a new JSON key                                              |
| The service account lacks read access to this project                   | Missing IAM role or disabled API        | Grant the **Viewer** role and enable the **Cloud Resource Manager API**                          |
| The project was not found                                               | Wrong project ID                        | Check the **Project ID** matches your GCP project exactly                                        |
| Could not reach the GCP Resource Manager API                            | Network or connectivity issue           | Retry; ensure outbound access to `*.googleapis.com`                                              |

**Test connection** only verifies read access. If the credential saves fine but GKE cluster creation fails with a permissions error, the service account is missing `roles/container.admin` or `roles/iam.serviceAccountUser`, or the **Kubernetes Engine API** is not enabled - see the **GKE provisioning** tab above.

Creating a VPC network from the cluster wizard fails with `Required 'compute.networks.create' permission` when the service account lacks **Compute Network Admin** (`roles/compute.networkAdmin`) - grant it with the optional binding from the **GKE provisioning** tab, or pick an existing network instead.