> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Arvo-AI/aurora/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Cloud Platform (GCP)

> Connect Aurora to your Google Cloud Platform projects for infrastructure management

## Overview

Aurora integrates with Google Cloud Platform using OAuth 2.0 to securely access your GCP projects. Once connected, Aurora can manage GKE clusters, Cloud Run services, and other GCP resources across all your projects.

## What Aurora Can Access

Once authenticated, Aurora can discover and manage:

* **GKE Clusters**: Kubernetes clusters in Google Kubernetes Engine
* **Cloud Run Services**: Serverless container deployments
* **Compute Engine**: VM instances and instance groups
* **Cloud Storage**: Buckets and objects
* **Cloud Functions**: Serverless functions
* **BigQuery**: Data warehouse and analytics
* **Cloud SQL**: Managed database instances
* **VPC Networks**: Virtual Private Cloud networking
* **IAM**: Service accounts and permissions
* **Billing**: Project billing information and usage

## Prerequisites

<Steps>
  <Step title="GCP Account">
    You need a Google Cloud Platform account with at least one active project
  </Step>

  <Step title="Billing Enabled">
    At least one project must have billing enabled for Aurora to manage resources
  </Step>

  <Step title="Required Permissions">
    You need Owner or Editor role on your GCP projects to grant Aurora the necessary permissions
  </Step>
</Steps>

## Environment Variables

Configure these environment variables in Aurora's `.env` file:

```bash theme={null}
# Google Cloud OAuth Credentials (from Google Cloud Console)
CLIENT_ID=your-google-oauth-client-id.apps.googleusercontent.com
CLIENT_SECRET=your-google-oauth-client-secret

# Backend URL for OAuth callbacks
NEXT_PUBLIC_BACKEND_URL=https://your-aurora-backend.com

# Frontend URL for post-auth redirects
FRONTURL=https://your-aurora-frontend.com/chat
```

### Creating OAuth Credentials

<Steps>
  <Step title="Open Google Cloud Console">
    Go to [Google Cloud Console](https://console.cloud.google.com/) and select your project
  </Step>

  <Step title="Enable APIs">
    Navigate to **APIs & Services > Library** and enable:

    * Google Cloud Resource Manager API
    * Identity and Access Management (IAM) API
    * Service Usage API
  </Step>

  <Step title="Create OAuth Client">
    Go to **APIs & Services > Credentials** and click **Create Credentials > OAuth client ID**
  </Step>

  <Step title="Configure OAuth Consent Screen">
    If prompted, configure the OAuth consent screen with your application details
  </Step>

  <Step title="Set Application Type">
    Choose **Web application** as the application type
  </Step>

  <Step title="Add Authorized Redirect URIs">
    Add your Aurora backend callback URL:

    ```
    https://your-aurora-backend.com/callback
    ```
  </Step>

  <Step title="Save Credentials">
    Copy the Client ID and Client Secret to your `.env` file
  </Step>
</Steps>

## Authentication Flow

Aurora uses the OAuth 2.0 authorization code flow for GCP authentication:

<Steps>
  <Step title="User Initiates Login">
    Click the "Connect GCP" button in Aurora's UI
  </Step>

  <Step title="Redirect to Google">
    Aurora redirects you to Google's OAuth consent page
  </Step>

  <Step title="Grant Permissions">
    Review and grant Aurora the requested permissions:

    * `https://www.googleapis.com/auth/cloud-platform` (Full GCP access)
    * `https://www.googleapis.com/auth/userinfo.email` (Email address)
    * `openid` (OpenID Connect authentication)
  </Step>

  <Step title="Authorization Code Exchange">
    Google redirects back to Aurora with an authorization code
  </Step>

  <Step title="Token Storage">
    Aurora exchanges the code for access and refresh tokens, storing them securely in HashiCorp Vault
  </Step>

  <Step title="Post-Auth Setup">
    Aurora automatically performs setup tasks:

    * Validates projects and billing status
    * Enables required APIs (25 APIs across all projects)
    * Creates Aurora service accounts for secure access
    * Configures IAM permissions
    * Updates organization policies for Cloud Run public access
    * Verifies permission propagation
    * Triggers infrastructure discovery
  </Step>
</Steps>

## Post-Authentication Setup

After OAuth callback, Aurora runs an asynchronous Celery task (`gcp_post_auth_setup_task`) that:

### 1. Project Validation

* Fetches all accessible GCP projects
* Filters projects with active billing
* If more than 5 eligible projects, prompts for manual selection

### 2. API Enablement

Enables 25 required Google Cloud APIs across all selected projects:

* Cloud Resource Manager API
* Compute Engine API
* Kubernetes Engine API
* Cloud Run Admin API
* Cloud Functions API
* Cloud Storage API
* Cloud SQL Admin API
* Cloud Billing API
* IAM API
* Service Usage API
* And 15+ more services

### 3. Service Account Creation

* Creates Aurora-managed service accounts in your root project
* Grants necessary IAM roles across all projects
* Configures service account impersonation

### 4. Organization Policy Updates

* Updates org policies to allow Cloud Run public access (`allUsers` principal)
* Configures domain-restricted sharing policies if needed

### 5. Permission Verification

* Verifies service account permissions have propagated (max 20 attempts, 30s intervals)
* Tests token generation for each project
* Reports partial or full verification status

## Root Project Selection

Aurora automatically selects a "root project" for service account creation using this priority:

1. **User Preference**: Previously selected root project (stored in `user_preferences` table)
2. **Billing + IAM**: First project with both billing enabled and IAM permissions
3. **Fallback**: First accessible project

You can override the root project selection through the Aurora UI.

## API Endpoints

### Login

```http theme={null}
POST /login
Content-Type: application/json

{
  "userId": "user-id-here"
}
```

Returns OAuth authorization URL with state parameter for CSRF protection.

### OAuth Callback

```http theme={null}
GET /callback?code=AUTH_CODE&state=USER_ID
```

Handles OAuth callback, exchanges code for tokens, and triggers post-auth setup.

### Setup Status

```http theme={null}
GET /gcp/setup/status/{task_id}
```

Checks the progress of post-authentication setup tasks.

### Force Disconnect

```http theme={null}
POST /api/gcp/force-disconnect
Headers: X-User-ID: your-user-id
```

Removes GCP tokens and clears cached credentials.

## Troubleshooting

### No Projects Found

**Error**: "No GCP projects found during login"

**Solution**: Ensure you have at least one GCP project in your account. Create one at [Google Cloud Console](https://console.cloud.google.com/).

### No Billing Enabled

**Error**: "No GCP project with active billing found"

**Solution**: Enable billing on at least one project:

1. Go to **Billing** in Google Cloud Console
2. Link a billing account to your project
3. Verify billing is active

### Token Refresh Failed

**Error**: "No refresh token available. Please re-authenticate."

**Solution**:

* Re-authenticate through the Aurora UI
* Ensure OAuth consent screen includes `access_type=offline` and `prompt=consent` parameters
* Check that refresh tokens are being stored in Vault

### API Enablement Errors

**Error**: "Error enabling required APIs"

**Solution**:

1. Verify you have `Service Usage Admin` role
2. Check project quotas and limits
3. Manually enable APIs through Cloud Console if needed
4. Wait a few minutes for API propagation

### Permission Propagation Timeout

**Warning**: "Propagation verification: PARTIAL (X/Y projects)"

**Solution**:

* IAM permissions can take up to 10 minutes to propagate
* Aurora will retry automatically (20 attempts over \~10 minutes)
* If partial verification persists, check service account IAM bindings manually
* Some projects may have org policies blocking service account access

### Organization Policy Conflicts

**Error**: "Org Policy update failed for some projects"

**Solution**:

1. Check if your organization has strict domain policies
2. Verify you have `Organization Policy Administrator` role if using org-level policies
3. Some projects may inherit conflicting policies from parent folders/organizations
4. You may need to manually update `iam.allowedPolicyMemberDomains` constraint

### Service Account Errors

**Error**: "Aurora full-access setup had errors"

**Solution**:

* Verify you have `Service Account Admin` and `Project IAM Admin` roles
* Check project-level IAM permissions
* Ensure service accounts can be created in the root project
* Review Cloud Console audit logs for detailed error messages

## Security Considerations

* **Tokens**: Access and refresh tokens are stored securely in HashiCorp Vault with encryption at rest
* **Scopes**: Aurora requests `cloud-platform` scope for full GCP access - review carefully before granting
* **Service Accounts**: Aurora creates service accounts in your projects - audit them regularly
* **IAM Roles**: Review the roles granted to Aurora service accounts in your IAM policies
* **Org Policies**: Aurora may modify organization policies for Cloud Run - review changes in your org policy logs

## Token Management

* **Access Tokens**: Valid for \~1 hour, automatically refreshed using refresh tokens
* **Refresh Tokens**: Long-lived, stored securely, used to obtain new access tokens
* **Token Rotation**: Aurora automatically handles token refresh when access tokens expire
* **Cache Invalidation**: Redis cache is cleared after OAuth reconnect to ensure fresh credentials

## Required OAuth Scopes

```
https://www.googleapis.com/auth/cloud-platform
https://www.googleapis.com/auth/userinfo.email
openid
```

## Next Steps

After connecting GCP:

1. Aurora will automatically discover your infrastructure
2. View discovered resources in the Aurora dashboard
3. Use Aurora's AI agent to manage GCP resources
4. Deploy applications to GKE clusters or Cloud Run
5. Monitor costs and optimize resource usage