GCP Setup

This runbook explains how to set up all GCP resources for a new Orcha environment.

What Gets Created

The setup-gcp.sh script creates:

1. Document AI Processor - OCR processor for document text extraction
2. Workload Identity Federation - Allows AWS to authenticate to GCP without stored credentials
3. Gmail Pub/Sub - Topic, subscription, and push invoker service account for Gmail notifications

OAuth credentials must be created manually in the console:

• Gmail OAuth - For email acquisition (reading inbox)
• Google Auth OAuth - For Cognito user authentication (separate app)

When to Run

After deploying Phase 1 (FoundationStack + DataStack) and before deploying Phase 2 (ComputeStack).

Prerequisites

1. GCP project exists (e.g., getorcha-prod)
2. gcloud CLI authenticated: gcloud auth login
3. AWS account ID known
4. App domain known (e.g., app.getorcha.com)

Steps

1. Authenticate to GCP

gcloud auth login

2. Run the Setup Script

cd /home/volrath/code/orcha/orcha/infra
./scripts/setup-gcp.sh \
    --gcp-project getorcha-prod \
    --aws-account 700558745280 \
    --env prod \
    --app-domain app.getorcha.com

The script will:

• Enable required APIs
• Create Document AI OCR processor
• Set up Workload Identity Federation
• Create Gmail Pub/Sub resources
• Output SSM parameter values

3. Create Gmail OAuth Credentials (Manual)

1. Go to Google Cloud Console - Credentials

2. Configure OAuth Consent Screen (if not done):

   • User Type: External
   • App name: Orcha
   • Scopes: https://www.googleapis.com/auth/gmail.readonly

3. Create OAuth 2.0 Client ID:

   • Application type: Web application
   • Name: Orcha Prod
   • Authorized redirect URIs: https://app.getorcha.com/oauth/gmail/callback

4. Note the Client ID and Client Secret

3a. Create Google OAuth for User Authentication (Manual)

This creates a separate OAuth app for Cognito user authentication. This is distinct from the Gmail OAuth above which is for email acquisition.

1. Still in Google Cloud Console - Credentials

2. Create another OAuth 2.0 Client ID:

   • Application type: Web application
   • Name: Orcha Auth - {env} (e.g., "Orcha Auth - prod")
   • Authorized redirect URIs: https://{cognito-domain}.auth.eu-central-1.amazoncognito.com/oauth2/idpresponse

   The Cognito domain is output by CDK deployment (e.g., v1-orcha-prod-auth). Full URI example: https://v1-orcha-prod-auth.auth.eu-central-1.amazoncognito.com/oauth2/idpresponse

3. Note the Client ID and Client Secret - these go into different SSM params than Gmail:

   • /v1-orcha/cognito-google-client-id
   • /v1-orcha/cognito-google-client-secret

4. Update SSM Parameters

Add the script output to your secrets, filling in the OAuth values:

# Edit secrets with values from script output and OAuth console
vim secrets

# Update SSM
./scripts/update-secrets.sh --from-file secrets

5. Verify Setup

# Document AI processor
curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://eu-documentai.googleapis.com/v1/projects/getorcha-prod/locations/eu/processors" \
    | jq '.processors[].displayName'

# Workload Identity Pool
gcloud iam workload-identity-pools describe aws-prod \
    --location=global --project=getorcha-prod

# Gmail Pub/Sub
gcloud pubsub topics describe gmail-notifications --project=getorcha-prod
gcloud pubsub subscriptions describe gmail-push --project=getorcha-prod

Troubleshooting

"Permission denied" calling Document AI from AWS

Cause: Workload Identity Federation misconfigured or AWS role name mismatch.

Fix:

1. Verify AWS IAM role is named v1-orcha-service-role
2. Check the service account binding:

   gcloud iam service-accounts get-iam-policy \
       orcha-docai@getorcha-prod.iam.gserviceaccount.com
   

"User gmail-api-push@system.gserviceaccount.com is not in permitted organization"

Cause: Org policy exception not set or set at wrong level (must be at folder level, not project).

Fix: The script sets the iam.managed.allowedPolicyMembers policy at the folder level. Verify:

FOLDER_ID=$(gcloud projects describe getorcha-prod --format="value(parent.id)")
gcloud org-policies describe iam.managed.allowedPolicyMembers --folder=$FOLDER_ID

If missing, the script will create it automatically. The policy must be at the folder level because project-level policies don't override inherited org policies for this constraint.

Gmail push notifications not arriving

Cause: Pub/Sub subscription misconfigured or endpoint unreachable.

Fix:

1. Check subscription status:

   gcloud pubsub subscriptions describe gmail-push --project=getorcha-prod
   

2. Verify the push endpoint is reachable
3. Check the push invoker service account exists

OAuth redirect error

Cause: Redirect URI mismatch.

Fix: Ensure the OAuth client's authorized redirect URI exactly matches: https://<app-domain>/oauth/gmail/callback

Reference

Related

• cognito-setup.md - Configure Cognito IdPs with OAuth credentials
• update-secrets.md - SSM parameter updates
• PLAN.md - Implementation phases