Supported customization actions

To customize your virtual machine images, such as running terminal scripts, updating boot parameters, transferring binaries, or installing GPU drivers, you can define specific helper actions inside the spec.steps block of your customization recipe (imagebuilder.yaml).

Overview

During the execution phase of an Image Builder build, the orchestrator runs the steps declared in your customization recipe (spec.steps) sequentially on the temporary worker VM.

Each step must specify a name, an action, and an inputs block tailored to that action type. Image Builder supports the following customization actions:

• Shell: Executes inline terminal scripts or commands on the worker guest OS.
• UpdateKernelCommandLine: Modifies boot parameters and kernel command-line flags.
• FileCopy: Transfers configuration files, scripts, or assets from Cloud Storage or local workspaces onto the VM.
• InstallGPU: Downloads, compiles, and registers NVIDIA GPU drivers.

Shell action

The Shell action lets you execute inline terminal scripts or single shell commands on the guest OS of the temporary worker VM to perform customizations like updating packages, configuring user accounts, or compiling software.

Specify either of the following inputs under steps.inputs:

• inlineScript (string): Raw multiline shell commands to execute.
• command (string): A single system command string or relative path to a binary file executable.

Sample configurations

The following tabs show sample step configurations for running an inline script versus running a single command:

- name: "Update guest packages and configure groups"
  action: Shell
  inputs:
    inlineScript: |
      #!/bin/bash
      apt-get update -y
      apt-get install -y fail2ban build-essential
      groupadd -r adminusers

- name: "Log kernel identifier"
  action: Shell
  inputs:
    command: "uname -a"

Special behaviors

When you run Shell actions, the customization provisioner manages security auditing and automated system reboots as described in the following sections:

Security auditing

To prevent sensitive tokens, secrets, or proprietary code from leaking into execution logs, the customization provisioner doesn't print the raw lines of your scripts unless interactive debugging is enabled (debug: true). Instead, it logs the SHA-256 integrity hash of your script payload to the build logs. This hash provides an immutable audit trace of exactly what code ran on the image.

System reboots (Exit Code 3010)

Some shell actions, such as kernel patch updates or storage partition adjustments, require a system reboot before subsequent steps can run.

To request a system reboot during customization, your shell script must end with the command exit 3010. When the customization provisioner receives exit code 3010, it handles the reboot lifecycle as follows:

1. The provisioner detects exit code 3010, pauses execution, and marks the step progress index.
2. The provisioner reboots the worker VM.
3. After the VM restarts, the provisioner mounts the workspace and automatically resumes the pipeline at the next step in the queue.

Reboot example:

The following example shows a step configuration that updates packages and requests a reboot:

- name: "Install core updates and request reboot"
  action: Shell
  inputs:
    inlineScript: |
      #!/bin/bash
      echo "Applying configuration package upgrades..."
      apt-get dist-upgrade -y
      # Terminate with return code 3010 to trigger a system reboot
      exit 3010
- name: "Post-reboot verification"
  action: Shell
  inputs:
    command: "uname -r"

UpdateKernelCommandLine action

The UpdateKernelCommandLine action locates, replaces, inserts, or removes command-line flags passed to the kernel at system boot, such as when you configure console logs or adjust kernel parameters.

Specify the following properties under the steps.inputs map:

• oldArguments (string, Required): The exact command-line arguments to locate, remove, or replace inside the bootloader config.
• newArguments (string, Optional): The replacement arguments to write in place of the target flags. If you omit the newArguments property, Image Builder removes the parameters configured in the oldArguments property entirely from the boot line.

Sample configurations

The following tabs show sample step configurations for replacing or removing kernel boot arguments:

- name: "Configure detailed boot logging"
  action: UpdateKernelCommandLine
  inputs:
    oldArguments: "loglevel=4"
    newArguments: "loglevel=6 console=ttyS0"

- name: "Enable verbose startup diagnostics"
  action: UpdateKernelCommandLine
  inputs:
    oldArguments: "quiet"

OS-specific execution details

The following tabs describe how the customization provisioner handles image modifications depending on the source guest operating system:

FileCopy action

The FileCopy action copies configuration files, binaries, or certificates from a remote bucket or your local repository to your custom image. The customization provisioner downloads or reads the source file, writes it to your specified guest path on the worker VM, and configures the permissions.

Specify the following inputs under steps.inputs:

• destination (string, Required): The absolute path in the guest OS where the file is created.
• permissions (string, Required): The octal representation of the target configuration permissions, such as "0755" or "0644".
• Specify either of the following source properties:
  • gcsSourcePath (string): The Cloud Storage URI of the source file, which must follow the format gs://BUCKET_NAME/OBJECT_NAME.
  • localSourcePath (string): The relative path to the file inside the local workspace repository folder. Path traversal using ../ is blocked for security.

Sample configurations

The following tabs show sample step configurations for copying a file from Cloud Storage versus copying from your local workspace:

- name: "Import licensing configuration"
  action: FileCopy
  inputs:
    gcsSourcePath: "gs://enterprise-configs-bucket/licensing/license.key"
    destination: "/etc/app/license.key"
    permissions: "0600"

- name: "Deploy setup automation daemon"
  action: FileCopy
  inputs:
    localSourcePath: "bin/setup-daemon"
    destination: "/usr/local/bin/setup-daemon"
    permissions: "0755"

OS-specific guidelines

The following tabs describe file location guidelines depending on the target guest operating system:

InstallGPU action

Use the InstallGPU action to build VM images optimized for machine learning, data science, or scientific workloads. Image Builder downloads, compiles, and registers NVIDIA GPU drivers on your custom images. Depending on your base image type and target hardware, you can choose between installing precompiled drivers or compiling custom driver .run files.

Specify one of the following inputs under steps.inputs:

• version (string): The target NVIDIA driver version number, such as "595.129.03". If you specify only version, the orchestrator downloads the driver from the official NVIDIA repository (https://us.download.nvidia.com/tesla/<version>).
• gcsRunfile (string): The Cloud Storage path of a custom NVIDIA driver installer file, which must use the format gs://BUCKET_NAME/OBJECT_NAME.run.
• sourceRunfile (string): The relative path to an installer .run file inside the local workspace repository folder.

Sample configurations

The following tabs show sample step configurations for installing a specific pre-packaged driver version versus installing a custom runfile:

- name: "Configure default NVIDIA drivers"
  action: InstallGPU
  inputs:
    version: "<var>DRIVER_VERSION</var>"

- name: "Deploy custom GPU driver from Cloud Storage"
  action: InstallGPU
  inputs:
    gcsRunfile: "gs://<var>BUCKET_NAME</var>/drivers/NVIDIA-Linux-aarch64-<var>DRIVER_VERSION</var>.run"

- name: "Deploy custom GPU driver from workspace"
  action: InstallGPU
  inputs:
    sourceRunfile: "drivers/NVIDIA-Linux-x86_64-<var>DRIVER_VERSION</var>.run"

Configuration methods

The following tabs describe the supported methods for configuring NVIDIA GPU drivers on your custom images:

What's next

• Review top-level schema blocks in the Image customization file schema.
• Configure pipeline orchestration parameters in the Cloud Build configuration file schema.
• Follow the tutorial to Create an Image Builder pipeline.