Google Cloud provider - authentication¶
The Google Cloud provider authenticates exclusively with
Application Default Credentials (ADC).
There is no provider-config field for credentials, no service-account-key
file setting, and no credential-selection flag — GCPProviderConfig only
carries project_id, region, zones, network, and subnetwork.
How ORB resolves credentials¶
Every Compute Engine client (InstancesClient, InstanceTemplatesClient,
InstanceGroupManagersClient, RegionInstanceGroupManagersClient,
ImagesClient) is constructed with no explicit credentials argument. The
underlying google-cloud-compute client library resolves ADC itself, in
its standard order:
GOOGLE_APPLICATION_CREDENTIALSenvironment variable, pointing at a service-account key file.- The credentials set by
gcloud auth application-default login(local development). - The attached service account on Compute Engine, GKE (via Workload Identity), Cloud Run, or Cloud Functions metadata server.
ORB's own health check (check_health) calls google.auth.default()
directly and refreshes the resulting credential against
google.auth.transport.requests.Request() to confirm ADC is reachable
before reporting the provider healthy.
Single identity, by design¶
Google Cloud's ADC model resolves to exactly one credential per process, and
every Google Cloud provider instance in that process shares it: none of the
Compute Engine clients are constructed with an explicit credentials or
project argument, so they all resolve ADC the same way. project_id is set
per provider instance, but the identity is not — unlike the AWS provider
(multiple named profiles) or the Azure provider (client_id to select a
specific managed identity), the Google Cloud provider has no mechanism to use
a different identity per provider instance or per template.
In practice, this means if you configure multiple Google Cloud provider instances in one ORB process targeting different projects, the single ADC identity for that process must itself have the required IAM roles in every one of those projects — per-instance credentials are not supported. If the projects need separate identities, run separate ORB deployments (or processes), each with its own ADC source.
Required IAM roles¶
The identity ORB runs as needs, at minimum, the Compute Engine permissions
to create and delete instances, instance templates, and managed instance
groups in project_id:
roles/compute.instanceAdmin.v1is the simplest broad grant covering instance, instance-template, and MIG lifecycle operations.- If instances are attached to a service account
(
service_account_email), the identity running ORB also needsroles/iam.serviceAccountUseron that service account (Google Cloud requires this to allow attaching it to a new instance).
Setting up ADC¶
Local development¶
Service account key file¶
Running on Google Cloud compute (recommended for production)¶
Attach a service account to the GCE instance, GKE node pool (with Workload Identity), or Cloud Run service running ORB. No environment variable is required; the metadata server supplies credentials automatically.
Troubleshooting¶
| Symptom | Likely cause | Fix |
|---|---|---|
Health check reports GCP credential check failed: ... with the ADC hint |
No ADC source available in the current environment | Set GOOGLE_APPLICATION_CREDENTIALS, run gcloud auth application-default login, or attach a service account via workload identity. |
GCPAuthorizationError on create/delete operations |
The ADC identity lacks IAM permissions on project_id |
Grant roles/compute.instanceAdmin.v1 (or a narrower custom role with equivalent permissions). |
| Instance creation fails with a service-account attachment error | ADC identity lacks roles/iam.serviceAccountUser on service_account_email |
Grant roles/iam.serviceAccountUser on the target service account. |
GCPQuotaExceededError |
Compute Engine quota exhausted for the project/region | Request a quota increase in the Google Cloud console, or reduce max_machines. |
GCPRateLimitError |
Compute Engine API throttling (TooManyRequests) |
Retried automatically up to max_retries; reduce request concurrency if it persists. |