@google-cloud/compute 1.1.0

Properties

Methods

attachDisk(disk[, options], callback)
create(config)
delete([callback])
detachDisk(deviceName[, callback])
exists(callback)
get([options])

getMetadata([callback])
getSerialPortOutput([port], callback)
getTags(callback)
reset([callback])
resize(machineType[, options], callback)
setMetadata(metadata[, callback])

setTags(tags, fingerprint[, callback])
start([callback])
stop([callback])
waitFor(status[, options], callback)

new VM(zone, name)

Example

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

Parameters

Name	Type	Optional	Description
zone			Zone object this instance belongs to.
name			Name of the instance.

See also: Instances and Networks; Instance Resource

Properties

id string

name string

zone Zone

The parent Zone instance of this VM instance.

Methods

attachDisk(disk[, options], callback)

Attach a disk to the instance.

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

Parameters

Name Type Optional Description

disk

module:compute/disk

The disk to attach.

options

object

Yes

See the Instances: attachDisk request body.

Values in options have the following properties:

Name	Type	Optional	Description
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:

Name

Type

Optional

Description

err

error

An error returned while making this request.

Value can 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.

create(config)

Create a virtual machine.

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

Parameter

Name	Type	Optional	Description
config	object		See {Zone#createVM}.

delete([callback])

Delete the instance.

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

Parameters

Name Type Optional Description

callback

function()

Yes

The callback function.

Values in callback have the following properties:

Name

Type

Optional

Description

err

error

An error returned while making this request.

Value can 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

detachDisk(deviceName[, callback])

Detach a disk from the instance.

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

Parameters

Name Type Optional Description

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

function()

Yes

The callback function.

Values in callback have the following properties:

Name

Type

Optional

Description

err

error

An error returned while making this request.

Value can 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

exists(callback)

Check if the vm exists.

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

Parameters

Name Type Optional Description

callback

function()

The callback function.

Values in callback have the following properties:

Name

Type

Optional

Description

err

error

An error returned while making this request.

Value can be null.

exists

boolean

Whether the vm exists or not.

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.

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

Parameters

Name Type Optional Description

options

Yes

Configuration object.

Values in options have the following properties:

Name	Type	Optional	Description
autoCreate	boolean		Automatically create the object if it does not exist. Default: `false`

getMetadata([callback])

Get 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.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;
});

Parameters

Name Type Optional Description

callback

function()

Yes

The callback function.

Values in callback have the following properties:

Name

Type

Optional

Description

err

error

An error returned while making this request.

Value can be null.

metadata

object

The instance's metadata.

apiResponse

object

The full API response.

See also: Instance Resource; Instance: get API Documentation

getSerialPortOutput([port], callback)

Returns the serial port output for the instance.

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

Parameters

Name Type Optional Description

port

number

Yes

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

callback

function()

The callback function.

Values in callback have the following properties:

Name

Type

Optional

Description

err

error

An error returned while making this request.

Value can be null.

output

object

The output from the port.

apiResponse

object

The full API response.

See also: Instances: getSerialPortOutput API Documentation

getTags(callback)

Get the instance's tags and their fingerprint.

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

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

Parameters

Name Type Optional Description

callback

function()

The callback function.

Values in callback have the following properties:

Name	Type	Description
err	error	An error returned while making this request. Value can be null.
tags	Array of object	Tag objects from this VM.
fingerprint	string	The current tag fingerprint.
apiResponse	object	The full API response.

reset([callback])

Reset the instance.

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

Parameters

Name Type Optional Description

callback

function()

Yes

The callback function.

Values in callback have the following properties:

Name

Type

Optional

Description

err

error

An error returned while making this request.

Value can 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

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.

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

Parameters

Name Type Optional Description

machineType

string

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

options

object

Yes

Configuration object.

Values in options have the following properties:

Name	Type	Optional	Description
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:

Name

Type

Optional

Description

err

error

An error returned while making this request.

Value can be null.

apiResponse

object

The full API response.

See also: Instances: setMachineType API Documentation; Predefined machine types

setMetadata(metadata[, callback])

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.

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

Parameters

Name Type Optional Description

metadata

object

New metadata.

callback

function()

Yes

The callback function.

Values in callback have the following properties:

Name

Type

Optional

Description

err

error

An error returned while making this request.

Value can 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

setTags(tags, fingerprint[, callback])

Set the instance's tags.

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

Parameters

Name Type Optional Description

start([callback])

Start the instance.

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

Parameters

Name Type Optional Description

callback

function()

Yes

The callback function.

Values in callback have the following properties:

Name

Type

Optional

Description

err

error

An error returned while making this request.

Value can 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

stop([callback])

Stop the instance.

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

Parameters

Name Type Optional Description

callback

function()

Yes

The callback function.

Values in callback have the following properties:

Name

Type

Optional

Description

err

error

An error returned while making this request.

Value can 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

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).

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

Parameters

Name Type Optional Description

status

string

The status to wait for. This can be: - "PROVISIONING" - "STAGING" - "RUNNING" - "STOPPING" - "SUSPENDING" - "SUSPENDED" - "TERMINATED"

options

object

Yes

Configuration object.

Values in options have the following properties:

Name	Type	Optional	Description
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:

Name

Type

Optional

Description

err

error

An error returned while waiting for the status.

Value can be null.

metadata

object

The instance's metadata.