Google Cloud Storage

Google Cloud Storage offers global object storage with strong consistency and integration with other GCP services.

Prerequisites

1. GCP Project with Storage API enabled
2. Service Account with Storage permissions
3. Storage Bucket created in your preferred region
4. Pub/Sub Topic and Subscription for event notifications

Service Account Permissions

Create a service account with these roles:

• Storage Admin (or custom role with storage.objects.*)
• Pub/Sub Editor (for event notifications)

Configuration

GCP Credentials

Safebucket uses Application Default Credentials (ADC). You can authenticate using any supported method:

• GOOGLE_APPLICATION_CREDENTIALS environment variable pointing to a service account key file
• User credentials via gcloud auth application-default login
• Attached service account (GKE, Cloud Run, Compute Engine)

See the ADC documentation for all supported methods.

Environment Variables

# Storage configuration
STORAGE__TYPE=gcp
STORAGE__GCP__BUCKET_NAME=safebucket-gcp
STORAGE__GCP__PROJECT_ID=your-project-id
STORAGE__GCP__TOPIC_NAME=safebucket-bucket-events
STORAGE__GCP__SUBSCRIPTION_NAME=safebucket-bucket-events-sub

# GCP credentials (or use any ADC method above)
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

# Events configuration
EVENTS__TYPE=gcp
EVENTS__GCP__PROJECT_ID=your-project-id
EVENTS__GCP__TOPIC_NAME=safebucket-notifications
EVENTS__GCP__SUBSCRIPTION_NAME=safebucket-notifications-sub

YAML Configuration

storage:
  type: gcp
  gcp:
    bucket_name: safebucket-gcp
    project_id: your-project-id
    topic_name: safebucket-bucket-events
    subscription_name: safebucket-bucket-events-sub

events:
  type: gcp
  gcp:
    project_id: your-project-id
    topic_name: safebucket-notifications
    subscription_name: safebucket-notifications-sub

CORS

[
  {
    "origin": ["http://localhost:3000"],
    "method": ["GET", "HEAD", "PUT", "DELETE"],
    "responseHeader": [
      "Content-Type",
      "x-goog-content-length-range",
      "x-goog-meta-bucket-id",
      "x-goog-meta-file-id",
      "x-goog-meta-user-id",
      "x-goog-meta-share-id",
      "ETag"
    ],
    "maxAgeSeconds": 3600
  }
]

Apply it to the bucket:

gcloud storage buckets update gs://safebucket-gcp --cors-file=cors.json

# Verify
gcloud storage buckets describe gs://safebucket-gcp --format="default(cors_config)"

Replace origin with your actual app URL(s).

note

Unlike S3, responseHeader does not accept a * wildcard, so every custom header the browser sends must be listed explicitly. The x-goog-meta-* entries carry upload metadata and x-goog-content-length-range enforces the upload size; both are sent by the browser and must be allowed.

GCS Event Notifications Setup

1. Create Pub/Sub Topic and Subscription:

   # Create topic
   gcloud pubsub topics create safebucket-bucket-events
   
   # Create subscription
   gcloud pubsub subscriptions create safebucket-bucket-events-sub \
     --topic=safebucket-bucket-events

2. Configure Bucket Notifications:

   gsutil notification create -t safebucket-bucket-events \
     -f json gs://safebucket-gcp

3. Create Service Account and Download Key:

   # Create service account
   gcloud iam service-accounts create safebucket-storage
   
   # Add roles
   gcloud projects add-iam-policy-binding your-project-id \
     --member="serviceAccount:[email protected]" \
     --role="roles/storage.admin"
   
   # Download key
   gcloud iam service-accounts keys create gcs-key.json \
     --iam-account=safebucket-storage@your-project-id.iam.gserviceaccount.com