GCP Virtual Machines

Manage GCP virtual machines using the Compute Engine API with support for multi-project deployments and Cloud Monitoring integration.

List Virtual Machines

Retrieve all VM instances across your GCP projects.

Endpoint

GET /api/gcp/vms

Response

{
  "value": [
    {
      "provider": "GCP",
      "name": "my-instance",
      "id": "1234567890123456789",
      "status": "RUNNING",
      "location": "us-central1-a",
      "machineType": "e2-medium",
      "projectId": "my-project-id"
    }
  ]
}

Instance Status Values

status

string

RUNNING - Instance is running
STOPPED - Instance is stopped
TERMINATED - Instance is terminated
PROVISIONING - Instance is being created
STAGING - Resources are being allocated
STOPPING - Instance is shutting down

Create Virtual Machine

Provision a new GCP VM instance.

Endpoint

POST /api/gcp/vms/create

Request Parameters

projectId

string

required

GCP project ID where the instance will be created

zone

string

required

Compute Engine zone (e.g., us-central1-a, europe-west1-b)

vmName

string

required

Name for the VM instance (must match regex [a-z](?:[-a-z0-9]{0,61}[a-z0-9])?)

machineType

string

default:"e2-medium"

Machine type (e.g., e2-small, e2-medium, n1-standard-1)

sourceImage

string

Boot disk source image

Request Example

{
  "projectId": "my-project-id",
  "zone": "us-central1-a",
  "vmName": "my-instance",
  "machineType": "e2-medium",
  "sourceImage": "projects/debian-cloud/global/images/family/debian-12"
}

Response

{
  "message": "Maszyna wirtualna 'my-instance' została pomyślnie utworzona."
}

Default Configuration

Compute Configuration

Machine Type: e2-medium (2 vCPUs, 4 GB memory)
Boot Disk Size: 10 GB
Boot Disk Image: Debian 12
Auto-delete Disk: Enabled

Network Configuration

Network: global/networks/default
Access Config: External NAT (ephemeral external IP)
IP Forwarding: Disabled by default

Machine Type Options

Shared-core (E2)

e2-micro - 2 vCPUs (shared), 1 GB memory
e2-small - 2 vCPUs (shared), 2 GB memory
e2-medium - 2 vCPUs (shared), 4 GB memory

Standard (N1)

n1-standard-1 - 1 vCPU, 3.75 GB memory
n1-standard-2 - 2 vCPUs, 7.5 GB memory
n1-standard-4 - 4 vCPUs, 15 GB memory

The instance is created synchronously. The operation waits for the instance to be fully provisioned before returning.

Delete Virtual Machine

Delete a GCP VM instance.

Endpoint

POST /api/gcp/vms/delete

Request Parameters

projectId

string

required

GCP project ID

zone

string

required

Zone where the instance is located

vmName

string

required

Instance name to delete

Request Example

{
  "projectId": "my-project-id",
  "zone": "us-central1-a",
  "vmName": "my-instance"
}

Response

{
  "message": "Rozpoczęto usuwanie maszyny wirtualnej 'my-instance'."
}

The boot disk is automatically deleted if the instance was created with auto_delete=True (default behavior).

Find VM by Name

Search for a VM instance across all projects and zones.

Endpoint

GET /api/gcp/vms/find/<vm_name>

Response

{
  "projectId": "my-project-id",
  "zone": "us-central1-a",
  "vmName": "my-instance",
  "instanceId": "1234567890123456789",
  "status": "RUNNING",
  "machineType": "e2-medium",
  "resourceId": "projects/my-project-id/zones/us-central1-a/instances/my-instance"
}

Search Behavior

Enumerate Projects

Lists all accessible GCP projects in the authenticated account

Aggregate Search

Performs aggregated list across all zones in each project

Name Match

Returns the first instance matching the exact name

Resource ID

Constructs the full resource ID for monitoring and operations

Error Handling

401 Unauthorized
400 Bad Request
403 Forbidden
404 Not Found
500 Server Error

{
  "error": "Nie znaleziono aktywnego konta GCP w sesji"
}

Cause: No active GCP account in session or missing refresh token.Solution: Authenticate through the GCP OAuth flow.

{
  "error": "Pola 'projectId', 'zone' oraz 'vmName' są wymagane."
}

Cause: Missing required parameters.Solution: Include all required fields in the request body.

{
  "error": "Brak uprawnień do tworzenia VM w projekcie 'my-project-id'. Szczegóły: ..."
}

Cause: Insufficient IAM permissions.Solution: Grant compute.instances.create permission or Compute Instance Admin role.

{
  "error": "Maszyna wirtualna 'my-instance' nie została znaleziona."
}

Cause: Instance doesn’t exist or is in a different project/zone.Solution: Verify instance name, project ID, and zone.

{
  "error": "Wystąpił nieoczekiwany błąd serwera: ..."
}

Cause: GCP API error or internal server error.Solution: Check error details and GCP service status.

Required IAM Permissions

The service account or user must have these permissions:

# For VM operations
- compute.instances.create
- compute.instances.delete
- compute.instances.get
- compute.instances.list

# For network operations
- compute.networks.get
- compute.subnetworks.use

# For disk operations
- compute.disks.create

Code Reference

The GCP VM management implementation is located in:

Source: backend/gcp/vm.py:6-148
Dependencies: Google Cloud SDK
- google-cloud-compute
- google-cloud-monitoring
- google-auth

Get Started

Authentication

Core Features

Virtual Machines

Containers

Storage

Networking

Monitoring & Logs

Deployment

List Virtual Machines

Endpoint

Response

Instance Status Values

Create Virtual Machine

Endpoint

Request Parameters

Request Example

Response

Default Configuration

Delete Virtual Machine

Endpoint

Request Parameters

Request Example

Response

Find VM by Name

Endpoint

Response

Search Behavior

Error Handling

Required IAM Permissions

Code Reference

Next Steps

VM Monitoring

Alert Policies

Build docs developers (and LLMs) love

Get Started

Authentication

Core Features

Virtual Machines

Containers

Storage

Networking

Monitoring & Logs

Deployment

​List Virtual Machines

​Endpoint

​Response

​Instance Status Values

​Create Virtual Machine

​Endpoint

​Request Parameters

​Request Example

​Response

​Default Configuration

​Delete Virtual Machine

​Endpoint

​Request Parameters

​Request Example

​Response

​Find VM by Name

​Endpoint

​Response

​Search Behavior

​Error Handling

​Required IAM Permissions

​Code Reference

​Next Steps

VM Monitoring

Alert Policies

Build docs developers (and LLMs) love

List Virtual Machines

Endpoint

Response

Instance Status Values

Create Virtual Machine

Endpoint

Request Parameters

Request Example

Response

Default Configuration

Delete Virtual Machine

Endpoint

Request Parameters

Request Example

Response

Find VM by Name

Endpoint

Response

Search Behavior

Error Handling

Required IAM Permissions

Code Reference

Next Steps