> ## Documentation Index
> Fetch the complete documentation index at: https://ona.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# GCP 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:

```json theme={null}
{
  "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"
  ]
}
```

<Note>
  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](https://github.com/gitpod-io/terraform-google-ona-runner/blob/main/docs/iam.md) in the Terraform module for the complete list.
</Note>

## 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](/ona/editors/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:

```yaml theme={null}
# 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:

```bash theme={null}
# 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:

```bash theme={null}
# 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

<Accordion title="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:

  ```bash theme={null}
  # 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.
</Accordion>

<Accordion title="Validation Commands">
  Test your access before deployment:

  ```bash theme={null}
  # 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
  ```
</Accordion>