VM

VM

An Instance object allows you to interact with a Google Compute Engine instance.

Constructor

new VM(zone, name)

Parameters:
Name Type Description
zone Zone

Zone object this instance belongs to.
name string

Name of the instance.
See:
Example
const Compute = require('@google-cloud/compute');
const compute = new Compute();
const zone = compute.zone('zone-name');
const vm = zone.vm('vm-name');

Members

id

name

zone

The parent Zone instance of this VM instance.

Methods

attachDisk(disk, optionsopt, callback)

Attach a disk to the instance.

Parameters:
Name Type Attributes Description
disk module:compute/disk

The disk to attach.
options object <optional>

See the Instances: attachDisk request body.

Properties
Name Type Description
readOnly boolean

Attach the disk in read-only mode. (Alias for options.mode = READ_ONLY)
callback function

The callback function.

Properties
Name Type Attributes Description
err error <nullable>

An error returned while making this request.
operation Operation

An operation object that can be used to check the status of the request.
apiResponse object

The full API response.
See:
Throws:

if a {module:compute/disk} is not provided.

Type
Error
Example
const Compute = require('@google-cloud/compute');
const compute = new Compute();
const zone = compute.zone('zone-name');
const vm = zone.vm('vm-name');

const disk = zone.disk('my-disk');

function callback(err, operation, apiResponse) {
  // `operation` is an Operation object that can be used to check the status
  // of the request.
}

vm.attachDisk(disk, callback);

//-
// Provide an options object to customize the request.
//-
const options = {
  autoDelete: true,
  readOnly: true
};

vm.attachDisk(disk, options, callback);

//-
// If the callback is omitted, we'll return a Promise.
//-
vm.attachDisk(disk, options).then(function(data) {
  const operation = data[0];
  const apiResponse = data[1];
});

create(config)

Create a virtual machine.

Parameters:
Name Type Description
config object

See {Zone#createVM}.
Example
const Compute = require('@google-cloud/compute');
const compute = new Compute();
const zone = compute.zone('zone-name');
const vm = zone.vm('vm-name');

const config = {
  // ...
};

vm.create(config, function(err, vm, operation, apiResponse) {
  // `vm` is a VM object.

  // `operation` is an Operation object that can be used to check the
  // status of the request.
});

//-
// If the callback is omitted, we'll return a Promise.
//-
vm.create(config).then(function(data) {
  const vm = data[0];
  const operation = data[1];
  const apiResponse = data[2];
});

delete(callbackopt)

Delete the instance.

Parameters:
Name Type Attributes Description
callback function <optional>

The callback function.

Properties
Name Type Attributes Description
err error <nullable>

An error returned while making this request.
operation Operation

An operation object that can be used to check the status of the request.
apiResponse object

The full API response.
See:
Example
const Compute = require('@google-cloud/compute');
const compute = new Compute();
const zone = compute.zone('zone-name');
const vm = zone.vm('vm-name');

vm.delete(function(err, operation, apiResponse) {
  // `operation` is an Operation object that can be used to check the status
  // of the request.
});

//-
// If the callback is omitted, we'll return a Promise.
//-
vm.delete().then(function(data) {
  const operation = data[0];
  const apiResponse = data[1];
});

detachDisk(deviceName, callbackopt)

Detach a disk from the instance.

Parameters:
Name Type Attributes Description
deviceName module:compute/disk | string

The device name of the disk to detach. If a Disk object is provided, we try to find the device name automatically by searching through the attached disks on the instance.
callback function <optional>

The callback function.

Properties
Name Type Attributes Description
err error <nullable>

An error returned while making this request.
operation Operation

An operation object that can be used to check the status of the request.
apiResponse object

The full API response.
See:
Example
const Compute = require('@google-cloud/compute');
const compute = new Compute();
const zone = compute.zone('zone-name');
const vm = zone.vm('vm-name');

const disk = zone.disk('my-disk');

vm.detachDisk(disk, function(err, operation, apiResponse) {
  // `operation` is an Operation object that can be used to check the status
  // of the request.
});

//-
// If the callback is omitted, we'll return a Promise.
//-
vm.detachDisk(disk).then(function(data) {
  const operation = data[0];
  const apiResponse = data[1];
});

exists(callback)

Check if the vm exists.

Parameters:
Name Type Description
callback function

The callback function.

Properties
Name Type Attributes Description
err error <nullable>

An error returned while making this request.
exists boolean

Whether the vm exists or not.
Example
const Compute = require('@google-cloud/compute');
const compute = new Compute();
const zone = compute.zone('zone-name');
const vm = zone.vm('vm-name');

vm.exists(function(err, exists) {});

//-
// If the callback is omitted, we'll return a Promise.
//-
vm.exists().then(function(data) {
  const exists = data[0];
});

get(optionsopt)

Get a virtual machine if it exists.

You may optionally use this to "get or create" an object by providing an object with autoCreate set to true. Any extra configuration that is normally required for the create method must be contained within this object as well.

Parameters:
Name Type Attributes Description
options options <optional>

Configuration object.

Properties
Name Type Description
autoCreate boolean

Automatically create the object if it does not exist. Default: false
Example
const Compute = require('@google-cloud/compute');
const compute = new Compute();
const zone = compute.zone('zone-name');
const vm = zone.vm('vm-name');

vm.get(function(err, vm, apiResponse) {
  // `vm` is a VM object.
});

//-
// If the callback is omitted, we'll return a Promise.
//-
vm.get().then(function(data) {
  const vm = data[0];
  const apiResponse = data[1];
});

getLabels(callback)

Get the instance's labels and their fingerprint.

This method wraps {module:compute/vm#getMetadata}, returning only the labels property.

Parameters:
Name Type Description
callback function

The callback function.

Properties
Name Type Attributes Description
err error <nullable>

An error returned while making this request.
labels Array.<object>

Label objects from this VM.
fingerprint string

The current label fingerprint.
apiResponse object

The full API response.
Example
const Compute = require('@google-cloud/compute');
const compute = new Compute();
const zone = compute.zone('zone-name');
const vm = zone.vm('vm-name');

vm.getLabels(function(err, labels, fingerprint, apiResponse) {});

//-
// If the callback is omitted, we'll return a Promise.
//-
vm.getLabels().then(function(data) {
  const labels = data[0];
  const fingerprint = data[1];
  const apiResponse = data[2];
});

getMetadata(callbackopt)

Get the instance's metadata.

Parameters:
Name Type Attributes Description
callback function <optional>

The callback function.

Properties
Name Type Attributes Description
err error <nullable>

An error returned while making this request.
metadata object

The instance's metadata.
apiResponse object

The full API response.
See:
Example
const Compute = require('@google-cloud/compute');
const compute = new Compute();
const zone = compute.zone('zone-name');
const vm = zone.vm('vm-name');

vm.getMetadata(function(err, metadata, apiResponse) {});

//-
// If the callback is omitted, we'll return a Promise.
//-
vm.getMetadata().then(function(data) {
  // Representation of this VM as the API sees it.
  const metadata = data[0];
  const apiResponse = data[1];

  // Custom metadata and predefined keys.
  const customMetadata = metadata.metadata;
});

getSerialPortOutput(portopt, optionsopt, callback)

Returns the serial port output for the instance.

Parameters:
Name Type Attributes Description
port number <optional>

The port from which the output is retrieved (1-4). Default: 1.
options object <optional>

Configuration object.

Properties
Name Type Attributes Description
start string <optional>

The starting byte position of the output to return. To start with the first byte of output to the specified port, omit this field or set it to 0.
callback function

The callback function.

Properties
Name Type Attributes Description
err error <nullable>

An error returned while making this request.
output object

The output from the port.
apiResponse object

The full API response.
See:
Example
const Compute = require('@google-cloud/compute');
const compute = new Compute();
const zone = compute.zone('zone-name');
const vm = zone.vm('vm-name');

vm.getSerialPortOutput(function(err, output, apiResponse) {});

//-
// If the callback is omitted, we'll return a Promise.
//-
vm.getSerialPortOutput().then(function(data) {
  const output = data[0];
  const apiResponse = data[1];
});

getTags(callback)

Get the instance's tags and their fingerprint.

This method wraps {module:compute/vm#getMetadata}, returning only the tags property.

Parameters:
Name Type Description
callback function

The callback function.

Properties
Name Type Attributes Description
err error <nullable>

An error returned while making this request.
tags Array.<object>

Tag objects from this VM.
fingerprint string

The current tag fingerprint.
apiResponse object

The full API response.
Example
const Compute = require('@google-cloud/compute');
const compute = new Compute();
const zone = compute.zone('zone-name');
const vm = zone.vm('vm-name');

vm.getTags(function(err, tags, fingerprint, apiResponse) {});

//-
// If the callback is omitted, we'll return a Promise.
//-
vm.getTags().then(function(data) {
  const tags = data[0];
  const fingerprint = data[1];
  const apiResponse = data[2];
});

reset(callbackopt)

Reset the instance.

Parameters:
Name Type Attributes Description
callback function <optional>

The callback function.

Properties
Name Type Attributes Description
err error <nullable>

An error returned while making this request.
operation Operation

An operation object that can be used to check the status of the request.
apiResponse object

The full API response.
See:
Example
const Compute = require('@google-cloud/compute');
const compute = new Compute();
const zone = compute.zone('zone-name');
const vm = zone.vm('vm-name');

vm.reset(function(err, operation, apiResponse) {
  // `operation` is an Operation object that can be used to check the status
  // of the request.
});

//-
// If the callback is omitted, we'll return a Promise.
//-
vm.reset().then(function(data) {
  const operation = data[0];
  const apiResponse = data[1];
});

resize(machineType, optionsopt, callback)

Set the machine type for this instance, stopping and restarting the VM as necessary.

For a list of the standard, high-memory, and high-CPU machines you may choose from, see Predefined machine types.

In order to change the machine type, the VM must not be running. This method will automatically stop the VM if it is running before changing the machine type. After it is sucessfully changed, the VM will be started.

Parameters:
Name Type Attributes Description
machineType string

Full or partial machine type. See a list of predefined machine types here.
options object <optional>

Configuration object.

Properties
Name Type Description
start boolean

Start the VM after successfully updating the machine type. Default: false.
callback function

The callback function.

Properties
Name Type Attributes Description
err error <nullable>

An error returned while making this request.
apiResponse object

The full API response.
See:
Example
const Compute = require('@google-cloud/compute');
const compute = new Compute();
const zone = compute.zone('zone-name');
const vm = zone.vm('vm-name');

vm.resize('n1-standard-1', function(err, apiResponse) {
  if (!err) {
    // The VM is running and its machine type was changed successfully.
  }
});

//-
// By default, calling `resize` will start your server after updating its
// machine type. If you want to leave it stopped, set `options.start` to
// `false`.
//-
const options = {
  start: false
};

vm.resize('ns-standard-1', options, function(err, apiResponse) {
  if (!err) {
    // The VM is stopped and its machine type was changed successfully.
  }
});

//-
// If the callback is omitted, we'll return a Promise.
//-
vm.resize('ns-standard-1', options).then(function(data) {
  const apiResponse = data[0];
});

setLabels(labels, callbackopt)

Set labels for this instance.

Parameters:
Name Type Attributes Description
labels object

New labels.
callback function <optional>

The callback function.

Properties
Name Type Attributes Description
err error <nullable>

An error returned while making this request.
operation Operation

An operation object that can be used to check the status of the request.
apiResponse object

The full API response.
See:
Example
const Compute = require('@google-cloud/compute');
const compute = new Compute();
const zone = compute.zone('zone-name');
const vm = zone.vm('vm-name');

const labels = {
  'startup-script': '...',
  customKey: null // Setting `null` will remove the `customKey` property.
};

vm.setLabels(labels, function(err, operation, apiResponse) {
  // `operation` is an Operation object that can be used to check the status
  // of the request.
});

//-
// If the callback is omitted, we'll return a Promise.
//-
vm.setLabels(labels).then(function(data) {
  const operation = data[0];
  const apiResponse = data[1];
});

setMetadata(metadata, callbackopt)

Set the custom metadata for this instance.

This will combine the metadata key/value pairs with any pre-existing metadata. Any changes will override pre-existing keys. To remove a pre-existing key, explicitly set the key's value to null.

Parameters:
Name Type Attributes Description
metadata object

New metadata.
callback function <optional>

The callback function.

Properties
Name Type Attributes Description
err error <nullable>

An error returned while making this request.
operation Operation

An operation object that can be used to check the status of the request.
apiResponse object

The full API response.
See:
Example
const Compute = require('@google-cloud/compute');
const compute = new Compute();
const zone = compute.zone('zone-name');
const vm = zone.vm('vm-name');

const metadata = {
  'startup-script': '...',
  customKey: null // Setting `null` will remove the `customKey` property.
};

vm.setMetadata(metadata, function(err, operation, apiResponse) {
  // `operation` is an Operation object that can be used to check the status
  // of the request.
});

//-
// If the callback is omitted, we'll return a Promise.
//-
vm.setMetadata(metadata).then(function(data) {
  const operation = data[0];
  const apiResponse = data[1];
});

setTags(tags, fingerprint, callbackopt)

Set the instance's tags.

Parameters:
Name Type Attributes Description
tags Array.<string>

The new tags for the instance.
fingerprint string

The current tags fingerprint. An up-to-date fingerprint must be provided.
callback function <optional>

The callback function.

Properties
Name Type Attributes Description
err error <nullable>

An error returned while making this request.
operation Operation

An operation object that can be used to check the status of the request.
apiResponse object

The full API response.
See:
Example
const Compute = require('@google-cloud/compute');
const compute = new Compute();
const zone = compute.zone('zone-name');
const vm = zone.vm('vm-name');

vm.getTags(function(err, tags, fingerprint) {
  tags.push('new-tag');

 vm.setTags(tags, fingerprint, function(err, operation, apiResponse) {
    // `operation` is an Operation object that can be used to check the
    //  status of the request.
  });
});

//-
// If the callback is omitted, we'll return a Promise.
//-
vm.getTags().then(function(data) {
  const tags = data[0];
  const fingerprint = data[1];

  tags.push('new-tag');

  return vm.setTags(tags, fingerprint);
}).then(function(data) {
  const operation = data[0];
  const apiResponse = data[1];
});

start(callbackopt)

Start the instance.

Parameters:
Name Type Attributes Description
callback function <optional>

The callback function.

Properties
Name Type Attributes Description
err error <nullable>

An error returned while making this request.
operation Operation

An operation object that can be used to check the status of the request.
apiResponse object

The full API response.
See:
Example
const Compute = require('@google-cloud/compute');
const compute = new Compute();
const zone = compute.zone('zone-name');
const vm = zone.vm('vm-name');

vm.start(function(err, operation, apiResponse) {
  // `operation` is an Operation object that can be used to check the status
  // of the request.
});

//-
// If the callback is omitted, we'll return a Promise.
//-
vm.start().then(function(data) {
  const operation = data[0];
  const apiResponse = data[1];
});

stop(callbackopt)

Stop the instance.

Parameters:
Name Type Attributes Description
callback function <optional>

The callback function.

Properties
Name Type Attributes Description
err error <nullable>

An error returned while making this request.
operation Operation

An operation object that can be used to check the status of the request.
apiResponse object

The full API response.
See:
Example
const Compute = require('@google-cloud/compute');
const compute = new Compute();
const zone = compute.zone('zone-name');
const vm = zone.vm('vm-name');

vm.stop(function(err, operation, apiResponse) {
  // `operation` is an Operation object that can be used to check the status
  // of the request.
});

//-
// If the callback is omitted, we'll return a Promise.
//-
vm.stop().then(function(data) {
  const operation = data[0];
  const apiResponse = data[1];
});

update(callbackopt)

Update the instance.

NOTE: This method will pull the latest record of the current metadata, then merge it with the object you provide. This means there is a chance of a mismatch in data if the resource is updated immediately after we pull the metadata, but before we update it.

Parameters:
Name Type Attributes Description
callback function <optional>

The callback function.

Properties
Name Type Attributes Description
err error <nullable>

An error returned while making this request.
operation Operation

An operation object that can be used to check the status of the request.
apiResponse object

The full API response.
See:
Example
const Compute = require('@google-cloud/compute');
const compute = new Compute();
const zone = compute.zone('zone-name');
const vm = zone.vm('vm-name');

const metadata = {
  deletionProtection: false,
};

vm.update(metadata, function(err, operation, apiResponse) {
  // `operation` is an Operation object that can be used to check the
  // status of the request.
});

//-
// If the callback is omitted, we'll return a Promise.
//-
vm.update(metadata).then(function(data) {
  const operation = data[0];
  const apiResponse = data[1];
});

waitFor(status, optionsopt, callback)

This function will callback when the VM is in the specified state.

Will time out after the specified time (default: 300 seconds).

Parameters:
Name Type Attributes Description
status string

The status to wait for. This can be: - "PROVISIONING" - "STAGING" - "RUNNING" - "STOPPING" - "SUSPENDING" - "SUSPENDED" - "TERMINATED"
options object <optional>

Configuration object.

Properties
Name Type Description
timeout number

The number of seconds to wait until timing out, between 0 and 600. Default: 300
callback function

The callback function.

Properties
Name Type Attributes Description
err error <nullable>

An error returned while waiting for the status.
metadata object

The instance's metadata.
Example
const Compute = require('@google-cloud/compute');
const compute = new Compute();
const zone = compute.zone('zone-name');
const vm = zone.vm('vm-name');

vm.waitFor('RUNNING', function(err, metadata) {
  if (!err) {
    // The VM is running.
  }
});

//-
// By default, `waitFor` will timeout after 300 seconds while waiting for the
// desired state to occur. This can be changed to any number between 0 and
// 600. If the timeout is set to 0, it will poll once for status and then
// timeout if the desired state is not reached.
//-
const options = {
  timeout: 600
};

vm.waitFor('TERMINATED', options, function(err, metadata) {
  if (!err) {
    // The VM is terminated.
  }
});

//-
// If the callback is omitted, we'll return a Promise.
//-
vm.waitFor('RUNNING', options).then(function(data) {
  const metadata = data[0];
});