AWSM-O
I am AWSM-O (aw-s uh m oh)! (Amazon Web Services... and then M-O, to make it similar to AWESOM-O)
I help automate working with EC2 instances from node.js. I'm a bit more friendly than amazon's AWS api.
example
var awsmo = awsCredentials: './credentials.csv' region: 'eu-west-1' instanceDefaults: remoteUser: 'ubuntu' sshKeyMappings: amazon_key: './amazon_key.pem' ; var instance = awsmo;
install
npm install --save awsm-o
documentation
AwsmO(options)
Creates a new instance of AwsmO. Options are:
awsCredentials
(required) - either a path to your aws credentials csv file, or an object with anaccessKeyId
and asecretAccessKey
.region
(required) - your AWS region string, for example'us-west-1'
.sshKeyMappings
(required if using ssh/scp/creating an instance) - an object where each key represents the name of an ssh key used by EC2, and the value is the location of that key on disk (relative toprocess.cwd()
). The key names need to align with EC2 in order to assign the correct key when creating an instance, for example{ myprivatekey: '/home/jon/.ssh/myprivatekey.pem' }
if the key name in AWS ismyprivatekey
.instanceDefaults
(optional) - an object of options used to initializeEc2Instance
objects. Seeawsmo.createEc2Instance(opts [, callback])
for details on these options. It can be convenient to put settings here if they would be the same for every instance. Examples of good candidates for this treatment areremoteUser
andavailabilityZone
.sequential
(default = false) - if set to true, only one command will be executed at a time. See sequential mode for more details.pollDelay
(default = 10000) - the default interval when polling an instance for changes. in milliseconds.log
(default = none) - the logger to use. should be a TaggedLogger. A simple way to integrate with whatever logger you currently might be using is to supply an adapter: ``` log: new TaggedLogger({ log: function (level, msg, meta) { // level is a string; "info", "warn" or "error" // msg is the log message // meta has timestamp, which is a Date object, and tags, which is a list // of tags describing the context from which this message is logged console.log(level, meta.tags, msg); } })
#### `awsmo.getEc2Instance(instanceId [, callback])`
Returns a new Ec2Instance object, with the given instanceId.
AWSM-O will query for details about this instance, and determine the correct
SSH key to use for accessing this instance based on the key name used for this
instance and the `sshKeyMappings` supplied in the `AwsmO` constructor.
<a name="createEc2Instance"/>
#### `awsmo.createEc2Instance(opts [, callback])`
Returns a new Ec2Instance object, using the given options to create it.
Options may be supplied here or as `instanceDefaults` in the `AwsmO` constructor.
Options supplied here take precedence over those supplied as `instanceDefaults`.
The options are:
* `name` (default = `'AWSM-O instance'`) - the name to give the instance.
* `imageId` __(required)__ - the AMI ID to create this instance with,
for example `'ami-12345678'`
* `awsKeyName` __(required)__ - name of the ssh key to use, for example
`'myprivatekey'`
* `remoteUser` __(required for ssh access)__ - name of the remote user to use
for ssh access, for example `'ubuntu'`
* `securityGroupIds` __(required)__ - security groups that this instance should
belong to (array), for example `['sg-12345678', 'sg-45678901']`
* `availabilityZone` __(required)__ - availability zone to create the
instance in, for example `"eu-west-1b"`
* `instanceType` (default = `'t1.micro'`) - type of instance to create
### Ec2Instance
Represents an EC2 instance. To get an Ec2Instance object you need to call either
`awsmo.getEc2Instance` or `awsmo.createEc2Instance`.
#### `ec2instance.getState(callback)`
Fetch the state of the instance.
* `callback(err, state)` - callback to call when the state is retrieved. `state`
is a string representing the current state, i.e. `'pending'`, `'running'`,
`'stopping'`, `'stopped'`, `'shutting-down'` or `'terminated'`.
Example:
```javascript
var inst = awsmo.getEc2Instance('i-12345787');
inst.getState(function(err, state) {
console.log(state); // -> 'running'
});
ec2instance.setName(name, callback)
Set the name of an instance.
name
- the name to set on the instance.callback(err)
- called once the name has been set.
ec2instance.publicDnsName
A promise of the publicDnsName for this instance. Should only be used if you know the instance should have, or is about to receive, a public dns name.
You can use it like a regular getPublicDnsName
function by calling
instance.publicDnsName.then(function(err, publicDnsName) { ...
.
start(callback)
, stop(callback)
, reboot(callback)
, terminate(callback)
Lifecycle functions. Each one will perform the requested function, and callback
once the desired state has been achieved. For example, calling instance.stop()
will not call back until the instance has a state of 'stopped'
.
ec2instance.ssh(command, callback)
Run a command on the remote instance.
command
an array with each part of the command to run. for example,['ifconfig', 'eth0']
callback(err, output)
callback to be called once the command has been run.output
is a string with the stdout of the process.
ec2instance.scp(from, [to ,] callback)
Copy a file to the instance.
from
path to the file to copy (relative to the cwd).to
(default ='.'
) where to copy the file on the instancecallback(err, output)
callback to be called when the scp operation is complete.
ec2instance.createAmi(name, description, callback)
Create an AMI from this instance.
The instance will be stopped before the AMI is created.
name
the name of the AMI. If the name is taken, AWSM-O will generate a unique name by appending a number to the given name.description
the description of the AMI.callback(err, amiId)
callback to be called when the ami has been created.
Normally, you can use awsm-o like any other node library, with nested callbacks to manage control flow, like this:
var instance = awsmo;
Not that you would ever write code like that, but you get the point. For cases such as this, we have sequential mode.
If sequential
option in the awsmo constructor is set to true
, then we
can just do this:
var instance = awsmo;instance;instance;instance;instance;
Only one operation is run at a time, and each operation will automatically wait for those before it to finish before running. The operation queue is contained inside awsmo, not each instance, so it will work over many instance objects assign well. If you want to have two simultaneous sequential modes, you'd have to create two awsmo instances.