DEV Community: Adam Johnson

Optimizing AWS Java Lambdas

Adam Johnson — Wed, 31 Oct 2018 17:01:19 +0000

This was originally authored by Stephanie Gawroriski (Xer) on the IOpipe blog.

If your Java lambdas are running slow, it can be a nightmare to find the culprit! This article will cover a bunch of tried and true tips that you can utilize to optimize your code so that it runs faster, or uses less memory.

There are many optimization techniques that you can use and some will work better than others depending on the situation. In this article we will concentrate on optimizations that can improve your Java AWS Lambda functions.

Finding which parts of the function are slow

The most important thing when optimizing is to know where to optimize. This is something a profiler can help you with; it can tell you, in extremely granular detail, all of the potentially problematic regions of your code in terms of performance.

Note that profiler data might not always be precise and sometimes that imprecision might misrepresent situations, so they should really be used as a pointer in the direction of code that needs to be optimized. It is an available tool and one that can be very important when you look at the performance of your own code.

Of course, you are not required to use profiler, you could potentially measure how long execution takes by using System.nanoTime() at the start and end of a block of code. That would naturally just be a simple metric and it would have far less overhead than using a full-fledged profiler.

Doing this may help you concentrate on only a certain portion of code rather than seeing all of the data that represents all of your code. It might be very primitive but, like debugging messages made by System.err.printf(), it is quick and easy to add and the only thing you will be given is the information you specifically ask for. You could even use a combination of this with profiling to give you a better idea of what is happening with your code, and with printf() you may find this situation only happens under certain circumstances — profilers generally do not contain any information about the input for a method, so they lack some context.

The First Place to Look: The Algorithm

No matter which optimization you plan on performing, the first factor to check is whether the algorithms you are using in your code are optimal. Improvements in the algorithm used will in many cases outweigh the other optimizations that you perform on your code, saving time and money.

For example, if you were sorting numbers or other entries passed by a user, then you will need to choose a sorting algorithm. Algorithms such as selection sort will be slow, while merge sort will perform better. If you spend your time optimizing selection sort then in most cases even the mostly badly written merge sort will probably still run faster than your lean and fast selection sort.

Reducing the complexity of your classes

There was a lot of discussion of this solution in my previous article Java Libraries are Your Lambda Enemy. When a class is initialized by the virtual machine, it parses the class and needs to load all the information for the class, however this is in itself not a complex process. The complexity generally comes from the JIT compiler needing to compile all the code so it runs faster in the virtual machine. However a large number of simple classes can slow this process down because the virtual machine needs to handle far more classes; especially when there are many class dependencies. So you should keep your class complexity down and the number of classes down.

This feels like an obvious solution — fewer classes means less for the virtual machine to do. But it’s easy to accidentally add what seem like small libraries that turn out to need many dependencies. One thing to be particularly aware of is ServiceLoader— any classes which are discovered by the service loader will be initialized when they are iterated through. So this means that services that you might not ever use might just get initialized. If you need to use the service loader to discover services then those service class implementations should be simple factory classes.

Initializing variables and classes when needed and using the cache

This is something that varies, but usually the practice on normal servers is to initialize all you can when the program starts. Since the processes are more long lived these steps are done at the start so they never really become a problem in the long run. However in the Lambdas, with the massive contention during cold starts, the time spent initializing every single variable will be costly and cut into your initial cold start which may potentially time out or not be fast enough to where it overwhelms the lambda.

So to put less pressure on the cold start you should instead opt to initialize data only when it is needed. That way any complex data is only initialized as it is needed.

If your class generates any other objects which are used on an as-needed basis, if they are not required at all times then you can use a cache to keep it in memory for awhile. If you can recycle the cached objects you will save on initialization time for that class.

The proper way to implement this cache is to use SoftReference<T>, this reference will keep pointing to the object until there are no strong references to it (fields and variables) and when memory has been exhausted (during garbage collection). If you need to know when the reference is cleared then you can use ReferenceQueue<T>; note that this uses polling which can either return immediately or wait until an object is made available and as such if a queue is used it will likely best be placed in its own thread.

Avoid blocking

One of the worst things you can do in your code when it has to have a low latency is blocking. This blocking happens when you wait for data in another thread ( synchronized, Object.wait(), and Lock.lock()) or when you are waiting for a result from a remote request (such as HTTP). Any time your program is just sitting around waiting for something to happen, is time spent wasted. Since only a single execution of a Lambda happens at once there will really be no benefit if the CPU is not being used at all because your cost is the same regardless of how much or how little CPU you use (if you Thread.sleep() with a long duration that will cost you despite nothing happening).

If it is possible in your code, one way to reduce the time spent blocking is to create a thread which works in the background, then when you actually need the result you could block until it is available. You can have a worker object which stores the result of the calculation and have within there an atomic type (such as AtomicInteger or AtomicObject<T>), read that value to see if one is available then if not lock on a monitor and then wait for a result to be calculated, reading in a loop and ignoring InterupptedException.

Alternatively a more performative implementation would use ReadWriteLock and Condition to perform the same function (since lower level locks, despite requiring more implementation work, can perform better than volatile and synchronized).

Of course, if the thread has to run and finish but no result is needed, then it can just wait on a lock then once it is obtained it can just unlock and exit. Naturally if you want to avoid using locks and instead just constantly read from an atomic variable until some value is set, your busy loop should Thread.yield() so that we can tell the operating system that we want to give up the rest of our CPU slice and give that to another thread. Yielding may or may not have an effect depending on the number of threads which can run at the same time in the container the lambda is running in, however if in the event there are not enough resources to run so many threads at once it will free up CPU slices so a thread which is actually doing something can do what it needs to do.

Hopefully you find this information useful and can use it to help optimize your Lambdas so that they perform better, to lower your costs and allow you to serve requests faster.

The Right Way™ to do Serverless in Python (Part 2)

Adam Johnson — Tue, 10 Jul 2018 19:58:03 +0000

Note: This article was authored by Michael Lavers

In Part 1 we covered the serverless basics and got our feet wet with the Serverless Framework. If you haven't read that part yet, it's highly encouraged that you start there. Assuming you've followed along in Part 1, you now know how to create and deploy a simple AWS Lambda function in Python; including a web API using AWS API Gateway. But we've only just scratched the surface of what you can do in serverless with Python. In this post, we'll introduce a library that allows you to plug any web framework that speaks WSGI into serverless (pretty much all of them); and we'll take a look at AWS' own Python web framework for creating web APIs.

Zappa

Zappa, named after the legendary Frank Zappa, is the original Python serverelss library/framework. It was originally conceived as django-zappa, a library to allow you to deploy Django web applications to AWS Lambda. It has since grown in leaps and bounds and now supports any WSGI compatible Python web framework. It has also expanded it's feature set and is very much a "batteries included" tool for creating, deploying and managing serverless web applications written in Python.

What is WSGI?

If you've done Python web development before, you've likely heard of WSGI. But what is it? WSGI stands for "Web Server Gateway Interface" and it's an implementation agnostic interface between web servers and web applications/frameworks. It was created by the Python community back in 2003 because there wasn't a standard way to develop a web application in Python back then. Instead you first had to pick a web server, which could use CGI, FastCGI, mod_python or something else entirely and develop against that. Which meant your web application was very much coupled to the web server in which it was built upon (remember Zope?). Now we have WSGI and all modern Python web frameworks support it, which means you can use whatever web server you like -- or no server at all? Yes, thanks to Zappa, WSGI is supported on serverless, too.

The reason I refer to Zappa as a "library/framework" is that it kind of lives in both worlds. Zappa at it's core is a compatibility/translation layer between serverless and WSGI. For example, with AWS Lambda, Zappa takes the HTTP event we covered in Part 1 and converts it into a WSGI compatible equivalent representation that all WSGI web frameworks can use. This is where Zappa feels like a "library", but then Zappa packs a ton of useful features on top and starts to feel more like a "framework". Although, like WSGI, Zappa is very much agnostic when it comes to the actual web framework you use.

Which web framework should I use?

If you're asking this question, then I would recommend you start with either Django or Flask. Django is the most popular web framework in Python and is very much a "batteries included" option. Flask is arguably the second most popular web framework in Python and calls itself a "micro framework"; it has a simpler API and doesn't come with all the bells and whistles that Django does. Both are excellent options and are very well documented. In this post, we'll focus on these two web frameworks when it comes to Zappa, but Zappa should work with pretty much any Python web framework. Suffice to say, if you're using Bottle, Pyramid, Tornado, Falcon or something else -- it should be easy to get your web application running on serverless using Zappa.

Django Meets Zappa

As we mentioned in Part 1, the rule of thumb for new Python serverless projects is to use Python 3.6, and true to form, Django has dropped Python 2.7 support in Django 2.0. This may seem like a sad day for all the Python 2.7 loyalists out there, but the pros greatly outweigh the cons here. Think about it: no more six. That alone should put a smile on your face -- at least until Python 4 is released.

Now before we dive into Zappa, we first need to create a Django web app. Django makes this really easy:

pip install -U django
django-admin startproject mydjangoapp
cd mydjangoapp

This will install the latest version of django using pip and the django-admin startproject command will create a directory called mydjangoapp with a preconfigured Django web app ready to go. Now if you've done Python web development before, you're likely asking "what about the virtualenv?" If you don't know what a "virtualenv" is, it's a best practice in Python to create a "virtual environment" for each project so that all your dependencies remain in one place and don't get mixed up with other projects. There are a number of tools out there to make managing virtual environments easy. for example, the one gaining a lot of traction recently is Kenneth Reitz' Pipenv. If you don't know who that is, he's the guy behind requests, you likely know his work. But I'm still partial to virtualenvwrapper I'm going to treat virtual environments as a personal preference. It's still a best practice, though, so pick whichever tool fits your workflow the best.

Now that we have a Django project created and we're in our mydjangoapp directory let's fire up Zappa:

pip install -U zappa
zappa init

Zappa is going to ask a series of questions about your web app. For now, you can stick with the defaults that Zappa suggests. As we mentioned in Part 1, like with the Serverless Framework, Zappa is going to check that your AWS credentials are properly configured. If you have multiple AWS profiles configured, Zappa wil ask which one to use, but if you only have one, then the default is what you want. After running zappa init and answering the questions, you'll find that Zappa has created a zappa_settings.json file in your project directory. This file serves the same purpose as the serverless.yml in Part 1, but because it is JSON there are no comments. Thankfully, Zappa documents the available settings.

Now to deploy:

zappa deploy dev

Zappa will perform steps similar to Serverless Framework covered in Part 1, but out-of-the-box it will do some handy Python-specific things like sort out dependencies for us. Once it is done deploying, you should see something like this:

Deployment complete!: https://xxxxxxxxxx.execute-api.us-east-1.amazonaws.com/dev

If you've read Part 1 this is going to look familiar. It's a URL provided by AWS API Gateway. Let's open it up in a browser and see what we get:

DisallowedHost at /

Invalid HTTP_HOST header: 'xxxxxxxxxx.execute-api.us-east-1.amazonaws.com'. You may need to add 'xxxxxxxxxx.execute-api.us-east-1.amazonaws.com' to ALLOWED_HOSTS.

Huh. Ok, let's do that. Open up mydjangoapp/settings.py and look for the ALLOWED_HOSTS setting and change it to the following:

ALLOWED_HOSTS = [".execute-api.us-east-1.amazonaws.com"]

Why aren't we including the xxxxxxxxxx part? Well, this part of the hostname is prone to change. For example, if you decide to deploy a staging or production environment with Zappa, then this part of the hostname is going to be different. Setting your ALLOWED_HOSTS this way allows you to support every environment you deploy with Zappa in AWS us-east-1. If you decide to deploy in another AWS region, then you'll need to update your ALLOWED_HOSTS accordingly. Let's save and re-deploy:

zappa update dev

Notice here the command is zappa update and not zappa deploy. This is because most of your serverless web app is already deployed. All we need to do now is replace our package in the S3 bucket Zappa created for us. You should notice that zappa update runs noticeably faster. Once done, let's reload our https://xxxxxxxxxx.execute-api.us-east-1.amazonaws.com/dev URL in a browser:

Page not found  (404)

Ok, we're making progress. The reason we're getting a "Page Not Found" error is that Django doesn't configure a page for / by default. Let's fix that. First, we'll need to create a Django app in our project. A Django web application is comprised of "apps". Say your web application had a blog and a store, each of those would be an "app" in your Django project. To create an app:

python manage.py startapp myapp

This command will create a myapp directory in your project. Inside that directory are a handful of modules to support an app. But before we start working on our app we must first register it within our Django project. To do this, we need to open our mydjangoapp/settings.py again and look for the INSTALLED_APPS setting. There we want to add our app to the end of the list, so it should look something like this:

INSTALLED_APPS = [
    ...
    'myapp',
]

Note that INSTALLED_APPS will have several Django apps already installed. We want to keep those and just add a new app to the list. So the .... represents all the Django apps that are already configured. Save this file and open up mydjangoapp/urls.py. This file is where Django configures all the routes of our web application. In fact, if you notice, there's already a route configured:

urlpatterns = [
    path('admin/', admin.site.urls),
]

Interesting. What if we open https://xxxxxxxxxx.execute-api.us-east-1.amazonaws.com/dev/admin/ in a browser? How about that. The Django admin app is already there running. Unfortunately we haven't configured any users in our Django project, so we won't be able to get beyond this login page. Back to what we were originally doing. Let's add a route for / and serve up an HTML template. First we'll need to import Django's TemplateView. After the from django.urls import path line, add the following:

from django.views.generic import TemplateView

And then update our urlpatterns like so:

urlpatterns = [
    path('admin/', admin.site.urls),
    path('', TemplateView.as_view(template_name='index.html')),
]

Here we're configuring an empty route, which is equivalent to / which is to be served by TemplateView using a template_name of index.html. Now to create the template, we need to go back to our app. From our project directory, we create a templates directory in our app and add a template to it:

mkdir myapp/templates
echo "<h1>Hello Django</h1>" > myapp/templates/index.html

Note that the template's name is index.html like we specified in our urls.py. Django will automatically load any templates it finds in any of the INSTALLED_APPS, assuming a templates directory is present for that app. Now re-deploy:

zappa update dev

And reload https://xxxxxxxxxx.execute-api.us-east-1.amazonaws.com/dev in a web browser:

Hello Django

And just like that you have a serverless Django web app. Zappa truly couldn't make it any easier. Deploying the same app to a regular web server would actually be more work. Aren't you glad you ditched those things?

Now as cool as a stock Django app running on serverless is, if we refer back to Part 1, we're really looking to build a web API and workers, right? With Django, we're in luck, as it has one of the most powerful and well-documented REST frameworks out there called Django REST Framework. And if you follow the installation instructions you'll have a fully-featured REST API running on serverless in no time. Or if you're building a GraphQL API, then the excellent Graphene integrates with Django.

As for workers, Zappa offers a solution not unlike the one we described in Part 1. If you had a function called scheduled_job in myapp/tasks.py that you wanted to execute every ten minutes, you would open your zappa_settings.json and add the following:

{
    "dev": {
       ...
       "events": [{
           "function": "myapp.tasks.scheduled_job",
           "expression": "rate(10 minutes)"
       }],
       ...
    }
}```
{% endraw %}


And then to deploy it:
{% raw %}


```bash
zappa schedule dev

And you're good to go. And what about custom domains? Zappa has you covered there, too. Before we continue, assuming you don't need this app, Zappa makes it easy to clean up:

zappa unschedule dev
zappa undeploy dev

Want to learn more about Django? Check out the Django documentation. Or even better, check out these Django tutorials.

Flask Meets Zappa

Now if the Django setup wasn't straightforward enough, Flask might be even easier. Assuming we're starting from a new virtualenv (see Django section for suggested tools for creating a virtualenv). We first install Flask and Zappa:

pip install -U flask zappa

Then create a project directory:

mkdir myflaskapp
cd myflaskapp

And within that directory add a app.py with the following:

from flask import Flask

app = Flask(__name__)

@app.route('/')
def hello():
    return {'message': 'hi there'}

if __name__ == '__main__':
    app.run()

Then fire up Zappa:

zappa init

Like with our Django app, Zappa will auto-detect that our app is using Flask. And to deploy:

zappa deploy dev

And we should get:

Deployment complete!: https://xxxxxxxxxx.execute-api.us-east-1.amazonaws.com/dev

And to test it:

curl https://xxxxxxxxxx.execute-api.us-east-1.amazonaws.com/dev

Which should return:

{"message": "hi there"}

Talk about an instant web API. So what's happening here? Zappa probably feels like magic, but it's really just clever. In Django, the WSGI is exposed in mydjangoapp/wsgi.py. So Zappa creates a AWS Lambda handler for us that accepts HTTP requests. This handler transforms these requests into equivalent WSGI requests and passes them onto mydjangoapp/wsgi.py. With Flask, it's pretty much the same idea. The only difference is that Flask exposes it's WSGI via the app.run() method in our app.py above.

The Zappa topics we've covered already with Django are applicable to Flask as well. From scheduled jobs to custom domains, they're all supported.

Want to learn more about Flask? Check out the Flask documentation. Or even better, check out this Flask mega tutorial.

Oh, and don't forget to clean up:

zappa undeploy dev

More Zappa?

In this post, we've only scratched the surface of what you can do with Zappa. Check out the Zappa documentation for more, including how to rollback deployments, tail logs, keep your functions warm, fire asynchronous jobs, etc.

Chalice

If Zappa didn't inspire you to start building a serverless Python web app, I don't know what will, but it also appears to have inspired (at least in part) a team at AWS to start their own web framework specifically built for AWS Lambda. They call it Chalice.

This project is interesting for a couple reasons. First is that it is one of the few Python web frameworks out there that doesn't implement WSGI. While I've been waxing poetic on the virtues of WSGI, Chalice is built specifically for AWS LAmbda, and as such doesn't need an abstraction layer like WSGI. The trade off here is simplicity for lock in: the Chalice implementation is simplified by only having to target AWS LAmbda, but that also means you can only use Chalice with AWS Lambda. Second, Chalice's API is clearly influenced by another web framework we've already covered in this post, which helps with the learning curve. Which one you ask? Let's take a look.

Assuming we're starting with a fresh virtualenv, install Chalice with:

pip install -U chalice

And to create a project:

chalice new-project mychaliceapp

This command creates a directory called mychaliceapp with a pre-configured Chalice project. Inside there's a .chalice hidden directory that contains config files, a requirements.txt and an app.py. There's our first clue, if you recall, in our Flask app we created a app.py as well, which is a common Flask idiom. But if we take a look at the app.py it will become clear:

from chalice import Chalice

app = Chalice(app_name='mychaliceapp')

@app.route('/')
def index():
    return {'hello': 'world'}

Look familiar? They say imitation is the sincerest form of flattery. And if I'm Armin Ronacher (creator of Flask), I'm feeling pretty flattered. And to deploy:

chalice deploy

When the deploy finishes, Chalice will return a URL that should be familiar by now: https://xxxxxxxxxx.execute-api.us-east-1.amazonaws.com/api

You guessed it, there's our old friend, API Gateway. And to test it:

curl https://xxxxxxxxxx.execute-api.us-east-1.amazonaws.com/api

Which should return:

{"hello": "world"}

We didn't even have to write any code for that one. Does that make it codeless as well?

Chalice offers a Flask-esque API and is very much designed for JSON REST APIs. It also comes bundled with some nice integrations with other AWS services, including authentication with AWS Cognito. It is clear that the project is focused on the problem they're trying to solve, as such, as long as your problem is JSON REST APIs then Chalice can help you get up and running on AWS Lambda quickly. Anything else? You're going to want to look at the other options we've covered so far.

In Summation

In this post, we've taken a look a two Python tools looking to make developing, deploying and managing serverless apps easier. One that is agnostic as to what web framework you use, the other is very much opinionated. One thing is clear, the Python community is getting a lot right when it comes to serverless.

In Part 3 we're going to compare and contrast all the options available in the serverless space for Python web apps. We'll also introduce you to a serverless observability tool that will give you visibility into your serverless web apps like never before. Stay tuned.

The Right Way™ to do Serverless in Python (Part 1)

Adam Johnson — Thu, 28 Jun 2018 20:55:07 +0000

Note: This article was authored by Michael Lavers

As you've undoubtedly heard, serverless has grown in leaps and bounds since the release of AWS Lambda in November 2013. And while the idea of not having to manage a server, paying only for the compute you actually use and horizontal scaling out-of-the box may sound really appealing, where do you start? As a Python developer, maybe you've heard of the Serverless Framework or Zappa; and either the prospect of working with an unfamiliar ecosystem like Node.js (in Serverless' case) is daunting, or maybe you're unclear on what these tools actually do and if they're overkill when you're just getting started. If that's the case, you've come to the right place. In this blog post we'll take a brief tour of serverless as it applies to Python as well as some handy tips and tricks to help you get your feet wet.

Is my app/workload right for serverless?

This is probably the most important question you need to ask about serverless. While serverless has a lot to offer, it isn't ideal for all apps/workloads. For example, the current maximum duration for an AWS Lambda function invocation is five minutes. What this means is that if your app/workload can't be broken up into five minute chunks, then serverless might not be the best option. If your app uses websockets, for example, which maintains a persistent connection with the server, on AWS Lambda this connection would be closed and need to be reestablished every five minutes. It would also mean you're paying for all that compute time for a workload that is really just keeping a socket open. But if your app is mostly stateless, like a REST or GraphQL API, then serverless may be a great fit, as HTTP requests rarely go beyond 30 seconds, let alone five minutes.

Where serverless really shines is workloads where you might have spikes and/or periods of low activity. If you think about it, that description likely applies to most apps/workloads you've worked on. When your app/workload spikes, then AWS Lambda is there to provide considerable horizontal scaling, by default handling 1,000 concurrent requests out-of-the-box (this limit can be increased). And when your app/workload is in a low activity period, your meter isn't running at full tilt, which can save you a lot on operating expenses. Think about it; most apps/workloads serve a range of timezones, so why should you pay full price to run your app/workload when your customers are asleep?

If you're still not sure whether or not your app/workload is a good fit, here's a handy calculator to compare AWS Lambda to EC2.

Python 2 or 3?

The Python ecosystem has gone through a lot of changes the past decade -- the most significant being the release of Python 3 and the transition of many codebases from Python 2.x to 3.x. In the serverless world, the advice here is consistent with any other Python project: use Python 3.6 if it's a new project. While Python 2.7 has served many of us well, it will cease to receive updates after 2020. So if you haven't already started your transition to 3.6, you have two years to do so.

If you have an existing Python 2.7 project, you're in luck, as AWS Lambda supports 2.7, but you should seriously consider starting to port your code to Python 3.6 soon. Here's a super helpful cheatsheet on how to write Python2+3 compatible code. And like the cheat sheet, the advice here will be 2.7/3.6 compatible.

Web API or Worker?

Before we go over the serverless tools available to Python, lets drill down a little more into our app/workload. If you have a web app that serves a front-end with several web assets (HTML, JavaScript, CSS, images, etc.), then you should not be serving these up via your AWS Lambda function. That's not to say that you can't, just that you shouldn't. Remember that with AWS Lambda you pay for the time your function is running. It doesn't make much sense to spend this time serving up web assets. In fact, since your front-end likely has many web assets, this could be a relatively expensive way of doing what is otherwise a simple task. For serving up web assets, you should look at a CDN (Content Delivery Network). AWS has a service specifically built for this purpose called CloudFront, here's a guide on how to use it with S3.

But that really only covers your web app's front-end. Or maybe your app/workload doesn't have a front-end at all. We're going to break these workloads into two categories: web APIs (REST, GraphQL, etc.), and workers. You're likely already familiar with the web API variety, and AWS Lambda allows us to serve them using a service called API Gateway (more on that later). The other, what I'm going to call "workers," is all the other tasks your app might need to do, such as: sending email, uploading files, push notifications, etc. Serverless can handle this workload, and even offers it's own cron job like service to handle scheduled tasks.

The reason I'm defining these two categories is that while in serverless these workloads may look similar (or indistinguishable, as they're both essentially functions), some tools are better at or designed for one over the other. In this guide, I'll point out where this is the case. Hopefully you're already thinking about what parts of your app will be served via a web API and what parts can be worker tasks run in the background so you can pick the right tool for the job.

Serverless Framework

The big kahuna in the serverless space is undoubtedly the Serverless Framework, and for good reason. The team behind it has poured considerable time and effort into developer experience to make it one of the most intuitive and accessible serverless tools out there. It also offers a feature set that is second to none, supporting multiple clouds in addition to AWS Lambda and a growing plugin ecosystem. For a Python developer, this would seem like the obvious starting point and it certainly is a great one.

But serverless framework is not without some Python-specific caveats. For starters, Serverless is written in Node.js, which may not be your cup of tea. But like any good tool, if done right, you shouldn't even notice what language it is implemented in, and the case could certainly be made here for Serverless. That being said, you'll still need to install Node and NPM, but after that you're only a npm install -g serverless away from having the Serverless CLI be your primary interface. You won't need to know any JavaScript, although your configs will be YAML by default.

Let's give it a try.

npm install -g serverless

The CLI can be accessed using either serverless or the shorthand sls. I prefer sls, so lets create a project:

mkdir ~/my-serverless-project
cd ~/my-serverless-project
sls create -n my-serverless-project -t aws-python3

Here I've created a directory called my-serverless-project and created a project using sls create. I'm also specifying a template with -t aws-python3. Serverless comes bundled with several templates that will set some sensible defaults for you in your serverless.yml that will be created when you run sls create. In this case, I'm specifying the AWS template for Python 3.6. There's also a aws-python2 if you're project is Python 2.7. There are other templates for other languages and clouds, but that's outside of the scope of this guide. The -n my-serverless-project specifies a service name, you can change this to whatever you want to name your project. Once you run these commands you should have a serverless.yml in your my-serverless-project directory. Let's take a look at the contents:

cat serverless.yml

As you will see the serverless.yml is YAML and comes loaded with several helpful comments explaining each section of the config. At this point I recommend reading through these comments as it will be helpful later on. Once done, let's write a hello world equivalent of a lambda function:

def handler(event, context):
    return {"message": "hi there"}

And save that in our my-serverless-project directory as hello.py. The name handler is just what lambda functions are commonly referred, you can name your functions whatever you like. Now that we have a function, let's make Serverless aware of it by adding it to our serverless.yml. First open up your serverless.yml and look for the functions section. Then replace that section with the following:

functions:
  hello:
    handler: hello.handler

Now save your serverless.yml. To deploy this function, we'll need to make sure we have our AWS credentials configured. Assuming we're all good there, then just run the following:

sls deploy

Deployment will take a little while. In short, here's the steps that Serverless is doing:

Creating a CloudFormation template based on the serverless.yml
Compressing the CloudFormation template and your hello.py into a zip archive
Creating a S3 bucket and uploading the zip archive to it
Executing the CloudFormation template, which includes configuring an AWS Lambda function and pointing it to the S3 zip archive

You could do all of these steps manually, but why would you want to? When our deploy is complete, we can test it with the following command:

sls invoke -f hello

Here -f hello is the name of the function we specified in our serverless.yml file. The sls invoke command invokes the function. A function invocation is a fancy word for calling the function. When we invoke this function, it should respond with:

{"message": "hi there"}

If that's what you see, congratulations, you've just created your first AWS Lambda function. But this isn't terribly useful.? What if we wanted to do something a little more challenging, like making a HTTP request and returning the result. Let's create a new file called httprequest.py and add the following:

import requests

def handler(event, context):
    r = requests.get("https://news.ycombinator.com/news")
    return {"content": r.content}

Update the functions section of your serverless.yml:

functions:
  hello:
    handler: hello.handler
  httprequest:
    handler: httprequest.handler

And re-deploy and invoke our new function:

sls deploy
sls invoke -f httprequest

You should now see an ImportError. This is because requests is not installed. With AWS Lambda, we need to bundle any libraries we want to use with our function. We can do this a number of ways, with pip we can run:

# Don't run this just yet, keep reading
pip install requests -t .

This will install the requests wheel (and it's dependencies) in our my-serverless-project directory. But there's a catch. AWS Lambda runs on 64-bit Linux. And because requests comes with dependencies that are compiled, if you're not running 64-bit Linux as well this copy of requests you just installed won't run on AWS Lambda. So what do you do if you're running Mac OS? Or Windows? Or FreeBSD? Or, well, you get the picture.

Serverless plugins (and Docker) to the rescue.

Thankfully Serverless comes with a plugin ecosystem to fill in the gaps, and for Python, packages with compiled code just happens to be one of those gaps. The relevant plugin here is aptly named serverless-python-requirements, and to install it:

npm install -g serverless-python-requirements

And add the following lines to the end of your serverless.yml:

plugins:
  - serverless-python-requirements

Now right away this plugin enables requirements.txt support. So instead of the pip line above, we now just need to add a requirements.txt file to our project directory and the next time we run sls deploy the requirements will be installed and bundled automatically. Let's do that now:

echo "requests" >> requirements.txt

But we haven't solved our compilation problem yet. To do that we'll need to add a custom section to our serverless.yml. This section is where we can put our custom configuration options, but it's also where plugins look to for their own config options. Our new custom section should look like this:

custom:
  pythonRequirements:
    dockerizePip: true

What this does is tell the serverless-python-requirements plugin to compile the Python packages in a Docker container before bundling them in the zip archive to ensure they're compiled for 64-bit Linux. You'll also need to install Docker in order for this to work, but once done this plugin will handle the dependencies you define in your requirements.txt file automatically. Pretty cool, huh?

Now let's re-deploy and re-invoke our function:

sls deploy
sls invoke -f httprequest

Even if you are running 64-bit Linux, this is way cleaner, don't you think?

Now before we continue, you likely have a few questions. What are event, context and how is any of this useful to me?

AWS Lambda functions are event-driven, so when you invoke a function, you're actually triggering an event within AWS Lambda. The first argument of your lambda function contains the event that triggered the function, which is represented within AWS Lambda as a JSON object, but what is passed to Python is a dict of that object. When you run sls invoke -f hello, what is passed to the lambda function is an empty dict. But if it was an API request, it would contain the entire HTTP request represented as a dict. In other words, the event dict acts as your lambda function's input parameters and what your lambda function returns is the output. With AWS Lambda, your output needs to be JSON serializable as well. Here's some example events you might see with AWS Lambda.

The second argument is the AWS Lambda context, which is a Python object with useful meta data about the lambda function and the current invocation. For example, every invocation has a aws_request_id which is useful if you want to track down what happened in a specific invocation within your logs. Check here for more information about the context object. You probably won't need to worry about the context object right away, but you'll eventually find it useful when debugging.

So how is this useful? Well, if your app/workload can work with a JSON serializable input and produce a JSON serializable output, then it can plug right into a AWS Lambda. If we go back to our two workload categories, web API and worker, we've already pretty much implemented what you'll need for a worker. Lets say we wanted to run our httprequest function every ten minutes, in order to do that all we would need to do is add the following to our serverless.yml:

functions:
  httprequest:
    handler: httprequest.handler
    events:
      - schedule: rate(10 minutes)

And re-deploy:

sls deploy

And we're done. Now httprequest is being triggered automatically every ten minutes. If you want more fine-grained control, you can specify a specific time your function should be triggered as well. You can also build more complex workflows using SNS, SQS or other AWS services.

What about the web API? Remember earlier we covered events and mentioned that an HTTP request can be represented as an event? In the case of web APIs, it is Amazon's API Gateway service that will be triggering the events for us. In addition to this, API Gateway will provide a hostname that can receive HTTP requests, transform those HTTP requests into an event object, invoke our lambda function, collect the response and pass it on to the requester as an HTTP response. That might sound complex, but thankfully the Serverless framework abstracts much of this for us. Let's add an HTTP endpoint to our serverless.yml:

functions:
  webapi:
    handler: webapi.handler
    events:
      - http:
          path: /
          method: get

This looks a lot like our scheduled worker task earlier, doesn't it? Like in the scheduled task, here we configure this handler to handle http events and specify a path and method. As you've likely guessed, the path is our HTTP request path and the method is the HTTP method this handler will handle. You'll also notice we've added a new handler, let's create that now in webapi.py:

import json

def handler(event, context):
    return {"statusCode": 200, "body": json.dumps({"message": "I'm an HTTP response"})}

Here our handler will accept an event from the API Gateway and will respond with a JSON serializable dict. Within the dict we have two keys, the first is statusCode which is the HTTP status code we want the API Gateway to respond with and the second is the HTTP body of the response. You'll also notice that we serialize the body into JSON as well. The reason we do this is that API Gateway expects the HTTP response body to be a string. So if we want our web API to respond with JSON, we need to serialize it before handing it back to API Gateway. This also means that if you wanted to support some other form of serialization, like XML, YAML or something else -- you could do that, too.

Now let's deploy it:

sls deploy

Once done the Serverless framework will provide us with an endpoint:

endpoints:
 GET - https://XXXXXXXXXX.execute-api.us-east-1.amazonaws.com/dev

Your endpoint will look a little different. What just happened here? Well, in short, Serverless created our new AWS Lambda function and then configured an AWS API Gateway to point to this lambda function. The endpoint you see above is the one provided by API Gateway.

Let's take our endpoint for a spin:

curl https://XXXXXXXXXX.execute-api.us-east-1.amazonaws.com/dev

And you should see the following response:

{"message": "I'm an HTTP response"}

Congratulations, you've just created your first serverless web API. Now you've probably noticed that the URL API Gateway provides is pretty ugly. It would be a lot nicer if it could be something more readable like https://api.mywebapi.com/. Well, there's a plugin for that, too.

Cleaning Up

In this post we've created three Lambda functions and an API Gateway. But these were really just examples to help you get your feet wet in serverless. You'll probably want to clean up and to do that just run:

sls remove

And the Serverless framework will take care of the rest.

In Summation

In this post we've gone over some of the AWS Lambda basics and created a simple web API and worker using the Serverless framework. In Part 2 we cover some more advanced topics, including an introduction to two serverless frameworks specifically built for Python: Zappa and Chalice. We also demonstrate how quickly you can build a web API using these tools, including examples using popular web frameworks such as Django and Flask.