GCP Runner Access Requirements

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 specific permissions. GCP custom roles do not support wildcards, so you must list each permission explicitly. The example below covers the most common permissions needed:

{
  "title": "Ona GCP Runner Role",
  "description": "Permissions required for Ona GCP Runner deployment",
  "stage": "GA",
  "includedPermissions": [
    "compute.instances.create",
    "compute.instances.delete",
    "compute.instances.get",
    "compute.instances.list",
    "compute.instances.setMetadata",
    "compute.instances.setTags",
    "compute.instances.start",
    "compute.instances.stop",
    "compute.instances.resume",
    "compute.instanceGroups.create",
    "compute.instanceGroups.delete",
    "compute.instanceGroups.get",
    "compute.instanceGroups.list",
    "compute.instanceGroups.update",
    "compute.networks.get",
    "compute.networks.list",
    "compute.subnetworks.get",
    "compute.subnetworks.list",
    "compute.subnetworks.use",
    "compute.firewalls.create",
    "compute.firewalls.delete",
    "compute.firewalls.get",
    "compute.firewalls.list",
    "compute.firewalls.update",
    "compute.forwardingRules.create",
    "compute.forwardingRules.delete",
    "compute.forwardingRules.get",
    "compute.forwardingRules.list",
    "compute.backendServices.create",
    "compute.backendServices.delete",
    "compute.backendServices.get",
    "compute.backendServices.list",
    "compute.backendServices.update",
    "compute.healthChecks.create",
    "compute.healthChecks.delete",
    "compute.healthChecks.get",
    "compute.healthChecks.list",
    "compute.healthChecks.update",
    "storage.buckets.create",
    "storage.buckets.delete",
    "storage.buckets.get",
    "storage.buckets.list",
    "storage.objects.create",
    "storage.objects.delete",
    "storage.objects.get",
    "storage.objects.list",
    "artifactregistry.repositories.create",
    "artifactregistry.repositories.delete",
    "artifactregistry.repositories.get",
    "artifactregistry.repositories.list",
    "secretmanager.secrets.create",
    "secretmanager.secrets.delete",
    "secretmanager.secrets.get",
    "secretmanager.secrets.list",
    "secretmanager.versions.add",
    "secretmanager.versions.access",
    "secretmanager.versions.get",
    "secretmanager.versions.list",
    "iam.serviceAccounts.create",
    "iam.serviceAccounts.delete",
    "iam.serviceAccounts.get",
    "iam.serviceAccounts.list",
    "resourcemanager.projects.setIamPolicy",
    "resourcemanager.projects.getIamPolicy"
  ]
}

This list covers the most common deployment permissions. Depending on your configuration (CMEK, internal LB, etc.), additional permissions may be required. Refer to the IAM configuration guide in the Terraform module for the complete list.

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, 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:

Navigate to IAM & Admin → Quotas
Filter by service: Compute Engine API
Select your deployment region
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

​IAM Permissions Required

​Required Roles

​Custom Role (Alternative)

​Network Connectivity Requirements

​Ona Services

​Management Plane

​VS Code

​JetBrains

​Release Artifacts

​Container Registries

​Your Infrastructure

​Runner Proxy Domain

​SCM and SSO Providers

​Optional Services

​Prometheus Remote Write

​Additional Container Registries

​GCP Services and APIs Required

​Core GCP Services

​Supporting GCP Services

​Required APIs

​Metadata Service Access

​Image Access Requirements

​Required Images

​Organizational Policy Configuration

​Allowlisting Recommendations

​Quota Requirements

​Compute Engine Quotas

​Regional Quotas

​Requesting Quota Increases

​Troubleshooting

IAM Permissions Required

Required Roles

Custom Role (Alternative)

Network Connectivity Requirements

Ona Services

Management Plane

VS Code

JetBrains

Release Artifacts

Container Registries

Your Infrastructure

Runner Proxy Domain

SCM and SSO Providers

Optional Services

Prometheus Remote Write

Additional Container Registries

GCP Services and APIs Required

Core GCP Services

Supporting GCP Services

Required APIs

Metadata Service Access

Image Access Requirements

Required Images

Organizational Policy Configuration

Allowlisting Recommendations

Quota Requirements

Compute Engine Quotas

Regional Quotas

Requesting Quota Increases

Troubleshooting