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.
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 resourcesroles/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 |
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
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"
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"
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) |
