From 8a0911eed56482d582c7169d924594a55e4d287f Mon Sep 17 00:00:00 2001 From: bartrtl Date: Sat, 15 Nov 2025 08:35:24 -0500 Subject: [PATCH] Add GCP IAM permissions documentation for Cloud Run deployment MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Document all required IAM roles for Cloud Build and Compute Engine service accounts - Add step-by-step permission configuration in DEPLOYMENT.md - Include permission table explaining why each role is needed - Enable artifactregistry.googleapis.com API in deployment steps This resolves permission issues encountered during automated Cloud Build deployment to Cloud Run, including storage access, artifact registry uploads, and service account impersonation requirements. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .env.example | 1 - DEPLOYMENT.md | 67 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 67 insertions(+), 1 deletion(-) diff --git a/.env.example b/.env.example index a260636..c5890de 100644 --- a/.env.example +++ b/.env.example @@ -2,7 +2,6 @@ # REQUIRED - Application won't work without these # ======================================== -# OpenAI API Key # Get from: https://platform.openai.com/api-keys # Must be from the same organization/project as your Agent Builder workflow OPENAI_API_KEY= diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md index a3afba4..868a4ef 100644 --- a/DEPLOYMENT.md +++ b/DEPLOYMENT.md @@ -559,9 +559,76 @@ gcloud services enable \ run.googleapis.com \ cloudbuild.googleapis.com \ containerregistry.googleapis.com \ + artifactregistry.googleapis.com \ secretmanager.googleapis.com ``` +### Step 2.5: Configure Required IAM Permissions + +**IMPORTANT**: When using Cloud Build to deploy to Cloud Run, you need to grant specific IAM permissions to the service accounts. Run these commands after creating your project: + +```bash +# Set your project ID +export PROJECT_ID=YOUR_PROJECT_ID +export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)') + +# Grant permissions to Cloud Build service account +gcloud projects add-iam-policy-binding $PROJECT_ID \ + --member="serviceAccount:${PROJECT_NUMBER}@cloudbuild.gserviceaccount.com" \ + --role="roles/storage.admin" + +gcloud projects add-iam-policy-binding $PROJECT_ID \ + --member="serviceAccount:${PROJECT_NUMBER}@cloudbuild.gserviceaccount.com" \ + --role="roles/artifactregistry.writer" + +gcloud projects add-iam-policy-binding $PROJECT_ID \ + --member="serviceAccount:${PROJECT_NUMBER}@cloudbuild.gserviceaccount.com" \ + --role="roles/run.admin" + +# Grant permissions to Compute Engine default service account +gcloud projects add-iam-policy-binding $PROJECT_ID \ + --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \ + --role="roles/storage.admin" + +gcloud projects add-iam-policy-binding $PROJECT_ID \ + --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \ + --role="roles/artifactregistry.writer" + +gcloud projects add-iam-policy-binding $PROJECT_ID \ + --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \ + --role="roles/run.admin" + +gcloud projects add-iam-policy-binding $PROJECT_ID \ + --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \ + --role="roles/logging.logWriter" + +# Allow Cloud Build to act as the compute service account +gcloud iam service-accounts add-iam-policy-binding \ + ${PROJECT_NUMBER}-compute@developer.gserviceaccount.com \ + --member="serviceAccount:${PROJECT_NUMBER}@cloudbuild.gserviceaccount.com" \ + --role="roles/iam.serviceAccountUser" \ + --project=$PROJECT_ID + +# Allow compute service account to act as itself (required for Cloud Run deployment) +gcloud iam service-accounts add-iam-policy-binding \ + ${PROJECT_NUMBER}-compute@developer.gserviceaccount.com \ + --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \ + --role="roles/iam.serviceAccountUser" \ + --project=$PROJECT_ID +``` + +**Why these permissions are needed:** + +| Role | Service Account | Purpose | +|------|----------------|---------| +| `storage.admin` | Cloud Build, Compute Engine | Upload source code and artifacts to Cloud Storage | +| `artifactregistry.writer` | Cloud Build, Compute Engine | Push Docker images to Artifact Registry | +| `run.admin` | Cloud Build, Compute Engine | Deploy and manage Cloud Run services | +| `logging.logWriter` | Compute Engine | Write build and deployment logs to Cloud Logging | +| `iam.serviceAccountUser` | Cloud Build → Compute, Compute → itself | Allow service accounts to impersonate/act as other accounts during deployment | + +**Note**: These are the minimum required permissions for automated Cloud Build deployment. If you encounter permission errors during deployment, check that all these roles are properly assigned. + ### Step 3: Set Up Environment Variables All configuration is now managed through `.env.local`. Configure your deployment variables: