Docs / Cloud Accounts / Connect GCP Account

Connect GCP Account

Published · Last updated: June 2026 · 10 min read

Overview

CloudAIPilot connects to your Google Cloud Platform (GCP) project using a Service Account — a machine identity with specific, scoped permissions. This separates infrastructure access from any individual user account, and lets you revoke access at any time by disabling the service account in your GCP console.

CloudAIPilot never stores your root Google credentials. It only ever holds the service account JSON key, which is encrypted immediately on upload.

Security & PQC Note

Your GCP Service Account JSON key is encrypted at rest using Post-Quantum Cryptography (PQC) standards (ML-KEM-768). Even in the event of a future classical cryptographic break, your cloud credentials remain mathematically secure.

Before You Begin

You will need:

  • A GCP account with Project Owner or Project IAM Admin permissions on the target project
  • Your GCP Project ID (visible in the GCP Console header, or under Home → Project info)
  • Billing enabled on the project (required to provision Compute Engine resources)

You are connecting one GCP project at a time. If you manage multiple projects, repeat this process for each one. The service account you create is project-scoped by default.

Step-by-Step Guide

Step 1: Enable Required APIs on the Project

GCP APIs are disabled by default. Before creating the service account, enable the APIs CloudAIPilot needs:

  1. In the GCP Console, make sure the correct project is selected in the top project switcher.
  2. Go to APIs & Services → Library.
  3. Search for and enable each of the following APIs:
  • Compute Engine API — required for server provisioning and management
  • Cloud Billing API — required for FinOps cost data (can be skipped if you don't need cost visibility)
  • Cloud Resource Manager API — required for project-level operations

If any API shows a "Enable billing" prompt, your project's billing account is not linked. Go to Billing → Link a billing account before proceeding.

Step 2: Create the Service Account

  1. Navigate to IAM & Admin → Service Accounts.
  2. Click Create Service Account.
  3. Fill in the details:
    • Service account name: cloudaipilot-orchestrator
    • Service account ID: auto-fills from the name — leave as-is
    • Description: CloudAIPilot infrastructure management
  4. Click Create and continue.

Step 3: Assign Roles to the Service Account

On the "Grant this service account access to project" screen, add the following roles one at a time using the role selector:

Server management:

  • Compute Admin — provision, resize, stop, and delete Compute Engine instances and disks
  • Compute Network Admin — manage VPC firewall rules and networking for servers

Storage (for backup vault):

  • Storage Admin — read and write to Cloud Storage buckets used as offsite backup vaults (optional — only required if you plan to use GCS as your backup destination)

FinOps & billing (optional):

  • Billing Account Viewer — read billing data for the FinOps cost dashboard

Note on Billing Account Viewer: This role is assigned at the Billing Account level, not the project level. After creating the service account, you will set this separately in Step 5. For now, skip it in this screen and click Continue.

Click Done to finish creating the service account.

Step 4: Generate the JSON Key

  1. In the Service Accounts list, click the name of the cloudaipilot-orchestrator account you just created.
  2. Go to the Keys tab.
  3. Click Add Key → Create new key.
  4. Select JSON as the key type and click Create.
  5. The key file downloads automatically to your computer. Keep this file secure — you will upload it to CloudAIPilot in the next step and then delete it.

Step 5: (Required for FinOps) Grant Billing Account Viewer at the Billing Level

The Billing Account Viewer role must be set at the billing account level, not at the project level:

  1. Go to Billing in the GCP Console.
  2. Select the billing account linked to your project.
  3. Click Account management → Add member.
  4. Enter the service account's email address — it looks like: cloudaipilot-orchestrator@YOUR-PROJECT-ID.iam.gserviceaccount.com
  5. Assign the role Billing Account Viewer and click Save.

Without this step, server provisioning still works — only the FinOps dashboard will show no cost data for this GCP project.

Step 6: Connect to CloudAIPilot

  1. In CloudAIPilot, go to Cloud Accounts → Add Account → GCP.
  2. Upload the JSON key file you downloaded in Step 4.
  3. Enter your Project ID in the field provided (find it under GCP Console → Home → Project info).
  4. Click Test & Connect.
  5. CloudAIPilot performs a pre-flight check: it verifies the service account has the required permissions before saving. If the check fails, a specific error message appears — see the troubleshooting section below.

Security: CloudAIPilot encrypts the JSON key immediately on upload and removes the plaintext from memory. Delete the downloaded JSON file from your local machine after connecting — you cannot retrieve it from CloudAIPilot later.

Verifying a Successful Connection

After clicking Connect, you should see the GCP account appear in your Cloud Accounts list with a green Connected status. If you navigate to Servers → Add Server, your GCP project's regions should now appear as provisioning targets.

If the status shows Permission Error or Failed, see the troubleshooting section below.

Common Connection Errors

"Compute Engine API has not been used in project … before or it is disabled"
You skipped Step 1. Go to APIs & Services → Library and enable the Compute Engine API on the project.
"Permission denied on resource project"
The service account is missing the Compute Admin or Compute Network Admin role. Revisit Step 3 and confirm both roles are assigned to the service account in IAM.
"The provided key is invalid or has been revoked"
The JSON key file was deleted or disabled in GCP before uploading. Go back to the service account's Keys tab and generate a new key.
"Project ID not found"
The Project ID you entered doesn't match the project in the JSON key. The JSON key contains a "project_id" field — use that exact value in the Project ID field in CloudAIPilot.
FinOps dashboard shows no data after connecting
Either the Cloud Billing API is not enabled (Step 1), or Billing Account Viewer was not granted at the billing account level (Step 5). Both are required for cost data to flow.

Human-in-the-Loop Safety

Once connected, CloudAIPilot reads your GCP project and can propose infrastructure changes. It will never provision a new Compute Engine instance, resize a disk, or remove any resource without generating an Approval Card for you to review and confirm first.

Revoking Access

To disconnect CloudAIPilot from your GCP project:

  • In CloudAIPilot: Cloud Accounts → [your account] → Remove
  • In GCP (immediate revocation): Go to IAM & Admin → Service Accounts → find cloudaipilot-orchestrator → click the three-dot menu → Disable or Delete. This immediately revokes all access regardless of the state in CloudAIPilot.

Related Articles