Compute Engine
Compute Engine uses its native REST v1 paths under /compute/v1/projects/{project}
on port 4588. Configure SDK endpoints explicitly and use synthetic credentials.
By default the emulator does not execute virtual machines or forward network traffic.
With FLOCI_GCP_SERVICES_COMPUTE_MOCK=false each instance runs as a Docker container;
see Instance containers.
Set FLOCI_GCP_SERVICES_COMPUTE_ENABLED=false to disable the service.
FLOCI_GCP_SERVICES_COMPUTE_OPERATION_DELAY_MS defaults to 50 ms.
Regions and zones come from the bundled location catalog: all 43 regions and
their 130 real zones (for example us-central1-f and europe-west1-d). To serve fewer regions,
set FLOCI_GCP_SERVICES_COMPUTE_REGIONS to a comma-separated list, such as
us-central1,europe-west1. Each listed region keeps its real zones from the catalog. Unset or
empty serves the whole catalog. Any region or zone outside that set returns 404.
Machine, accelerator and disk catalogs are a small deterministic fixture catalog,
not an assertion of current Google availability, quotas or pricing.
Resources and operations share a project-scoped checkpoint through StorageFactory. Normal writes are validated against a private snapshot before committing. Operation completion is advanced when the project is read, using persisted timestamps, so polling and restart recovery do not depend on a request-scoped background thread. Resource metadata changes are committed when the operation is accepted; lifecycle status becomes final at operation completion. No guest progress is measured.
Networking and operations
Custom-mode networks, regional subnetworks, firewall rules, and global/regional IPv4 addresses support insert/get/list/delete. Firewalls also support updates. Subnet overlap, scope, references, firewall ports and dependent-resource deletion are validated. External addresses come from the documentation-only 203.0.113.0/24 range. Auto-mode VPCs, IPv6, Shared VPC and cross-project references are unsupported, except public images.
Global, regional and zonal operations support get/list/wait/delete. A wait may
return an unfinished operation, which clients must continue polling. Nonzero UUID
request IDs deduplicate mutations. Operation responses use Compute's status,
targetLink and scope fields, not google.longrunning.Operation.
Inventory supports maxResults, opaque pageToken, name ordering and descending
creation time. Filters support equality/inequality/existence on name, id, status,
family and labels, combined with AND. Other expressions fail explicitly. Tokens
are bound to project, collection, scope, filters and ordering. Inventory is not a
snapshot across concurrent writes.
projects.get returns the project's Compute resource: its number as id, the
default Compute service account, and commonInstanceMetadata.
projects.setCommonInstanceMetadata replaces that metadata through a global
operation. It needs the current fingerprint, so a missing or stale one fails with
412 (conditionNotMet). Keys must match [a-zA-Z0-9-_]{1,128}, values must be
strings of at most 256 KiB, and keys must be unique. The other project methods
(usage export, default network tier, Shared VPC, moves) are unsupported.
Public interfaces follow the Compute REST reference. Credential acceptance retains the emulator's existing auth bypass; resource isolation is not IAM enforcement.
IAM policies
Instances, disks, images, snapshots, subnetworks and resource policies support
getIamPolicy, setIamPolicy and testIamPermissions. These return directly, without
an operation. setIamPolicy takes {"policy": ...} or the deprecated flat bindings
and etag, and a stale etag fails with 409. A numeric ID reaches the same policy as
the resource name. Deleting a resource deletes its policy, including a boot disk removed
with its instance, so a recreated name starts empty.
Policies are stored but not enforced: Compute calls are never denied because of them, and
testIamPermissions returns every permission requested. Public images have no policies:
these methods return 403 on them. Other collections return 501.
Machine types
machineTypes serves a fixed catalog with the published vCPU and memory values:
| Series | Types |
|---|---|
| E2 | e2-micro, e2-small, e2-medium; e2-standard 2 to 32; e2-highmem 2 to 16; e2-highcpu 2 to 32 |
| N1 | n1-standard 1 to 96 |
| N2 | n2-standard 2 to 128; n2-highmem 2 to 128; n2-highcpu 2 to 96 |
| N2D | n2d-standard 2 to 224 |
| T2D | t2d-standard 1 to 60 |
| C3 | c3-standard 4 to 176 |
| G2 | g2-standard 4 to 96, each with its NVIDIA L4 count |
isSharedCpu is true for the e2-micro, e2-small and e2-medium types. Custom machine
types and -lssd variants are not available, so an instance using one fails with 404.
Instances and disks
Zonal instances support insert/get/list/aggregatedList/start/stop/reset/delete, setMachineType, setMetadata, setTags, setLabels, addAccessConfig/deleteAccessConfig, attachDisk/detachDisk, setDiskAutoDelete and getSerialPortOutput (see Serial port output). A stopped VM has status TERMINATED; reset does not imply guest health. One IPv4 NIC and one boot disk are required. Machine changes require a stopped VM. Ephemeral external addresses are released on stop; reserved addresses remain associated.
Zonal disks support insert/get/list/aggregatedList/delete/resize/update/setLabels. Attached disks cannot be deleted. Deleting an instance retains disks unless their attachment enables autoDelete. Disk sizes and source sizes are validated. Only supported Hyperdisk types accept provisioned IOPS/throughput; unsupported knobs fail. Performance limits are basic API checks, not complete machine/disk quota or size-ratio emulation. Multi-writer disks and regional disks are unsupported.
Resource policies
Regional resourcePolicies support insert/get/list/aggregatedList/patch/delete with
instanceSchedulePolicy (vmStartSchedule, vmStopSchedule, timeZone, startTime,
expirationTime) and snapshotSchedulePolicy (hourly, daily or weekly schedule,
retentionPolicy, snapshotProperties). Exactly one policy type is required; other
types (group placement, workload) fail explicitly. Policies are stored as sent and
report status READY; hourly and weekly startTime values such as 9:00 come back
zero-padded (09:00).
Schedules are validated but never executed, in both modes: no VM is started or stopped
and no snapshot is taken, even when instances run as
containers (FLOCI_GCP_SERVICES_COMPUTE_MOCK=false). To act on
a schedule in a test, call instances.start/stop or snapshots.insert with a
sourceDisk yourself.
Validation follows the API reference: instance schedules take five-field unix-cron
expressions and a tz database timeZone. A daily snapshot schedule needs
daysInCycle 1 and a startTime that resolves in UTC to 00:00, 04:00, 08:00, 12:00,
16:00 or 20:00 (08:00, or 13:00-5 with an hour offset). Hourly and weekly
startTime must be on the hour (HH:00). hoursInCycle takes 1 to 23.
patch without updateMask applies the body as a JSON merge patch, as for other
Compute patch methods: objects merge field by field, null removes a field and arrays
are replaced. This is what both clients rely on: gcloud's update commands send only
the changed fields, and Terraform sends whole objects. A snapshot schedule cadence in
the body (hourlySchedule, dailySchedule or weeklySchedule) replaces the stored
cadence, so the schedule can switch from daily to hourly. With updateMask, only the
listed paths change and a listed path missing from the body is cleared. The name and
the policy type cannot change, and attached policies stay attached.
Instances accept instance schedule policies and disks accept snapshot schedule policies,
either in resourcePolicies on insert (including disk initializeParams) or through
addResourcePolicies / removeResourcePolicies. The policy must exist in the same
region as the instance or disk, and at most one policy can be attached to a resource.
resourcePolicies is returned as self links on get and list. Deleting a policy that is
still attached fails with resourceInUseByAnotherResource.
Images and snapshots
Global images support sources from disks, images and snapshots, family lookup, labels, inventory and deletion. Global standard snapshots support disk sources, labels, inventory and deletion. Source identity and size survive source deletion; restored disks cannot be smaller than their source. Images do not acquire invented backing snapshots. Copying a snapshot means restoring a disk and snapshotting it. Guest disk bytes and regional/instant snapshots are not emulated.
Public images
The public image projects debian-cloud, ubuntu-os-cloud, rocky-linux-cloud,
centos-cloud and cos-cloud serve a small read-only catalog, with one current
image per family. Any project can boot from these images, or copy them into an
image of its own:
| Project | Families |
|---|---|
debian-cloud |
debian-13, debian-13-arm64, debian-12, debian-12-arm64, debian-11 |
ubuntu-os-cloud |
ubuntu-2404-lts-amd64, ubuntu-2404-lts-arm64, ubuntu-2204-lts, ubuntu-2204-lts-arm64 |
rocky-linux-cloud |
rocky-linux-9, rocky-linux-8 |
centos-cloud |
centos-stream-9 |
cos-cloud |
cos-stable, cos-121-lts |
images.get, images.list (including filter) and images.getFromFamily work in
those projects. A boot disk created from a family
(projects/debian-cloud/global/images/family/debian-12) records the concrete image
(debian-12-bookworm-v20261001) in sourceImage, as GCP does. Image names follow
Google's naming, so Terraform's image = "debian-cloud/debian-12" resolves and
shows no diff on later plans. Writes into a public project, and reads of anything
other than its images, return 403. Image versions are fixed: there are no deprecated
or older images, licenses or guest OS features.
Global external application load balancer
Zonal GCE_VM_IP_PORT endpoint groups support endpoint attach/detach/list. Global HTTP health checks, EXTERNAL_MANAGED backend services, URL maps, HTTP target proxies and TCP forwarding rules support configuration and ordered cleanup. Backend and URL-map updates require current fingerprints. Path matchers, host rules, pathRules and session-affinity configuration are validated; actual request routing, health checks, TLS certificates, regional load balancing and advanced routeRules are not implemented. Endpoint membership is stored separately from the public NEG resource.
Address ownership and release
Global external HTTP forwarding rules can share a PREMIUM IPv4 address when their TCP ports do not overlap. Ownership uses complete resource links, and deleting one rule preserves every other owner. A forwarding rule's IP address is immutable; changing it requires replacing the rule.
Deleting an in-use address reservation through the API releases the reservation, not the IP attached to its instance or forwarding rule. The attached address remains unavailable to the allocator until the consumer releases it. This follows Google's API release semantics, which differ from the Cloud console's restriction on releasing in-use addresses.
Instance containers
Set FLOCI_GCP_SERVICES_COMPUTE_MOCK=false to back every instance with a Docker
container. This mode is opt-in, and it needs the Docker socket, as GKE and Cloud
Run do. The API stays the same in both modes; only these behaviours change:
| API call | Container |
|---|---|
instances.insert |
Pulls the boot image's Docker image (status PROVISIONING), then creates and starts the container (STAGING). The operation reaches DONE and the instance RUNNING once the container is up |
instances.stop |
docker stop, then TERMINATED. The stopped container is kept, as a stopped VM keeps its boot disk |
instances.start |
docker start of the kept container, or a new one if it is gone |
instances.reset |
docker restart |
instances.setMachineType |
Removes the stopped container, so the next start creates one with the new limits |
instances.delete |
docker rm -f |
Resource policy instance schedules do not start or stop containers; see Resource policies.
The container runs the boot image's Docker image with an idle init process; the
guest scripts below and anything you start with docker exec -it <container> bash
run inside it, and the metadata server is available to it, as
is SSH. The
container is named floci-gcp-compute-<project>-<zone>-<instance> and carries
the resource identity labels
with io.floci.service=compute. With FLOCI_GCP_SERVICES_COMPUTE_INSTANCE_RESOURCE_LIMITS
on (the default), it is limited to the machine type's vCPUs and memory.
Images. The boot disk's source image picks the Docker image. A bundled
catalog matches on the image's family first, then on its name prefix:
debian-12 maps to debian:12, ubuntu-2204-lts to ubuntu:22.04,
rocky-linux-9 to rockylinux:9, and so on. Anything else runs
FLOCI_GCP_SERVICES_COMPUTE_DEFAULT_IMAGE (debian:12), with a warning in the log.
To use your own mapping, point FLOCI_GCP_SERVICES_COMPUTE_IMAGE_CATALOG_PATH at a
JSON file in the same format as compute/image-catalog.json:
{"images": [{"family": "golden", "prefixes": ["golden-"], "dockerImage": "registry.local/golden:1"}]}
Failures. If Docker is unreachable, the pull fails, or the container is not
up within FLOCI_GCP_SERVICES_COMPUTE_LAUNCH_TIMEOUT (5 minutes), the instance
still reaches RUNNING, without a container, and a warning is logged. The API
never fails because of Docker.
Restarts. On shutdown, floci-gcp stops the running instance containers. On
startup it starts the containers of RUNNING instances again, keeps those of
TERMINATED instances, and removes those whose instance was deleted. It only
touches containers that carry its own io.floci.owner label, so several
emulators can share one Docker daemon.
Startup and shutdown scripts
On every boot (insert, start and reset), the instance runs startup-script and
then startup-script-url, as root, as the guest environment's
google_metadata_script_runner does. Instance metadata overrides project metadata
(projects.setCommonInstanceMetadata) key by key. Each script is copied to
/var/lib/google/<key> and run verbatim; one without a shebang runs under
/bin/sh. startup-script-url is read from floci-gcp's own Cloud Storage
(gs://BUCKET/FILE or https://storage.googleapis.com/BUCKET/FILE); other URLs are
reported and skipped. The boot's operation does not wait for the scripts, and a
script still running after FLOCI_GCP_SERVICES_COMPUTE_STARTUP_SCRIPT_TIMEOUT
(30 minutes) is reported and left running.
shutdown-script and shutdown-script-url run on stop and delete while the
instance is STOPPING, for up to FLOCI_GCP_SERVICES_COMPUTE_SHUTDOWN_SCRIPT_TIMEOUT
(90 seconds). Reset is a hard reset and runs none.
cloud-init
On images that ship cloud-init (Ubuntu and Container-Optimized OS), an instance
with a user-data metadata key runs cloud-init on every boot, around its startup
scripts as on Compute Engine: the local, network and config stages run before
them, and the final stage (packages, runcmd, #! scripts) after them and
after a declared container starts, since cloud-final.service waits for
multi-user.target. A startup script therefore cannot rely on what runcmd
sets up. Only the instance's own user-data counts, as with cloud-init's GCE data
source; user-data-encoding: base64 is decoded. Any format cloud-init accepts
works: #cloud-config, #! scripts, MIME multipart, gzip.
gcloud compute instances create web --zone us-central1-a \
--image-family ubuntu-2404-lts-amd64 --image-project ubuntu-os-cloud \
--metadata-from-file user-data=cloud-config.yaml
The container gets cloud-init from its package manager on the first boot that
needs it, so that boot needs network access. The user-data and meta-data
(instance-id is the instance's id, local-hostname its name) are written to the
NoCloud seed /var/lib/cloud/seed/nocloud, because cloud-init's GCE data source
only runs on Google hardware. The output of every stage and cloud-init status
go to serial port 1 under cloud-init[1].
- Per-instance modules (
runcmd,write_files,packages,#!scripts) run once per instance and not again after a stop and start or a reset, as the boot disk keeps cloud-init's records. On Container-Optimized OS,write_filesandruncmdrun on every boot, as Google documents for that image. - Docker owns the container's network and hostname, so cloud-init leaves both alone
(
network: {config: disabled},preserve_hostname: true). Container images ship no locales, so thelocalemodule is off unless your cloud-config setslocale. Modules that need systemd or a real kernel, such asntporgrowpart, may fail or do nothing. - Each part of cloud-init (the early stages, then the final stage) waits up to
FLOCI_GCP_SERVICES_COMPUTE_STARTUP_SCRIPT_TIMEOUT, as the startup scripts do. Past it the boot moves on and says so on serial port 1; the final stage still waits for the early stages to finish. - The image setting comes from the image the boot disk was created from, and stays with the disk if that image is deleted later.
- Debian, Rocky Linux and CentOS images do not run it. To run it on another image,
add
"cloudInit": "per-instance"(or"every-boot") to that image's entry in your own image catalog.
SSH and published ports
A new instance container publishes port 22 and every TCP port an enabled ingress
firewall rule on the instance's network allows (a rule with targetTags only
when the instance has one of those tags), each on a host port Docker picks, up to
64 ports. The ports are reported in the log and on serial port 1:
2026-10-25T05:01:18.361Z vm floci-gcp[1]: Published ports: 22/tcp -> localhost:32770, 8080/tcp -> localhost:32771
docker port <container> 22 gives the same answer. Ports are chosen when the
container is created (insert, or the first start after setMachineType); a
firewall rule added later applies from then on. Source ranges, deny rules and
priorities are not enforced: a published port is reachable from the Docker host.
networkIP and natIP keep their Compute Engine values.
On every boot the instance applies ssh-keys as the Linux guest agent does:
- Instance keys, then project keys from
setCommonInstanceMetadata, unless the instance setsblock-project-ssh-keysto true or still uses the legacysshKeyskey. Lines areUSERNAME:KEY, optionally ending ingoogle-ssh {"userName":"USERNAME","expireOn":"TIME"}; expired and malformed lines are skipped. - Each user is created with a home directory and no password, joins the agent's
groups that exist in the image (
adm,dip,docker,lxd,plugdev,video) andgoogle-sudoers, which maysudowithout a password. Its keys go into~/.ssh/authorized_keysafter a# Added by Googleline each; lines the user added stay. - A user whose keys leave metadata keeps its account but loses those keys and
google-sudoers. - With
enable-oslogintrue (the instance value overriding the project's), accounts are left alone.
setMetadata and setCommonInstanceMetadata apply the keys again on running
instances at once. If the image has no sshd, the first boot installs
openssh-server with its package manager (apt-get, apk, dnf, microdnf or
yum), which needs network access from the container; then sshd is started. The
agent's progress goes to serial port 1 as google_guest_agent lines. Connect with
ssh -p <host port> USERNAME@localhost. OS Login, gcloud compute ssh key
pushing through OS Login, and SSH host keys in guest attributes are not
emulated.
Container VMs
An instance whose metadata has a gce-container-declaration runs the declared
container, as Container-Optimized OS does with the container startup agent
(konlet). Terraform's metadata = { gce-container-declaration = ... } and
gcloud compute instances create-with-container both set it:
spec:
containers:
- name: web
image: nginx:1.27
command: [/docker-entrypoint.sh]
args: [nginx, -g, daemon off;]
env:
- name: MODE
value: dev
volumeMounts:
- name: cache
mountPath: /var/cache/nginx
volumes:
- name: cache
emptyDir:
medium: Memory
restartPolicy: Always
On every boot, after the startup scripts, floci-gcp starts the container as a
second Docker container named floci-gcp-compute-<project>-<zone>-<instance>_klt,
in the instance container's network (konlet uses the VM's host network), so it
shares the instance's address and the metadata server knows
it as that instance. It reads image, command (the entrypoint), args (the
command), env, stdin, tty and restartPolicy (Always, the default,
OnFailure or Never), and mounts emptyDir volumes with medium: Memory as
tmpfs (read-only when the mount says readOnly: true). With
FLOCI_GCP_SERVICES_COMPUTE_INSTANCE_RESOURCE_LIMITS on, it gets the machine type's
vCPUs and memory too. securityContext.privileged is honoured only with
FLOCI_GCP_SERVICES_COMPUTE_ALLOW_PRIVILEGED_CONTAINERS=true: the container would
be privileged on the Docker host, not only inside the instance, so by default it
runs unprivileged and serial port 1 says so. Its output goes to serial port 1, one
line each behind the container's name, after konlet's own lines:
2026-10-24T15:20:01.123Z vm konlet-startup[1]: Configured container 'web' will be started with name 'floci-gcp-compute-p-us-central1-a-vm_klt'.
2026-10-24T15:20:03.456Z vm web[1]: hello
As on Compute Engine, the declaration is read at boot: a change made with
setMetadata applies at the next start or reset. Stop and delete remove the
container after the shutdown scripts; reset replaces it. A declaration konlet
would refuse (not exactly one container, an unknown restart policy, a volume
mount without its volume) is reported on serial port 1 and starts nothing; the
instance still runs.
Limitations. hostPath and gcePersistentDisk volumes are not mounted (the
serial port says so), and private registry credentials are not fetched from the
instance's service account; the image is pulled as any other floci-gcp image is.
Serial port output
instances.getSerialPortOutput serves serial port 1: the scripts' output and the
runner's progress (and a container VM's output), one line each, in this form:
2026-10-21T16:20:01.123Z vm google_metadata_script_runner[1]: Starting startup scripts.
2026-10-21T16:20:01.456Z vm google_metadata_script_runner[1]: startup-script: hello
2026-10-21T16:20:01.460Z vm google_metadata_script_runner[1]: startup-script exit status 0
start and next are byte positions across everything written, the most recent
1 MiB is kept, a negative start reads the last bytes, and bytes that are not
valid UTF-8 come back as \xNN. Ports 2 to 4 are empty, and so is port 1 in mock
mode. The output is kept in memory: it does not survive an emulator restart, and
it is dropped when the instance is deleted. Kernel and boot messages are not
emulated.
Metadata server
floci-gcp serves the GCE metadata server on its main port under
/computeMetadata/v1. Every instance container gets GCE_METADATA_HOST (and
GCE_METADATA_IP) set to the emulator's address, so the Google client libraries
and curl -H 'Metadata-Flavor: Google' "http://$GCE_METADATA_HOST/computeMetadata/v1/..."
reach it. The server answers for the instance whose container sent the request,
identified by its container IP address.
| Path | Value |
|---|---|
instance/id, name, hostname, description |
From the instance; the hostname is NAME.ZONE.c.PROJECT.internal |
instance/zone, instance/machine-type |
projects/NUMBER/zones/ZONE, projects/NUMBER/machineTypes/TYPE |
instance/image |
The boot disk's source image, projects/PROJECT/global/images/NAME |
instance/tags |
JSON array; ?alt=text gives one tag per line |
instance/attributes/KEY |
Instance metadata |
instance/network-interfaces/0/... |
ip, network, gateway, subnetmask, mac, mtu, dns-servers, access-configs/0/external-ip |
instance/disks/N/... |
device-name, index, interface, mode, type |
instance/service-accounts/{default,EMAIL}/... |
email, aliases, scopes, token, identity?audience=AUD[&format=full] |
project/project-id, project/numeric-project-id |
The project ID and number |
project/attributes/KEY |
Project metadata (projects.setCommonInstanceMetadata) |
universe/universe-domain |
googleapis.com |
Requests need Metadata-Flavor: Google and must not carry X-Forwarded-For; such
requests get 403, and unknown keys get 404. A path ending in / lists its entries,
and a directory requested without the slash redirects to it. ?recursive=true
returns JSON with camelCase keys (attribute keys and service account emails keep
their spelling), and with alt=text returns path value lines. ?alt=json returns
a single value as JSON. ?wait_for_change=true blocks until the value's ETag
differs from last_etag, or for timeout_sec
(FLOCI_GCP_SERVICES_COMPUTE_METADATA_SERVER_DEFAULT_WAIT_TIMEOUT, 300 seconds,
when absent). It is rejected on the token and on a non-recursive directory.
Tokens are stub access tokens: floci-gcp accepts any credential. Identity tokens
have Google's shape, with the requested aud and, with format=full, the
google.compute_engine claims, but they are not signed by a Google key, so only
code that skips signature verification accepts them. An instance created without
serviceAccounts has none, as on GCE.
Limitations. 169.254.169.254 and metadata.google.internal are not routed;
use GCE_METADATA_HOST. Identifying the caller by address needs the container's
own IP to reach floci-gcp. That holds when floci-gcp runs in Docker on the same
network, or directly on a Linux host. With floci-gcp on the host under Docker
Desktop, requests arrive from a proxy address and get 404.