Use image check during image creation or import to validate an image. - Elastic Compute Service

Note

Creating or importing an image triggers an image check. The check doesn't interrupt the workflow, even if it fails.
Image check is free of charge.
Images that pass the check are automatically tagged with operating system version (acs:ecs:image:osVersion) and kernel version (acs:ecs:image:kernelVersion) tags.

Limitations

Image check supports only custom images created from unencrypted snapshots or from instances without encrypted cloud disks.

Image check does not support some Linux and Windows operating systems, which are listed in the following tables.

Unsupported Linux operating systems

Operating system	Version
Gentoo	Gentoo 13 64-bit
	Gentoo_32
	Gentoo_64
	Gentoo_arm64
Aliyun	LifseaOS 10 64-bit
	LifseaOS 3 64-bit
	LifseaOS 3 64-bit GPU Edition
FreeBSD	FreeBSD 10.1 64-bit
	FreeBSD 8.2 64-bit
	Freebsd_32
	Freebsd_64
	FreeBSD 11.1 64-bit
	FreeBSD 11.2 64-bit
	FreeBSD 11.3 64-bit
	FreeBSD 12.1 64-bit
	FreeBSD 11.4 64-bit
	Freebsd_arm64
	FreeBSD 13.0 64-bit
	FreeBSD 12.3 64-bit
CoreOS	CoreOS 681.2.0 64-bit
	CoreOS_32
	CoreOS_64
	CoreOS 1353.8.0 64-bit
	CoreOS 1465.8.0 64-bit
	CoreOS 1576.5.0 64-bit
	CoreOS 1688.5.3 64-bit
	CoreOS 1745.7.0 64-bit
	CoreOS 2023.4.0 64-bit
	CoreOS 2247.6.0 64-bit
	CoreOS 2303.3.0 64-bit
	CoreOS 2303.4.0 64-bit
	CoreOS 2345.3.0 64-bit
	CoreOS_arm64
Fedora CoreOS	FedoraCoreOS_64
	Fedora CoreOS 33.20210217.3.0_3
	FedoraCoreOS_arm64
	Fedora CoreOS 34.20210529.3.0_3
Solaris	Solaris 10u8 64-bit
mars	Aliyun Customized Linux
Customized Linux	CustomizedLinux_64
	CustomizedLinux_32
	CustomizedLinux_arm64

Unsupported Windows operating systems

Operating system	Version
Windows Server 2008	Windows Server 2008 Standard Edition 64-bit Chinese Edition
	Windows Server 2008 Standard Edition 64-bit English Edition
	Windows Server 2008 Standard Edition SP2 32-bit Chinese Edition
	Windows Server 2008 Enterprise Edition 32-bit Chinese Edition
	Windows Server 2008 Standard Edition SP2 32-bit English Edition
	WindowsServer2008_64
	WindowsServer2008_32
	Windows Server 2008 Standard Edition SP2 32-bit Japanese Edition
Windows Server 2003	Windows Server 2003 R2 Standard Edition SP2 64-bit Chinese Edition
	Windows Server 2003 R2 Standard Edition SP2 32-bit Chinese Edition
	Windows Server 2003 R2 Standard Edition SP2 64-bit English Edition
	Windows Server 2003 R2 Enterprise Edition 64-bit English Edition
	Windows Server 2003 R2 Enterprise Edition 64-bit Chinese Edition
	Windows Server 2003 R2 Enterprise Edition 32-bit Chinese Edition
	WindowsServer2003_64
	WindowsServer2003_32
Windows 7	Windows7_32
Windows 8	Windows8_32
Windows 10	Windows10_32

Configure image check

During image creation

Console

When you create a custom image in the ECS console, an image check runs by default. No changes are needed. For more information, see Create a custom image by using an instance and Create a custom image by using a snapshot.

API

Set the DetectionStrategy=Standard parameter by calling the CreateImage operation. You can run this operation on OpenAPI Explorer, which saves you the trouble of calculating signatures and automatically generates SDK code examples.

During image import

Console

When you import a custom image in the ECS console, an image check runs by default. No changes are needed. For more information, see Import a custom image.

API

Set the DetectionStrategy=Standard parameter in the ImportImage operation. You can run this operation in OpenAPI Explorer, which saves you the trouble of calculating signatures and automatically generates SDK code examples.

Image check results

Console

On the Custom Images page, find the image you created. An image check task runs automatically after the image status changes to Available.
Hover over the check result and click View Details to view the detailed image check results. After the image check is complete, the Check Result column displays the check status. Hover over the check result to view the number of Critical, Suggested, and Passed items, and click View Details to view the complete check report.
If any items require fixes, follow the recommendations.
- (For Linux images only) Click Fix and use the ACS-ECS-RepairImage public template in CloudOps Orchestration Service (OOS) to fix the issues.
- Alternatively, fix the issues manually based on the recommendations in the image details. For details on the image check items and recommended fixes, see Image check items and repair suggestions.
The image check results page categorizes items into three types: items with no risks found, critical fixes, and recommended optimizations. Each category lists the specific check items and provides links for fixes or optimizations.

API

Call the DescribeImages operation and use the image ID to query the results. You can run this operation in OpenAPI Explorer. This tool simplifies the process by handling signature calculations and automatically generating SDK code examples.

Note

In the response, DetectionOptions contains the detection results, Status indicates the task status, and Item contains the result for each check item.

Image checks and fixes

Linux

Check item	Description	Recommended fix
GUESTOS.Platform	The system platform. Must be a Linux operating system.	Not applicable
GUESTOS.OSVersion	The operating system version.	Not applicable
GUESTOS.Architecture	The system architecture.	Not applicable
GUESTOS.RtcTimeMode	Specifies the time zone of the image's hardware clock (RTC). Valid values are UTC or local. We recommend setting the hardware clock to UTC.	To set the hardware clock to UTC, see Linux time and time zones.
GUESTOS.BootMode	The boot mode of the image. Valid values are LEGACY or UEFI.	Not applicable
GUESTOS.KernelVersion	The kernel version.	Not applicable
GUESTOS.Virtio	Checks if the virtio driver is installed. ECS instances require this driver for virtualization and may fail to start without it.	To install the virtio driver for an image, see Install virtio driver.
GUESTOS.Nvme	Checks if the NVMe driver is installed. Certain ECS instance families, such as ecs.g7se, use NVMe-attached cloud disks and require this driver in the image.	To install the NVMe driver for an image, see How do I install the NVMe driver for an existing custom image?.
GUESTOS.Fstab	Checks the `/etc/fstab` file. Incorrect configurations, such as non-existent devices or incorrect device UUIDs, can cause system startup failures.	To correctly configure `/etc/fstab`, see Configure UUIDs in the fstab file to automatically mount data disks.
GUESTOS.Grub	Checks the GRUB bootloader configuration. Incorrect settings, such as invalid device paths or UUIDs, can cause system startup failures.	None
GUESTOS.Dhcp	Checks if the network is configured for DHCP. Using a static IP address in the image can cause network failures when the instance starts.	To set the network configuration mode of the image to DHCP, see Configure DHCP for a Linux instance.
GUESTOS.Selinux	Checks if SELinux is disabled. We recommend disabling SELinux in cloud images to prevent potential startup failures.	To disable SELinux, see Enable or disable SELinux.
GUESTOS.OnlineResizeFS	Checks if the image supports automatic resizing of the root partition. If the image has cloud-init, the `growpart` command, and other required tools installed, the root partition of an instance created from this image automatically expands. For example, if you create an instance with a 100 GB system disk from a 20 GB image, the root partition expands to 100 GB.	To configure the image to support automatic resizing, see Install cloud-init.
GUESTOS.SystemImage	Checks if the image is a valid system disk image. Do not import invalid images, such as ISO images or empty images.	Not applicable
GUESTOS.CloudAssistant	Checks if Cloud Assistant is installed. Cloud Assistant is a native automation and management tool for ECS that allows you to run batch operations, execute commands (such as Shell, PowerShell, and Bat commands), and transfer files on ECS instances without passwords, logins, or bastion hosts. Installing Cloud Assistant is recommended for efficient instance management.	To install Cloud Assistant, see Install the Cloud Assistant Agent.
GUESTOS.CloudInit	Checks if cloud-init is installed in the image. cloud-init is the industry standard for cloud instance initialization, handling setup tasks such as configuring hostnames, SSH key pairs, and root partition resizing.	To install cloud-init for an image, see Install cloud-init.
GUESTOS.SecurityCenterAgent	Checks if the Security Center agent is installed in the image. Security Center is a unified security management system that provides real-time threat detection and protection. Its features include security posture overview, anti-ransomware, anti-virus, anti-tampering, and compliance checks to comprehensively detect and protect your servers and web applications.	To install the Security Center agent for an image, see Install the client.
GUESTOS.SupportMocInstanceTypes	Checks if the image supports ECS Bare Metal Instance families. The latest ECS instance families, such as ecs.g6 and ecs.g7, are often based on the ECS Bare Metal Instance architecture. An instance may fail to start on these families if the image's OS and kernel version are outdated. For more information about instance families, see Instance family.	If you are using CentOS 5, we recommend that you upgrade to the latest version, CentOS 5.11. For more information, see How do I resolve instance downtime after migration?. Operating systems that do not support ECS Bare Metal Instance families are often older, end-of-life (EOL) versions. We recommend that you upgrade to an operating system version that is actively maintained by its vendor as soon as possible.

Windows

Check item	Description	Recommended fix
GUESTOS.Platform	The system platform. Must be a Windows operating system.	Not applicable
GUESTOS.OSVersion	The operating system version.	Not applicable
GUESTOS.Architecture	The system architecture.	Not applicable
GUESTOS.KernelVersion	The kernel version.	Not applicable
GUESTOS.Virtio	Checks if the virtio driver is installed. ECS instances require this driver to function correctly and may fail to start without it.	To install the virtio driver for an image, see Install virtio driver.
GUESTOS.BCD	Checks whether the Boot Configuration Data (BCD) file in the image is valid. A missing or corrupted BCD file can cause instance startup failures.	Use the correct BCD file.
GUESTOS.Registry	Checks if the registry files in the image are valid. Missing or corrupted registry files can cause instance startup failures.	Use the correct registry files.
GUESTOS.Hotfix	Checks for correct patch installation. Missing required patches or installing known problematic patches can cause instance startup failures.	Uninstall incorrect patches. Incorrect patches include KB5009624, KB5009595, KB5009546, KB5009557, KB5009555, KB5014738, KB5014702, KB5014692, and KB5014678. For 64-bit Microsoft Windows Server 2008 R2 operating systems, you must also install patch KB3033929.
GUESTOS.Disk	Checks if the disk settings are correct. Residual driver entries in the registry can cause instance startup failures.	Clear residual drivers from the registry
GUESTOS.Sysprep	Checks for successful Sysprep completion during image creation. An interrupted Sysprep process, such as from a forced shutdown, can cause the resulting instance to fail at startup.	Create the image again. Make sure that the Sysprep process is not interrupted. For more information, see Create a virtual machine and install an operating system.
GUESTOS.Update	Checks if the Update process was completed during image creation. If the Update process was interrupted, for example, by a forced shutdown, the instance may fail to start.	Create the image again. Make sure that the system update process is not interrupted. For more information, see Create a virtual machine and install an operating system.
GUESTOS.Xen	Checks for residual Xen drivers, which can cause system startup failures.	Disable the Xen driver
GUESTOS.CloudAssistant	Checks if Cloud Assistant is installed. Cloud Assistant is a native automation and management tool for ECS that allows you to run batch operations, execute commands (such as Shell, PowerShell, and Bat commands), and transfer files on ECS instances without passwords, logins, or bastion hosts. Installing Cloud Assistant is recommended for efficient instance management.	To install Cloud Assistant, see Install the Cloud Assistant Agent.
GUESTOS.Server	Checks if the service configurations in the image are correct. If driver installation is disabled, the instance will fail to update drivers.	Allow driver installation
GUESTOS.DesktopConfig	Checks if the desktop configuration file (desktop.ini) is missing. If it is missing, desktop settings will not be applied.	Configure the correct desktop.ini file.
GUESTOS.BootMgr	Checks if the system boot manager (BootMgr) is missing. A missing BootMgr prevents the system from booting.	Configure the correct BootMgr.

Clear residual drivers

The HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control registry tree contains configuration information that controls system startup and certain devices. Its Class subkey contains filter drivers registered on the device. Residual driver entries from uninstalled software can cause instances created from the image to fail at startup. This section explains how to manually clean up these residual entries.

Log on to the source server from which the image file was created.
Open the Registry Editor.

For example, on Windows 10, enter regedit in the taskbar search box and press Enter.
Open the disk registry key.

The path is HKEY_LOCAL_MACHINE\SYSTEM\ControlSet001\Control\Class\{4d36e967-e325-11ce-bfc1-08002be10318}.
Confirm and delete the residual driver entries.
1. Check the value of the UpperFilter property to identify residual driver entries.
  
  An entry is considered residual if its corresponding driver file is missing from C:\Windows\System32\drivers but its entry remains in UpperFilters.
  
  Warning
  Be cautious when you delete driver entries. Make sure that the driver is not a system-default driver to avoid system exceptions.
  
  For example, partmgr is a system-default driver and must not be deleted from UpperFilters. In the registry path HKEY_LOCAL_MACHINE\OfflineSYSTEM\ControlSet001\Control\Class\{4d36e967-e325-11ce-bfc1-08002be10318}, the value of UpperFilters is partmgr. This is a system-default driver and does not need to be deleted.
2. In UpperFilters, delete the names of the residual drivers.

Disable the Xen driver

ECS instances do not use the Xen driver. However, older images may contain residual Xen driver entries that can cause startup failures. You can disable the Xen driver in the registry.

Log on to the source server from which the image file was created.
Open the Registry Editor.

For example, on Windows 10, enter regedit in the taskbar search box and press Enter.
Open the corresponding registry key.

The path is HKEY_LOCAL_MACHINE\SYSTEM\ControlSet001\Services\XenPCI\Parameters.
Clear the value of the hide_devices property.

Double-click the hide_devices property. In the dialog box that appears, clear the value data, and then click OK.

Allow driver installation

The HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services registry tree records all services in the system. Some services control whether drivers can be installed. If driver installation is disabled in the image's registry, instances created from it cannot update their drivers. You must modify the property that disables this setting.

Log on to the source server from which the image file was created.
Open the Registry Editor.

For example, on Windows 10, enter regedit in the taskbar search box and press Enter.
Open the corresponding registry key.
- For Windows Server 2008 R2 and later: HKEY_LOCAL_MACHINE\SYSTEM\ControlSet001\Services\DeviceInstall\Parameters.
- For Windows Server 2008 R2 and earlier: HKEY_LOCAL_MACHINE\SYSTEM\ControlSet001\Services\PlugPlay\Parameters.
Modify the property that disables driver installation. If the DeviceInstallDisabled property exists and its value is not 0, change its value to 0 or delete the property.
- For example, on Windows Server 2008 R2, this property is of the REG_DWORD type and is located in the registry path HKEY_LOCAL_MACHINE\SYSTEM\ControlSet001\Services\PlugPlay\Parameters.
- For example, on Windows Server 2016, if the DeviceInstallDisabled property of the REG_DWORD type in the registry path HKEY_LOCAL_MACHINE\SYSTEM\ControlSet001\Services\DeviceInstall\Parameters has a value of 1, you must change the value to 0 or delete the property.

Next steps

After you check and repair a custom image, you can use it to create an ECS instance. For more information, see Create an instance from a custom image or a shared image.