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

# Google Cloud Platform

> Managed cloud databases and storage (Cloud SQL, Firestore, BigQuery, Cloud Storage, Memorystore).

## What is this integration?

Google Cloud Platform (GCP) provides fully managed cloud services including relational databases (Cloud SQL), NoSQL document databases (Firestore), and serverless data warehouses (BigQuery).

## What Monk manages

* Cloud SQL instances, databases, and users
* Firestore databases with PITR and backup support
* BigQuery datasets and table snapshots
* Memorystore for Redis instances with export/import support
* Cloud Storage buckets
* Cloud Storage HMAC keys for S3-compatible access
* Service accounts and IAM bindings
* API enablement via Service Usage

## What the Agent can do and how to use it

* **Database Creation**: Provision Cloud SQL, Firestore, BigQuery, and Memorystore for Redis
* **Backup & Recovery**: Automated backups, on-demand snapshots, export/import, and restore operations
* **Scaling**: Modify instance tiers, storage, and enable high availability
* **Security**: Configure authorized networks, SSL, and IAM permissions
* **Monitoring**: Access instance status and connection information

Steps:

1. Ensure GCP provider is added: `monk cluster provider add -p gcp`
2. monk update \<namespace>/\<name>

## Required IAM Permissions

The principal whose credentials are configured via `monk cluster provider add -p gcp` (a service account or user) needs IAM roles on the target project covering the entities you intend to manage.

### Quick start (broad roles)

Grants enough permission to manage every entity in this package:

* `roles/editor` — create/update/delete most resources
* `roles/resourcemanager.projectIamAdmin` — required because `roles/editor` cannot modify IAM (used by `gcp/service-account`, `gcp/project-iam-binding`, `gcp/resource-iam-binding`)
* `roles/serviceusage.serviceUsageAdmin` — enable APIs via `gcp/service-usage`

### Least-privilege roles

Grant only the roles for the entities your stack uses:

| Entity area                                                                          | Role                                                                |
| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------- |
| API enablement (`gcp/service-usage`)                                                 | `roles/serviceusage.serviceUsageAdmin`                              |
| Cloud SQL (`cloud-sql-instance`, `cloud-sql-database`, `cloud-sql-user`)             | `roles/cloudsql.admin`                                              |
| Firestore (`firestore-database`)                                                     | `roles/datastore.owner`                                             |
| BigQuery (`bigquery-dataset`)                                                        | `roles/bigquery.admin`                                              |
| Memorystore Redis (`memorystore-redis`)                                              | `roles/redis.admin`                                                 |
| Cloud Storage (`cloud-storage`, `cloud-storage-hmac-keys`)                           | `roles/storage.admin`                                               |
| Pub/Sub (`pubsub-topic`, `pubsub-subscription`)                                      | `roles/pubsub.admin`                                                |
| Cloud Run (`cloud-run-service`, `cloud-run-job`)                                     | `roles/run.admin`                                                   |
| Cloud DNS (`cloud-dns-zone`, `cloud-dns-record-set`)                                 | `roles/dns.admin`                                                   |
| Artifact Registry (`artifact-registry-repository`)                                   | `roles/artifactregistry.admin`                                      |
| Cloud CDN / load balancing (`cloud-cdn-backend-bucket`, `cloud-cdn-backend-service`) | `roles/compute.loadBalancerAdmin`                                   |
| Cloud Tasks (`cloud-tasks-queue`)                                                    | `roles/cloudtasks.admin`                                            |
| Cloud Armor (`cloud-armor-security-policy`)                                          | `roles/compute.securityAdmin`                                       |
| Service accounts (`gcp/service-account`, `service-account-key`)                      | `roles/iam.serviceAccountAdmin`, `roles/iam.serviceAccountKeyAdmin` |
| Project IAM bindings (`project-iam-binding`, `resource-iam-binding`)                 | `roles/resourcemanager.projectIamAdmin`                             |
| IAP (`iap-settings`, `iap-access-policy`, `iap-oauth-client`)                        | `roles/iap.admin`                                                   |
| Identity Platform (`identity-platform-*`)                                            | `roles/identityplatform.admin`                                      |
| Cost estimation (`get-cost-estimate`, `costs` actions)                               | `roles/monitoring.viewer`                                           |

For per-entity permission lists at the API-method level, see `src/gcp/README.md`.

## Auth

* Uses GCP provider credentials configured via `monk cluster provider add -p gcp`
* GCP credentials are automatically injected into the GCP client

## Getting Started

1. Ensure GCP provider is added:

```bash theme={null}
monk cluster provider add -p gcp
```

2. Define a Cloud SQL instance (save as gcp-stack.yaml):

```yaml theme={null}
namespace: my-app

enable-apis:
  defines: gcp/service-usage
  apis:
    - sqladmin.googleapis.com

my-postgres:
  defines: gcp/cloud-sql-instance
  name: my-app-db
  database_version: POSTGRES_14
  tier: db-f1-micro
  region: us-central1
  backup_start_time: "03:00"              # Enable automated backups
  point_in_time_recovery_enabled: true    # Enable PITR
  depends:
    wait-for:
      runnables:
        - my-app/enable-apis
      timeout: 300
```

3. Create/update:

```bash theme={null}
monk load gcp-stack.yaml
monk update my-app/my-postgres
monk describe my-app/my-postgres
```

***

## S3-Compatible Cloud Storage Access (HMAC)

Create HMAC keys to access Cloud Storage using S3-compatible clients.
Make sure `storage.googleapis.com` is enabled via `gcp/service-usage`, and
use a service account from `gcp/service-account`:

```yaml theme={null}
storage-hmac-keys:
  defines: gcp/cloud-storage-hmac-keys
  service_account_email: <- connection-target("sa") entity-state get-member("email")
  access_key_secret_ref: gcs-hmac-access-key
  secret_key_secret_ref: gcs-hmac-secret-key
  permitted-secrets:
    gcs-hmac-access-key: true
    gcs-hmac-secret-key: true
  connections:
    sa:
      runnable: gcp/service-account/my-sa
      service: service-account
```

Use `https://storage.googleapis.com` as the S3 endpoint and the secrets
`gcs-hmac-access-key` / `gcs-hmac-secret-key` as credentials.

***

## Cloud SQL Backup & Restore Actions

| Action               | Description                                      |
| -------------------- | ------------------------------------------------ |
| `get-backup-info`    | View backup configuration and PITR status        |
| `create-backup`      | Create an on-demand backup                       |
| `list-backups`       | List available backups (automated and on-demand) |
| `describe-backup`    | Get detailed information about a specific backup |
| `delete-backup`      | Delete a backup                                  |
| `restore`            | Restore from backup (overwrites instance)        |
| `get-restore-status` | Check status of restore operation                |

```bash theme={null}
# View backup configuration
monk do my-app/my-postgres/get-backup-info

# Create a backup before maintenance
monk do my-app/my-postgres/create-backup description="Pre-upgrade backup"

# List available backups
monk do my-app/my-postgres/list-backups

# Restore from backup (WARNING: overwrites instance!)
monk do my-app/my-postgres/restore backup_id="1765968494026"

# Check restore progress
monk do my-app/my-postgres/get-restore-status operation_name="operations/abc123"
```

***

## Firestore Backup & Restore Actions

| Action               | Description                           |
| -------------------- | ------------------------------------- |
| `get-backup-info`    | View PITR status and configuration    |
| `export-documents`   | Export database to Cloud Storage      |
| `import-documents`   | Import from Cloud Storage export      |
| `list-backups`       | List scheduled backups in a location  |
| `describe-backup`    | Get backup details                    |
| `delete-backup`      | Delete a scheduled backup             |
| `restore`            | Restore to a new database from backup |
| `get-restore-status` | Check restore operation progress      |

```bash theme={null}
# View backup configuration
monk do my-app/my-firestore/get-backup-info

# Export database to Cloud Storage
monk do my-app/my-firestore/export-documents output_uri_prefix="gs://my-bucket/backup"

# Import from Cloud Storage
monk do my-app/my-firestore/import-documents input_uri_prefix="gs://my-bucket/backup"

# List scheduled backups
monk do my-app/my-firestore/list-backups location="us-central1"

# Restore to a new database
monk do my-app/my-firestore/restore backup_name="projects/.../backups/..." target_database="restored-db"
```

**Note:** Firestore PITR enables reading historical document versions (7 days), not database-level restore. Use `export-documents` for full database backups.

***

## BigQuery Backup & Restore Actions

| Action              | Description                                 |
| ------------------- | ------------------------------------------- |
| `get-backup-info`   | View time travel settings and storage model |
| `create-snapshot`   | Create a table snapshot                     |
| `list-snapshots`    | List tables/snapshots in dataset            |
| `describe-snapshot` | Get table/snapshot details                  |
| `delete-snapshot`   | Delete a snapshot table                     |
| `restore`           | Create new table from snapshot              |

```bash theme={null}
# View backup configuration
monk do my-app/my-dataset/get-backup-info

# Create a snapshot of a table
monk do my-app/my-dataset/create-snapshot source_table="events"

# Create snapshot at a specific point in time (time travel)
monk do my-app/my-dataset/create-snapshot source_table="events" snapshot_time="2024-12-16T10:00:00Z"

# List all tables/snapshots
monk do my-app/my-dataset/list-snapshots

# Restore by creating a new table from snapshot
monk do my-app/my-dataset/restore snapshot_table="events_backup" target_table="events_restored"
```

**Time Travel:** BigQuery provides built-in time travel (2-7 days) for querying historical data without creating snapshots:

```sql theme={null}
SELECT * FROM `project.dataset.table`
FOR SYSTEM_TIME AS OF TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 DAY)
```

***

## Restore Behavior Summary

| Database  | Restore Target | Warning                             |
| --------- | -------------- | ----------------------------------- |
| Cloud SQL | Same instance  | ⚠️ **OVERWRITES** existing instance |
| Firestore | New database   | ✅ Safe - creates new database       |
| BigQuery  | New table      | ✅ Safe - creates new table (clone)  |