Google Cloud provider - configuration reference
This page documents every field on
GCPProviderConfig
(provider-level settings) and
GCPTemplate
(per-template settings). Provider config is a pydantic-settings model
with the ORB_GCP_ env-var prefix, so every provider-level field can also
be set via environment variable.
Provider configuration
| Field |
Type |
Default |
Env var |
Description |
provider_type |
str |
"gcp" |
ORB_GCP_PROVIDER_TYPE |
Provider type identifier. |
project_id |
str (required) |
- |
ORB_GCP_PROJECT_ID |
Google Cloud project ID used for all Compute Engine operations. Must match the canonical Google Cloud project ID format (lowercase letters, digits, hyphens; 6-30 characters). |
region |
str |
"us-central1" |
ORB_GCP_REGION |
Default Google Cloud region, e.g. "us-central1" or "europe-west4". |
zones |
list[str] |
[] |
ORB_GCP_ZONES |
Optional preferred zones, e.g. ["us-central1-a", "us-central1-b"]. |
network |
str \| None |
None |
ORB_GCP_NETWORK |
Default VPC network self-link or name. |
subnetwork |
str \| None |
None |
ORB_GCP_SUBNETWORK |
Default subnetwork self-link or name. |
max_retries |
int |
3 |
ORB_GCP_MAX_RETRIES |
Maximum retry attempts for Google Cloud API calls. |
connect_timeout |
int |
30 |
ORB_GCP_CONNECT_TIMEOUT |
Connection timeout, in seconds. |
read_timeout |
int |
60 |
ORB_GCP_READ_TIMEOUT |
Read timeout, in seconds. |
There is no credential-related field on GCPProviderConfig — the Google Cloud
provider authenticates exclusively via Application Default Credentials.
See Authentication.
Worked provider config example
{
"providers": [
{
"name": "gcp_main",
"type": "gcp",
"config": {
"project_id": "my-gcp-project",
"region": "us-central1",
"zones": ["us-central1-a", "us-central1-b"],
"network": "projects/my-gcp-project/global/networks/orb-vpc",
"subnetwork": "projects/my-gcp-project/regions/us-central1/subnetworks/orb-subnet"
}
}
]
}
CLI equivalents
orb provider add --provider-type gcp \
--gcp-project-id my-gcp-project \
--gcp-region us-central1 \
--gcp-zones us-central1-a,us-central1-b \
--gcp-network projects/my-gcp-project/global/networks/orb-vpc \
--gcp-subnetwork projects/my-gcp-project/regions/us-central1/subnetworks/orb-subnet
Service account flags (--gcp-service-account-email,
--gcp-service-account-scopes) are also available on orb provider add
but map to template defaults rather than the provider config above — see
Template fields.
Provider capabilities
provider_api |
Spot |
On-demand |
Async operations |
Start/stop |
Max instances |
MIG |
yes |
yes |
yes |
no |
1000 |
SingleVM |
yes |
yes |
no |
yes |
1 |
The Google Cloud provider strategy supports create_instances,
terminate_instances, cleanup_machine_resources,
get_instance_status, describe_resource_instances,
validate_template, get_available_templates, health_check,
resolve_image, start_instances, and stop_instances. Start/stop only
takes effect for SingleVM; calling it against a MIG-backed request
returns a warning and performs no action, because MIG-managed instances
follow the group's own lifecycle policy.
Template fields
Every field below lives on GCPTemplate.
Identity and placement
| Field |
Type |
Required |
Description |
provider_api |
enum |
no (default MIG) |
MIG or SingleVM. |
project_id |
string |
yes |
Google Cloud project ID (canonical format). |
region |
string |
yes |
Google Cloud region, e.g. "us-central1". |
zones |
list[string] |
conditionally |
See placement rules below. |
mig_scope |
enum |
no (default regional) |
regional or zonal. Only used for provider_api="MIG". |
Placement rules enforced at validation time:
provider_api="MIG", mig_scope="zonal" requires exactly one zone.
provider_api="MIG", mig_scope="regional" should use at least two
zones when zones are specified at all (an empty list lets Google Cloud choose).
provider_api="SingleVM" requires max_machines == 1 and exactly one
explicit zone.
Compute
| Field |
Type |
Default |
Description |
machine_type |
string (required) |
- |
Google Cloud machine type, e.g. "e2-standard-4". Alias: instance_type. |
Networking
| Field |
Type |
Description |
network |
string | None |
VPC network self-link or name. Falls back to the provider-level network. |
subnetwork |
string | None |
Subnetwork self-link or name. Falls back to the provider-level subnetwork. |
network_tags |
list[string] |
Network tags applied to created instances (used for firewall targeting). |
Identity and access
| Field |
Type |
Default |
Description |
service_account_email |
string | None |
None |
Service account attached to created instances. |
service_account_scopes |
list[string] |
["https://www.googleapis.com/auth/compute"] |
OAuth scopes for the attached service account. Every scope must start with https://www.googleapis.com/auth/ and the list cannot be empty. |
Image
| Field |
Type |
Description |
source_image |
string | None |
Full image self-link. Takes priority over source_image_family/source_image_project when both are present. |
source_image_family |
string | None |
Image family, e.g. "debian-12". Must be paired with source_image_project. |
source_image_project |
string | None |
Project owning the image family, e.g. "debian-cloud". |
A template must supply either source_image, or both
source_image_family and source_image_project.
Disks
| Field |
Type |
Description |
boot_disk_type |
string (disk type resource name) |
e.g. "pd-balanced", "pd-ssd", "pd-standard". |
boot_disk_size_gb |
int (>= 10) |
Boot disk size in GiB. |
Labels and naming
| Field |
Type |
Description |
labels |
dict[str, str] |
Labels applied to created resources. |
mig_name |
string | None |
Explicit MIG name. Auto-generated (orb-mig-<template_id>-<hex>) when omitted. |
instance_template_name_prefix |
string | None |
Prefix for the generated instance template name. Default "orb". |
Unsupported fields
| Field |
Behaviour |
key_name |
Rejected with a validation error. Google Cloud does not support named SSH key pairs. |
Worked template examples
Regional MIG, Debian 12
{
"template_id": "gcp-mig-example",
"provider_name": "gcp_main",
"provider_api": "MIG",
"project_id": "my-gcp-project",
"region": "us-central1",
"zones": ["us-central1-a", "us-central1-b"],
"machine_type": "e2-standard-4",
"source_image_family": "debian-12",
"source_image_project": "debian-cloud",
"max_machines": 2
}
Standalone VM (SingleVM)
{
"template_id": "gcp-single-vm-example",
"provider_name": "gcp_main",
"provider_api": "SingleVM",
"project_id": "my-gcp-project",
"region": "us-central1",
"zones": ["us-central1-a"],
"machine_type": "e2-standard-4",
"source_image_family": "debian-12",
"source_image_project": "debian-cloud",
"max_machines": 1
}
Environment-variable cheat sheet
export ORB_GCP_PROJECT_ID="my-gcp-project"
export ORB_GCP_REGION="us-central1"
export ORB_GCP_ZONES='["us-central1-a","us-central1-b"]'
export ORB_GCP_NETWORK="projects/my-gcp-project/global/networks/orb-vpc"
export ORB_GCP_SUBNETWORK="projects/my-gcp-project/regions/us-central1/subnetworks/orb-subnet"
export ORB_GCP_MAX_RETRIES="5"