Image customization file

This document describes the structure and parameters of the customization recipe file, imagebuilder.yaml, that you use to define the base OS image, hardware configurations, release destinations, and customization actions for your Image Builder pipeline.

Schema overview

The customization configuration uses the API version imagebuilder.gcp.com/v1 and the resource kind OSImageCustomization.

A standard recipe file has the following structure:

apiVersion: imagebuilder.gcp.com/v1
kind: OSImageCustomization
metadata:
  # Recipe metadata and identifying details
infrastructureConfig:
  # VM machine type, zone, and network settings
source:
  # Base source image profile
destinations:
  # Output OS image release targets
spec:
  config:
    # Build options and validation test flags
  steps:
    # Customization actions (Shell, FileCopy, UpdateKernelCommandLine, InstallGPU)

Metadata

Provides identifying details for this custom build template:

metadata:
  name: CONFIG_NAME
  description: DESCRIPTION
  • name (string, Required): The identifier for this configuration.
  • description (string, Optional): A description of the build's purpose.

Infrastructure configuration

Specifies the hardware and network properties of temporary virtual machine instances that Image Builder creates during build and validation tasks:

infrastructureConfig:
  machineType: MACHINE_TYPE
  zone: ZONE
  acceleratorType: nvidia-l4
  acceleratorCount: 1
  debug: false
  instanceDurationHours: 2.0
  reservations:
    - RESERVATION_NAME
  • machineType (string, Required): The Compute Engine machine type to use for the worker and test VMs, such as e2-standard-4. Bare metal machine types are not supported.
  • zone (string, Required): The zone where the worker and test VMs run, such as us-central1-a.
  • acceleratorType (string, Optional): The GPU accelerator type to attach to the worker VM, such as nvidia-tesla-t4 or nvidia-l4.
  • acceleratorCount (number, Optional): The number of GPU accelerators to attach to the worker VM.
  • debug (boolean, Optional): If you set debug to true, Image Builder preserves the worker VM whether customization completes or fails so you can inspect or troubleshoot the active instance using SSH. Defaults to false.
  • instanceDurationHours (number, Optional): Limits the worker VM runtime. The time limit begins when customization completes or encounters a script error, allowing you to connect to the active VM during interactive debugging sessions. Capped at a maximum of 2.0 hours.
  • reservations (array of strings, Optional): Capacity reservation resource names (such as test-reservation in the same project) to consume when Image Builder creates VMs.

Source image

Identifies the base operating system image that Image Builder uses to launch the worker VM. You must specify one of the following options:

To specify a standard image family:

source:
  imageFamily: projects/IMAGE_PROJECT/global/images/family/IMAGE_FAMILY

To specify a direct image version URI:

source:
  imagePath: projects/IMAGE_PROJECT/global/images/IMAGE_NAME
  • imageFamily (string): The path to a standard image family group, such as projects/ubuntu-os-cloud/global/images/family/ubuntu-2204-lts.
  • imagePath (string): The direct resource URI to a specific Compute Engine image version, such as projects/cos-cloud/global/images/cos-105-17412-226-28.

Destinations

Defines where and how to release the compiled custom OS image. This property contains a list of release destination objects under diskImage:

destinations:
  diskImage:
    - name: IMAGE_NAME
      project: PROJECT_ID
      family: IMAGE_FAMILY
      description: DESCRIPTION
      licenses:
        - projects/PROJECT_ID/global/licenses/LICENSE_NAME
      labels:
        env: production
      signatureDatabaseFile: SIGNATURE_DB_PATH
      storageLocations:
        - us-central1
  • name (string, Required): The base name prefix assigned to the final Compute Engine image resource. Image Builder automatically appends the unique build ID to this prefix and truncates the final image name to 63 characters.
  • family (string, Optional): The image family to apply to the newly generated image.
  • project (string, Required): The Cloud de Confiance project where Image Builder writes the output image.
  • description (string, Optional): Description text attached to the generated image metadata.
  • licenses (array of strings, Optional): Resource paths of specific software licenses applied to this image.
  • labels (map, Optional): Tagging metadata key-value pairs, such as env: production.
  • signatureDatabaseFile (string, Optional): Resource path to a secure boot signature database file.
  • storageLocations (array of strings, Optional): Target storage region or multi-region, such as us-central1 or us, where Compute Engine stores the final disk blocks. Note: Although this property is formatted as a list, you can specify only a single location per image destination.

Specification configuration

Applies general execution options:

spec:
  config:
    skipSystemTests: false
  • skipSystemTests (boolean, Optional): Toggles whether the test VM evaluates boot conditions, networking, and UEFI structures. Defaults to false.

Specification steps

Specifies a list of step objects that Image Builder runs in order on the worker VM. For complete input parameter schemas and usage examples for each step type, see Supported customization actions.

All customization step objects share the following common properties:

spec:
  steps:
    - name: STEP_NAME
      action: ACTION_TYPE
      inputs:
        # Action-specific input parameters
  • name (string, Required): User-defined name for this customization step.
  • action (string, Required): The helper action to invoke. Supported actions:
  • inputs (object, Required): The key-value properties required by the selected action. For complete parameter references and examples, see Supported customization actions.

The following snippet shows an example step using the Shell action:

spec:
  steps:
    - name: setup-environment
      action: Shell
      inputs:
        inlineScript: |
          #!/usr/bin/env bash
          echo "Running customization..."

What's next