Google Cloud Platform

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:

Ensure GCP provider is added: monk cluster provider add -p gcp
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

Ensure GCP provider is added:

monk cluster provider add -p gcp

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

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

Create/update:

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:

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

# 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

# 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

# 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:

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)

​What is this integration?

​What Monk manages

​What the Agent can do and how to use it

​Required IAM Permissions

​Quick start (broad roles)

​Least-privilege roles

​Auth

​Getting Started

​S3-Compatible Cloud Storage Access (HMAC)

​Cloud SQL Backup & Restore Actions

​Firestore Backup & Restore Actions

​BigQuery Backup & Restore Actions

​Restore Behavior Summary