Image Builder overview

Image Builder is a declarative operating system (OS) image customization tool that runs within your Google Cloud project using Cloud Build. It automates the process of building, customizing, and validating OS images to help verify that they boot correctly and follow your configuration requirements before you publish them for production workloads.

Key benefits

By automating the lifecycle of custom OS images inside Google Cloud, Image Builder helps you manage infrastructure and validate configuration requirements. Image Builder provides the following features for your custom OS image builds:

  • Automate OS image creation: Create and maintain custom OS images using declarative YAML recipes and automated Cloud Build workflows, without the need for custom scripting or external tools. Because Image Builder runs within Cloud Build, you can use Cloud Build triggers to automatically launch image builds on repository events (such as a Git push or tag), set up recurring schedules (for example, weekly builds for security patches), or respond to Pub/Sub messages (to trigger builds programmatically from external workflows or webhooks).
  • Validate images before publishing: Verify images before publishing them. Google-provided checks validate that intermediate images boot, support Secure Boot (when applicable), load required network drivers, and run a healthy guest agent.
  • Trace script execution: Track the code that runs during your build pipeline. Image Builder automatically records the cryptographic SHA-256 hash of your inline customization scripts inside the build logs to maintain an audit trail.
  • Pay only for resources used: The Image Builder service is available at no additional charge. You incur costs only for the underlying compute, storage, and build resources consumed while your pipelines run.

How Image Builder works

Image Builder runs inside your Google Cloud project by using a Cloud Build orchestrator container. The image build process consists of the following phases:

  1. Validation and preparation: The orchestrator container checks YAML syntax and verifies that all required APIs are enabled and that target Identity and Access Management (IAM) security permissions are active.
  2. Workspace and disk preparation: The orchestrator container archives the Cloud Build workspace directory (/workspace) containing your source code and configurations into a compressed tar file (.tar.gz) and uploads this tar file to the Cloud Storage workdir bucket specified in your build configuration. The orchestrator container then uses a statically-compiled customization provisioner file system to create a temporary Compute Engine image, which defines the secondary data disk attached to your worker VM.
  3. Worker VM execution: The orchestrator container launches an ephemeral worker VM instance by using the specified source image as the boot disk and attaches the secondary data disk containing the customization provisioner.
  4. Customization: A startup script mounts the data disk and starts the customization provisioner on the worker VM. The provisioner downloads the workspace archive and applies your declared customizations, such as running shell scripts, copying files, or compiling drivers. It also performs a security sanitization pass to clean SSH keys, unique machine IDs, and log histories. It then shuts down the instance.
  5. Validation (testing): The orchestrator container creates a temporary test OS image from the customized boot disk and provisions a temporary test VM to run the following system-defined validation checks:
    • Intel IDPF driver verification: Verifies that supported instances load the Intel Infrastructure Data Path Function (idpf) network driver rather than generic display or fallback drivers.
    • Networking and guest agent verification: Confirms the guest agent service is active, at least one non-loopback network interface is up, and names conform to conventions (eth* or en*).
    • Secure Boot verification: Ensures that UEFI Secure Boot is active and that the system enforces guest kernel verification.
    • Suspend or resume verification: Suspends the test VM by using the Compute Engine API and verifies that network connectivity is recovered post-resume without a system reboot.
  6. Release: If all validation checks pass, the orchestrator container prepares the final image:
    • If Artifact Registry is configured: The orchestrator container exports the customized boot disk as a tar file to an Artifact Registry generic repository and creates the final production Compute Engine image using the Artifact Registry URI as its source.
    • If Artifact Registry is not configured: The orchestrator container creates the Compute Engine image directly in your project using the customized boot disk.

Pricing and quota considerations

The Image Builder service is available at no extra cost. However, Google Cloud charges for standard resources provisioned during the build, test, and release phases:

  • Compute Engine: charges for worker VMs, test VMs, and attached Persistent Disks.
  • Cloud Build: charges for orchestrator container runtime minutes.
  • Cloud Storage: charges for workspace archives, log exports, and intermediate assets.
  • Artifact Registry: charges for storing exported image tar files, if configured.
  • Custom images: charges for storing intermediate test, debug, and production images.

For detailed information about resource costs, refer to the pricing documentation for Compute Engine, Cloud Build, Cloud Storage, Artifact Registry, and custom image storage.

Quota requirements

Ensure your project has sufficient Compute Engine CPU and Persistent Disk quotas in the zone where you run your builds. Insufficient quota in the target zone causes the pipeline to fail during VM provisioning.

What's next