Skip to main content

Google Cloud

This article refers to Platform v3.3.0. The current Platform version is v3.3.0.

Beta
This platform is newly supported and the integration is currently in Beta. You can follow this guide from start to finish, but you may come across minor issues. If you do, contact our support team and we will resolve them as soon as possible.

Overview​

This guide walks you through running Barbara OS on a Google Compute Engine (GCE) instance using the gcp_amd64 image. You upload the factory image to Cloud Storage, turn it into a private Compute Engine image in your own project, launch an instance from it, and Barbara OS provisions itself on first boot.

The gcp_amd64 image is a UEFI, x86_64, GPT disk image built for Google Compute Engine. It ships with the VirtIO network and virtio-scsi storage drivers built into the kernel and exposes a serial console, so it boots headless on a GCE VM and is managed entirely through Barbara — there is no SSH key injection and no cloud-init, and the only Google agent it ships (the OS Config agent) is restricted to read-only OS inventory.

The procedure has five phases:

  1. Install the prerequisites in your Google Cloud project.
  2. Download the GCP image from Barbara Panel.
  3. Upload the image tarball to Cloud Storage.
  4. Create a private Compute Engine image from it.
  5. Launch the instance, read the Barbara ID, and register the node in Panel.

Pre-requisites​

  • An active Google Cloud project — billing enabled and no organization-policy restrictions blocking Compute Engine or Cloud Storage.

  • The Google Cloud CLI (gcloud, which bundles gsutil), installed and authenticated (gcloud auth login and gcloud config set project <project>).

  • The Compute Engine and Cloud Storage APIs enabled:

    gcloud services enable compute.googleapis.com storage.googleapis.com

  • A Cloud Storage bucket in your target region to stage the image.

  • IAM roles for the workflow: roles/storage.admin (upload to GCS), roles/compute.storageAdmin (create the image), roles/compute.instanceAdmin.v1 (create/read VMs), and roles/iam.serviceAccountUser on the Compute Engine default service account (required for instances create).

  • The Barbara OS image for GCP (gcp_amd64), downloaded from Barbara Panel — see the OS Images view.

Instance requirements​

The image boots in UEFI mode with a GPT disk, so the Compute Engine image must be created with the UEFI_COMPATIBLE guest OS feature (see Create the image). Launch it with the default VirtIO NIC — do not select gVNIC (its gve driver is not built into the kernel). Secure Boot must be off (the image is UEFI but not signed for Secure Boot).

Strict minimum​

  • RAM: 2 GB
  • Boot disk: 32 GB
  • vCPU: 2
  • Architecture: x86_64
  • RAM: 4 GB
  • Boot disk: 64 GB
  • vCPU: 2
  • Architecture: x86_64

An e2-small (2 vCPU / 2 GB) meets the minimum; e2-medium (2 vCPU / 4 GB) matches the recommendation.

note

The factory image is a 16 GB disk, which is smaller than the 32 GB minimum, so set --boot-disk-size to at least 32 GB when you create the instance. On first boot, Barbara OS creates and expands the user data partition to fill the boot disk, so choose a boot disk large enough for your workloads: the extra space becomes usable storage automatically.

Download the image from Panel​

Download the gcp_amd64 image from the OS Images view in Barbara Panel (see OS Images view). The GCP image is a gzipped tarball whose name follows the <device>-<environment>-<version>-<build>.tar.gz pattern — for example gcp_amd64-pro-4.9.0-1784214128.tar.gz.

The tarball contains a single raw disk image named exactly disk.raw — this is exactly the format Compute Engine consumes, so do not extract it. The commands below use <gcp-image>.tar.gz as a placeholder; substitute the actual filename.

Upload the image to Cloud Storage​

Copy the tarball to your staging bucket:

gcloud storage cp <gcp-image>.tar.gz gs://<your-bucket>/

Create the image​

Create a private Compute Engine image directly from the tarball in Cloud Storage:

gcloud compute images create barbara-gcp \
  --source-uri gs://<your-bucket>/<gcp-image>.tar.gz \
  --guest-os-features=UEFI_COMPATIBLE
  • barbara-gcp — the image name; pick one that fits your inventory. It must be RFC 1035-compliant (lowercase letters, digits and hyphens; no dots or underscores).
  • --source-uri — the gs:// path of the tarball you uploaded.
  • --guest-os-features=UEFI_COMPATIBLE — required: gcp_amd64 is a UEFI/GPT image, and Compute Engine boots it in UEFI mode only when the image carries this feature.

Image creation takes a couple of minutes while Compute Engine processes the disk.raw. Check that the feature stuck before launching anything from the image, because it cannot be added afterwards:

gcloud compute images describe barbara-gcp --format='value(guestOsFeatures[].type,status)'

Expect UEFI_COMPATIBLE and READY.

Use images create --source-uri, not images import

gcloud compute images import runs a Cloud Build translation workflow that inspects and adapts the guest OS, needs a much larger set of roles, and rejects custom builds. Barbara OS is a custom build and the tarball is already GCE-ready, so use images create --source-uri, which ingests the raw disk directly.

Created the image without UEFI_COMPATIBLE?

If you forgot the --guest-os-features flag, the image boots in BIOS mode and the UEFI/GPT disk will not start. Guest OS features can't be changed on an existing image, but you don't need to re-upload the tarball — derive a new image from the existing one with the feature added, then launch from the derived image:

# check whether an image already has it:
gcloud compute images describe <image> --format="value(guestOsFeatures[].type)"

# derive a UEFI-enabled image from the existing one (no re-upload):
gcloud compute images create barbara-gcp-uefi \
  --source-image barbara-gcp \
  --guest-os-features=UEFI_COMPATIBLE

A VM already created from a non-UEFI image can't be switched to UEFI — recreate it from the UEFI image.

Launch the instance​

Launch an instance from the image:

gcloud compute instances create barbara-node \
  --image barbara-gcp \
  --zone <zone> \
  --machine-type e2-small \
  --boot-disk-size 64GB
  • --machine-type e2-small — any standard type works; size it to your workload.
  • --boot-disk-size — set the boot disk size (in GB); the data partition grows into it on first boot.
  • Leave the NIC at its default (VirtIO). Do not enable Secure Boot (--shielded-secure-boot) — the image is UEFI but not Secure-Boot-signed; --shielded-vtpm / integrity monitoring are fine.
  • The agent only needs outbound connectivity (to the Barbara Panel MQTT broker, the container registry, and the image/OTA storage). No inbound ports are required for normal operation — see From the agent API if you want to query the Barbara ID over the network, which needs an inbound firewall rule.

On first boot, Barbara OS binds its disk encryption to the instance's SMBIOS identity (product_uuid and product_serial), creates the cache and data partitions, and grows data to fill the boot disk.

That first boot also decrypts the agent's own binaries, which is CPU-bound, so on the shared-core types (e2-micro, e2-small) the node takes noticeably longer to appear in Panel than on the recommended e2-medium. An instance that reports RUNNING but has not shown up yet is usually still working through that step, so read the serial console before concluding that something failed.

warning

Register the factory image and launch each instance from it. The disk encryption key is derived on first boot and tied to that instance's identity, so do not create an image from an already-initialized instance's disk and reuse it — the copy stays bound to the original instance and will not decrypt elsewhere.

Retrieve the Barbara ID and register the node​

To add the node to Barbara Panel you need its Barbara ID — a unique identifier of the form gcp_amd64-<hex>, derived on first boot from the instance's SMBIOS identity. On a headless GCE VM you read it from the agent's local HTTP API: the image is headless (no display device, so no on-screen QR), and the ID is not printed to the serial console.

From the agent API (programmatic)​

Before the node is registered, the agent exposes a small HTTP API on TCP port 18100 that returns the Barbara ID as JSON:

curl -s http://<external-ip>:18100/device/barbaraId
# {"barbaraId":"gcp_amd64-5262355a6184a160726cdc5ed3caa72b"}

# just the value:
curl -s http://<external-ip>:18100/device/barbaraId | jq -r .barbaraId

The GCE default firewall does not open 18100, so add a temporary, scoped rule to reach it from your workstation, then remove it:

MYIP=$(curl -s https://api.ipify.org)
gcloud compute firewall-rules create allow-barbara-agent-18100 \
  --network=default --direction=INGRESS --action=ALLOW \
  --rules=tcp:18100 --source-ranges="${MYIP}/32"

curl -s http://<external-ip>:18100/device/barbaraId

gcloud compute firewall-rules delete allow-barbara-agent-18100 -q
Availability and access
  • This API is available only until the node is registered in Panel. Once you register it, the API shuts down and the port closes, so query it during onboarding.
  • It is unauthenticated. Scope the firewall rule to a trusted source IP/CIDR (your operator workstation) — never 0.0.0.0/0 — and delete it once you have the ID.

Watch the boot (serial console)​

For boot-level troubleshooting — not for the Barbara ID — the image logs the whole boot to the serial console (ttyS0), which you can read without any inbound rule:

gcloud compute instances get-serial-port-output barbara-node --zone <zone> --port 1
VM Manager and gcloud compute ssh

The image bundles the Google OS Config agent in an inventory-only build. Using it is optional — Barbara nodes are managed entirely from Barbara Panel, and the only VM Manager feature available here is the read-only OS inventory (installed packages, OS version) in the GCP console. OS policies and patch execution are disabled by internal Barbara policy — turned off inside the agent binary and not re-enableable from GCP metadata, so the node is never remotely reconfigured or patched from Google Cloud.

If you do want the VM Manager → "OS information" panel, enable VM Manager on your project — Console → Compute Engine → VM Manager → Enable, or:

gcloud services enable osconfig.googleapis.com
gcloud compute project-info add-metadata --metadata=enable-osconfig=TRUE

Until VM Manager is enabled the panel reads "OS information not available" even though the agent is running; once enabled it populates a few minutes later.

Barbara OS ships no Google guest agent, so metadata-based SSH-key injection (used by gcloud compute ssh) is not available — manage the node through Barbara Panel and use the serial console for boot-level inspection.

For the full set of ways to find a node's identifier, see Get the Barbara ID of the node.

Summary​

You have uploaded the gcp_amd64 image to Cloud Storage, created a private Compute Engine image, launched it on a standard GCE VM, and let Barbara OS self-provision and bind its encryption on first boot. With the Barbara ID in hand, the next step is to add the node to Barbara Panel.