Skip to main content

Virtual Machine

VirtualMachine​

Defines a managed virtual machine or a stateful VM cluster.

Provisions compute capacity from a VirtualMachineConfiguration template.

PropertyTypeDescription
apiVersionstringAPI schema version. Must be lowops.manifests.v1.
kindstringResource kind. Must be VirtualMachine.
metadatamapReserved keys such as name and project resolve the manifest identity and its parent Project.
specSpecUser-authored specification of the virtual machine. See Spec.

BucketConfigsEntry​

PropertyTypeDescription
keystring
valueComputedVirtualMachineBucketConfig

DiskConfigsEntry​

PropertyTypeDescription
keystring
valueComputedVirtualMachineDiskConfig

Spec​

User-provided virtual machine configuration.

Sets machine size, clustering, mesh strategy, health probes, autoscaling and service account access.

PropertyTypeDescription
descriptionstringOptional free-text description. The engine copies it to the instance template and managed instance group descriptions.
machineTypestringCompute machine type, for example e2-standard-4.
meshStrategystringService mesh integration. SIDECAR deploys a proxy sidecar. PROXYLESS uses gRPC libraries and no sidecar. DISABLED and EXCLUDED keep the VM out of the mesh and create no routing.
statefulStatefulStateful clustering. When omitted, scaling governs the VM as a stateless autoscaled group. See Stateful.
configurationConfigurationTemplate reference and boot-time injection. See Configuration.
healthHealthHealth probe settings. When unset, the instance has no application health check. See Health.
portslist of PortsEntryMap of port number to protocol (for example http, grpc). Each entry creates mesh routing and backend service configuration. When empty, the engine creates no routing.
accessControlApplicationAccessControlConfigPermissions of the VM service account over other resources, such as secrets, buckets and pub/sub. See ApplicationAccessControlConfig.
scalingScalingAutoscaling of stateless VMs. For stateful VMs, use stateful.clusterSize. See Scaling.

Configuration​

Base configuration and runtime injection.

Selects the VirtualMachineConfiguration template and injects variables, secrets and volume mounts at boot.

PropertyTypeDescription
sourcestringName of the VirtualMachineConfiguration that supplies the operating system and base startup script. Required.
variableslist of VariablesEntryVariables for the startup script. A value overrides the defaultValue of the matching variable in the VirtualMachineConfiguration. The engine rejects shell metacharacters (;, &, `
secretslist of SecretsEntryMap of environment-variable name to Secret manifest name, injected into the startup script. The engine also provisions the default secrets that the referenced configuration declares.
volumeMountslist of VolumeMountsEntryMap of in-VM mount path (for example /data) to volume source, combined with the volumes of the referenced VirtualMachineConfiguration. See VirtualMachineVolumeMount.

SecretsEntry​

PropertyTypeDescription
keystring
valuestring

VariablesEntry​

PropertyTypeDescription
keystring
valuestring

VolumeMountsEntry​

PropertyTypeDescription
keystring
valueVirtualMachineVolumeMount

Health​

Application health probes.

Startup and liveness probes for the application on the VM.

PropertyTypeDescription
startupHostHealthConfigNOT YET IMPLEMENTED. The engine ignores this field. The VM health check comes from liveness. See HostHealthConfig.
livenessHostHealthConfigHealth check settings of the VM. They drive the health check of the instance backend service and the auto-healing of the managed instance group. See HostHealthConfig.

PortsEntry​

PropertyTypeDescription
keyint32
valuestring

Scaling​

Autoscaling bounds for stateless VMs.

Sets the size range of the instance group autoscaler. Ignored for stateful VMs.

PropertyTypeDescription
minint32Minimum number of instances. Applied only when greater than 0. The default is 1.
maxint32Maximum number of instances. Applied only when greater than 0. The default is 10.

Stateful​

Stateful cluster topology.

Runs the VMs as a stateful managed instance group instead of a stateless autoscaled group.

PropertyTypeDescription
enabledboolIf true, the VMs run as a stateful managed instance group with persistent disks and stable network identities. If false, a stateless autoscaled group runs the VMs.
clusterSizeint32Number of instances in the stateful cluster. Applies only when enabled is true. For stateless VMs, use scaling.min and scaling.max.
allowTcplist of int32NOT YET IMPLEMENTED. The engine ignores this field. Intended use: TCP ports open between the cluster instances.
healthHostHealthConfigNOT YET IMPLEMENTED. The engine ignores this field. Intended use: the health probe that gates and repairs cluster members. See HostHealthConfig.

ApplicationAccessControlConfig​

All external access rules of an application.

Each block adds IAM bindings, SQL grants, or secret access.

PropertyTypeDescription
additionalRoleslist of stringExtra IAM roles for the application service account, beyond the roles from the other blocks.
pubsubApplicationAccessControlPubsubConfigPublish and subscribe grants for specific Pub/Sub topics.
bucketslist of ApplicationAccessControlBucketConfigCloud Storage buckets that the application can read or write.
databaseApplicationAccessControlDatabaseConfigPostgreSQL database access: instance, schema, privileges, and credential source.
secretslist of SecretsEntryMap from Secret manifest name to how the application gets the secret.
redislist of ApplicationAccessControlRedisConfigRedis instances that the application can use.
jobslist of ApplicationAccessControlJobConfigCloud Run Jobs of other applications that this application can trigger with the RunJob API.

VirtualMachineVolumeMount​

Mount of a volume in a VM application.

Sets the mount instructions (fstab entries or FUSE attachments) on the VM.

PropertyTypeDescription
sourcestringVolume source. Same as DiskSnapshotConfiguration.source.
mountOptionslist of stringExtra mount options. The engine joins them into the mount command.
diskConfigVirtualMachineVolumeMountDiskConfigSize, type, and snapshot settings for a DISK mount.

ComputedVirtualMachineBucketConfig​

Computed bucket mount for a VM.

Links the VM configuration to the bucket that Cloud Storage FUSE mounts.

PropertyTypeDescription
sourcestringResolved bucket to mount. It comes from the volume name in the VirtualMachineConfiguration manifest.
mountOptionsstringFUSE mount option string. The engine computes it from the VM operating system.

HostHealthConfig​

Health check for host endpoints.

Sets the probes and backend health checks for GCP load balancers.

PropertyTypeDescription
protocolstringHealth check protocol: http, http2, https, grpc, or tcp. It applies to container probes (Cloud Run, GKE) and the VM backend health check.
portint64TCP port that the health check targets.
checkIntervalSecint64Interval between checks, in seconds. The default is 30 for generated probes. Default 30
timeoutSecint64Seconds to wait for a probe response before it fails. The engine sets 10 for generated probes. Default 5
healthyThresholdint64Consecutive successful probes that mark the endpoint healthy. The default is 1. Default 1
unhealthyThresholdint64Consecutive failed probes that mark the endpoint unhealthy. The default is 2. Default 2
enableLogsboolNOT YET IMPLEMENTED. The engine ignores this field. Intended to enable health-check logs.
pathstringHTTP request path for HTTP-family probes. The default is /. Default "/"

ComputedVirtualMachineDiskConfig​

Computed specification of a VM attached disk.

Combines size, snapshot, and filesystem details.

PropertyTypeDescription
namestringResolved disk name, from the volume name in the VirtualMachineConfiguration manifest.
fileSystemstringDisk filesystem, from the volume fileSystem in the VirtualMachineConfiguration manifest.
mountOptionsstringDisk mount option string. The engine computes it from the filesystem and VM operating system.
sourceSnapshotstringSource snapshot, from the volume mount sourceSnapshot in the VirtualMachine manifest.
encryptedboolDisk encryption flag, from the volume encrypted in the VirtualMachineConfiguration manifest.
diskSizeGbint64Disk size, in GB, from the volume mount diskSizeGb in the VirtualMachine manifest.
diskTypestringCompute Engine disk type, from the volume mount diskType in the VirtualMachine manifest.

SecretsEntry​

PropertyTypeDescription
keystring
valueSecretSourceConfig

ApplicationAccessControlRedisConfig​

Redis cache access for a workload.

Injects the connection URL as an environment variable. All instances use TLS (SERVER_AUTHENTICATION).

PropertyTypeDescription
namestringName of the Redis manifest. The application deploys after the DNS record of the instance resolves. Required.
envVarstringEnvironment variable that receives the connection URL redis[s]://memory-<redis-name>.<internal-domain>:<port>. Meshed strategies (SIDECAR, PROXYLESS) use redis:// on port 6380. Direct access (DISABLED) uses rediss:// on port 6379. Required.
caCertPathstringAbsolute path in the container of the server CA certificate (PEM). The application must load it into its TLS trust pool. Required.

VirtualMachineVolumeMountDiskConfig​

Specification of an attached disk volume.

Sets the size and type of the disk behind the mount.

PropertyTypeDescription
sizeGbint64Disk size, in GB. Only for DISK volumes. The minimum is 200 GB.
typestringCompute Engine disk type, for example pd-ssd. Only for DISK volumes.
snapshotslist of DiskSnapshotConfigurationOptional snapshot configurations that seed the disk in specific environments.

ApplicationAccessControlDatabaseConfig​

PostgreSQL access for a workload.

Runs CREATE USER and GRANT on the target SQL instance.

PropertyTypeDescription
namestringName of the Database manifest (an AlloyDB/PostgreSQL instance) that the application needs.
schemastringDatabase (schema) in the instance that the application connects to.
privilegeslist of stringSQL privileges for the application database role on the schema: USAGE, CREATE, or ALL. Each one becomes a GRANT statement.
readOnlyboolIf true, the application has read-only access, typically to a read replica.
extensionslist of stringPostgreSQL extensions to enable. Each entry runs CREATE EXTENSION IF NOT EXISTS. The engine merges the lists of all applications that share a schema.
secretSourceSecretSourceConfigSource of the database credentials: the Secret manifest and how the application gets it (environment variable or file mount). Required.

ApplicationAccessControlBucketConfig​

Cloud Storage access for a workload.

Grants roles/storage.objectViewer or roles/storage.objectUser on a bucket.

PropertyTypeDescription
namestringName of the Bucket manifest. It must exist in every environment of the parent ReleaseTrack. Required.
sourcestringName of a GithubRepository manifest whose contents seed the bucket through a gcloud storage rsync job in CI/CD. Optional.
permissionstringREAD_ONLY grants roles/storage.objectViewer. WRITE grants roles/storage.objectUser.
mountPathstringAbsolute path in the container where Cloud Storage FUSE mounts the bucket. If omitted, the engine grants access but does not mount the bucket.
subPathstringBucket prefix that limits access, for example to mount one folder. If omitted, access covers the whole bucket.
promoteboolIf true, the engine promotes the bucket content through the ReleaseTrack with the application.
envVarstringEnvironment variable that receives the bucket name, instead of a filesystem mount. Mutually exclusive with mount_path.

ApplicationAccessControlPubsubConfig​

Pub/Sub permissions for a workload.

The engine grants the roles to the service account of the workload.

PropertyTypeDescription
publishTolist of stringNames of PubSub manifests that the workload can publish to. Each entry grants roles/pubsub.publisher on the topic.
subscribeTolist of stringEach entry, a PubSub manifest name, grants roles/pubsub.subscriber on the TOPIC. On a topic, this role only gives pubsub.topics.attachSubscription. The workload can attach a subscription, but it cannot pull from or acknowledge on any subscription, even a managed one in spec.subscriptions. To create a subscription, the workload also needs pubsub.subscriptions.create on the project, which this field does not grant. To consume from a managed subscription, use pull_from. The behavior stays unchanged for old manifests.
pullFromlist of ApplicationAccessControlPubsubPullConfigEach entry grants roles/pubsub.subscriber on one subscription from spec.subscriptions of a PubSub manifest, and nothing on the topic or the project. The topic and subscription must exist in the project of the workload, or validation fails. See ApplicationAccessControlPubsubPullConfig.

ApplicationAccessControlJobConfig​

Permission to trigger a Cloud Run Job of another application.

Grants roles/run.developer on the job and injects the job resource name as an environment variable.

PropertyTypeDescription
applicationstringName of the Application manifest that owns the target job. Required.
jobstringName of the job. It matches an ApplicationJobReference.name of that application. Required.
envVarstringEnvironment variable for the full Cloud Run resource name of the job. If empty, the caller must derive the job name.

ApplicationAccessControlPubsubPullConfig​

Pub/Sub subscription that a workload consumes.

Grants roles/pubsub.subscriber on a subscription or its dead-letter subscription.

PropertyTypeDescription
topicstringName of the PubSub manifest (topic) that declares the subscription. Required.
subscriptionstringName of the subscription in spec.subscriptions of that manifest. Required.
deadLetterboolIf true, the grant targets the dead-letter subscription <topic>-<subscription>-dlq-sub. The subscription must declare deadLetter. To republish messages, the worker also needs the topic in publish_to.

DiskSnapshotConfiguration​

Source snapshot for an environment.

The snapshot link for a new compute disk of a VM.

PropertyTypeDescription
sourcestringFor a BUCKET volume, the bucket name to mount. For a DISK volume, an optional Compute snapshot self-link.
mountOptionslist of stringExtra mount options, for example FUSE or fstab flags.
diskConfigDiskSnapshotDiskConfigSize, type, and per-environment snapshot sources for a DISK volume.

SecretSourceConfig​

How to retrieve a secret and mount it into a workload.

The engine grants IAM access to the Secret Manager payload and resolves values JIT.

PropertyTypeDescription
envVarstringName of the environment variable that holds the secret. Mutually exclusive with file_path: set exactly one.
versionstringSecret Manager version: latest or a number such as 1. Defaults to latest.

DiskSnapshotDiskConfig​

Properties of a disk created from a snapshot.

Sets the size and type of the disk.

PropertyTypeDescription
sizeGbint64Disk size, in GB. Only for DISK volumes.
typestringCompute Engine disk type, for example pd-ssd. Only for DISK volumes.
snapshotslist of SnapshotsEntryMap from environment name to the source snapshot self-link in that environment.

SnapshotsEntry​

PropertyTypeDescription
keystring
valuestring