lambdash: AWS Lambda Shell Hack: New And Improved!

easier, simpler, faster, better

Seven months ago I published the lambdash AWS Lambda Shell Hack that lets you run shell commands to explore the environment in which AWS Lambda functions are executed.

I also posted samples of command output that show fascinating properties of the AWS Lambda runtime environment.

In the last seven months, Amazon has released new features and enhancements that have made a completely new version of lambdash possible, with many benefits including:

  • Ability to use AWS CloudFormation to create all needed resources including the AWS Lamba function and the IAM role.

  • Ability to create AWS Lambda functions by referencing a ZIP file in an S3 bucket.

  • Simpler IAM role structure.

  • Increased AWS Lamba function memory limit, with corresponding faster execution.

  • Ability to invoke an AWS Lambda function synchronously.

This last point means that we no longer need to put the shell command output into an S3 bucket and poll the bucket from the local host. Instead, we can simply return the shell command output directly to the client that invoked the AWS Lambda function.

The above have made the lambdash code much simpler, much easier to intstall, and much, much faster to execute and get results.

You can browse the source here:

https://github.com/alestic/lambdash

There are three easy steps to get lambdash working:

1. CloudFormation Stack

Option 1: Here are sample steps to create the lambdash AWS Lambda function and to use a local command to invoke the function and output the results of commands run inside of Lambda

git clone git@github.com:alestic/lambdash.git
cd lambdash
./lambdash-install

The lambdash-install script runs the aws-cli command aws cloudformation create-stack passing in the template file to create the AWS Lambda function in a CloudFormation stack.

The above assumes that you have installed aws-cli and have appropriate credentials configured.

Option 2: You may use the AWS Console to create a lambdash CloudFormation stack by pressing this button:

Launch Stack

Accept all the defaults, confirm the IAM role creation (after reading the CloudFormation template and verifying that I am not doing anything malicious), and perhaps add a Tag to help identify the lambdash CloudFormation stack.

2. Environment Variable

Since the CloudFormation stack creates the AWS Lambda function with a unique name, you need to find out what this name is before you can invoke it with the lambdash command.

If you ran the lambdash-install command, it printed the export statement you should use.

If you used the AWS Console, click on the lambdash CloudFormation stack’s [Output] tab and copy the export command listed there.

It will look something like this, with your own unique 12-character suffix:

export LAMBDASH_FUNCTION=lambdash-function-ABC123EXAMPL

Run this in your current shell and, perhaps, add it to your $HOME/.bashrc or equivalent.

3. Local lambdash Program

The previous step installs the AWS Lambda function in the AWS environment. You also need a complementary local command that will invoke the function with your requested command line then receive and print the stdout and stderr content.

This is the lambdash program, which is now a small Python script that uses boto3.

You can either use the lambdash program in the GitHub repo you cloned above, or download it directly:

sudo curl -so/usr/local/bin/lambdash \
  https://raw.githubusercontent.com/alestic/lambdash/master/lambdash
sudo chmod +x /usr/local/bin/lambdash

This Python program requires boto3, so install it using your favorite method. This worked for me:

sudo -H pip install boto3

Now you’re ready to run shell commands on AWS Lambda.

Usage

You can now execute shell commands in the AWS Lambda environment and see the output. This command shows us that Amazon has upgraded the AWS Lambda environment from Amazon Linux 2014.03 when it was launched, to 2015.03 today:

$ lambdash cat /etc/issue
Amazon Linux AMI release 2015.03
Kernel \r on an \m

Nodejs has been upgraded from v0.10.32 to v0.10.36

$ lambdash node -v
v0.10.36

Here’s a command I use to occasionally check in on changes in the Amazon’s awslambda nodejs framework that runs our Lambda functions:

mkdir awslambda-source
lambdash tar cvzf - -C /var/runtime/node_modules/awslambda . | 
  tar xzf - -C awslambda-source

For example, the most recent change was to “log only 256K of errorMessage into customer’s cloudwatch”. Good to know.

Cleanup

Deleting the lambdash CloudFormation stack removes all resources including the AWS Lambda function and the IAM role. You can do this by running this command in the GitHub repo:

./lambdash-uninstall

Or, you can delete the lambdash CloudFormation stack in the AWS Console.