Getting Started With AWS 2021 - AWS Serverless Tutorial

This page describes my exploration of the AWS "serverless" tutorial in 2021. Much of it is idiosyncratic to me. I strive for "good enough" accuracy. i.e. Some things I say may not be literally true, but present a "simplified truth" sufficient for the immediate tasks.

Reference Data

This is stuff you will want to refer back to, as you work through the tutorial.  I put it at the beginning to make it easy to find.  Skip over it to the next section, if you're here for the first time.

• AWS Console
• AWS Serverless Tutorial 
• AWS Amplify - assorted tools for developing web apps
• AWS CodeCommit - git
• AWS IAM - Identity and Access Management (user ID management)

Prologue

Before you start the tutorial, you must have an AWS account, and it must be tied to a credit card. 

Some AWS services are "free forever." Others are "free for new users for the first 12 months." Other services change from day one. We're going to try and use only free services, but Amazon insists on a credit card number.

I recommend creating a single-use card number (a.k.a. virtual account number or VAN). If you're unfamiliar with VANs, some credit cards enable you to generate a new account number with a defined expiration date and credit limit.  I generated a 3-month card with a $20 limit. That satisfied Amazon and it capped any unintended charges at $20. It also ensures that if I fail to delete everything when I'm finished, Amazon can't bill me when 12-month free trials end.

You don't have to do this, but it puts YOU in charge of what/when Amazon can bill.

We're going to do this all with a single 'root' user ID. That's unwise in a real environment, but simplest for a training exercise. I named my user 'kevin'. You can choose another name if you prefer.

Sign Up for an AWS Account

I'm not going to provide a lot of detail/images here. This is pretty straightforward. See "Prologue" in this document for billing suggestions. You will need a working phone number which has not been used before to sign up for AWS. Using a unique number appears to be necessary to get the free 12-month trial offers. You can use a cell or a land line.

1. Go to Amazon Web Services (AWS) - Cloud Computing Services
2. Press the orange "Create an AWS Account" button in the upper-right corner.
3. Enter the requested information and work your way through the sign-up wizard.
1. When you get to the account type prompt, choose "Personal".
2. When you get to the credit card page, see notes under "Prologue" on this page. Enter the card info carefully. I gave them the wrong expiration date and it took an hour to fix it and get my account working.
3. At some point, they'll call your phone number to validate it. Be sure your ringer is enabled!

Begin the Tutorial

I followed this tutorial: serverless web application tutorial but some pages have changed since it was originally published. I'll give you the steps I followed in May of 2021. The estimated durations in the tutorial are wildly optimistic.  You might get close to those times the second time you run through the tutorial.

You should look at the pictures and architecture explanation in the tutorial. They are clear and educational.

Build a Static Site

The first thing you're going to do is to deploy some plain old web pages. There won't be any "back end" -- just static content.  The tutorial is for a fictitious web site named "Wild Rydes". You'll be using:

• AWS Amplify - Amazon's toolkit for building web apps.
• AWS CodeCommit - Amazon's git repository service.
• AWS IAM - Identity and Access Management (developer user ID management)

Steps:

1. Open the Amplify Console.
2. Set the region to "N. Virginia" a.k.a. us-east-1. 
   
   
   
1. Wait until later to learn all about regions. There might be better ones. This one will work.
3. AWS prefers to deploy from git, so create a git repository with Amazon:
1. Go to AWS CodeCommit.  Choose "Create Repository"
   
   
   
2. Name the repository "wildrydes-site" and press "Create":
   

Install git and aws CLI (Command Line Interface):

1. If you don't have git on your local computer, install it. Details are beyond the scope of this tutorial. If you're working with Windows, I recommend you install WSL and then install git in WSL. git really works best with a bash shell, and WSL provides bash.
2. Install the "aws" command on your computer.  See these instructions.  Details are beyond the scope of this tutorial.  Run "aws configure" to configure the aws command.

Create a git user:

Before you can do anything with your git repository, you need a user ID with permission to use it.

1. Open IAM.
2. Click on "Users: 1" to get to the screen for choosing users.
   
3. Click on your user name:
   
   
   
4. Choose the "Security Credentials" tab
   
   
   
5. Scroll down to "HTTPS Git credentials for AWS CodeCommit" and press "Generate Credentials": 
   
   
   
6. It will generate a user ID and a password.  Save them in your password safe. (That generated password is way too long to write on a Post-It.) Then close the credentials window.
   
   
   
7. Open the git repository where the tutorial provides web pages for Wild Rydes.
8. Choose "Clone URL" and "Clone HTTPS"
   
   
   
9. It will copy an URL to your clipboard.
10. Note: If you are running on a Mac, and if you have run this tutorial before, and your are starting over fresh, open Keychain, find "git-codecommit..." and delete it.
11. Open a bash shell on your local computer and run: git clone https://git-codecommit.us-east-1.amazonaws.com/v1/repos/wildrydes-site
1. When it prompts for credentials, use the ones you saved to your password safe (above).
2. It will warn you that you cloned an empty repository. That is OK.
3. Run: cd wildrydes-site
12. Copy the site content from Amazon by running this command:
1. aws s3 cp s3://wildrydes-us-east-1/WebApplication/1_StaticWebHosting/website ./ --recursive
13. Commit the new files to git:
2. git add .
3. git commit -m 'new'
4. git push
14. Deploy your site to production from git:
1. Open the Amplify Console.
2. Scroll down to "Host Your Web App" and press the "Get Started" button under that heading.
   
   
   
3. Click on "AWS CodeCommit" and press continue:
   
   
   
4. Choose your "wildrydes-site" repository and press Next:
   
   
   
5. You will come to the "Configure build settings" page. Scroll down to the bottom and press "Next"
   
   
   
6. On the "Review" screen, press "Save and Deploy"
   
   
   
7. Wait about 2 minutes after it *says* it has finished.
8. Then click on the Amazon smile: 
   
   
   
9. Copy the URL from your browser URL field. That's the URL of your new site.
1. Save this URL. (I saved mine in my password safe.)
15. At this point you have several web pages comprising a static web site.  Click around to familiarize yourself with the static edition of Wild Rydes.
16. We're going to make a trivial change to the web site, just to demonstrate that AWS auto-deploys when you update git.
1. Use any editor on your local computer to edit the "index.html" file in the wildrydes-site directory.
2. Scroll down and find "How Does This Work?" and change it to "How Does This Work? (modified)"
3. Save you file
4. Run the "git litany" from your command line: git add . && git commit -m message && git push
5. Wait just a little longer than seems necessary (about 3 minutes) and refresh your web browser pointing to the site. You should see "HOW DOES THIS WORK? (MODIFIED)" if you scroll down. 
17. Stop and think for a moment.  Did you provision an Apache web server? (No.) Did you provision a Linux or Windows server to host your application? (No.)  Did you tell AWS how much memory or CPU you'll need? (No.)  This is what "serverless" means.  Amazon just provides the service of hosting web pages. The CPU, RAM, networking are all allocated as you need them, and reallocated when you have finished with them, *without* you having to specify them.  You're in the "business" of serving up a web site.  You don't really care about FLOPS or GB; you just want web pages delivered, and that's what serverless AWS is providing.

Create Some Application Users

In an earlier step, we created a user ID to be used for a developer. Now we're going to manage users for our application. (i.e. Customers of the Wild Rydes company.) You'll be using:

• Amazon Cognito - User Management

Steps:

1. Open Cognito.
2. Choose "Manage your User Pools"
3. Choose "Create a User Pool"
4. Name your user pool "WildRydes" and click "Review defaults" 
   
5. Scroll down and press "Create pool" 
   
   
   
6. Save the Pool ID to your password safe. 
   

   
   
   
   
   
7. We have created the application user pool. We need to tie it to our application:
8. Select App Clients from the left nav bar: 
   
   
   
9. Choose "Add an app client"
   
   
   
10. Enter the App client name: WildRydesWebApp
    
    
    
11. Scroll down, uncheck "Generate client secret" and press "Create app client" 
    
    
    
12. Save the generated "App client id" in your password safe.
13. Now you will update the JavaScript in your site to connect it to the user pool ID, app client ID and Region...
14. From your local machine, edit `wild-ryde-site/js/config.js` in a text editor
15. Update the Cognito section with the correct values for the User Pool ID and the App Client ID from your password safe. 
    
    
    
16. Save the file and run the git litany: git add . && git commit -m msg && git push
17. Wait a minute for the site to deploy. Then open your Wild Rydes site and press the "Giddy Up" button.
18. Enter a valid email address, make up a password, and click "Let's Ryde". Record the email+password in your password safe.
19. Check your email, and enter your email address and the verification code into the Let's Ryde form and press "Verify".  You should get a message "Verification successful".  Dismiss it.
20. In your browser address bar, enter your Wild Rydes URL followed by "/signin.html".
21. Enter the email address and password you registered at Wild Rydes withand press "Sign In".  You should see "Successfully Authenticated!"
22. At this point you have a user pool, your app can register new users in that pool, and your app can process user logins.

Build your "serverless" back-end

You'll be using:

• AWS Lambda - to define a "serverless" event response function
• Amazon DynamoDB - NoSQL database to store your app data
• IAM - Identity and Access Management
• Cognito - User management
• API Gateway - Wrap a REST API around your Lambda function

Steps:

1. Create a database table
1. From the AWS Management Console, choose Services then select DynamoDB under Databases.
2. Choose Create table. 
   
   
   
3. Enter Rides for the Table name and  RideId for the Partition key and select String for the key type. (Fields are case-sensitive.) Check the Use default settings box and press Create.
   
   
   
4. Scroll to the bottom of the Overview section of your new table and note the ARN. You will use this in the next section.
   
   
   
2. Create an IAM role for your Lambda function to run as. All code runs with SOME set of permissions. Here is where we define the permissions for your Lambda (event response) code
1. From the AWS Management Console, choose Services then select IAM.
2. Select Roles in the left nav bar and then choose Create Role.
3. Click "AWS Service", "Lambda", and "Next:Permissions" 
4. Type "AWSLambdaBasicExecutionRole" and put a check mark in the checkbox for that name.
   
   
   
5. Press "Next:Tags"
6. Press "Next:Review"
7. On the Review tab, enter WildRydesLambda for the Role Name and press "Create Role" 
   
   
   
8. Enter WildRydesLambda in the search box and click on the WildRydesLambda link: 
   
   
   
9. On the Permissions tab, click "Add inline policy" 
   
   
   
10. Click "Choose a service" 
    
    
    
11. Enter DynamoDB in the search box and then click the DynamoDB link: 
    
    
    
12. Enter PutItem in the search box and check the checkbox: 
    
    
    
13. Select "Specific" and click Add ARN: 
    
    
    
14. Enter the DynamoDB ARN you saved earlier. The default value is not QUITE the same as the table ARN. (The other fields default correctly.)  Then press the Add button. 
    
    
    
15. Press "Review policy" 
    
    
    
16. Enter DynamoDBWriteAccess for the policy name and choose Create policy
    
3. Create your Lambda function
1. From the AWS Management Console, choose Services then select Lambda.
2. From the AWS Lamda screen, select Functions and press "Create function"
3. Enter RequestUnicorn in the Name field and leave the default Node.js release selected:
   
   
   
4. In the Permissions section, "Use an existing role" and choose the role WildRydesLambda. Then press "Create function"
   
   
   
   
   
   
   
5. Edit index.js (via the in-browser editor) and paste in the code from https://webapp.serverlessworkshops.io/serverlessbackend/lambda/requestUnicorn.js
6. Choose File > Save from the in-browser editor, to save your code.
7. Press the Deploy button, to deploy your code.
8. Click the Test tab: 
   
9. Paste the code from https://gist.github.com/kleinfelter/8feb0aa698f36067db33967e573d77c3 to replace the default JSON, enter the event name "TestRequestEvent" and press Save Changes and then Test. 
   
   
   
   
   
   
   
10. Expand the Details section and check to see that you got a successful status: 
    
    
    
11. This shows that your back-end works.
4. Publish an API endpoint that wraps your function.  Functions don't just live out there -- they are accessed via a REST API published via the AWS API Gateway.
1. Create a REST API
1. From the AWS Management Console, choose Services then select API Gateway.
2. IF it shows you an introductory screen, press "Get Started". You want to be on this page: https://console.aws.amazon.com/apigateway/home?region=us-east-1#/apis/create
3. Complete the form as shown, and press "Create API". 
   
   
   
2. Setup Cognito to authenticate your API
1. Choose Authorizers and Create New Authorizer. 
   
   
   
2. Complete the form as shown, and press Create. 
   
   
   
3. Do not close the tab with the results of pressing Create!
4. In a browser address bar, enter your site URL followed by /ride.html.  You'll get a "Successfully Authenticated" message resembling the following.  Copy your auth token, circled in red below: 
   

   
   
   
   
   
5. Back on the tab with the results from creating your Athorizer, press Test.  
   
   
   
6. Paste in the auth token and press Test.  
   
   
   
7. You should receive a 200 response code.
3. Create the Resource and Method for your REST API
1. Select WildRydes API from your breadcrumbs: 
   
   
   
2. Click Resources, Actions, Create Resource. 
   
   
   
3. Complete the form as shown, and press Create Resource: 
   
   
   
4. Choose ride, Actions, Create Method: 
   
   
   
5. Choose Post and click the checkmark.  
   
   
   
6. Complete the form as shown and press Save.  
   
   
   
7. Click Method Request:  
   
   
   
8. Click the pencil by Authorization:  
   
   
   
9. Choose WildRydes for authorization. Be sure to click the checkmark after selecting WildRydes!  
   
4. Deploy
1. From the breadcrumbs, select APIs.  
   
   
   
2. Click on the WildRydes link.
3. Press Actions and choose Deploy.  
   
   
   
4. Complete the form as shown, and press Deploy.  
   
   
   
5. Save the Invoke URL it shows you:  
   
5. Update the web site to use the API
1. On your local computer, edit the js/config.js file.
2. Paste the Invoke URL into the invokeURL field.  
   
   
   
3. Save the file.
4. Run the git litany: git add . && git commit -m msg && git push
6. Test:
1. Wait 3 minutes for the deploy to complete. Then visit /rides.html on your web site's URL.
2. Login to your WildRydes site (if it prompts).
3. Click somewhere on the map.
4. Push "Request Unicon". You'll see a unicorn icon appear at your location, and some chat-like messages display.  If you use a Chrome-compatible browser, you'll see a simple animation of the unicorn's travel.  Cute.  The animation didn't work for me in Safari, but I have an old version of MacOS.

Cleanup

Delete everything afterward, so as not to get billed for it.  This demonstrates the non-integrated AWS approach to applications.  There is no "delete the tutorial projet" -- just "delete piece 1" and "delete piece 2" and ...  If you don't find all the pieces, you can't delete them all.

1. Delete the app:
• AWS Console > Services > AWS Amplify > WildRydes site > Actions > Delete
2. Delete the Cognito user pool:
• AWS Console > Services > Cognito > Manage User Pools > WildRydes > Delete Pool
3. Delete the Lambda function
• AWS Console > Services > Lambda > RequestUnicorn > Action > Delete
4. Delete the IAM roles
• AWS Console > Services > IAM > Roles > WildRydesLambda > Role actions > Delete Role
5. Delete the DynamoDB:
• WS Console > Services > DynamoDB > Tables > Rides > Delete Table
6. Delete the REST API endpoint:
• AWS Console > Services > API Gateway > WildRydes > Actions > Delete API
7. Delete your git repository
• AWS Console > Services > CodeCommit > wildrydes-site > Delete Repository
8. Delete your CloudWatch log (You didn't know you created one of those, did you?):
• AWS Console > Services > CloudWatch > Logs > Log Groups > /aws/lambda/RequestUnicorn > Actions > Delete Log Group
9. On your local computer, you might want to delete the wildrydes-site folder:
• cd to wherever you store your code and projects
• rm -rf windrydes-site  

What a mess! I just want a big "delete your project" button.