GCP Provider

The GCP provider enables integration with Google Cloud Platform, providing role-based access control (RBAC) capabilities through Google Cloud IAM and Resource Manager.

Capabilities

Role-Based Access Control (RBAC): Supports GCP IAM roles and bindings
Project Management: Access to GCP projects and resources
Permission Management: Access to GCP IAM permissions and policies
Service Account Integration: Support for service account authentication

Prerequisites

GCP Project Setup

GCP Project: Active Google Cloud Platform project with appropriate permissions
IAM Permissions: The agent needs permissions to:
- Read IAM roles and bindings
- Access project and resource information
- List GCP service account details

Required GCP Permissions

The following GCP IAM permissions are required for the agent to function properly:

permissions:
  - iam.roles.list
  - iam.roles.get
  - resourcemanager.projects.get
  - resourcemanager.projects.getIamPolicy
  - iam.serviceAccounts.list
  - iam.serviceAccounts.get

Recommended Role: roles/viewer (includes all necessary read permissions)

Authentication Methods

The GCP provider supports multiple authentication methods:

1. Service Account Key File (Recommended)

Uses a service account key file for authentication:

providers:
  gcp-prod:
    name: GCP Production
    provider: gcp
    config:
      project_id: YOUR_PROJECT_ID
      service_account_key_path: /path/to/service-account-key.json

2. Service Account Key JSON (Inline)

Uses service account key JSON content directly in configuration:

providers:
  gcp-prod:
    name: GCP Production
    provider: gcp
    config:
      project_id: YOUR_PROJECT_ID
      service_account_key: |
        {
          "type": "service_account",
          "project_id": "YOUR_PROJECT_ID",
          "private_key_id": "YOUR_PRIVATE_KEY_ID",
          "private_key": "-----BEGIN PRIVATE KEY-----\nYOUR_PRIVATE_KEY\n-----END PRIVATE KEY-----\n",
          "client_email": "YOUR_SERVICE_ACCOUNT@YOUR_PROJECT_ID.iam.gserviceaccount.com",
          "client_id": "YOUR_CLIENT_ID",
          "auth_uri": "https://accounts.google.com/o/oauth2/auth",
          "token_uri": "https://oauth2.googleapis.com/token"
        }

3. Service Account Key (Structured)

Uses structured credentials object:

providers:
  gcp-prod:
    name: GCP Production
    provider: gcp
    config:
      project_id: YOUR_PROJECT_ID
      credentials:
        type: service_account
        project_id: YOUR_PROJECT_ID
        private_key_id: YOUR_PRIVATE_KEY_ID
        private_key: |
          -----BEGIN PRIVATE KEY-----
          YOUR_PRIVATE_KEY
          -----END PRIVATE KEY-----
        client_email: YOUR_SERVICE_ACCOUNT@YOUR_PROJECT_ID.iam.gserviceaccount.com
        client_id: YOUR_CLIENT_ID
        auth_uri: https://accounts.google.com/o/oauth2/auth
        token_uri: https://oauth2.googleapis.com/token

4. Default Credentials (ADC)

When no credentials are provided, uses Application Default Credentials (environment variables, metadata service, etc.):

providers:
  gcp-prod:
    name: GCP Production
    provider: gcp
    config:
      project_id: YOUR_PROJECT_ID

Configuration Options

Option	Type	Required	Default	Description
`project_id`	string	Yes	-	GCP project ID
`service_account_key_path`	string	No	-	Path to service account key file
`service_account_key`	string	No	-	Service account key JSON content
`credentials`	object	No	-	Structured service account credentials
`stage`	string	No	`GA`	GCP API stage (GA, BETA, ALPHA)
`region`	string	No	-	Default GCP region (informational)

Getting Credentials

Service Account Setup

Create Service Account: In GCP Console → IAM & Admin → Service Accounts → Create Service Account
Set Permissions: Grant the service account the Viewer role or custom role with required permissions
Create Key: In the service account details → Keys → Add Key → Create New Key
- Choose JSON format
- Download the key file
Configure Agent: Use the downloaded key file path or content in your configuration

gcloud CLI Setup

Install gcloud CLI: Follow the gcloud CLI installation guide
Initialize gcloud:
```
gcloud init
```
Set Application Default Credentials:
```
gcloud auth application-default login
```
Get Project ID:
```
gcloud config get-value project
```

Compute Engine/GKE Setup (Default Credentials)

Enable Default Service Account: Ensure your Compute Engine instance or GKE cluster has a service account attached
Grant Permissions: Grant the service account appropriate IAM permissions
No Configuration Needed: Agent will automatically use the metadata service

Example Configurations

Production Environment with Service Account Key File

version: "1.0"
providers:
  gcp-prod:
    name: GCP Production
    description: Production GCP environment
    provider: gcp
    enabled: true
    config:
      project_id: YOUR_PROD_PROJECT_ID
      service_account_key_path: /etc/agent/gcp-prod-key.json
      region: us-central1

Development Environment with Inline Key

version: "1.0"
providers:
  gcp-dev:
    name: GCP Development
    description: Development GCP environment
    provider: gcp
    enabled: true
    config:
      project_id: YOUR_DEV_PROJECT_ID
      service_account_key: |
        {
          "type": "service_account",
          "project_id": "YOUR_DEV_PROJECT_ID",
          "private_key_id": "YOUR_PRIVATE_KEY_ID",
          "private_key": "-----BEGIN PRIVATE KEY-----\nYOUR_PRIVATE_KEY\n-----END PRIVATE KEY-----\n",
          "client_email": "agent-dev@YOUR_DEV_PROJECT_ID.iam.gserviceaccount.com",
          "client_id": "YOUR_CLIENT_ID",
          "auth_uri": "https://accounts.google.com/o/oauth2/auth",
          "token_uri": "https://oauth2.googleapis.com/token"
        }

Multi-Project Setup

version: "1.0"
providers:
  gcp-prod:
    name: GCP Production
    description: Production project
    provider: gcp
    enabled: true
    config:
      project_id: YOUR_PROD_PROJECT_ID
      service_account_key_path: /etc/agent/prod-key.json
  
  gcp-staging:
    name: GCP Staging
    description: Staging project
    provider: gcp
    enabled: true
    config:
      project_id: YOUR_STAGING_PROJECT_ID
      service_account_key_path: /etc/agent/staging-key.json
  
  gcp-dev:
    name: GCP Development
    description: Development project
    provider: gcp
    enabled: true
    config:
      project_id: YOUR_DEV_PROJECT_ID
      # Uses Application Default Credentials

Using Default Credentials

version: "1.0"
providers:
  gcp-compute:
    name: GCP Compute
    description: GCP using default credentials
    provider: gcp
    enabled: true
    config:
      project_id: YOUR_PROJECT_ID
      region: us-central1

Features

GCP IAM Integration

The GCP provider automatically discovers and indexes GCP predefined and custom roles, making them available for role elevation requests.

API Stage Support

Support for different GCP API stages:

GA (Generally Available): Stable production APIs
BETA: Beta APIs with additional features
ALPHA: Alpha APIs with experimental features

Permission Indexing

The provider includes comprehensive GCP IAM permissions data, enabling:

Permission search and discovery
Role analysis and recommendations
Policy validation

Troubleshooting

Common Issues

Authentication Failures
- Verify service account key is valid and properly formatted
- Check project ID is correct and accessible
- Ensure service account has necessary permissions
Project Access Issues
- Verify the service account has access to the specified project
- Check if billing is enabled on the project
- Ensure required APIs are enabled (IAM, Resource Manager)
Permission Issues
- Verify service account has Viewer role or equivalent permissions
- Check if organization policies restrict access
- Ensure IAM API is enabled

Debugging

Enable debug logging to troubleshoot GCP provider issues:

logging:
  level: debug

Look for GCP-specific log entries to identify authentication and permission issues.

Environment Variables

The GCP provider also supports standard Google Cloud environment variables:

GOOGLE_APPLICATION_CREDENTIALS: Path to service account key file
GOOGLE_CLOUD_PROJECT: GCP project ID
GCLOUD_PROJECT: Alternative project ID variable

API Requirements

Ensure the following APIs are enabled in your GCP project:

Identity and Access Management (IAM) API
Cloud Resource Manager API