GCP access requirements

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

Configure IAM permissions

Use the Terraform module’s IAM configuration guide to configure service accounts, custom roles, or predefined roles. The module guide is the source of truth for GCP runner permissions.

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
• https://*.prss.microsoft.com
• https://*.vscode-gitpod-cdn.com (required for VS Code Web functionality)
• https://vscode.gitpod.io (required for VS Code Web functionality)

JetBrains

Required for JetBrains IDE functionality including IDE downloads and services.

• https://www.jetbrains.com
• https://download.jetbrains.com
• https://download-cf.jetbrains.com
• https://download-cdn.jetbrains.com
• https://data.services.jetbrains.com
• https://plugins.jetbrains.com
• https://downloads.marketplace.jetbrains.com
• https://account.jetbrains.com

See the JetBrains network access requirements for more details.

Release Artifacts

Downloads Ona updates, CLI binaries, and agent components necessary for Runner and Environment operation. These are served from app.gitpod.io/releases/* (same domain as the control plane). This access is required from the user laptops.

• https://app.gitpod.io/releases/cli/stable/manifest.json
• https://app.gitpod.io/releases/cli/stable/gitpod-linux-amd64
• https://app.gitpod.io/releases/cli/stable/gitpod-linux-amd64.exe
• https://app.gitpod.io/releases/cli/stable/gitpod-linux-amd64.sha256
• https://app.gitpod.io/releases/cli/stable/gitpod-linux-arm64
• https://app.gitpod.io/releases/cli/stable/gitpod-linux-arm64.sha256
• https://app.gitpod.io/releases/vscode/releases/*/vscode-remote.vsix
• https://app.gitpod.io/releases/vscode/releases/*/vscode-agent-amd64
• https://app.gitpod.io/releases/vscode/releases/*/vscode-agent-arm64
• https://app.gitpod.io/releases/jetbrains/releases/*/jetbrains-agent-amd64
• https://app.gitpod.io/releases/jetbrains/releases/*/jetbrains-agent-arm64

Container Registries

Downloads container images used by development environments and runner infrastructure.

Ona runner images (Google Artifact Registry):

• https://us-docker.pkg.dev/gitpod-artifacts/docker-public (project ID: 760152953637)

Ona default Dev Container image:

• https://mcr.microsoft.com/devcontainers/base:2.0.4-noble

Your Infrastructure

Runner Proxy Domain

The runner must be able to reach its own configured domain over HTTPS. It periodically verifies DNS resolution and TLS connectivity by requesting https://<your-runner-domain>/_health. Blocking this egress causes the runner to report degraded status.

• https://<your-runner-domain> (the domain you configured during setup)

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

Service	API Endpoint	Purpose	Why Needed
Compute Engine	compute.googleapis.com	VM management and networking	Creates development environment VMs, manages instance groups, autoscaling, load balancers, and networking infrastructure
Cloud Storage	storage.googleapis.com	Object storage	Stores build cache, environment snapshots, and Terraform state with lifecycle management
Artifact Registry	artifactregistry.googleapis.com	Container registry	Stores and manages container images for development environments with vulnerability scanning
Secret Manager	secretmanager.googleapis.com	Secure credential storage	Stores runner authentication tokens, the runner secrets key, SSL certificates, and other sensitive configuration securely
Cloud Logging	logging.googleapis.com	Centralized logging	Collects logs from runner components and development environments for debugging and monitoring
Cloud Monitoring	monitoring.googleapis.com	Infrastructure monitoring	Monitors VM health, resource utilization, and provides alerting for runner infrastructure

Supporting GCP Services

Service	API Endpoint	Purpose	Why Needed
Memorystore for Redis	redis.googleapis.com	In-memory data store	Stores runner state, session information, and coordinates between runner instances
Cloud Run	run.googleapis.com	Serverless containers	Provides serverless execution environment for auxiliary services and webhooks
Cloud Pub/Sub	pubsub.googleapis.com	Event processing	Processes compute lifecycle events for event-driven environment reconciliation
Cloud Functions	cloudfunctions.googleapis.com	Serverless functions	Handles authentication proxy and event-driven workflows

Required APIs

API	Endpoint	Purpose	Why Needed
Identity and Access Management	iam.googleapis.com	Access control	Creates service accounts, custom roles, and manages permissions for runner components
IAM Credentials	iamcredentials.googleapis.com	Token generation	Generates short-lived access tokens for secure service-to-service authentication
Cloud Resource Manager	cloudresourcemanager.googleapis.com	Project management	Manages project-level IAM policies and resource organization
VPC Access	vpcaccess.googleapis.com	Serverless VPC connectivity	Enables Cloud Run services to access VPC resources securely
Service Networking	servicenetworking.googleapis.com	Private connectivity	Creates private connections to managed services like Memorystore Redis
Cloud KMS	cloudkms.googleapis.com	(Optional) CMEK encryption	Encrypts persistent disks, storage buckets, and secrets with customer-managed encryption keys

Metadata Service Access

Endpoint	Protocol	Purpose	Why Needed
metadata.google.internal (169.254.169.254)	HTTP	VM metadata service	Required 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 Family	Project/Source	Owner	Purpose
cos-stable	cos-cloud	Google	Runner orchestrator service
ona-environment-*	gitpod-next-production	Ona	Development 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:ona-environment-*"

Quota Requirements

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

Compute Engine Quotas

Resource	Minimum Required	Recommended	Purpose
CPUs	100	500+	Development environment VMs
Persistent Disk SSD (GB)	1,000	5,000+	Environment storage
In-use IP addresses	50	200+	VM networking
Firewall rules	10	50+	Network security
Forwarding rules	5	20+	Load balancer configuration
Backend services	5	20+	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

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 \
  networkconnectivity.googleapis.com \
  redis.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