The AWS SDK for JavaScript version 3 (v3) is a rewrite of v2 with some great new features, including modular architecture. For more information, see the AWS SDK for JavaScript v3 Developer Guide.

Managing Amazon EC2 Instances

This Node.js code example shows:

The Scenario

In this example, you use a series of Node.js modules to perform several basic instance management operations. The Node.js modules use the SDK for JavaScript to manage instances by using these Amazon EC2 client class methods:

For more information about the lifecycle of Amazon EC2 instances, see Instance Lifecycle in the Amazon EC2 User Guide for Linux Instances.

Prerequisite Tasks

To set up and run this example, first complete these tasks:

Describing Your Instances

Create a Node.js module with the file name ec2_describeinstances.js. Be sure to configure the SDK as previously shown. To access Amazon EC2, create an AWS.EC2 service object. Call the describeInstances method of the Amazon EC2 service object to retrieve a detailed description of your instances.

// Load the AWS SDK for Node.js
var AWS = require('aws-sdk');
// Set the region 
AWS.config.update({region: 'REGION'});

// Create EC2 service object
var ec2 = new AWS.EC2({apiVersion: '2016-11-15'});

var params = {
  DryRun: false
};

// Call EC2 to retrieve policy for selected bucket
ec2.describeInstances(params, function(err, data) {
  if (err) {
    console.log("Error", err.stack);
  } else {
    console.log("Success", JSON.stringify(data));
  }
});

To run the example, type the following at the command line.

node ec2_describeinstances.js

This sample code can be found here on GitHub.

Managing Instance Monitoring

Create a Node.js module with the file name ec2_monitorinstances.js. Be sure to configure the SDK as previously shown. To access Amazon EC2, create an AWS.EC2 service object. Add the instance IDs of the instances for which you want to control monitoring.

Based on the value of a command-line argument (ON or OFF), call either the monitorInstances method of the Amazon EC2 service object to begin detailed monitoring of the specified instances or call the unmonitorInstances method. Use the DryRun parameter to test whether you have permission to change instance monitoring before you attempt to change the monitoring of these instances.

// Load the AWS SDK for Node.js
var AWS = require('aws-sdk');
// Set the region 
AWS.config.update({region: 'REGION'});

// Create EC2 service object
var ec2 = new AWS.EC2({apiVersion: '2016-11-15'});

var params = {
  InstanceIds: ['INSTANCE_ID'],
  DryRun: true
};

if (process.argv[2].toUpperCase() === "ON") {
  // Call EC2 to start monitoring the selected instances
  ec2.monitorInstances(params, function(err, data) {
    if (err && err.code === 'DryRunOperation') {
      params.DryRun = false;
      ec2.monitorInstances(params, function(err, data) {
          if (err) {
            console.log("Error", err);
          } else if (data) {
            console.log("Success", data.InstanceMonitorings);
          }
      });
    } else {
      console.log("You don't have permission to change instance monitoring.");
    }
  });
} else if (process.argv[2].toUpperCase() === "OFF") {
  // Call EC2 to stop monitoring the selected instances
  ec2.unmonitorInstances(params, function(err, data) {
    if (err && err.code === 'DryRunOperation') {
      params.DryRun = false;
      ec2.unmonitorInstances(params, function(err, data) {
          if (err) {
            console.log("Error", err);
          } else if (data) {
            console.log("Success", data.InstanceMonitorings);
          }
      });
    } else {
      console.log("You don't have permission to change instance monitoring.");
    }
  });
}

To run the example, type the following at the command line, specifying ON to begin detailed monitoring or OFF to discontinue monitoring.

node ec2_monitorinstances.js ON

This sample code can be found here on GitHub.

Starting and Stopping Instances

Create a Node.js module with the file name ec2_startstopinstances.js. Be sure to configure the SDK as previously shown. To access Amazon EC2, create an AWS.EC2 service object. Add the instance IDs of the instances you want to start or stop.

Based on the value of a command-line argument (START or STOP), call either the startInstances method of the Amazon EC2 service object to start the specified instances, or the stopInstances method to stop them. Use the DryRun parameter to test whether you have permission before actually attempting to start or stop the selected instances.

// Load the AWS SDK for Node.js
var AWS = require('aws-sdk');
// Set the region 
AWS.config.update({region: 'REGION'});

// Create EC2 service object
var ec2 = new AWS.EC2({apiVersion: '2016-11-15'});

var params = {
  InstanceIds: [process.argv[3]],
  DryRun: true
};

if (process.argv[2].toUpperCase() === "START") {
  // Call EC2 to start the selected instances
  ec2.startInstances(params, function(err, data) {
    if (err && err.code === 'DryRunOperation') {
      params.DryRun = false;
      ec2.startInstances(params, function(err, data) {
          if (err) {
            console.log("Error", err);
          } else if (data) {
            console.log("Success", data.StartingInstances);
          }
      });
    } else {
      console.log("You don't have permission to start instances.");
    }
  });
} else if (process.argv[2].toUpperCase() === "STOP") {
  // Call EC2 to stop the selected instances
  ec2.stopInstances(params, function(err, data) {
    if (err && err.code === 'DryRunOperation') {
      params.DryRun = false;
      ec2.stopInstances(params, function(err, data) {
          if (err) {
            console.log("Error", err);
          } else if (data) {
            console.log("Success", data.StoppingInstances);
          }
      });
    } else {
      console.log("You don't have permission to stop instances");
    }
  });
}

To run the example, type the following at the command line specifying START to start the instances or STOP to stop them.

node ec2_startstopinstances.js START INSTANCE_ID

This sample code can be found here on GitHub.

Rebooting Instances

Create a Node.js module with the file name ec2_rebootinstances.js. Be sure to configure the SDK as previously shown. To access Amazon EC2, create an Amazon EC2 service object. Add the instance IDs of the instances you want to reboot. Call the rebootInstances method of the AWS.EC2 service object to reboot the specified instances. Use the DryRun parameter to test whether you have permission to reboot these instances before actually attempting to reboot them.

// Load the AWS SDK for Node.js
var AWS = require('aws-sdk');
// Set the region 
AWS.config.update({region: 'REGION'});

// Create EC2 service object
var ec2 = new AWS.EC2({apiVersion: '2016-11-15'});

var params = {
  InstanceIds: ['INSTANCE_ID'],
  DryRun: true
};

// Call EC2 to reboot instances
ec2.rebootInstances(params, function(err, data) {
  if (err && err.code === 'DryRunOperation') {
    params.DryRun = false;
    ec2.rebootInstances(params, function(err, data) {
        if (err) {
          console.log("Error", err);
        } else if (data) {
          console.log("Success", data);
        }
    });
  } else {
    console.log("You don't have permission to reboot instances.");
  }
});

To run the example, type the following at the command line.

node ec2_rebootinstances.js

This sample code can be found here on GitHub.