Skip to main content

GCP Setup and Permissions Guide for Orchestr8

Prerequisites​

CLI Tool Requirements​

Before deploying to GCP, ensure you have the required command-line tools. See the Prerequisites Guide for complete installation instructions for all tools.

Required for GCP:

  • Core tools: kubectl, helm, git (required for all providers)
  • GCP-specific: gcloud CLI for authentication and management
  • Optional: terraform (required for --provision-infrastructure flag)

Quick Verification:

# Verify all required tools are installed
o8 doctor --verbose

# Show installation instructions for missing tools  
o8 doctor --fix

Required GCP APIs​

The following Google Cloud APIs must be enabled on your project:

  • Service Usage API (serviceusage.googleapis.com) - Enable this first!
  • Cloud Resource Manager API (cloudresourcemanager.googleapis.com)
  • Compute Engine API (compute.googleapis.com)
  • Kubernetes Engine API (container.googleapis.com)
  • Identity and Access Management API (iam.googleapis.com)
  • Secret Manager API (secretmanager.googleapis.com)

Required IAM Permissions​

Your Google Cloud account needs one of the following roles on the project:

  • Owner (roles/owner) - Recommended for initial setup
  • Editor (roles/editor) plus:
    • Service Usage Admin (roles/serviceusage.serviceUsageAdmin)
    • Kubernetes Engine Admin (roles/container.admin)
    • Compute Admin (roles/compute.admin)
    • Service Account Admin (roles/iam.serviceAccountAdmin)
    • Secret Manager Admin (roles/secretmanager.admin)

Authentication Setup​

Step 1: Install Google Cloud SDK​

# Windows (using Chocolatey)
choco install gcloudsdk

# Or download from: https://cloud.google.com/sdk/docs/install

Step 2: Authenticate with gcloud​

# Login to your Google account
gcloud auth login

# Set your project
gcloud config set project YOUR_PROJECT_ID

Step 3: Set up Application Default Credentials (Required for Terraform)​

# This is CRITICAL for Terraform to work!
gcloud auth application-default login

# This creates credentials at:
# Windows: %APPDATA%\gcloud\application_default_credentials.json
# Linux/Mac: ~/.config/gcloud/application_default_credentials.json

Step 4: Enable Required APIs​

# Enable Service Usage API first (required to enable other APIs)
gcloud services enable serviceusage.googleapis.com

# Then enable all other required APIs
gcloud services enable \
    cloudresourcemanager.googleapis.com \
    compute.googleapis.com \
    container.googleapis.com \
    iam.googleapis.com \
    secretmanager.googleapis.com

Provisioning Infrastructure with O8​

Once authentication and APIs are set up:

# Install O8
uv tool install orchestr8-platform

# Provision GCP infrastructure and deploy platform
o8 setup \
    --provider gcp \
    --provision-infrastructure \
    --gcp-project-id YOUR_PROJECT_ID \
    --domain your-domain.com \
    --github-org your-github-org \
    --cluster cluster-name \
    --region us-central1 \
    --environment dev

Troubleshooting​

Error: "Permission denied to list services for consumer container"​

This error occurs when Terraform doesn't have proper authentication. Solution:

# Ensure Application Default Credentials are set
gcloud auth application-default login

# If you have a service account key set in GOOGLE_APPLICATION_CREDENTIALS, unset it:
# Windows PowerShell:
[Environment]::SetEnvironmentVariable('GOOGLE_APPLICATION_CREDENTIALS', '', 'User')
[Environment]::SetEnvironmentVariable('GOOGLE_APPLICATION_CREDENTIALS', '', 'Process')
# Linux/Mac:
unset GOOGLE_APPLICATION_CREDENTIALS

Error: "Required 'compute.networks.create' permission"​

If you encounter permission errors even with owner role:

  1. Ensure you're using Application Default Credentials (not service account key)

  2. Try refreshing your credentials:

    gcloud auth application-default login --force

  3. As a workaround, comment out the API enablement in terraform/bootstrap/main.tf

Error: "APIs not enabled"​

Enable the required APIs manually:

gcloud services enable serviceusage.googleapis.com
gcloud services enable cloudresourcemanager.googleapis.com compute.googleapis.com container.googleapis.com iam.googleapis.com secretmanager.googleapis.com

Error: "Insufficient permissions"​

Ensure your account has the Owner role or the specific roles listed above:

# Check your current roles
gcloud projects get-iam-policy YOUR_PROJECT_ID \
    --flatten="bindings[].members" \
    --format="table(bindings.role)" \
    --filter="bindings.members:YOUR_EMAIL"

# Grant owner role (requires existing owner permissions)
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
    --member="user:YOUR_EMAIL" \
    --role="roles/owner"

Infrastructure Components Created​

When O8 provisions GCP infrastructure, it creates:

  1. GKE Cluster

    • Regional cluster with auto-scaling (2-10 nodes)
    • Workload Identity enabled
    • Private cluster option available
    • Preemptible nodes for dev/test environments

  2. Service Accounts

    • Dedicated service accounts for ArgoCD
    • Workload Identity bindings for secure pod authentication

  3. Networking

    • VPC with custom subnet
    • Firewall rules for cluster communication
    • Load balancer for ingress

  4. ArgoCD Installation

    • Deployed via Helm
    • Configured with GKE Workload Identity
    • Admin password stored in Secret Manager

  5. External Secrets Operator (optional)

    • Integration with GCP Secret Manager
    • Automatic secret synchronization

Cost Optimization​

For development environments:

  • O8 automatically uses preemptible nodes (70% cost savings)
  • Default machine type: e2-standard-4
  • Auto-scaling configured to minimize idle resources

For production:

  • Use standard nodes for stability
  • Consider committed use discounts
  • Enable cluster autoscaling

Next Steps​

After infrastructure is provisioned:

  1. Access ArgoCD

    # Get credentials
    gcloud container clusters get-credentials CLUSTER_NAME --region REGION

    # Port-forward to ArgoCD
    kubectl port-forward svc/argocd-server -n argocd 8080:80

    # Login at http://localhost:8080
    # Username: admin
    # Password: (check terraform output or Secret Manager)

  2. Deploy Modules

    # O8 will automatically deploy configured modules
    # Check ArgoCD UI for deployment status

  3. Configure DNS

    • Point your domain to the cluster's ingress IP
    • Configure SSL certificates via cert-manager

Destroying Infrastructure​

To tear down all GCP resources:

o8 destroy --cluster CLUSTER_NAME

This will:

  • Delete the GKE cluster
  • Remove all service accounts
  • Clean up networking resources
  • Preserve Terraform state for recovery