A Cloud Function can't access Cloud Storage. Debug the IAM permission denied error.

Step 1: Identify Which Service Account the Function Uses

# Check the Cloud Function's service account
gcloud functions describe my-function \
  --region=us-central1 \
  --format="value(serviceAccountEmail)"

# Output might show:
# my-project@appspot.gserviceaccount.com  (App Engine default)
# 123456789-compute@developer.gserviceaccount.com  (Compute default)
# my-function@my-project.iam.gserviceaccount.com  (Custom SA)

# Common mistake: You granted permissions to the wrong service account!

Step 2: Check Current IAM Permissions

# Check bucket-level permissions
gcloud storage buckets get-iam-policy gs://my-bucket

# Check if the service account has the expected role
gcloud projects get-iam-policy my-project \
  --flatten="bindings[].members" \
  --filter="bindings.members:my-function@my-project.iam.gserviceaccount.com" \
  --format="table(bindings.role)"

# Test the service account's access directly
gcloud auth activate-service-account \
  --key-file=service-account-key.json

gcloud storage ls gs://my-bucket/

Step 3: Understand IAM Scope

# Project-level role (applies to ALL buckets in project)
gcloud projects add-iam-policy-binding my-project \
  --member="serviceAccount:my-function@my-project.iam.gserviceaccount.com" \
  --role="roles/storage.objectViewer"

# Bucket-level role (applies to specific bucket only - preferred!)
gcloud storage buckets add-iam-policy-binding gs://my-bucket \
  --member="serviceAccount:my-function@my-project.iam.gserviceaccount.com" \
  --role="roles/storage.objectViewer"

# Object-level (IAM conditions for specific prefixes)
gcloud storage buckets add-iam-policy-binding gs://my-bucket \
  --member="serviceAccount:my-function@my-project.iam.gserviceaccount.com" \
  --role="roles/storage.objectViewer" \
  --condition="expression=resource.name.startsWith('projects/_/buckets/my-bucket/objects/allowed-prefix/'),title=AllowedPrefixOnly"

Step 4: Create Dedicated Service Account

# Create a dedicated service account (best practice)
gcloud iam service-accounts create cloud-function-storage \
  --display-name="Cloud Function Storage Access" \
  --description="Service account for Cloud Function to access specific GCS bucket"

# Grant minimal permissions at bucket level
gcloud storage buckets add-iam-policy-binding gs://my-bucket \
  --member="serviceAccount:cloud-function-storage@my-project.iam.gserviceaccount.com" \
  --role="roles/storage.objectViewer"

# Deploy function with the dedicated service account
gcloud functions deploy my-function \
  --region=us-central1 \
  --runtime=nodejs18 \
  --service-account=cloud-function-storage@my-project.iam.gserviceaccount.com \
  --source=.

Step 5: Check for Blocking Policies

# Check VPC Service Controls (common in enterprise)
gcloud access-context-manager perimeters list

# Check Organization Policy constraints
gcloud resource-manager org-policies list --project=my-project

# Check IAM deny policies
gcloud iam policies list --attachment-point=projects/my-project

# If VPC-SC is blocking, you need to add the function to the perimeter
# or configure ingress/egress rules

Step 6: Verify with IAM Policy Troubleshooter

# Use Policy Troubleshooter to test permissions
gcloud policy-troubleshoot iam \
  //storage.googleapis.com/projects/_/buckets/my-bucket/objects/test.txt \
  --principal-email=my-function@my-project.iam.gserviceaccount.com \
  --permission=storage.objects.get

Terraform Implementation

# Create dedicated service account
resource "google_service_account" "function_sa" {
  account_id   = "cloud-function-storage"
  display_name = "Cloud Function Storage Access"
  description  = "Dedicated SA for Cloud Function GCS access"
}

# Grant bucket-level access only
resource "google_storage_bucket_iam_member" "function_access" {
  bucket = google_storage_bucket.data.name
  role   = "roles/storage.objectViewer"
  member = "serviceAccount:${google_service_account.function_sa.email}"
}

# Deploy function with dedicated SA
resource "google_cloudfunctions_function" "my_function" {
  name        = "my-function"
  runtime     = "nodejs18"
  region      = "us-central1"

  service_account_email = google_service_account.function_sa.email

  # Other config...
}

Common IAM Gotchas

Service Account Best Practices

# 1. One service account per function/service
# 2. Use bucket-level, not project-level permissions
# 3. Enable audit logging for service accounts

gcloud projects add-iam-policy-binding my-project \
  --member="serviceAccount:cloud-function-storage@my-project.iam.gserviceaccount.com" \
  --role="roles/storage.objectViewer" \
  --condition=None

# 4. Set up alerts for service account usage
# 5. Rotate keys regularly (or use Workload Identity)