Configure your firewall rules, IAM permissions, and network security to allow the required connections for your GCP Runner to function properly.

​
IAM Permissions Required

Your GCP service account needs the following permissions to deploy and manage the runner infrastructure:

​
Required Roles

  • Compute Admin (roles/compute.admin) - Manage VMs, networks, and load balancers
  • Storage Admin (roles/storage.admin) - Manage Cloud Storage buckets and objects
  • Artifact Registry Administrator (roles/artifactregistry.admin) - Manage container images
  • Secret Manager Admin (roles/secretmanager.admin) - Store and retrieve secrets
  • Service Account Admin (roles/iam.serviceAccountAdmin) - Create service accounts for runner components
  • Project IAM Admin (roles/resourcemanager.projectIamAdmin) - Manage project-level IAM bindings

​
Custom Role (Alternative)

Instead of broad roles, you can create a custom role with these specific permissions: 
{
  "title": "Ona GCP Runner Role",
  "description": "Permissions required for Ona GCP Runner deployment",
  "stage": "GA",
  "includedPermissions": [
    "compute.instances.*",
    "compute.instanceGroups.*",
    "compute.networks.*",
    "compute.subnetworks.*",
    "compute.firewalls.*",
    "compute.forwardingRules.*",
    "compute.backendServices.*",
    "compute.healthChecks.*",
    "storage.buckets.*",
    "storage.objects.*",
    "artifactregistry.repositories.*",
    "secretmanager.secrets.*",
    "secretmanager.versions.*",
    "iam.serviceAccounts.*",
    "resourcemanager.projects.setIamPolicy"
  ]
}

​
Network Connectivity Requirements

Configure your firewall and network security groups to allow outbound connections to these endpoints:

​
Ona Services

​
Management Plane

Controls Runner and Environment orchestration by communicating with Ona’s control plane.
  • https://app.gitpod.io
  • https://app.ona.com

​
VS Code

Required for VS Code IDE functionality including server downloads and extension marketplace access.
  • https://update.code.visualstudio.com/api/commits/stable/server-linux-x64-web
  • https://update.code.visualstudio.com/api/commits/stable/server-linux-arm64-web
  • https://update.code.visualstudio.com/commit:*/server-linux-x64/stable
  • https://update.code.visualstudio.com/commit:*/server-linux-arm64/stable
  • https://*.vscode-unpkg.net
  • https://marketplace.visualstudio.com
  • https://*.gallerycdn.vsassets.io

​
JetBrains

Required for JetBrains IDE functionality including IDE downloads and services.
  • https://download.jetbrains.com
  • https://download-cf.jetbrains.com
  • https://download-cdn.jetbrains.com
  • https://data.services.jetbrains.com

​
Release Artifacts

Downloads Ona updates, CLI binaries, and agent components necessary for Runner and Environment operation. This access is required from the user laptops.
  • https://releases.gitpod.io/cli/stable/manifest.json
  • https://releases.gitpod.io/cli/stable/gitpod-linux-amd64
  • https://releases.gitpod.io/cli/stable/gitpod-linux-amd64.exe
  • https://releases.gitpod.io/cli/stable/gitpod-linux-amd64.sha256
  • https://releases.gitpod.io/cli/stable/gitpod-linux-arm64
  • https://releases.gitpod.io/cli/stable/gitpod-linux-arm64.sha256
  • https://releases.gitpod.io/vscode/releases/*/vscode-remote.vsix
  • https://releases.gitpod.io/vscode/releases/*/vscode-agent-amd64
  • https://releases.gitpod.io/vscode/releases/*/vscode-agent-arm64
  • https://releases.gitpod.io/jetbrains/releases/*/jetbrains-agent-amd64
  • https://releases.gitpod.io/jetbrains/releases/*/jetbrains-agent-arm64

​
Container Registries

Downloads container images used by development environments and Runner infrastructure. Ona default devcontainer image:
You can override this from your organization policy if you cannot allow external registries
  • https://mcr.microsoft.com/devcontainers/base:ubuntu-24.04

​
Your Infrastructure

​
SCM and SSO Providers

Access to your source code repositories and authentication providers for user login and code access. Configure access to your specific providers (complete HTTPS URLs):
  • GitHub, GitLab, Bitbucket URLs
  • SSO provider URLs (Okta, Azure AD, etc.)

​
Optional Services

​
Prometheus Remote Write

Optional metrics collection endpoint for monitoring Runner and Environment performance.
  • Your metrics endpoint URL (HTTPS 443)

​
Additional Container Registries

Optional access to custom container registries for pulling private or organization-specific images. Common registries (allow those you use):
  • https://index.docker.io
  • https://registry-1.docker.io
  • https://auth.docker.io
  • https://ghcr.io
  • Your private registry URLs (HTTPS 443)

​
GCP Services and APIs Required

​
Core GCP Services

ServiceAPI EndpointPurposeWhy Needed
Compute Enginecompute.googleapis.comVM management and networkingCreates development environment VMs, manages instance groups, autoscaling, load balancers, and networking infrastructure
Cloud Storagestorage.googleapis.comObject storageStores build cache, environment snapshots, and Terraform state with lifecycle management
Artifact Registryartifactregistry.googleapis.comContainer registryStores and manages container images for development environments with vulnerability scanning
Secret Managersecretmanager.googleapis.comSecure credential storageStores runner authentication tokens, SSL certificates, and other sensitive configuration securely
Cloud Logginglogging.googleapis.comCentralized loggingCollects logs from runner components and development environments for debugging and monitoring
Cloud Monitoringmonitoring.googleapis.comInfrastructure monitoringMonitors VM health, resource utilization, and provides alerting for runner infrastructure

​
Supporting GCP Services

ServiceAPI EndpointPurposeWhy Needed
Memorystore for Redisredis.googleapis.comIn-memory data storeStores runner state, session information, and coordinates between runner instances
Cloud Runrun.googleapis.comServerless containersProvides serverless execution environment for auxiliary services and webhooks
Cloud Pub/Subpubsub.googleapis.comEvent processingProcesses compute lifecycle events for event-driven environment reconciliation
Cloud Functionscloudfunctions.googleapis.comServerless functionsHandles authentication proxy and event-driven workflows

​
Required APIs

APIEndpointPurposeWhy Needed
Identity and Access Managementiam.googleapis.comAccess controlCreates service accounts, custom roles, and manages permissions for runner components
IAM Credentialsiamcredentials.googleapis.comToken generationGenerates short-lived access tokens for secure service-to-service authentication
Cloud Resource Managercloudresourcemanager.googleapis.comProject managementManages project-level IAM policies and resource organization
VPC Accessvpcaccess.googleapis.comServerless VPC connectivityEnables Cloud Run services to access VPC resources securely
Service Networkingservicenetworking.googleapis.comPrivate connectivityCreates private connections to managed services like Memorystore Redis
Cloud KMScloudkms.googleapis.com(Optional) CMEK encryptionEncrypts persistent disks, storage buckets, and secrets with customer-managed encryption keys

​
Metadata Service Access

EndpointProtocolPurposeWhy Needed
metadata.google.internal (169.254.169.254)HTTPVM metadata serviceRequired for GCP VM instances to access metadata, service account tokens, and instance information

​
Image Access Requirements

GCP Runners require access to specific VM images. If your GCP Organization restricts image access through organizational policies, ensure your GCP project can launch Compute Engine instances from these images.

​
Required Images

Image FamilyProject/SourceOwnerPurpose
cos-stablecos-cloudGoogleRunner orchestrator service
gcp-runner-image-*gitpod-next-productionOnaDevelopment environment VMs

​
Organizational Policy Configuration

If your organization uses image access restrictions, configure your organizational policy to allow: 
# Example organizational policy constraint
constraint: compute.trustedImageProjects
listPolicy:
  allowedValues:
    - "projects/cos-cloud"
    - "projects/gitpod-next-production"

​
Allowlisting Recommendations

Use Project-Level Access: Allow access by project ID rather than specific image names to automatically receive security updates and new features. Regular Updates: Ona updates images regularly for security patches and feature improvements. Project-level access ensures automatic access to updated images. Testing Access: Verify image access before deployment: 
# Test access to required images
gcloud compute images list --project=cos-cloud --filter="family:cos-stable"
gcloud compute images list --project=gitpod-next-production --filter="name:gcp-runner-image-*"

​
Quota Requirements

Ensure your GCP project has sufficient quotas for the runner deployment:

​
Compute Engine Quotas

ResourceMinimum RequiredRecommendedPurpose
CPUs100500+Development environment VMs
Persistent Disk SSD (GB)1,0005,000+Environment storage
In-use IP addresses50200+VM networking
Firewall rules1050+Network security
Forwarding rules520+Load balancer configuration
Backend services520+Load balancer backends

​
Regional Quotas

Quotas are region-specific. Ensure adequate quotas in your deployment region: 
# Check current quotas
gcloud compute project-info describe --project=YOUR_PROJECT_ID

​
Requesting Quota Increases

For production deployments, request quota increases through the GCP Console:
  1. Navigate to IAM & Admin → Quotas
  2. Filter by service: Compute Engine API
  3. Select your deployment region
  4. Request increases for the resources listed above

​
Troubleshooting Access Issues

​
Common Permission Issues

Insufficient IAM Permissions: Verify your service account has the required roles listed above. API Not Enabled: Enable all required APIs in your GCP project: 
# Enable required APIs
gcloud services enable compute.googleapis.com \
  storage.googleapis.com \
  artifactregistry.googleapis.com \
  secretmanager.googleapis.com \
  iam.googleapis.com \
  cloudresourcemanager.googleapis.com
Image Access Denied: Check organizational policies and image project access. Quota Exceeded: Monitor quota usage and request increases before deployment.

​
Validation Commands

Test your access before deployment: 
# Test compute permissions
gcloud compute instances list --project=YOUR_PROJECT_ID

# Test storage permissions  
gcloud storage buckets list --project=YOUR_PROJECT_ID

# Test IAM permissions
gcloud iam service-accounts list --project=YOUR_PROJECT_ID