Queries AWS for running EC2 instances.

$ npm install aws-ec2-running

var createQuery = require( 'aws-ec2-running' );

Creates a new Query instance for retrieving a list of running EC2 instances from AWS.

var opts = {
	'key': 'XXXXXXXXXXXXXXXXXX',
	'secret': 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'	
};

var query = createQuery( opts );
query.on( 'data', onData );

function onData( evt ) {
	console.log( evt.data );
	// returns ['<instance_id>','<instance_id>',...]
}

A callback function may be provided which accepts two arguments: error and data. When a request is successful, error is null.

var opts = {
	'key': 'XXXXXXXXXXXXXXXXXX',
	'secret': 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'	
};

var query = createQuery( opts, onData );

function onData( error, data ) {
	if ( error ) {
		throw error;
	}
	console.log( data );
	// returns ['<instance_id>','<instance_id>',...]
}

The constructor accepts the following options:

• region: AWS region. Default: 'us-east-1'.

• tags: object array specifying EC2 instance tags by which to filter running instances. Each object should consist of key and value properties, where key is the tag and value is the tag value.

  var opts = {
  	'key': 'XXXXXXXXXXXXXXXXXX',
  	'secret': 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
  	'tags': [
  		{
  			'key': 'app',
  			'value': 'amazing_app'
  		},
  		...
  	]
  };
  
  // Return only those running instances having the `app` tag with a value `amazing_app`...
  var query = createQuery( opts );
  query.on( 'data', onData );
  
  function onData( evt ) {
  	console.log( evt.data );
  	// returns ['<id>','<id>',...]
  }

• interval: positive number defining a poll interval for repeatedly querying AWS. The interval should be in units of milliseconds. If an interval is not provided, only a single query is made. Default: 300000 (5min).

  var opts = {
  	'key': 'XXXXXXXXXXXXXXXXXX',
  	'secret': 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
  	'interval': 3600000 // 1hr
  };
  
  // Every hour, fetch the list of running EC2 instances...
  var query = createQuery( opts );
  query.on( 'data', onData );
  
  function onData( evt ) {
  	console.log( evt.data );
  	// returns ['<id>','<id>',...]
  }

===

A Query instance has the following attributes...

Attribute defining a poll interval for repeatedly querying AWS. An interval should be in units of milliseconds. Default: 300000 (5min).

query.interval = 60000; // 1 minute

Once set, a Query instance immediately begins polling AWS according to the specified interval.

Read-only attribute providing the number of pending requests.

if ( query.pending ) {
	console.log( '%d requests still pending...', query.pending );
}

===

A Query instance has the following methods...

Instructs a Query instance to perform a single query.

query.query();

This method is useful when manually polling AWS (i.e., no fixed interval).

Instructs a Query instance to start polling AWS.

query.start();

Instructs a Query instance to stop polling AWS.

query.stop();

Note: pending requests are still allowed to complete.

===

A Query instance emits the following events...

A Query instance emits an error event whenever a non-fatal error occurs; e.g., an invalid value is assigned to an attribute, AWS query errors, etc. To capture errors,

function onError( evt ) {
	console.error( evt );
}

query.on( 'error', onError );

A Query instance emits an init event prior to querying AWS. Each query is assigned a unique identifier, which is emitted during this event.

function onInit( evt ) {
	console.log( evt.rid );
}

query.on( 'init', onInit );

Listening to this event can be useful for query monitoring.

A Query instance emits a data event after processing all query data. For queries involving pagination, all data is concatenated into a single array.

function onData( evt ) {
	console.log( evt.data );
}

query.on( 'data', onData );

A Query instance emits an end event once a query is finished processing requests.

function onEnd( evt ) {
	console.log( 'Query %d end...', evt.rid );
}

query.on( 'end', onEnd );

A Query instance emits a pending event anytime the number of pending requests changes. Listening to this event could be useful when wanting to gracefully end a Query instance (e.g., allow all pending requests to finish before killing a process).

function onPending( count ) {
	console.log( '%d pending requests...', count );
}

query.on( 'pending', onPending );

A Query instance emits a start event immediately before creating a new interval timer and starting to poll AWS.

function onStart() {
	console.log( 'Polling has begun...' );
}

query.on( 'start', onStart );

A Query instance emits a stop event when it stops polling AWS.

function onStop() {
	console.log( 'Polling has ended...' );
}

query.on( 'stop', onStop );

Note: pending requests may result in data and other associated events being emitted after a stop event occurs.

var createQuery = require( 'aws-ec2-running' );

var opts = {
	'key': '<your_key_id_goes_here>', // INSERT KEY HERE //
	'secret': '<your_secret_goes_here>', // INSERT SECRET HERE //
	'interval': 10000
};

/**
* FUNCTION: onError( evt )
*	Event listener invoked when a query instance emits an `error`.
*
* @param {Object} evt - error event object
*/
function onError( evt ) {
	console.error( evt );
}

/**
* FUNCTION: onData( evt )
*	Event listener invoked when data has been received.
*
* @param {Object} evt - event object
*/
function onData( evt ) {
	console.log( evt.data );
}

/**
* FUNCTION: onEnd( evt )
*	Event listener invoked when a query ends.
*
* @param {Object} evt - end event object
*/
function onEnd( evt ) {
	console.log( 'Query %d ended...', evt.rid );
}

var query = createQuery( opts );
query.on( 'error', onError );
query.on( 'data', onData );
query.on( 'end', onEnd );

// Stop polling after 60 seconds...
setTimeout( function stop() {
	query.stop();
}, 60000 );

To run the example code from the top-level application directory,

$ node ./examples/index.js

To use the module as a general utility, install the module globally

$ npm install -g aws-ec2-running

Usage: aws-ec2-running [options]

Options:

  -h,    --help                Print this message.
  -V,    --version             Print the package version.
         --key [key]           AWS credentials key id.
         --secret [secret]     AWS credentials secret.
         --interval [ms]       Poll interval (in milliseconds).
         --tag [key=value]     EC2 instance tag; e.g., 'beep=boop bop'.
         --region [region]     AWS region. Default: 'us-east-1'.

• In addition to the command-line key and secret options, the key and secret options may be specified via environment variables: AWS_ACCESS_KEY and AWS_ACCESS_SECRET. The command-line options always take precedence.

• If the process receives a terminating signal event (e.g., CTRL+C) while polling AWS, the process will stop polling and wait for any pending requests to complete before exiting.

• Multiple tags are supported. Key-value pairs should be separated by an = symbol. Keys are assumed to be free of any = symbols.

  $ aws-ec2-running --key <key> --secret <secret> --tag 'beep=boop' --tag 'woot=be bop'

Setting credentials using the command-line option:

$ aws-ec2-running --key <key> --secret <secret>
# => '[<id>,<id>,...]'

Setting credentials using environment variables:

$ AWS_ACCESS_KEY=<key> AWS_ACCESS_SECRET=<secret> aws-ec2-running
# => '[<id>,<id>,...]'

For local installations, modify the command to point to the local installation directory; e.g.,

$ ./node_modules/.bin/aws-ec2-running --key <key> --secret <secret>

Or, if you have cloned this repository and run npm install, modify the command to point to the executable; e.g.,

$ node ./bin/cli --key <key> --secret <secret>

Unit tests use the Mocha test framework with Chai assertions. To run the tests, execute the following command in the top-level application directory:

$ make test

All new feature development should have corresponding unit tests to validate correct functionality.

This repository uses Istanbul as its code coverage tool. To generate a test coverage report, execute the following command in the top-level application directory:

$ make test-cov

Istanbul creates a ./reports/coverage directory. To access an HTML version of the report,

$ make view-cov

MIT license.

Copyright © 2015. Athan Reines.