Troubleshoot validation tests

Linux

Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

For information about access to this release, see the access request page.

To verify that custom VM images boot correctly and meet configuration requirements, Image Builder executes automated validation tests on a temporary test VM. If one of these tests fails, the pipeline stops and Image Builder does not publish the final image.

Before you begin

• If you haven't already, set up authentication. Authentication verifies your identity for access to Google Cloud services and APIs. To run code or samples from a local development environment, you can authenticate to Compute Engine by selecting one of the following options:

  Select the tab for how you plan to use the samples on this page:

  Console

  When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

  gcloud

  1. Install the Google Cloud CLI. After installation, initialize the Google Cloud CLI by running the following command:

     gcloud init

     If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

     Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.
  2. Set a default region and zone.

  REST

  To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.

  Install the Google Cloud CLI.

  If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  For more information, see Authenticate for using REST in the Google Cloud authentication documentation.

Overview

If the customization steps complete successfully, the orchestrator exports the VM boot disk as a temporary test image (named image-builder-test-image-BUILD_ID in the image-builder-test-images family).

The orchestrator boots a test VM from this image and runs a suite of system tests. Image Builder outputs the test outcomes in a standard JUnit XML format directly to the Cloud Build logs.

Troubleshoot specific validation tests

Review the common failures and diagnostic steps for each validation test:

Intel IDPF driver verification

This test verifies that supported VM instances load the high-performance Intel Infrastructure Data Path Function (idpf) driver on physical network interfaces.

• Failure Condition: The VM fails validation if it reverts to a generic network adapter package or if the guest kernel lacks the active idpf driver module.
• Resolution:
  • Ensure your base operating system has a kernel version compatible with IDPF.
  • Confirm that standard network utilities are not stripping or block-listing the driver.
  • For custom kernel builds, verify that CONFIG_IDPF is configured.

Networking and guest agent verification

This test asserts that the instance has working guest communications and standardized network interface configurations.

• Failure Condition: The test fails under any of the following conditions:
  • The guest agent service manager SubState does not show a running status.
  • No non-loopback network interface is online.
  • Interface names don't match expected standard patterns (for example, eth* or en*).

• Resolution:

  • Verify that the guest agent is installed and configured to start at boot:

    systemctl is-active google-guest-agent
    

  • Ensure your network configurations (such as netplan or ifupdown templates) don't disable primary virtual interfaces.

Secure Boot verification

This test asserts that UEFI Secure Boot is active and that the system enforces guest OS kernel signature validation on the image.

• Failure Condition: The test fails if Compute Engine UEFI variables report SecureBoot is not 1 or SetupMode is not 0.

• Resolution:

  • Confirm your image includes valid signature keys.

  • In your imagebuilder.yaml file, verify that guestOsFeatures contains UEFI_COMPATIBLE under your destinations block:

    destinations:
      - diskImage:
          guestOsFeatures:
            - UEFI_COMPATIBLE
    

Suspend or resume verification

This test suspends the test VM using the Compute Engine API and asserts that after VM execution resumes, connectivity is restored without triggering a full guest reboot.

• Failure Condition: The test fails if the instance reboots on wake, hangs during suspension, or fails to recover network pings.
• Resolution:
  • Verify that ACPI services and power policies on the guest operating system are enabled and configured to respond to ACPI events.
  • Inspect guest system logs (/var/log/syslog or /var/log/messages) to check if custom daemons block system sleep requests.

Skip validation tests

Although we recommend that you validate production images, you can skip validation tests during testing by setting skipSystemTests: true under the spec.config block in your imagebuilder.yaml file:

spec:
  config:
    skipSystemTests: true