Constructor

VM

new VM(zone, name)

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

Parameter

zone

Zone

Zone object this instance belongs to.

name

string

Name of the instance.

See also

Instances and Networks

Instance Resource

Example

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

Properties

id

string

name

string

zone

Zone

The parent Zone instance of this VM instance.

Methods

attachDisk

attachDisk(disk, options, callback)

Attach a disk to the instance.

Parameter

disk

module:compute/disk

The disk to attach.

options

Optional

object

See the Instances: attachDisk request body.

Values in options have the following properties:

Parameter

readOnly

boolean

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

callback

function()

The callback function.

Values in callback have the following properties:

Parameter

err

error

An error returned while making this request.

Value may be null.

operation

Operation

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

apiResponse

object

The full API response.

See also

Disks Overview

Disk Resource

Instance: attachDisk API Documentation

Throws

Error 

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

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

create(config)

Create a virtual machine.

Parameter

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

delete(callback)

Delete the instance.

Parameter

callback

Optional

function()

The callback function.

Values in callback have the following properties:

Parameter

err

error

An error returned while making this request.

Value may be null.

operation

Operation

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

apiResponse

object

The full API response.

See also

Instance: delete API Documentation

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

detachDisk(deviceName, callback)

Detach a disk from the instance.

Parameter

deviceName

(module:compute/disk or 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

Optional

function()

The callback function.

Values in callback have the following properties:

Parameter

err

error

An error returned while making this request.

Value may be null.

operation

Operation

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

apiResponse

object

The full API response.

See also

Instance: detachDisk API Documentation

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

exists(callback)

Check if the vm exists.

Parameter

callback

function()

The callback function.

Values in callback have the following properties:

Parameter

err

error

An error returned while making this request.

Value may be null.

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

get(options)

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.

Parameter

options

Optional

options

Configuration object.

Values in options have the following properties:

Parameter

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];
});

getMetadata

getMetadata(callback)

Get the instance's metadata.

Parameter

callback

Optional

function()

The callback function.

Values in callback have the following properties:

Parameter

err

error

An error returned while making this request.

Value may be null.

metadata

object

The instance's metadata.

apiResponse

object

The full API response.

See also

Instance Resource

Instance: get API Documentation

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) {
  const metadata = data[0];
  const apiResponse = data[1];
});

getSerialPortOutput

getSerialPortOutput(port, callback)

Returns the serial port output for the instance.

Parameter

port

Optional

number

The port from which the output is retrieved (1-4). Default: 1.

callback

function()

The callback function.

Values in callback have the following properties:

Parameter

err

error

An error returned while making this request.

Value may be null.

output

object

The output from the port.

apiResponse

object

The full API response.

See also

Instances: getSerialPortOutput API Documentation

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

getTags(callback)

Get the instance's tags and their fingerprint.

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

Parameter

callback

function()

The callback function.

Values in callback have the following properties:

Parameter

err

error

An error returned while making this request.

Value may be null.

tags

Array of 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

reset(callback)

Reset the instance.

Parameter

callback

Optional

function()

The callback function.

Values in callback have the following properties:

Parameter

err

error

An error returned while making this request.

Value may be null.

operation

Operation

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

apiResponse

object

The full API response.

See also

Instances: reset API Documentation

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

resize(machineType, options, 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.

Parameter

machineType

string

Full or partial machine type. See a list of predefined machine types here.

options

Optional

object

Configuration object.

Values in options have the following properties:

Parameter

start

boolean

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

callback

function()

The callback function.

Values in callback have the following properties:

Parameter

err

error

An error returned while making this request.

Value may be null.

apiResponse

object

The full API response.

See also

Instances: setMachineType API Documentation

Predefined machine types

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];
});

setMetadata

setMetadata(metadata, callback)

Set the metadata for this instance.

Parameter

metadata

object

New metadata.

callback

Optional

function()

The callback function.

Values in callback have the following properties:

Parameter

err

error

An error returned while making this request.

Value may be null.

operation

Operation

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

apiResponse

object

The full API response.

See also

Instances: setMetadata API Documentation

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': '...'
};

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

setTags(tags, fingerprint, callback)

Set the instance's tags.

Parameter

tags

Array of string

The new tags for the instance.

fingerprint

string

The current tags fingerprint. An up-to-date fingerprint must be provided.

callback

Optional

function()

The callback function.

Values in callback have the following properties:

Parameter

err

error

An error returned while making this request.

Value may be null.

operation

Operation

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

apiResponse

object

The full API response.

See also

Instances: setTags API Documentation

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

start(callback)

Start the instance.

Parameter

callback

Optional

function()

The callback function.

Values in callback have the following properties:

Parameter

err

error

An error returned while making this request.

Value may be null.

operation

Operation

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

apiResponse

object

The full API response.

See also

Instances: start API Documentation

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

stop(callback)

Stop the instance.

Parameter

callback

Optional

function()

The callback function.

Values in callback have the following properties:

Parameter

err

error

An error returned while making this request.

Value may be null.

operation

Operation

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

apiResponse

object

The full API response.

See also

Instances: stop API Documentation

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];
});

waitFor

waitFor(status, options, callback)

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

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

Parameter

status

string

The status to wait for. This can be:

- "PROVISIONING"
- "STAGING"
- "RUNNING"
- "STOPPING"
- "SUSPENDING"
- "SUSPENDED"
- "TERMINATED"

options

Optional

object

Configuration object.

Values in options have the following properties:

Parameter

timeout

number

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

callback

function()

The callback function.

Values in callback have the following properties:

Parameter

err

error

An error returned while waiting for the status.

Value may be null.

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];
});