awsam

by mheffner

mheffner / awsam

Amazon Web Services Account Manager (modeled after 'rvm')

123 Stars 8 Forks Last release: Not found MIT License 138 Commits 10 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

AWSAM (Amazon Web Services Account Manager) allows you to easily manage multiple sets of AWS credentials. It has support for multiple accounts and multiple key-pairs per account.

Account switching auto-populates ENV vars used by AWS' command line tools and AWSAM additionally gives you intelligent wrappers for

ssh
and
scp
which can be used like:
# ssh by AWS instance id
$ assh [email protected]

ssh by AWS tag name

$ assh [email protected]

ssh by AWS tag name to an arbitrary node using a substring

#

This example assumes you have the following nodes and that

you're indifferent to which node you connect to:

web-node-01, web-node-02, web-node-3

$ assh -f [email protected]

scp by instance id

$ ascp local-file [email protected]:remote-file

AWSAM supports both AWS' legacy Java-based CLI tools and their newer python-based CLI.

Installation

  1. Install the gem.

    $ gem install awsam
    
  2. Install BASH rc file

    $ raem --init
    Initialized AWS Account Manager
    
    

    Add the following to your .bashrc:

    if [ -s $HOME/.awsam/bash.rc ]; then source $HOME/.awsam/bash.rc fi

  3. Open a new bash environment.

Environment variables

AWS Account Manager will set a variety of environment variables when you execute the

aenv
shell wrapper:
$ env | grep AMAZON_ACCESS
Exit 1
$ aenv env | grep AMAZON_ACCESS
AMAZON_ACCESS_KEY_ID=AK....

Some of these environment variables match the ones used by the Amazon EC2 CLI tools and some our unique to AWSAM. It is often convenient to use these environment variables in DevOPs scripts in place of hard-coded values -- allowing your scripts to be seamlessly used for staging and production environments simply by switching the active account with

aem
and wrapping execution of the command with
aenv
.

The environment variables set when selecting an account are:

  • AMAZON_ACCESS_KEY_ID
    and
    AWS_ACCESS_KEY_ID
    and
    AWS_ACCESS_KEY
    - API access key
  • AMAZON_SECRET_ACCESS_KEY
    and
    AWS_SECRET_ACCESS_KEY
    and
    AWS_SECRET_KEY
    - Secret API access key
  • AMAZON_AWS_ID
    - The integer ID of this AWS account

When selecting an SSH key, the following environment variables are set:

  • AMAZON_SSH_KEY_NAME
    - Name of the keypair.
  • AMAZON_SSH_KEY_FILE
    - Full path to the public key PEM file

NOTE: As of version 0.2.0, these are no longer set in the shell environment by default. You must run any command that requires AWS access with the

aenv
wrapper.

Updating

  1. Update repo (fetch && merge) or

    gem update awsam
  2. Run

    raem --init
    . Ignore instructions to setup .bashrc if you've already done so.
  3. Close and reopen your shell or

    source ~/.bashrc
    .

General Usage

Add an account

If the environment already contains AWS variables, these will be presented as defaults.

$ aem add
Creating a new AWS account...
Short name: staging
Description: Staging account
AWS Region [us-east-1]: us-east-1
Access key [12346]: 123 *from AWS credentials*
Secret key [secret123456]: 455 *from AWS credentials*
AWS ID: aws_account

Note: if your shell can't find the

aem
command it is most likely because you haven't successfully sourced
.awsam/bash.rc
in the install steps.

Select the active account

This will update the current environment with the appropriate AWS environment variables.

$ aem use staging

When selecting an account you can mark it as the default account with the

--default
option:
$ aem use --default staging

List accounts

The active account will be marked with an arrow. The default, if set, will be marked with an asterisk.

$ aem list

AWS Accounts:

prod [Librato Production] [1 key: my-prod-key] => staging [Staging account] *dev [Librato Development] [1 key: devel-key]

Import a key pair

Add a key to the default account, or the specified account. Defaults chosen from current environment if set. IMPORTANT:

my-key-name
must match the logical name of the AWS EC2 keypair.
$ aem key add my-key-name /path/to/my-keypair.pem
Imported key pair my-key-name for account staging [Staging account]

The keypair must match the name of the keypair in AWS

Select a key

This will select an SSH keypair to use from your current account and set the environment variables

AMAZON_SSH_KEY_NAME
and
AMAZON_SSH_KEY_FILE
appropriately. It will also highlight the key in the list output with the '>' character.
$ aem key use my-key-name

$ aem list

AWS Accounts:

staging [Staging account] => dev [Librato Development] [1 key: >my-key-name]

You can also define a default key for each account that will automatically be selected when the account is chosen. Just use the

--default
option when selecting a key to set a default key. Picking a default will place an asterisk next to the key name in the
aem
list
output.
$ aem key use --default my-key-name

aenv utility: wrap command execution with AWS environment

The

aenv
utility will wrap execution of any command with the AWS environment variables matching the currently selected account. This allows you to securely propagate environment variables only to commands that should have access to the current environment. Just prefix your command execution with
aenv
like:
$ aenv aws s3 ls

assh utility: SSH by instance ID

Instance IDs will be looked up using the current account details. If the instance's keypair name exists, that keyfile will be used as the identity file to ssh.

Usage:

$ assh [[email protected]]

Example:

$ assh [email protected]
warning: peer certificate won't be verified in this SSL session
Loging in as ubuntu to ec2-1.2.3.4.compute-1.amazonaws.com

...

[email protected]:~$

assh utility: SSH by tag name

Instances will be looked up by their tag name. This tag name can be found assigned to the "value" key when you run ec2-describe-tags, using the AWS CLI Tools.

Usage:

$ assh [[email protected]]

Example:

$ assh [email protected]
warning: peer certificate won't be verified in this SSL session
Loging in as ubuntu to ec2-1.2.3.4.compute-1.amazonaws.com

...

[email protected]:~$

If you use assh with a substringed tag name which matches against several nodes, you will have the option to choose a specific node. For example, let's say you have 3 nginx nodes all running the same code and your nodes are named:

web-node-01, web-node-02, web-node-03

Then you run the following from within your terminal:

Usage:

$ assh [email protected]
Please select which node you wish to use:
0) web-node-01 (i-43dfed45)
1) web-node-02 (i-789eft24)
2) web-node-03 (i-546fer56)
> 1

You'll notice that you're given a list of the nodes in your account that match the "web-node-*" pattern. The instance ID associated with each node is appended to each option as well. You will then be given a prompt (>) where you enter the index of the node you want to connect to.

Finally, if you use assh with a substringed tag name using the -f option, you can pass the base substring of a cluster of common nodes to connect to an arbitrary node within that cluster. The -f option assumes you have 'n' number of machines using a shared base name, all running mirrored environments. Once again, we will use the web-node-[01,02,03] scenario from our previous example:

Usage:

$ assh -f [[email protected]]web-node-

In this example, you would automatically connect to one of the machines in your account which matches the "web-node-*" pattern without having to explicitly choose a node.

assh utility: questions/help?

Run the following from your terminal:

$ assh --help

or:

$ assh -h

ascp utility: SCP by instance ID

Instance IDs will be looked up using the current account details. If the instance's keypair name exists, that keyfile will be used as the identity file to scp.

Usage:

$ ascp [[email protected]]:remote-file local-file
$ ascp local-file [[email protected]]:remote-file

Default user

You can specify a default user to assh by setting

AWS_DEFAULT_USER
:
$ AWS_DEFAULT_USER=ubuntu assh datanode
Please select which node you wish to use:

  1. metrics_facing-stg-v2-datanode-11 (i-30XXXXX, m1.large, 2014-02-12T20:46:29.000Z)
  2. metrics_facing-stg-v2-datanode-12 (i-91XXXXX, m1.large, 2014-02-13T04:20:32.000Z)
  3. metrics_facing-stg-v2-datanode-13 (i-64XXXXX, m1.large, 2014-03-04T18:59:26.000Z) q) Quit

> 2

Logging in as ubuntu to ec2-XXXX.compute-1.amazonaws.com

Remove a key

You can remove ah SSH key from an account (defaults to the current account).

$ aem key remove --acct prod my-prod-key

Remove an account

You can remove an account as long as it is not the active one.

$ aem remove staging

Contributing to awsam

  • Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
  • Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
  • Fork the project
  • Start a feature/bugfix branch
  • Commit and push until you are happy with your contribution
  • Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
  • Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

TODO List

assh utility:

  • ssh to a tag name (multiple?)
  • caches instance id => hostname for fast lookup
  • determines user?
  • supports complete SSH CLI options
  • inline commands, eg:
    ssh [email protected] sudo tail /var/log/messages

Copyright

Copyright (c) 2011 Mike Heffner. See LICENSE.txt for further details.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.