Starting March 27, 2025, we recommend using android-latest-release instead of aosp-main to build and contribute to AOSP. For more information, see Changes to AOSP.

GceManager

public class GceManager
extends Object

java.lang.Object
↳	com.android.tradefed.device.cloud.GceManager

Helper that manages the GCE calls to start/stop and collect logs from GCE.

Summary

Constants
`String`	`GCE_HOSTNAME_KEY`
`String`	`GCE_INSTANCE_CLEANED_KEY`
`String`	`GCE_INSTANCE_NAME_KEY`
`String`	`GCE_IP_PRECONFIGURED_KEY`

Public constructors
`GceManager(DeviceDescriptor deviceDesc, TestDeviceOptions deviceOptions, IBuildInfo buildInfo)` Ctor
`GceManager(DeviceDescriptor deviceDesc, TestDeviceOptions deviceOptions, IBuildInfo buildInfo, testResourceBuildInfos)` This constructor is deprecated. Use other constructors, we keep this temporarily for backward compatibility.
`GceManager(DeviceDescriptor deviceDesc, TestDeviceOptions deviceOptions, IBuildInfo buildInfo, String gceInstanceName, String gceHost)` Ctor, variation that can be used to provide the GCE instance name to use directly.

Public methods
`static boolean`	`AcloudShutdown(TestDeviceOptions options, IRunUtil runUtil, String instanceName, String hostname, boolean isIpPreconfigured)` Actual Acloud run to shutdown the virtual device.
`void`	`cleanUp()`
`static File`	`getBugreportzWithSsh(GceAvdInfo gceAvd, TestDeviceOptions options, IRunUtil runUtil)` Get a bugreportz from the device using ssh to avoid any adb connection potential issue.
`HostOrchestratorUtil`	`getHostOrchestratorUtil()` Returns the instance of the `HostOrchestratorUtil`.
`static String`	`getInstanceSerialLog(GceAvdInfo infos, File avdConfigFile, File jsonKeyFile, IRunUtil runUtil)` Reads the current content of the Gce Avd instance serial log.
`static File`	`getNestedDeviceSshBugreportz(GceAvdInfo gceAvd, TestDeviceOptions options, IRunUtil runUtil)` Get a bugreport via ssh for a nested instance.
`static void`	`logAndDeleteFile(File tempFile, String dataName, ITestLogger logger)`
`static void`	`logDirectory(File remoteDirectory, String baseName, ITestLogger logger, LogDataType type)`
`static boolean`	`logNestedRemoteFile(ITestLogger logger, GceAvdInfo gceAvd, TestDeviceOptions options, IRunUtil runUtil, String remoteFilePath, LogDataType type)` Fetch a remote file from a nested instance and log it.
`static boolean`	`logNestedRemoteFile(ITestLogger logger, GceAvdInfo gceAvd, TestDeviceOptions options, IRunUtil runUtil, String remoteFilePath, LogDataType type, String baseName)` Fetch a remote file from a nested instance and log it.
`void`	`logSerialOutput(GceAvdInfo infos, ITestLogger logger)` Log the serial output of a device described by `GceAvdInfo`.
`static CommandResult`	`remoteSshCommandExecution(GceAvdInfo gceAvd, TestDeviceOptions options, IRunUtil runUtil, long timeoutMs, String... command)` Execute the remote command via ssh on an instance.
`boolean`	`shutdownGce()` Shutdown the Gce instance associated with the `startGce()`.
`GceAvdInfo`	`startGce(String ipDevice, String user, Integer offset, MultiMap<String, String> attributes, ITestLogger logger)` Attempt to start a gce instance with either Acloud or Oxygen.
`GceAvdInfo`	`startGce()`
`GceAvdInfo`	`startGce(String ipDevice, MultiMap<String, String> attributes)` Attempt to start a gce instance.
`GceAvdInfo`	`startGce(String ipDevice, String user, Integer offset, MultiMap<String, String> attributes)` Attempt to start a gce instance with either Acloud or Oxygen.
	`startMultiDevicesGce( buildInfos)` This method is deprecated. Remove this after master branch is updated.
	`startMultiDevicesGce( buildInfos, MultiMap<String, String> attributes)` Attempt to start multi devices gce instance with Oxygen.

Protected methods
`static`	`buildShutdownCommand(File config, TestDeviceOptions options, String instanceName, String hostname, boolean isIpPreconfigured)`
`String`	`extractInstanceName(String bootupLogs)` Retrieve the instance name from the gce boot logs.

Constants

GCE_HOSTNAME_KEY

public static final String GCE_HOSTNAME_KEY

Constant Value: "gce-hostname"

GCE_INSTANCE_CLEANED_KEY

public static final String GCE_INSTANCE_CLEANED_KEY

Constant Value: "gce-instance-clean-called"

GCE_INSTANCE_NAME_KEY

public static final String GCE_INSTANCE_NAME_KEY

Constant Value: "gce-instance-name"

GCE_IP_PRECONFIGURED_KEY

public static final String GCE_IP_PRECONFIGURED_KEY

Constant Value: "gce-ip-pre-configured"

Public constructors

GceManager

public GceManager (DeviceDescriptor deviceDesc, 
                TestDeviceOptions deviceOptions, 
                IBuildInfo buildInfo)

Ctor

Parameters
`deviceDesc`	`DeviceDescriptor`: The `DeviceDescriptor` that will be associated with the GCE device.
`deviceOptions`	`TestDeviceOptions`: A `TestDeviceOptions` associated with the device.
`buildInfo`	`IBuildInfo`: A `IBuildInfo` describing the gce build to start.

GceManager

public GceManager (DeviceDescriptor deviceDesc, 
                TestDeviceOptions deviceOptions, 
                IBuildInfo buildInfo, 
                 testResourceBuildInfos)

This constructor is deprecated.
Use other constructors, we keep this temporarily for backward compatibility.

Parameters
`deviceDesc`	`DeviceDescriptor`
`deviceOptions`	`TestDeviceOptions`
`buildInfo`	`IBuildInfo`
`testResourceBuildInfos`

GceManager

public GceManager (DeviceDescriptor deviceDesc, 
                TestDeviceOptions deviceOptions, 
                IBuildInfo buildInfo, 
                String gceInstanceName, 
                String gceHost)

Ctor, variation that can be used to provide the GCE instance name to use directly.

Parameters
`deviceDesc`	`DeviceDescriptor`: The `DeviceDescriptor` that will be associated with the GCE device.
`deviceOptions`	`TestDeviceOptions`: A `TestDeviceOptions` associated with the device
`buildInfo`	`IBuildInfo`: A `IBuildInfo` describing the gce build to start.
`gceInstanceName`	`String`: The instance name to use.
`gceHost`	`String`: The host name or ip of the instance to use.

Public methods

AcloudShutdown

public static boolean AcloudShutdown (TestDeviceOptions options, 
                IRunUtil runUtil, 
                String instanceName, 
                String hostname, 
                boolean isIpPreconfigured)

Actual Acloud run to shutdown the virtual device.

Parameters
`options`	`TestDeviceOptions`: The `TestDeviceOptions` for the Acloud options
`runUtil`	`IRunUtil`: The `IRunUtil` to run Acloud
`instanceName`	`String`: The instance to shutdown.
`hostname`	`String`: hostname of the instance, only used for Oxygen cuttlefish.
`isIpPreconfigured`	`boolean`: whether the AVD was created on a remote device with preconfigured IP

Returns
`boolean`	True if successful

cleanUp

public void cleanUp ()

getBugreportzWithSsh

public static File getBugreportzWithSsh (GceAvdInfo gceAvd, 
                TestDeviceOptions options, 
                IRunUtil runUtil)

Get a bugreportz from the device using ssh to avoid any adb connection potential issue.

Parameters
`gceAvd`	`GceAvdInfo`: The `GceAvdInfo` that describe the device.
`options`	`TestDeviceOptions`: a `TestDeviceOptions` describing the device options to be used for the GCE device.
`runUtil`	`IRunUtil`: a `IRunUtil` to execute commands.

Returns
`File`	A file pointing to the zip bugreport, or null if an issue occurred.

Throws
	IOException

getHostOrchestratorUtil

public HostOrchestratorUtil getHostOrchestratorUtil ()

Returns the instance of the HostOrchestratorUtil.

Returns
`HostOrchestratorUtil`

getInstanceSerialLog

public static String getInstanceSerialLog (GceAvdInfo infos, 
                File avdConfigFile, 
                File jsonKeyFile, 
                IRunUtil runUtil)

Reads the current content of the Gce Avd instance serial log.

Parameters
`infos`	`GceAvdInfo`: The `GceAvdInfo` describing the instance.
`avdConfigFile`	`File`: the avd config file
`jsonKeyFile`	`File`: the service account json key file.
`runUtil`	`IRunUtil`: a `IRunUtil` to execute commands.

Returns
`String`	The serial log output or null if something goes wrong.

getNestedDeviceSshBugreportz

public static File getNestedDeviceSshBugreportz (GceAvdInfo gceAvd, 
                TestDeviceOptions options, 
                IRunUtil runUtil)

Get a bugreport via ssh for a nested instance. This requires requesting the adb in the nested virtual instance.

Parameters
`gceAvd`	`GceAvdInfo`: The `GceAvdInfo` that describe the device.
`options`	`TestDeviceOptions`: a `TestDeviceOptions` describing the device options to be used for the GCE device.
`runUtil`	`IRunUtil`: a `IRunUtil` to execute commands.

Returns
`File`	A file pointing to the zip bugreport, or null if an issue occurred.

Throws
	IOException

logAndDeleteFile

public static void logAndDeleteFile (File tempFile, 
                String dataName, 
                ITestLogger logger)

Parameters
`tempFile`	`File`
`dataName`	`String`
`logger`	`ITestLogger`

logDirectory

public static void logDirectory (File remoteDirectory, 
                String baseName, 
                ITestLogger logger, 
                LogDataType type)

Parameters
`remoteDirectory`	`File`
`baseName`	`String`
`logger`	`ITestLogger`
`type`	`LogDataType`

logNestedRemoteFile

public static boolean logNestedRemoteFile (ITestLogger logger, 
                GceAvdInfo gceAvd, 
                TestDeviceOptions options, 
                IRunUtil runUtil, 
                String remoteFilePath, 
                LogDataType type)

Fetch a remote file from a nested instance and log it.

Parameters
`logger`	`ITestLogger`: The `ITestLogger` where to log the file.
`gceAvd`	`GceAvdInfo`: The `GceAvdInfo` that describe the device.
`options`	`TestDeviceOptions`: a `TestDeviceOptions` describing the device options to be used for the GCE device.
`runUtil`	`IRunUtil`: a `IRunUtil` to execute commands.
`remoteFilePath`	`String`: The remote path where to find the file.
`type`	`LogDataType`: the `LogDataType` of the logged file.

Returns
`boolean`	whether the file is logged successfully.

logNestedRemoteFile

public static boolean logNestedRemoteFile (ITestLogger logger, 
                GceAvdInfo gceAvd, 
                TestDeviceOptions options, 
                IRunUtil runUtil, 
                String remoteFilePath, 
                LogDataType type, 
                String baseName)

Fetch a remote file from a nested instance and log it.

Parameters
`logger`	`ITestLogger`: The `ITestLogger` where to log the file.
`gceAvd`	`GceAvdInfo`: The `GceAvdInfo` that describe the device.
`options`	`TestDeviceOptions`: a `TestDeviceOptions` describing the device options to be used for the GCE device.
`runUtil`	`IRunUtil`: a `IRunUtil` to execute commands.
`remoteFilePath`	`String`: The remote path where to find the file.
`type`	`LogDataType`: the `LogDataType` of the logged file.
`baseName`	`String`: The base name to use to log the file. If null the actual file name will be used.

Returns
`boolean`	whether the file is logged successfully.

logSerialOutput

public void logSerialOutput (GceAvdInfo infos, 
                ITestLogger logger)

Log the serial output of a device described by GceAvdInfo.

Parameters
`infos`	`GceAvdInfo`: The `GceAvdInfo` describing the instance.
`logger`	`ITestLogger`: The `ITestLogger` where to log the serial log.

remoteSshCommandExecution

public static CommandResult remoteSshCommandExecution (GceAvdInfo gceAvd, 
                TestDeviceOptions options, 
                IRunUtil runUtil, 
                long timeoutMs, 
                String... command)

Execute the remote command via ssh on an instance.

Parameters
`gceAvd`	`GceAvdInfo`: The `GceAvdInfo` that describe the device.
`options`	`TestDeviceOptions`: a `TestDeviceOptions` describing the device options to be used for the GCE device.
`runUtil`	`IRunUtil`: a `IRunUtil` to execute commands.
`timeoutMs`	`long`: The timeout in millisecond for the command. 0 means no timeout.
`command`	`String`: The remote command to execute.

Returns
`CommandResult`	`CommandResult` containing the result of the execution.

shutdownGce

public boolean shutdownGce ()

Shutdown the Gce instance associated with the startGce().

Returns
`boolean`	returns true if gce shutdown was requested as non-blocking.

startGce

public GceAvdInfo startGce (String ipDevice, 
                String user, 
                Integer offset, 
                MultiMap<String, String> attributes, 
                ITestLogger logger)

Attempt to start a gce instance with either Acloud or Oxygen.

Parameters
`ipDevice`	`String`: the initial IP of the GCE instance to run AVD in, `null` if not applicable
`user`	`String`: the host running user of AVD, `null` if not applicable
`offset`	`Integer`: the device num offset of the AVD in the host, `null` if not applicable
`attributes`	`MultiMap`: attributes associated with current invocation, used for passing applicable information down to the GCE instance to be added as VM metadata
`logger`	`ITestLogger`: The `ITestLogger` where to log the device launch logs.

Returns
`GceAvdInfo`	a `GceAvdInfo` describing the GCE instance. Could be a BOOT_FAIL instance.

Throws
	com.android.tradefed.targetprep.TargetSetupError
`TargetSetupError`

startGce

public GceAvdInfo startGce ()

Returns
`GceAvdInfo`

Throws
`TargetSetupError`

startGce

public GceAvdInfo startGce (String ipDevice, 
                MultiMap<String, String> attributes)

Attempt to start a gce instance.

Parameters
`ipDevice`	`String`: the initial IP of the GCE instance to run AVD in, `null` if not applicable
`attributes`	`MultiMap`: attributes associated with current invocation, used for passing applicable information down to the GCE instance to be added as VM metadata

Returns
`GceAvdInfo`	a `GceAvdInfo` describing the GCE instance. Could be a BOOT_FAIL instance.

Throws
	com.android.tradefed.targetprep.TargetSetupError
`TargetSetupError`

startGce

public GceAvdInfo startGce (String ipDevice, 
                String user, 
                Integer offset, 
                MultiMap<String, String> attributes)

Attempt to start a gce instance with either Acloud or Oxygen.

Parameters
`ipDevice`	`String`: the initial IP of the GCE instance to run AVD in, `null` if not applicable
`user`	`String`: the host running user of AVD, `null` if not applicable
`offset`	`Integer`: the device num offset of the AVD in the host, `null` if not applicable
`attributes`	`MultiMap`: attributes associated with current invocation, used for passing applicable information down to the GCE instance to be added as VM metadata

Returns
`GceAvdInfo`	a `GceAvdInfo` describing the GCE instance. Could be a BOOT_FAIL instance.

Throws
	com.android.tradefed.targetprep.TargetSetupError
`TargetSetupError`

startMultiDevicesGce

public  startMultiDevicesGce ( buildInfos)

This method is deprecated.
Remove this after master branch is updated.

Parameters
`buildInfos`

Returns

Throws
`TargetSetupError`

startMultiDevicesGce

public  startMultiDevicesGce ( buildInfos, 
                MultiMap<String, String> attributes)

Attempt to start multi devices gce instance with Oxygen.

Parameters
`buildInfos`	: `ERROR(/List)`
`attributes`	`MultiMap`: attributes associated with current invocation

Returns
	a `ERROR(/List)` describing the GCE Avd Info.

Throws
`TargetSetupError`

Protected methods

buildShutdownCommand

protected static  buildShutdownCommand (File config, 
                TestDeviceOptions options, 
                String instanceName, 
                String hostname, 
                boolean isIpPreconfigured)

Parameters
`config`	`File`
`options`	`TestDeviceOptions`
`instanceName`	`String`
`hostname`	`String`
`isIpPreconfigured`	`boolean`

Returns

extractInstanceName

protected String extractInstanceName (String bootupLogs)

Retrieve the instance name from the gce boot logs. Search for the 'name': 'gce-' pattern to extract the name of it. We extract from the logs instead of result file because on gce boot failure, the attempted instance name won't show in json.

Parameters
`bootupLogs`	`String`

Returns
`String`