Virtual Machine
VirtualMachine
Defines the high-level intent for a managed virtual machine or a stateful VM cluster.
Provisions raw compute capacity while abstracting underlying hypervisor complexities. Orchestrates base image selection, service mesh integration topography, stateful volume management, and the secure injection of runtime secrets and bootstrapping scripts.
| Property | Type | Description |
|---|---|---|
| apiVersion | string | API schema version. Pins the manifest to a specific schema contract for backward-compatibility. Must be the constant lowops.manifests.v1. |
| kind | string | Resource kind discriminator. Identifies this document as a VirtualMachine so the engine routes it to the correct defaulter, validator, computer, and executor. Must be the constant VirtualMachine. |
| metadata | map | Classification labels and graph linkage. Free-form key/value pairs used to classify the manifest. Certain reserved keys (e.g. name, project) are read by the engine to resolve this manifest's identity and its parent Project in the dependency graph. |
| spec | Spec | Desired virtual machine configuration. The authoritative, user-authored specification for this virtual machine. See Spec. |
BucketConfigsEntry
| Property | Type | Description |
|---|---|---|
| key | string | |
| value | ComputedVirtualMachineBucketConfig |
DiskConfigsEntry
| Property | Type | Description |
|---|---|---|
| key | string | |
| value | ComputedVirtualMachineDiskConfig |
Spec
User-provided virtual machine configuration.
Encapsulates configuration parameters for machine sizing, stateful clustering topology, mesh networking strategy, health probing, autoscaling, and access-control authorizations for the VM's service account.
| Property | Type | Description |
|---|---|---|
| description | string | Human-readable description of this virtual machine. Optional free text describing the role of this VM. Propagated onto the provisioned compute instance template and managed instance group descriptions, and used as context by AI assistants when reasoning about the manifest. |
| machineType | string | Compute machine type. The machine type for the VM instances (e.g. e2-standard-4). Translates into the physical hardware allocation profile applied to the compute instance template. |
| meshStrategy | string | Service mesh integration strategy. Determines how the VM integrates with the service mesh: SIDECAR deploys a full proxy sidecar for traffic management; PROXYLESS uses gRPC libraries for mesh connectivity without a sidecar; DISABLED and EXCLUDED keep the VM out of the mesh (no routing is generated). Read by the executor and routing logic to decide sidecar injection and backend routing. |
| stateful | Stateful | Stateful clustering settings. Configures the VM(s) as a stateful managed instance group. When omitted, the VM is provisioned as a stateless, autoscaled group governed by scaling. See Stateful. |
| configuration | Configuration | Base template and runtime injection. References the VirtualMachineConfiguration template and supplies the variables, secrets, and volume mounts injected at boot. See Configuration. |
| health | Health | Health probe settings for this VM. See Health. When unset, no application health check is configured for the instance. |
| ports | list of PortsEntry | Exposed ports and their protocols. Map of port number to protocol (e.g. http, grpc). Each entry produces mesh routing and backend service configuration so traffic can reach the application on that port. When empty, no routing is generated. |
| accessControl | ApplicationAccessControlConfig | Service-account access grants. Defines the permissions the VM's service account holds over other platform resources (secrets, buckets, pub/sub, etc.). Aggregated during computation into the effective access-control config and injected environment. See ApplicationAccessControlConfig. |
| scaling | Scaling | Autoscaling configuration for this VM. Controls the number of instances via the managed instance group autoscaler. Only applies to stateless VMs; for stateful VMs use stateful.clusterSize instead. See Scaling. |
Configuration
Base configuration and runtime injection.
Selects the VirtualMachineConfiguration template that supplies the operating system and base startup script, and injects the environment variables, secrets, and persistent volume mounts consumed by that script at boot.
| Property | Type | Description |
|---|---|---|
| source | string | Referenced VirtualMachineConfiguration name. Required. Name of the VirtualMachineConfiguration manifest used as the base for this VM, defining the operating system and base startup script. Resolved during computation to build the effective startup script. |
| variables | list of VariablesEntry | Startup-script environment variables. Key/value pairs injected as variables into the referenced configuration's startup script. Values override the defaultValue declared for matching variables in the VirtualMachineConfiguration. |
| secrets | list of SecretsEntry | Startup-script secret bindings. Map of environment-variable name to the name of a Secret manifest. The resolved secret values are injected as environment variables for the startup script; the engine also auto-provisions default secrets declared by the referenced configuration. |
| volumeMounts | list of VolumeMountsEntry | Persistent volume mounts. Map of in-VM mount path (e.g. /data) to volume source. Combined with the volume definitions from the referenced VirtualMachineConfiguration to compute the effective disk and bucket mounts. See VirtualMachineVolumeMount. |
SecretsEntry
| Property | Type | Description |
|---|---|---|
| key | string | |
| value | string |
VariablesEntry
| Property | Type | Description |
|---|---|---|
| key | string | |
| value | string |
VolumeMountsEntry
| Property | Type | Description |
|---|---|---|
| key | string | |
| value | VirtualMachineVolumeMount |
Health
Application health probes.
Startup and liveness probe definitions for the application running on the VM. See Health.
| Property | Type | Description |
|---|---|---|
| startup | HostHealthConfig | Startup probe configuration. NOT YET IMPLEMENTED. Declared in the schema but currently ignored by the engine (no consumer reads it); the VM's health check is derived from liveness instead. Reserved for a distinct startup probe in the future. See HostHealthConfig. |
| liveness | HostHealthConfig | Liveness probe configuration. Protocol, port, path, and timing/threshold settings for the VM's health check. Drives the health check attached to the instance's backend service and managed instance group auto-healing. See HostHealthConfig. |
PortsEntry
| Property | Type | Description |
|---|---|---|
| key | int32 | |
| value | string |
Scaling
Autoscaling bounds for stateless VMs.
Controls the size of the managed instance group autoscaler for stateless deployments. Ignored for stateful VMs.
| Property | Type | Description |
|---|---|---|
| min | int32 | Minimum number of instances. Floor for the managed instance group autoscaler. Only applied when greater than 0; the executor falls back to 1 when unset. |
| max | int32 | Maximum number of instances. Ceiling for the managed instance group autoscaler. Only applied when greater than 0; the executor falls back to 10 when unset. |
Stateful
Stateful cluster topology.
Configures the VM(s) as a stateful managed instance group with persistent disks and stable network identities, rather than a stateless autoscaled group.
| Property | Type | Description |
|---|---|---|
| enabled | bool | Deploy as a stateful cluster. When true, the VMs are deployed as a stateful managed instance group with persistent disks and stable per-instance network identities. When false, a stateless (autoscaled) group is used instead. |
| clusterSize | int32 | Number of instances in the stateful cluster. Fixed count of VM instances provisioned in the stateful managed instance group. Applied only when enabled is true; for stateless VMs use scaling.min/scaling.max instead. |
| allowTcp | list of int32 | Intra-cluster TCP ports to allow. NOT YET IMPLEMENTED. Declared in the schema but currently ignored by the engine (no consumer reads it). Intended future behavior: open the listed TCP ports for communication between instances within the stateful cluster. |
| health | HostHealthConfig | Cluster health check configuration. NOT YET IMPLEMENTED. Declared in the schema but currently ignored by the engine (no consumer reads it). Intended future behavior: define the health probe used to gate and repair members of the stateful cluster. See HostHealthConfig. |
ComputedVirtualMachineDiskConfig
Represents the computed specification of a VM's attached disk.
Consolidates disk sizing, snapshots, and filesystem details into a unified block for persistent disk provisioning.
| Property | Type | Description |
|---|---|---|
| name | string | Disk resource name. The resolved disk name, derived from the name field of the volume in the VirtualMachineConfiguration manifest. |
| fileSystem | string | Disk filesystem. The filesystem to format the disk with, derived from the volume's fileSystem field in the VirtualMachineConfiguration manifest. |
| mountOptions | string | Computed mount options. The mount option string for the disk, computed from the filesystem and the VM's operating system. |
| sourceSnapshot | string | Source snapshot. The source snapshot to hydrate the disk from, derived from the volume mount's sourceSnapshot in the VirtualMachine manifest. |
| encrypted | bool | Encryption flag. Whether the disk is encrypted, derived from the volume's encrypted field in the VirtualMachineConfiguration manifest. |
| diskSizeGb | int64 | Disk size, in GB. The disk size, derived from the volume mount's diskSizeGb field in the VirtualMachine manifest. |
| diskType | string | Disk type. The Compute Engine disk type, derived from the volume mount's diskType field in the VirtualMachine manifest. |
ComputedVirtualMachineBucketConfig
Represents a computed bucket mount for a VM.
Resolves the linkage between the VM configuration and the exact bucket resource to be mounted via Cloud Storage FUSE.
| Property | Type | Description |
|---|---|---|
| source | string | Bucket resource name. The resolved bucket to mount, derived from the name field of the volume in the VirtualMachineConfiguration manifest. |
| mountOptions | string | Computed mount options. The mount option string for the FUSE mount, computed from the VM's operating system to ensure compatibility. |
ApplicationAccessControlConfig
Aggregates all external access rules an application requires.
Computes the comprehensive list of IAM bindings, SQL grants, and secret consumptions that must be provisioned alongside the application's actual deployment.
| Property | Type | Description |
|---|---|---|
| additionalRoles | list of string | Extra IAM roles for the service account. A list of additional IAM roles granted directly to the application's service account, beyond the roles derived from the other access-control blocks. |
| pubsub | ApplicationAccessControlPubsubConfig | Pub/Sub publish and subscribe grants. The application's permission to publish to or subscribe from specific Pub/Sub topics. See ApplicationAccessControlPubsubConfig. |
| buckets | list of ApplicationAccessControlBucketConfig | Cloud Storage bucket access rules. A list of bucket access rules describing which Cloud Storage buckets the application may read from or write to, and how they are mounted or exposed. See ApplicationAccessControlBucketConfig. |
| database | ApplicationAccessControlDatabaseConfig | PostgreSQL database access. The application's access to a specific PostgreSQL database instance and schema, including privileges and credential source. See ApplicationAccessControlDatabaseConfig. |
| secrets | list of SecretsEntry | Secrets consumed by the application. A map from Secret manifest name to the configuration describing how that secret is exposed to the application (as an environment variable or mounted file). See SecretSourceConfig. |
| redis | list of ApplicationAccessControlRedisConfig | Redis cache access. A list of Redis instances the application may use. Each entry injects the connection URL as an environment variable and creates a deployment dependency on the Redis DNS record. See ApplicationAccessControlRedisConfig. |
| jobs | list of ApplicationAccessControlJobConfig | Cloud Run Jobs the application may trigger. A list of Cloud Run Jobs (owned by other applications) that this application's service account may trigger via the RunJob API. Each entry grants roles/run.developer on the referenced job and injects its full resource name as an environment variable. See ApplicationAccessControlJobConfig. |
VirtualMachineVolumeMount
Connects a VM application to a specific backing volume.
Defines the runtime mounting instructions (like fstab entries or Fuse attachments) within the google_compute_instance.
| Property | Type | Description |
|---|---|---|
| source | string | Volume source. For a BUCKET volume, the name of the bucket to mount; for a DISK volume, an optional Google Compute snapshot self-link used as the source snapshot. Carried into the computed bucket/disk configuration. |
| mountOptions | list of string | Mount options. Additional mount options applied when attaching the volume; joined into the mount command for the instance. |
| diskConfig | VirtualMachineVolumeMountDiskConfig | Disk sizing for the mount. Size, type, and snapshot settings for a DISK-backed mount. See VirtualMachineVolumeMountDiskConfig. |
HostHealthConfig
Configuration for uptime and health checks on host endpoints.
Translates into google_compute_health_check and backend service parameters, driving routing decisions within GCP load balancers.
| Property | Type | Description |
|---|---|---|
| protocol | string | Probe protocol. The protocol the health check uses to reach the endpoint: one of http, http2, https, grpc, or tcp. Drives both the container startup/liveness probes (Cloud Run, GKE) and the compute backend health check for VMs. |
| port | int64 | Probe port. The TCP port the health check targets on the workload. |
| checkIntervalSec | int64 | Check interval, in seconds. How often the health check runs. Defaulted to 30 by the ingress defaulter when the probe is generated automatically. |
| timeoutSec | int64 | Probe timeout, in seconds. How long to wait for a single probe response before treating it as a failure. The ingress defaulter sets this to 10 when generating probes automatically. |
| healthyThreshold | int64 | Healthy threshold. The number of consecutive successful probes required to mark the endpoint healthy. Defaulted to 1 by the ingress defaulter. |
| unhealthyThreshold | int64 | Unhealthy threshold. The number of consecutive failed probes required to mark the endpoint unhealthy. Defaulted to 2 by the ingress defaulter. |
| enableLogs | bool | Enable health-check logging. NOT YET IMPLEMENTED. Declared in the schema but currently ignored by the engine (no consumer reads it). Intended future behavior: enable request/response logging on the generated google_compute_health_check. |
| path | string | Probe request path. The HTTP request path for HTTP-family probes. Defaults to /. Used as the request path on the container probe and the compute backend health check. |
ApplicationAccessControlJobConfig
Grants an application permission to trigger a Cloud Run Job owned by another application.
Resolves the target job via the owning Application's name and job name, then grants roles/run.developer to the calling application's service account on that job. The job's full Cloud Run resource name is injected as an env var (derived from the job name).
| Property | Type | Description |
|---|---|---|
| application | string | Owning application. Required. The Application manifest name that owns the target Cloud Run Job. Used together with job to resolve the concrete job resource to grant access on. |
| job | string | Target job name. Required. The job's name within the owning application, matching an ApplicationJobReference.name on that application. |
| envVar | string | Environment variable for the job resource name. The name of an environment variable injected into the caller with the job's full Cloud Run resource name. When empty, no variable is injected and the caller must derive the job name by convention. |
ApplicationAccessControlBucketConfig
Configures Google Cloud Storage interaction permissions for a workload.
Translates to roles/storage.objectViewer or roles/storage.objectUser IAM bindings assigned to the application's service account, and can map specific paths.
| Property | Type | Description |
|---|---|---|
| name | string | Target Bucket manifest name. Required. The name of the Bucket manifest this application requires access to. The bucket must exist in every environment defined by the parent ReleaseTrack. |
| source | string | Source repository to sync into the bucket. Optional reference to a GithubRepository manifest whose contents seed the bucket. The CI/CD system uses this to set up a gcloud storage rsync job that mirrors the repository data into the bucket. |
| permission | string | Access level granted on the bucket. The permission level for this bucket: READ_ONLY grants roles/storage.objectViewer, and WRITE grants roles/storage.objectUser to the application's service account on the bucket. |
| mountPath | string | In-container mount path for the bucket. The absolute path at which the bucket is mounted (via Cloud Storage FUSE) inside the container. When omitted, permissions are still granted but the bucket is not mounted as a filesystem. |
| subPath | string | Restrict access to a bucket sub-path. A sub-path (prefix) within the bucket that access is scoped to; when omitted, access covers the whole bucket. Commonly used to mount a specific folder of the bucket into the container. |
| promote | bool | Promote bucket contents with the release. When true, the bucket's content is promoted through the ReleaseTrack alongside the application, typically for shipping generic application configuration data with each release. |
| envVar | string | Environment variable to receive the bucket name. The name of an environment variable populated with the resolved bucket name, giving the application the bucket name as plain configuration instead of a filesystem mount. Mutually exclusive with mount_path. |
ApplicationAccessControlPubsubConfig
Configures Pub/Sub interaction permissions for a workload.
Translates to roles/pubsub.publisher and roles/pubsub.subscriber IAM bindings assigned to the application's underlying service account.
| Property | Type | Description |
|---|---|---|
| publishTo | list of string | Topics the workload may publish to. A list of PubSub manifest names this workload is allowed to publish messages to. Each entry grants roles/pubsub.publisher to the workload's service account on the corresponding topic. |
| subscribeTo | list of string | Topics the workload may subscribe to. A list of PubSub manifest names this workload is allowed to create subscriptions for and pull messages from. Each entry grants roles/pubsub.subscriber to the workload's service account on the corresponding topic. |
VirtualMachineVolumeMountDiskConfig
Configures the specification of an attached disk volume.
Parameters translate into the size and type of google_compute_disk created to back the attached volume mount.
| Property | Type | Description |
|---|---|---|
| sizeGb | int64 | Disk size, in GB. Only applicable to DISK volumes. The size of the attached disk; must be at least 200 GB. |
| type | string | Disk type. Only applicable to DISK volumes. The Compute Engine disk type (e.g. pd-ssd, pd-balanced) backing the mount. |
| snapshots | list of DiskSnapshotConfiguration | Per-environment snapshot sources. Optional snapshot configurations used to seed the disk for specific environments. See DiskSnapshotConfiguration. |
SecretsEntry
| Property | Type | Description |
|---|---|---|
| key | string | |
| value | SecretSourceConfig |
ApplicationAccessControlDatabaseConfig
Configures PostgreSQL interaction permissions for a workload.
Executes dynamic DDL (CREATE USER, GRANT) against the target SQL instance using an administrative proxy, setting up specific schema rights.
| Property | Type | Description |
|---|---|---|
| name | string | Target Database manifest name. The name of the Database manifest this application requires access to. Resolves to a concrete AlloyDB/PostgreSQL instance during computation. |
| schema | string | Database schema to connect to. The specific database (schema) within the instance the application connects to. Feeds the computed schema and per-deployment access grants used by the Database executor to provision users, roles, and grants. |
| privileges | list of string | SQL privileges to grant on the schema. A list of SQL privileges granted to the application's database role on the target schema. Each entry (one of USAGE, CREATE, ALL) translates into GRANT statements executed against the PostgreSQL instance. |
| readOnly | bool | Connect against a read replica. When true, the application is wired for read-only access, typically to connect to a read replica rather than the primary instance. |
| extensions | list of string | PostgreSQL extensions to enable. A list of PostgreSQL extensions to enable in the target database for this application. Each entry runs CREATE EXTENSION IF NOT EXISTS; extensions are merged across all applications sharing a schema in the computed database schema. |
| secretSource | SecretSourceConfig | Credential source for the database. Required. Defines how the application obtains its database credentials, e.g. from which Secret manifest and how it is exposed (environment variable or file mount). See SecretSourceConfig. |
ApplicationAccessControlRedisConfig
Configures Redis cache access for a workload.
Injects the Redis connection URL as an environment variable and establishes a graph dependency on the Redis manifest's DNS record to ensure the stable FQDN is resolvable before the application deploys.
All Memorystore Redis instances are provisioned with SERVER_AUTHENTICATION transit encryption (TLS). The CA certificate is extracted from the instance state and mounted as a volume in the container so the application can configure its TLS trust pool.
| Property | Type | Description |
|---|---|---|
| name | string | Target Redis manifest name. Required. The name of the Redis manifest this application requires access to. Establishes a graph dependency on that instance's DNS record so its FQDN is resolvable before the application deploys. |
| envVar | string | Environment variable for the connection URL. Required. The name of the environment variable populated with the Redis connection URL of the form 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. |
| caCertPath | string | In-container path for the server CA certificate. Required. The absolute file path at which the Memorystore server's CA certificate (extracted from instance state) is mounted. The application must load this PEM file into its TLS trust pool to validate the server's identity. |
DiskSnapshotConfiguration
Defines the source snapshot for a given environment.
Determines the specific google_compute_snapshot link used to provision a new compute disk for a VM within a target environment.
| Property | Type | Description |
|---|---|---|
| source | string | Volume source. For a BUCKET volume, the name of the bucket to mount; for a DISK volume, an optional Google Compute snapshot self-link used as the source snapshot. |
| mountOptions | list of string | Mount options. Additional mount options applied when attaching the volume (e.g. FUSE or fstab-style flags). |
| diskConfig | DiskSnapshotDiskConfig | Disk sizing and snapshots. Size, type, and per-environment snapshot sources for a DISK volume created from this configuration. See DiskSnapshotDiskConfig. |
SecretSourceConfig
Defines how a secret should be retrieved and mounted into a workload.
Triggers IAM bindings for Secret Manager payload access. Values are resolved JIT and passed into the container via environment variables or file mounts.
| Property | Type | Description |
|---|---|---|
| envVar | string | Environment variable name for the secret. The name of the environment variable populated with the secret's value. Mutually exclusive with file_path: set exactly one to choose environment-variable versus file-mount delivery. |
| version | string | Secret Manager version to resolve. The specific version of the secret to retrieve from the backend, either latest or a numeric version like 1. When omitted, latest is assumed. |
DiskSnapshotDiskConfig
Configures properties for a disk created from a snapshot.
Sets disk size and type attributes on the resulting google_compute_disk when hydrating a snapshot.
| Property | Type | Description |
|---|---|---|
| sizeGb | int64 | Disk size, in GB. Only applicable to DISK volumes. The size of the disk provisioned from the snapshot. |
| type | string | Disk type. Only applicable to DISK volumes. The Compute Engine disk type (e.g. pd-ssd, pd-balanced) of the provisioned disk. |
| snapshots | list of SnapshotsEntry | Per-environment snapshot sources. A map from environment name to the source snapshot self-link used to hydrate the disk in that environment. |
SnapshotsEntry
| Property | Type | Description |
|---|---|---|
| key | string | |
| value | string |