Google Cloud Platform Explained: Core Services, Real-World Architecture & When to Use GCP

#!/bin/bash
# -----------------------------------------------------------
# GCP PROJECT SETUP SCRIPT
# Run this once to initialise a new GCP project correctly.
# Requires: gcloud CLI authenticated via `gcloud auth login`
# -----------------------------------------------------------

# Define project configuration as variables — never hardcode these inline
PROJECT_ID="payments-service-prod"        # Must be globally unique across all GCP
BILLING_ACCOUNT_ID="012345-ABCDEF-789GHI" # Found in GCP Console > Billing
PRIMARY_REGION="us-central1"              # Closest region to your main user base
PRIMARY_ZONE="us-central1-a"             # Default zone within that region

# Step 1: Create the project
# --set-as-default means subsequent gcloud commands target this project automatically
gcloud projects create "${PROJECT_ID}" \
  --name="Payments Service Production" \
  --set-as-default

echo "Project '${PROJECT_ID}' created."

# Step 2: Link a billing account — without this, most services won't activate
gcloud billing projects link "${PROJECT_ID}" \
  --billing-account="${BILLING_ACCOUNT_ID}"

echo "Billing account linked."

# Step 3: Set the default region and zone so you don't have to repeat --region/--zone
# on every command. This saves you from accidentally deploying to the wrong region.
gcloud config set compute/region "${PRIMARY_REGION}"
gcloud config set compute/zone "${PRIMARY_ZONE}"

echo "Default region set to ${PRIMARY_REGION}, zone to ${PRIMARY_ZONE}."

# Step 4: Enable only the APIs your project actually needs.
# GCP disables most APIs by default — this is a security feature, not a bug.
# Enabling unused APIs increases your attack surface for nothing.
gcloud services enable \
  compute.googleapis.com \
  container.googleapis.com \
  cloudsql.googleapis.com \
  storage.googleapis.com

echo "Core APIs enabled."
echo "Project initialisation complete. Run 'gcloud config list' to verify."

# -----------------------------------------------------------
# CLOUD RUN SERVICE DEFINITION
# Deploys a containerised payments API to Cloud Run.
# Cloud Run auto-scales to zero when idle — you pay nothing
# when your service isn't handling requests.
# Deploy with: gcloud run services replace cloud_run_service.yaml
# -----------------------------------------------------------
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: payments-api
  namespace: "123456789"  # Your GCP Project Number (not Project ID)
  annotations:
    # Force all traffic through HTTPS — never allow plain HTTP in production
    run.googleapis.com/ingress: all
spec:
  template:
    metadata:
      annotations:
        # Scale down to zero instances when there are no requests
        # This is what makes Cloud Run cost-effective for variable traffic
        autoscaling.knative.dev/minScale: "0"
        # Cap at 10 instances to prevent runaway costs during a traffic spike
        autoscaling.knative.dev/maxScale: "10"
        # Each instance handles max 80 concurrent requests before a new one spins up
        run.googleapis.com/execution-environment: gen2
    spec:
      # How long Cloud Run waits for a response before treating it as a timeout
      timeoutSeconds: 30
      # CPU and memory are per-instance limits
      containers:
        - image: gcr.io/payments-service-prod/payments-api:v2.1.0
          ports:
            - containerPort: 8080  # Cloud Run always routes traffic to port 8080
          resources:
            limits:
              cpu: "1"        # 1 vCPU per instance
              memory: "512Mi" # 512MB RAM — right-size this based on profiling
          env:
            # Never hardcode secrets. Reference Secret Manager instead.
            - name: DB_PASSWORD
              valueFrom:
                secretKeyRef:
                  key: latest
                  name: payments-db-password  # Name of secret in Secret Manager
  traffic:
    # 100% of traffic goes to the latest revision
    # You can split traffic here for canary deployments (e.g., 90/10)
    - latestRevision: true
      percent: 100

# -----------------------------------------------------------
# GCS OBJECT UPLOAD + SIGNED URL GENERATION
# Real-world pattern: a user uploads a profile photo.
# We store it privately in GCS, then generate a short-lived
# signed URL so the frontend can display it without making
# the bucket publicly readable (a major security mistake).
#
# Install dependencies: pip install google-cloud-storage
# Auth: set GOOGLE_APPLICATION_CREDENTIALS env var to your
#       service account key JSON path, or use Workload Identity.
# -----------------------------------------------------------

import datetime
from pathlib import Path
from google.cloud import storage

GCP_PROJECT_ID = "payments-service-prod"
PRIVATE_BUCKET_NAME = "user-profile-photos-prod"  # This bucket is NOT public
SIGNED_URL_EXPIRY_MINUTES = 15  # Short expiry — limits blast radius if URL leaks


def upload_user_profile_photo(
    user_id: str,
    local_file_path: Path,
    content_type: str = "image/jpeg",
) -> str:
    """
    Uploads a profile photo to GCS and returns a signed URL
    the frontend can use to display it for the next 15 minutes.

    Returns the signed URL string.
    """
    storage_client = storage.Client(project=GCP_PROJECT_ID)
    bucket = storage_client.bucket(PRIVATE_BUCKET_NAME)

    # Build a deterministic object path — makes it easy to find later
    # and naturally organises objects by user without needing folders
    object_name = f"users/{user_id}/profile/avatar.jpg"

    blob = bucket.blob(object_name)

    # Set content type so browsers render it correctly, not download it
    blob.content_type = content_type

    # Upload the file — this overwrites any existing photo for this user
    blob.upload_from_filename(str(local_file_path))
    print(f"Uploaded '{local_file_path}' to gs://{PRIVATE_BUCKET_NAME}/{object_name}")

    # Generate a V4 signed URL — time-limited, cryptographically signed
    # by our service account. The bucket stays private; only holders of
    # this URL can access the object, and only until it expires.
    signed_url = blob.generate_signed_url(
        version="v4",
        expiration=datetime.timedelta(minutes=SIGNED_URL_EXPIRY_MINUTES),
        method="GET",  # Read-only access
    )

    print(f"Signed URL (valid {SIGNED_URL_EXPIRY_MINUTES} mins): {signed_url[:80]}...")
    return signed_url


if __name__ == "__main__":
    # Simulate uploading a photo for user ID 'usr_8821'
    sample_photo_path = Path("/tmp/avatar_upload.jpg")

    # In production this file comes from a multipart form upload
    sample_photo_path.write_bytes(b"<fake-jpeg-bytes-for-demo>")

    url = upload_user_profile_photo(
        user_id="usr_8821",
        local_file_path=sample_photo_path,
    )
    print(f"\nFrontend should use this URL to render the avatar: {url[:60]}...")

#!/bin/bash
# -----------------------------------------------------------
# GCP IAM LEAST-PRIVILEGE SETUP
# Creates a service account for a Cloud Run payments service
# with ONLY the permissions it actually needs:
#   - Read secrets from Secret Manager
#   - Write to a specific Cloud Storage bucket
#   - Publish to a specific Pub/Sub topic
# Nothing else. This limits blast radius if the service is compromised.
# -----------------------------------------------------------

PROJECT_ID="payments-service-prod"
SERVICE_NAME="payments-api"

# Step 1: Create a dedicated service account for this service
# One service account per service — never share service accounts
SERVICE_ACCOUNT_EMAIL="${SERVICE_NAME}@${PROJECT_ID}.iam.gserviceaccount.com"

gcloud iam service-accounts create "${SERVICE_NAME}" \
  --project="${PROJECT_ID}" \
  --display-name="Payments API Service Account" \
  --description="Identity for the payments-api Cloud Run service. Least-privilege access only."

echo "Service account created: ${SERVICE_ACCOUNT_EMAIL}"

# Step 2: Grant permission to read secrets from Secret Manager
# This is scoped to the PROJECT level — ideally scope it to individual secrets
# using resource-level IAM for even finer control
gcloud projects add-iam-policy-binding "${PROJECT_ID}" \
  --member="serviceAccount:${SERVICE_ACCOUNT_EMAIL}" \
  --role="roles/secretmanager.secretAccessor"

echo "Secret Manager access granted."

# Step 3: Grant permission to write objects to a specific bucket ONLY
# Note: roles/storage.objectCreator is narrower than roles/storage.objectAdmin
# objectCreator can write new objects but cannot delete or overwrite existing ones
TARGET_BUCKET="gs://payments-receipts-prod"

gcloud storage buckets add-iam-policy-binding "${TARGET_BUCKET}" \
  --member="serviceAccount:${SERVICE_ACCOUNT_EMAIL}" \
  --role="roles/storage.objectCreator"

echo "Storage write access granted to ${TARGET_BUCKET} only."

# Step 4: Grant Pub/Sub publish permission on one specific topic
TARGET_TOPIC="projects/${PROJECT_ID}/topics/payment-completed-events"

gcloud pubsub topics add-iam-policy-binding "payment-completed-events" \
  --project="${PROJECT_ID}" \
  --member="serviceAccount:${SERVICE_ACCOUNT_EMAIL}" \
  --role="roles/pubsub.publisher"

echo "Pub/Sub publish access granted to payment-completed-events topic."

# Step 5: Attach this service account to the Cloud Run service
# The service now authenticates as this SA automatically — no key files needed
gcloud run services update "${SERVICE_NAME}" \
  --project="${PROJECT_ID}" \
  --region="us-central1" \
  --service-account="${SERVICE_ACCOUNT_EMAIL}"

echo "Service account attached to Cloud Run service."
echo "IAM setup complete. This service account has NO other GCP permissions."