It's the boot disk source image — what OS gets installed on the VM. The value is passed verbatim to GCE's source_image field on the boot disk:
initialize_params=compute_v1.AttachedDiskInitializeParams(source_image=image)
(machine/providers/gcp.py:127)
| Form | Example | Behavior |
|---|---|---|
| Family path (recommended) | projects/debian-cloud/global/images/family/debian-12 |
Auto-resolves to the latest non-deprecated image in that family — you get OS patches without changing config |
| Specific image | projects/debian-cloud/global/images/debian-12-bookworm-v20260415 |
Pinned to one exact image version — reproducible but you have to bump it manually |
The family path is what the README example uses, and it's what you want unless you have a specific reason to pin.
| OS | Project | Family |
|---|---|---|
| Debian 12 | debian-cloud |
debian-12 |
| Ubuntu 24.04 LTS | ubuntu-os-cloud |
ubuntu-2404-lts-amd64 |
| Ubuntu 22.04 LTS | ubuntu-os-cloud |
ubuntu-2204-lts |
| Rocky Linux 9 | rocky-linux-cloud |
rocky-linux-9 |
| AlmaLinux 9 | almalinux-cloud |
almalinux-9 |
| Fedora | fedora-cloud |
fedora-cloud-41 (etc.) |
| Container-Optimized OS | cos-cloud |
cos-stable |
gcloud compute images list # everything (long)
gcloud compute images list --filter="family:debian-12" # one family
gcloud compute images list --project=ubuntu-os-cloud # all Ubuntu variants
Cloud-init support: the user-data we attach in create_vm only fires if the image ships with cloud-init enabled. The Debian, Ubuntu, Rocky, and AlmaLinux images above all do. The bare CentOS and stripped-down "minimal" images sometimes don't — if your machine never picks up the new user / SSH key after creation, that's the first thing to check.
Thank you. When I try to run "machine check" with my gcloud credentials, it fails with a message I will paste below. When I click on the URL it provies it goes into a very confusing page about requesting access from my administrator. I am the administrator! Also, it says that compute API has to be "used" or enabled on the project. I'm not sure what that means because when I go to the console web site I see the API is already enabled (I enabled it a few days ago). Here's the message:
The message didn't come through — looks like it got cut off after "Here's the message:". Mind pasting it again?
That said, your description ("administrator access" page, claims Compute API isn't enabled when you can see in the console it is) is a near-perfect match for one specific GCP footgun, so I'll guess at it preemptively.
When you use gcloud auth application-default login, the resulting credentials don't know which project to bill API calls to. So Google attributes the call to a separate "quota project" — which is not necessarily the same as the project-id in your machine config. If those don't match, the error message references the quota project (often some default Google-internal one like google.com:cloudsdktool-...), not your actual project. Following the "enable the API" link takes you to that other project, where you legitimately don't have admin rights — hence the "request access from administrator" page.
Tell ADC to use your project as the quota project:
gcloud auth application-default set-quota-project <your-project-id>
Then re-run machine check. The 403 should go away.
The cleanest fix is to use a service account JSON key (Option A from my earlier reply). Service accounts are bound to a specific project, so there's no quota-project ambiguity, and credentials-file: in your config is unambiguous.
Once you paste the actual error I can confirm — but if it contains the phrase serviceusage.services.use or references a project ID that isn't yours, that's exactly this.
FAIL: API authentication (403 GET https://compute.googleapis.com/compute/v1/projects/machine-testing: Compute Engine API has not been used in project machine-testing before or it is disabled. Enable it by visiting https://console.developers.google.com/apis/api/compute.googleapis.com/overview?project=machine-testing then retry. If you enabled this API recently, wait a few minutes for the action to propagate to our systems and retry.)
OK — different problem than I guessed. The URL in the error correctly references your project (machine-testing), so it's not a quota-project mismatch. GCP genuinely thinks Compute API isn't enabled on that specific project.
The most likely cause: you enabled it on a different project. This is easy to do because:
machine-testing vs machine-testing-484726.gcloud projects list
gcloud services list --enabled --project=machine-testing | grep compute
If the second command returns no rows, the API is genuinely not enabled on this project ID. Enable it explicitly:
gcloud services enable compute.googleapis.com --project=machine-testing
gcloud services enable dns.googleapis.com --project=machine-testing
Wait ~30 seconds for propagation, then re-run machine check.
When you clicked the link in the error, the console probably opened with a different project context (the one your console session was last on, not necessarily machine-testing). On that other project you may not be the owner — hence the access-request page. The CLI commands above sidestep this entirely because they take an explicit --project flag.
This GCP stuff is pretty hard to use. When I tried running that command it produced another error (I did already log in per your instructions):
Yeah, GCP's onboarding is genuinely rough — you're not imagining it.
The error text didn't come through this time either — looks like it got cut off after "another error:". Can you paste the actual message? I can't diagnose without seeing what gcloud printed.
A couple of common ones in case you can identify it from memory while you re-paste:
PERMISSION_DENIED: ... permission 'serviceusage.services.enable' denied — your gcloud-logged-in account doesn't have rights to enable APIs on that project. Fix: get the Owner or Service Usage Admin role, or have whoever does it for you.The project ... could not be found — the project ID is wrong (a typo, or you're using the project name instead of ID). gcloud projects list will show the actual IDs.The caller does not have permission — you're authenticated but as the wrong identity. gcloud auth list shows which account is active; gcloud config set account <email> switches.ERROR: (gcloud.services.list) You do not currently have an active account selected. Please run:
$ gcloud auth login
to obtain new credentials.
If you have already logged in with a different account, run:
$ gcloud config set account ACCOUNT
to select an already authenticated account to use.
Ah, classic GCP confusion — there are two separate logins, and you've only done one. Annoying but real:
| Command | Authenticates | Used by |
|---|---|---|
gcloud auth login |
The gcloud CLI itself |
gcloud projects list, gcloud services enable, etc. |
gcloud auth application-default login |
Application Default Credentials (a separate JSON file) | Python SDKs, Terraform, the machine tool — anything that calls google.auth.default() |
You did the second one (per my earlier instructions, so the machine tool would work). Now you're trying to run gcloud itself, which needs the first one.
gcloud auth login
This opens a browser, you pick the same Google account, done. Then your earlier command will work:
gcloud services list --enabled --project=machine-testing | grep compute
gcloud services enable compute.googleapis.com --project=machine-testing
Historically, gcloud was for humans typing commands and ADC was for programs running on servers (using service accounts via the metadata server). When Google added "let your local Python script use your personal credentials too," they bolted on a second flow rather than unifying them. So both the gcloud CLI and your Python code each have their own credential store, and you have to log in twice. The error message could absolutely just say "run gcloud auth login or gcloud auth application-default login depending on what you're doing" — but it doesn't.