Serverless framework - AWS config & hello-word setup

In the previous article in this series, I described what Serverless Framework is and what problems it solves. In this part we will deal with its installation, then we will configure it to work with the AWS cloud, and finally, I will present you a few tools that will make it easier for you to work with both Serverless Framework and the cloud itself. These three steps will allow us to move smoothly to the last article in this series, where I will show you how simple it can be to create a CRUD application based on a serverless AWS stack using the Serverless Framework.

Serverless Framework installation

Serverless Framework provides us with a CLI interface with which we manage our function-based application. This CLI is based on Node.js, which we must have installed on our computer. The minimum required version is Node v6, but I recommend you to install or update to the recommended stable version.

Instructions for installing Node.js can be found on its official website. After installing, verify that everything works correctly by checking if you have access to the following commands from the terminal

node -v
npm -v

npm is the default package manager for the Node.js environment. It is installed with Node.js and also provides the CLI, needed for installing packages from the global repository, among other things.

When this step is behind us, it’s time to install the Serverless Framework itself. We will use npm and the command below for this

npm install -g serverless

And just like with Node, after installation, we can verify that cli of Serverless Framework works from our bash.

serverless — version
sls — version
# sls is just a shortcut to the serverless command

AWS account configuration for Serverless Framework

Serverless Framework cli needs permission to your AWS account to create and manage resources on your behalf. There are several ways to grant this access. We will do it according to the convention by creating a dedicated User in IAM, generate a pair of keys, and attach them to aws cli.

If you don’t have aws-cli installed yet, here are the official installation instructions.

After that, we can log in to our AWS console and go to the IAM panel to create a dedicated user

Our user is intended to be used only as part of a given project, so its name should clearly indicate its use. We select Programmatic access because we want to generate a pair of keys

For our IAM User we need to create a new policy with limited permissions, only those that will be used by the cli of Serverless Framework. For this purpose, we go to a window where we can create such a policy.

In the JSON tab, paste the contents of this file. This file contains policy definitions in json format, which defines what permissions our User will have after assigning this policy to him. This policy has a wider range of privileges than what we will be doing in the next article, but it allows all available actions from Serverless Framework cli. However, if you are not comfortable with it, you can cut some permissions and add them only when they are actually used by you.

Click Review policy, give a meaningful name and description for the policy, and click Create policy.

Now we go back to our window where we created User. Refresh a list of policies, enter the name of the newly created policy in a search, and select it to assign it to the user. Then we move on until we see the following message.

At this point, we can view our access and secret key, which will be used to authenticate our AWS cli and Serviceless Framework cli as well.

In order to configure credentials to was cli, we execute the command below to go through the console wizard.

aws configure
AWS Access Key ID [None]: aws-key
AWS Secret Access Key [None]: aws-secret
Default region name [None]: eu-west-1 Default output format [None]: json

After this action, our keys should be saved in the .aws/credentials file, which is located in the user home directory.

If you already had a user assigned to your aws cli, you can overwrite this data or add another profile by editing the .aws/credentials file.

[default]
aws_access_key_id = access_key
aws_secret_access_key = secret_key
[second_profile]
aws_access_key_id = access_key2
aws_secret_access_key = secret_key2

The default profile, as the name suggests, is the default one and aws cli uses it if you don’t manually add a flag with the name of another profile.

To verify that aws cli is working properly you should now be able to execute the command below

aws s3 ls

The command should list all your buckets from the region you have set as default. If everything works, we can consider the setup complete.

Hello world with Serverless Framework

Now it’s time for a quick setup of a hello-world project. It will be really fast. No clicking on the console, no manual resource creation. We execute the sls command in the console, go through a short wizard, choose the name of the project, and the development environment. You can omit the step of creating an account in the Serverless platform, this will not be needed for our exercises.

The new project created, go to the created directory and run the below command in it. Our project generated from the template will be installed in AWS and ready for action.

sls deploy

What really happened behind the scene? Serverless Framework cli built our code package (handler.js file) and based on the deployment definition (serverless.yml) created the appropriate CloudFormation template, which already knew what resources to create for us in AWS. Such a simple hello-world function doesn’t really create many resources. You can check what resources have been created by viewing the definition of the CloudFormation template in the AWS console.

As you can see, we only have our Lambda function, the IAM role assigned to this function, and S3 bucket to which our zipped code was sent. Small note, the default serverless project probably will be created in the us-east-1 (N. Virginia) region, different from what we assigned to aws cli, so look for these resources in this region.

We can now try to call our function and view its logs

sls logs -f hello -t

As I mentioned earlier, at the moment our deployment is only a Lambda function. It is not issued by API Gateway, so we cannot call it via the endpoint. In the next part of this article, I will present you a more complex project that exposes the CRUD API via API Gateway and uses DynamoDB as a persistence layer. As for the installations, we managed to get to the end. Remember to clean up on the cloud after you’ve finished your SF experiments. Although you will not be charged for most serverless resources (if you do not use them), for security reasons I still recommend you to clean unused infrastructure. You can do this with the command below.

sls remove

Useful plugins for Visual Studio Code when working with Serverless Framework.

Finally, a small bonus. Due to the fact that I am switching from the IDE from JetBrains to VS-Code (a bit out of curiosity), I decided that I will share with you some useful extensions that may be useful for you to work with serverless projects and more. Here is a shortlist:

AWS Toolkit — thanks to it you will be able to manage the resources of your AWS account from the IDE level. An IAM Usera assignment is also required.

Serverless Framework — a simple code hint that will help you to write yaml definition in SF

Terminal — due to the fact that working with SF is mostly terminal work, I highly recommend you to install the terminal directly to the IDE.

Local History — it often happens at the stage of experimenting with new technology, we change lines of code blindly. We’ll change something in a few files and suddenly the app stops working. For some strange reason, Ctrl + Z didn’t work. This plugin comes to the rescue. It tracks local changes to each file and creates a history that can be easily previewed and restored.