Forem: eelayoubi

AWS Text-To-Speech Serverless Application

eelayoubi — Thu, 01 Dec 2022 16:00:43 +0000

In this article we will go through deploying a Text-To-Speech Serverless Application that contains two main flows presented in the following section.

Architecture

New Post

The user calls the API Gateway Restful endpoint that invokes the NewPost lambda function.
The NewPost Lambda function inserts information about the post into an Amazon DynamoDB table, where information about all posts is stored.
Then, the NewPost Lambda function publishes the post to the SNS topic we create, so it can be converted asynchronously.
Convert to Audio Lambda function, is subscribed to the SNS topic and is triggered whenever a new message appears (which means that a new post should be converted into an audio file).
The Convert to Audio Lambda function uses Amazon Polly to convert the text into an audio file in the specified language (the same as the language of the text).
The new MP3 file is saved in a dedicated S3 bucket.
Information about the post is updated in the DynamoDB table (the URL to the audio file stored in the S3 bucket is saved with the previously stored data.)

Get Post

The user calls the API Gateway Restful endpoint that invokes the GetPost lambda function which contains the logic for retrieving the post data.
The GetPost Lambda function retrieves information about the post (including the reference to Amazon S3) from the DynamoDB table and returns the information.

Deploying The Resources

You will find the code repository here.

To deploy the application, simply run:

terraform apply -auto-approve

Breaking it down

We are using Terraform to deploy the application.

As you saw in the architecture section. We have two flows, the first one, is when a user submit a post through the API Gateway. And the second flow, in which the user can request one post or all posts.

In the main.tf, we are using the terraform modules that we create, to provision the following:

DynamoDB Table for storing the posts metadata
NewPost Lambda function
GetPost Lambda function
ConvertToAudio Lambda Function
The API Gateway

The iam.tf is where we define the least-privilege permissions for the various lambda functions we have.

The public S3 bucket that is used to store all the audio posts, is declared in the s3.tf.

The SNS topic used to decouple the application into an asynchronous flow is defined in the sns.tf

We are creating a topic called new_posts, with a lambda as a subscription. So every time this topic receives a message, it will invoke the ConvertToAudio lambda function with that message as an event.

To allow SNS to invoke the ConvertToAudio lambda function, we create as well a lambda permission resource.

NewPost Lambda Function

The NewPost lambda function does two things:
1- Creates an item in the posts table with the following schema:

id: recordId,
text: string,
voice: string,
status: 'PROCESSING'

The status as you can see is PROCESSING, since it still needs to be converted to an audio.

2- Publishes the item id to the SNS topic (so it can be process by ConvertToAudio)

ConvertToAudio Lambda Function

The ConvertToAudio lambda function does the following:

Fetches the post metadata from the posts table
Splits the text into chunks (if text is larger than 2600 characters)
Invokes Polly synthesizeSpeech with the text and saves them to a local file
Uploads the audio file to the S3 bucket
Updates the post metadata in the posts table with the S3 audio url and sets the status to UPDATED

GetPost Lambda Function

The GetPost lambda function retrieves the post(s):

If postId (querystring) is "*", the function will return all posts in the posts table
If postId is a post Id, the function will return that specific post (if it exists) or an empty array.

Clean-up

Don't forget to clean everything up by running:

terraform destroy -auto-approve

Wrap-up

In this article I presented the Text-To-Speech serverless application. In the next article, I will go through how we can handle errors that our lambda could encounter, and how to process them in the API gateway.

Until then, thank you for reading this article. I hope you found it useful 👋🏻.

What were your goals for this week?

eelayoubi — Fri, 21 Oct 2022 08:36:05 +0000

Hello all,

I would like us to start some discussions around this week's work. To do that here are a couple of questions to kick of the discussion:

What were your goals for this week?
Did you achieve all of them?
If not, why is that? Did some unplanned work block you from achieving your goals?
Does it happen often? Is it a recurrent pattern?
How do you plan on mitigating it?
What are your takeaways from this week?

Let's end this week with some nice discussions and help each other move forward 🎉

Using AWS Step Functions To Implement The SAGA Pattern

eelayoubi — Sun, 16 Oct 2022 07:27:01 +0000

Introduction

In this post I will walk you through how to leverage AWS Step Functions to implement the SAGA Pattern.

Put simply, the Saga pattern is a failure management pattern, that provides us the means to establish semantic consistency in our distributed applications by providing compensating transactions for every transaction where you have more than one collaborating services or functions.

For our use case, imagine we have a workflow that goes as the following:

The user books a hotel
If that succeeds, we want to book a flight
If booking a flight succeeds we want to book a rental
If booking a rental succeeds, we consider the flow a success.

As you may have guessed, this is the happy scenario. Where everything went right (shockingly ...).

However, if any of the steps fails, we want to undo the changes introduced by the failed step, and undo all the prior steps if any.

What if booking the hotel step failed? How do we proceed? What if the booking hotel step passes but booking a flight fails? We need to be able to revert the changes.

Example:

User books a hotel successfully
Booking the flight failed
Cancel the flight (assuming the failure happened after we saved the flight record in the database)
Cancel the hotel record
Fail the machine

AWS Step functions can help us here, since we can implement these functionalities as steps (or tasks). Step functions can orchestrate all these transitions easily.

Deploying The Resources

You will find the code repository here.

Please refer to this section to deploy the resources.

For the full list of the resources deployed, check out this table.

DynamoDB Tables

In our example, we are deploying 3 DynamoDB tables:

BookHotel
BookFlight
BookRental

The following is the code responsible for creating the BookHotel table

module "book_hotel_ddb" {
  source         = "./modules/dynamodb"
  table_name     = var.book_hotel_ddb_name
  billing_mode   = var.billing_mode
  read_capacity  = var.read_capacity
  write_capacity = var.write_capacity
  hash_key       = var.hash_key
  hash_key_type  = var.hash_key_type

  additional_tags = var.book_hotel_ddb_additional_tags
}

Lambda Functions

We will be relying on 6 Lambda functions to implement our example:

BookHotel
BookFlight
BookRental
CancelHotel
CancelFlight
CancelRental

The functions are pretty simple and straightforward.

BookHotel Function

exports.handler = async (event) => {
  ...
  const {
    confirmation_id,
    checkin_date,
    checkout_date
  } = event

...

  try {
    await ddb.putItem(params).promise();
    console.log('Success')

  } catch (error) {
    console.log('Error: ', error)
    throw new Error("Unexpected Error")
  }

  if (confirmation_id.startsWith("11")) {
    throw new BookHotelError("Expected Error")
  }

  return {
    confirmation_id,
    checkin_date,
    checkout_date
  };
};

For the full code, please checkout the index.js file

As you can see, the function expects an input of the following format:

confirmation_id
checkin_date
checkout_date

The function will create an item in the BookHotel table. And it will return the input as an output.

To trigger an error, you can create a confirmation_id that starts with '11' this will throw a custom error that the step function will catch.

CancelHotel Function

const AWS = require("aws-sdk")
const ddb = new AWS.DynamoDB({ apiVersion: '2012-08-10' });

const TABLE_NAME = process.env.TABLE_NAME

exports.handler = async (event) => {

    var params = {
        TableName: TABLE_NAME,
        Key: {
            'id': { S: event.confirmation_id }
        }
    };

    try {
        await ddb.deleteItem(params).promise();
        console.log('Success')
        return {
            statusCode: 201,
            body: "Cancel Hotel uccess",
        };
    } catch (error) {
        console.log('Error: ', error)
        throw new Error("ServerError")
    }
};

This function simply deletes the item that was created by the BookHotel function using the confirmation_id as a key.

We could have checked if the item was created. But to keep it simple, and I am assuming that the failure of the Booking functions always happen after the records were created in the tables.

💡 NOTE: The same logic goes for all the other Book and Cancel functions.

Reservation Step Function

# Step Function
module "step_function" {
  source = "terraform-aws-modules/step-functions/aws"

  name = "Reservation"

  definition = templatefile("${path.module}/state-machine/reservation.asl.json", {
    BOOK_HOTEL_FUNCTION_ARN    = module.book_hotel_lambda.function_arn,
    CANCEL_HOTEL_FUNCTION_ARN  = module.cancel_hotel_lambda.function_arn,
    BOOK_FLIGHT_FUNCTION_ARN   = module.book_flight_lambda.function_arn,
    CANCEL_FLIGHT_FUNCTION_ARN = module.cancel_flight_lambda.function_arn,
    BOOK_RENTAL_LAMBDA_ARN     = module.book_rental_lambda.function_arn,
    CANCEL_RENTAL_LAMBDA_ARN   = module.cancel_rental_lambda.function_arn
  })

  service_integrations = {
    lambda = {
      lambda = [
        module.book_hotel_lambda.function_arn,
        module.book_flight_lambda.function_arn,
        module.book_rental_lambda.function_arn,
        module.cancel_hotel_lambda.function_arn,
        module.cancel_flight_lambda.function_arn,
        module.cancel_rental_lambda.function_arn,
      ]
    }
  }

  type = "STANDARD"
}

This is the code that creates the step function. I am relying on a terraform module to create it.

This piece of code, will create a step function with the reservation.asl.json file as a definition. And in the service_integrations, we are giving the step function the permission to invoke the lambda functions (since these functions are all part of the step function workflow)

Below is the full diagram for the step funtion:

The reservation.asl.json is relying on the Amazon State language.

If you open the file, you will notice on the second line the "StartAt" : "BookHotel". This tells the step functions to start at the BookHotel State.

Happy Scenario

"BookHotel": {
    "Type": "Task",
    "Resource": "${BOOK_HOTEL_FUNCTION_ARN}",
    "TimeoutSeconds": 10,
    "Retry": [
        {
            "ErrorEquals": [
                "States.Timeout",
                "Lambda.ServiceException",
                "Lambda.AWSLambdaException",
                "Lambda.SdkClientException"
            ],
            "IntervalSeconds": 2,
            "MaxAttempts": 3,
            "BackoffRate": 1.5
        }
    ],
    "Catch": [
        {
            "ErrorEquals": [
                "BookHotelError"
            ],
            "ResultPath": "$.error-info",
            "Next": "CancelHotel"
        }
    ],
    "Next": "BookFlight"
},

The BookHotel state is a Task. With a "Resource" that will be resolved to the BookHotel Lambda Function via terraform.

As you might have noticed, I am using a retry block. Where the step function will retry executing the BookHotel functions up to 3 times (after the first attempt) in case of an error that is equal to any of the following errors:

"States.Timeout"
"Lambda.ServiceException"
"Lambda.AWSLambdaException"
"Lambda.SdkClientException"

You can ignore the "Catch" block for now, we will get back to it in the unhappy scenario section.

After the BookHotel task is done, the step function will transition to the BookFlight, as specified in the "Next" field.

"BookFlight": {
    "Type": "Task",
    "Resource": "${BOOK_FLIGHT_FUNCTION_ARN}",
    "TimeoutSeconds": 10,
    "Retry": [
        {
            "ErrorEquals": [
                "States.Timeout",
                "Lambda.ServiceException",
                "Lambda.AWSLambdaException",
                "Lambda.SdkClientException"
            ],
            "IntervalSeconds": 2,
            "MaxAttempts": 3,
            "BackoffRate": 1.5
        }
    ],
    "Catch": [
        {
            "ErrorEquals": [
                "BookFlightError"
            ],
            "ResultPath": "$.error-info",
            "Next": "CancelFlight"
        }
    ],
    "Next": "BookRental"
},

The BookFlight state follows the same pattern. As we retry invoking the BookFlight function if we face any of the errors specified in the Retry block. If no error is thrown the step function will transition to the BookRental state.

"BookRental": {
    "Type": "Task",
    "Resource": "${BOOK_RENTAL_LAMBDA_ARN}",
    "TimeoutSeconds": 10,
    "Retry": [
        {
            "ErrorEquals": [
                "States.Timeout",
                "Lambda.ServiceException",
                "Lambda.AWSLambdaException",
                "Lambda.SdkClientException"
            ],
            "IntervalSeconds": 2,
            "MaxAttempts": 3,
            "BackoffRate": 1.5
        }
    ],
    "Catch": [
        {
            "ErrorEquals": [
                "BookRentalError"
            ],
            "ResultPath": "$.error-info",
            "Next": "CancelRental"
        }
    ],
    "Next": "ReservationSucceeded"
},

The BookRental state follows the same pattern. Again we retry invoking the BookRental function if we face any of the errors specified in the Retry block. If no error is thrown the step function will transition to the ReservationSucceeded state.

"ReservationSucceeded": {
    "Type": "Succeed"
 },

The ReservationSucceeded, is a state with Succeed type.
In this case it terminates the state machine successfully

Unhappy Scenarios

Oh no BookHotel failed

As you recall, in the BookHotel state, I included a Catch block. In the BookHotel function, if the confirmation_id starts with 11, a custom error of BookHotelError type will be thrown. This "Catch block" will catch it, and will use the state mentioned in the "Next" field, which is the CancelHotel in this case.

"CancelHotel": {
    "Type": "Task",
    "Resource": "${CANCEL_HOTEL_FUNCTION_ARN}",
    "ResultPath": "$.output.cancel-hotel",
    "TimeoutSeconds": 10,
    "Retry": [
        {
            "ErrorEquals": [
                "States.Timeout",
                "Lambda.ServiceException",
                "Lambda.AWSLambdaException",
                "Lambda.SdkClientException"
            ],
            "IntervalSeconds": 2,
            "MaxAttempts": 3,
            "BackoffRate": 1.5
        }
    ],
    "Next": "ReservationFailed"
},

The CancelHotel is a "Task" as well, and has a retry block to retry invoking the function in case of an unexpected error. The "Next" field instructs the step function to transition to the "ReservationFailed" state.

"ReservationFailed": {
    "Type": "Fail"
}

The "ReservationFailed" state is a Fail type, it will terminate the machine and mark it as "Failed".

BookFlight is failing

We can instruct the BookFlight lambda function to throw an error by passing a confirmation_id that starts with 22.

The BookFlight step function task, has a Catch block, that will catch the BookFlightError, and instruct the step function to transition to the CancelFlight state.

"CancelFlight": {
    "Type": "Task",
    "Resource": "${CANCEL_FLIGHT_FUNCTION_ARN}",
    "ResultPath": "$.output.cancel-flight",
    "TimeoutSeconds": 10,
    "Retry": [
      {
        "ErrorEquals": [
          "States.Timeout",
          "Lambda.ServiceException",
          "Lambda.AWSLambdaException",
          "Lambda.SdkClientException"
        ],
        "IntervalSeconds": 2,
        "MaxAttempts": 3,
        "BackoffRate": 1.5
      }
    ],
    "Next": "CancelHotel"
  },

Similar to the CancelHotel, the CancelFlight state will trigger the CancelFlight lambda function, to undo the changes. Then it will instruct the step function to go to the next step, CancelHotel. And we saw earlier that the CancelHotel will undo the changes introduced by the BookHotel, and will then call the ReservationFailed to terminate the machine.

BookRental is failing

The BookRental lambda function will throw the ErrorBookRental error if the confirmation_id starts with 33.

This error will be caught by the Catch block in the BookRental task. And will instruct the step function to go to the CancelRental state.

"CancelRental": {
    "Type": "Task",
    "Resource": "${CANCEL_RENTAL_LAMBDA_ARN}",
    "ResultPath": "$.output.cancel-rental",
    "TimeoutSeconds": 10,
    "Retry": [
        {
            "ErrorEquals": [
                "States.Timeout",
                "Lambda.ServiceException",
                "Lambda.AWSLambdaException",
                "Lambda.SdkClientException"
            ],
            "IntervalSeconds": 2,
            "MaxAttempts": 3,
            "BackoffRate": 1.5
        }
    ],
    "Next": "CancelFlight"
},

Similar to the CancelFlight, the CancelRental state will trigger the CancelRental lambda function, to undo the changes. Then it will instruct the step function to go to the next step, CancelFlight. After cancelling the flight, the CancelFlight has a Next field that instructs the step function to transition to the CancelHotel state, which will undo the changes and call the ReservationFailed state to terminate the machine.

Conclusion

In this post, we saw how we can leverage AWS Step Functions to orchestrate and implement a fail management strategy to establish semantic consistency in our distributed reservation application.

I hope you found this article beneficial. Thank you for reading ... 🤓

Additional Resources

Switching between multiple Terraform versions

eelayoubi — Mon, 03 Oct 2022 09:45:28 +0000

Hey All,

In case you are using Terraform to provision and manage your infrastructure, you normally install a specific version on your machine (or on your CI servers).

But what if you wanted to install another terraform version to test it out?

In case you have multiple environment in the same codebase, let's say dev and prod, and you deployed both of them using a fixed terraform version (1.2.7).

After a while a new terraform version is available (1.3.1). You can update the version on your machine and test if it works fine, if not re-install the older version ... Which can be a bit cumbersome ...

Or, you can use tfenv which is a Terraform version manager.

After installing tfenv, you can use the tfenv list command to list the available terraform versions you have installed:

~ tfenv list
  1.2.7
No default set. Set with 'tfenv use <version>'

There is a new terraform version available that I would like to test out.

To install it, you just simply run :

tfenv install 1.3.1
Installing Terraform v1.3.1
Downloading release tarball from https://releases.hashicorp.com/terraform/1.3.1/terraform_1.3.1_darwin_amd64.zip
######################################################################### 100.0%
Downloading SHA hash file from https://releases.hashicorp.com/terraform/1.3.1/terraform_1.3.1_SHA256SUMS
Not instructed to use Local PGP (/usr/local/Cellar/tfenv/3.0.0/use-{gpgv,gnupg}) & No keybase install found, skipping OpenPGP signature verification
Archive:  /var/folders/jl/tfyd0yns2xxgb_58fj3ljslc0000gn/T/tfenv_download.XXXXXX.ouHdm2P4/terraform_1.3.1_darwin_amd64.zip
  inflating: /usr/local/Cellar/tfenv/3.0.0/versions/1.3.1/terraform  
Installation of terraform v1.3.1 successful. **To make this your default version, run 'tfenv use 1.3.1'**

List down all the installed terraform again:

tfenv list         
* 1.3.1 (set by /usr/local/Cellar/tfenv/3.0.0/version)
  1.2.7

You can see that the latest version is selected now.

If you'd like to switch to the old version, you simply run:
tfenv use VERSION

So:

tfenv use 1.2.7

Now you can see the default selected version:

tfenv use 1.2.7
Switching default version to v1.2.7
Default version (when not overridden by .terraform-version or TFENV_TERRAFORM_VERSION) is now: 1.2.7
➜  ~ tfenv list     
  1.3.1
* 1.2.7 (set by /usr/local/Cellar/tfenv/3.0.0/version)

This way you can test the newer version in your dev codebase in an easy way with just switching versions.

I hope you enjoyed this short blog.

Thank you for reading!

Deploying the full three-tier application

eelayoubi — Wed, 06 Apr 2022 13:03:54 +0000

In the previous post, we deployed the public side of our infrastructure. In this part, we will deploy the whole stack. Which consists of the followings:

1 VPC
2 Public subnets
2 Private subnets
2 Autoscaling groups
5 Security Groups
2 Load Balancers, (one private, one public)
2 Private EC2 instances (representing our application tier)
2 Public EC2 instances (representing our presentation tier)
2 Nat Gateways (so private instances can connect to the internet)
2 Elastic IP addresses, one for each Nat gateway
1 rds instance

You can check out the source code for this part here

The following is the diagram of our infrastructure by the end of this part:

Our Application

Our application consists of 2 tiers that will be deployed to the EC2 instances as docker containers:

presentation tier (this represents normally the customer facing part of the application, so what the customer interacts with)
application tier (this is where we have our business logics)

To keep it simple, our presentation tier simply forward requests to the business tier, that in turn run sql queries on the rds instance.

There is a setup-ecrs.sh script that will build these application images and push them to separate ECrs repositories. You can inspect the script for more details.

To run the script, first run chmod +x setup-ecrs.sh, this will assign executable permission on our script. Then make sure you have aws cli installed and configured, we also need docker to be running, and simply type: ./setup-ecrs.sh

Our new Infrastructure

Building on what we did in part 1, we will add another Load Balancer. This one is an internal LB, that will forward the requests coming from the public presentation instances to the private application instances.

It is also worth mentioning that we created 2 Launch Templates and 2 autoscaling groups (one for the presentation tier, and one for the application tier).

Security Groups

To allow traffic between the load balancers, public, and private instances, we added a security group for each component, these can be viewed here.

Basically the front facing load balancer's security groups, allows http connection from everywhere.
The presentation tier security group allows connection from the front facing LB, and so on.

RDS

We added a module for rds. Which will basically provision an rds instance that the application EC2 instances will query for data.

This module will create 3 resources:

A db subnet group
A security group
An rds instance

The module will export the rds's address that is needed by the application tier.

Gateways

We added 2 Nat Gateways that will allow the EC2 instances in the private subnet (the application tier) to access the internet to download some packages to deploy the docker image.

The presentation tier EC2 instances are public and already have access to the internet, so they can download the needed packages without extra steps.

We assigned an Elastic IP address to each of the Nat Gatweways.

EC2

Our EC2 instances need to access ECR to pull the docker images of our applications. To allow this, we created an instance role, that gives EC2 access to ECR.

As we said already, we have 2 launch templates, one for the business layer and another for the presentation layer.

We created 2 user data files that the launch templates will reference.

Presentation user data script:

#!/bin/bash
sudo yum update -y
sudo yum install docker -y
sudo service docker start
sudo systemctl enable docker
sudo usermod -a -G docker ec2-user
aws ecr get-login-password --region ${region}  | docker login --username AWS --password-stdin ${ecr_url}
docker run --restart always -e APPLICATION_LOAD_BALANCER=${application_load_balancer} -p 3000:3000 -d ${ecr_url}/${ecr_repo_name}:latest

This script will install docker and run it. It will also login to the ECR registry so we can run our presentation tier docker container.

As you can see we are passing the APPLICATION_LOAD_BALANCER dns name as an environment variable to the docker container, since our application needs it to forward client requests to the business tier.

In the Launch template we are referencing this script:

user_data = base64encode(templatefile("./../user-data/user-data-presentation-tier.sh", {
    application_load_balancer = aws_lb.application_tier.dns_name,
    ecr_url                   = "${data.aws_caller_identity.current.account_id}.dkr.ecr.${var.region}.amazonaws.com"
    ecr_repo_name             = var.ecr_presentation_tier,
    region                    = var.region
  }))

The ecr_url is the url for the presentation ECR repository that was created when running the setup-ecrs.sh script.

The application launch template passes additional variables to the user data application tier:

user_data = base64encode(templatefile("./../user-data/user-data-application-tier.sh", {
    rds_hostname  = module.rds.rds_address,
    rds_username  = var.rds_db_admin,
    rds_password  = var.rds_db_password,
    rds_port      = 3306,
    rds_db_name   = var.db_name
    ecr_url       = "${data.aws_caller_identity.current.account_id}.dkr.ecr.${var.region}.amazonaws.com"
    ecr_repo_name = var.ecr_application_tier,
    region        = var.region
  }))

We are passing the RDS instance details, such as username, password, etc ...

Deploying the stack

As mentioned earlier, make sure to run ./setup-ecrs.sh prior to deploying the infrastructure. Since our EC2 instances will download the docker images from the ECRs repositories.

If you haven't initialized the terraform project yet, simply navigate to the terraform folder and run terraform init.

We have a terraform.example.tfvars that holds all our variables values. Change the file name to terraform.tfvars, so when we terraform apply our changes, it is picked up automatically.

Once complete, go ahead and run terraform apply, and type yes to approve the changes.

It might take a while, since we are provisioning a couple of resources, and especially the RDS instance takes some time.

If all goes as planned, the deployment is successful and you get the dns url for the front facing load balancer:

.........
Apply complete! Resources: 39 added, 0 changed, 0 destroyed.

Outputs:

lb_dns_url = "front-end-lb-**********.us-east-1.elb.amazonaws.com"

Testing the Application

Now that we have the Front end Load Balancer's dns, we can test the application by simply visiting front-end-lb-**********.us-east-1.elb.amazonaws.com/ which will printout the a hello message with the server's hostname

We can call the front-end-lb-**********.us-east-1.elb.amazonaws.com/init endpoint, that forward the request to the presentation layer, which forwards the requests to the application layer (via the internal Load Balancer) that finally creates a table called users, and adds 2 users in the table, you can view the code here:

app.get('/init', async (req, res) => {
  connection.query('CREATE TABLE IF NOT EXISTS users (id INT(5) NOT NULL AUTO_INCREMENT PRIMARY KEY, lastname VARCHAR(40), firstname VARCHAR(40), email VARCHAR(30));');
  connection.query('INSERT INTO users (lastname, firstname, email) VALUES ( "Tony", "Sam", "tonysam@whatever.com"), ( "Doe", "John", "john.doe@whatever.com" );');
  res.send({ message: "init step done" })
})

To view the users table you can call front-end-lb-**********.us-east-1.elb.amazonaws.com/users

Destroying the infrastructure

Keeping in mind that some of the services will incur some charges, don't forget to clean up the environment, you can do so by running terraform apply -destroy -auto-approve, followed by ./destroy-ecrs.sh which will delete the ECR repositories that store our docker images.

Summary

In this post, we completed creating the infrastructure. We created a main VPC, with public and private subnets, an Internet Gateway, Nat Gateways, , Load Balancers, Autoscaling Groups and so on ...

We saw how to provision and destroy our application using terraform.

However, you might have noticed that the application's lifecycle is tightly coupled with the infrastructure's lifecycle. In the coming blog, we will see how we can split them to their own lifecycles and add some refactoring to our scripts.

Feel free to comment and leave your thoughts 🙏🏻!

Introducing the architecture & Deploying the public side

eelayoubi — Fri, 18 Mar 2022 15:27:44 +0000

In this serie of blog posts, we will be building a highly available application on top of AWS cloud services.

We will be using Terraform to provision and deploy our infrastructure.

By the end of this serie, we will have the following architecture deployed

Infrastructure Setup

For the first part of this application, we will be deploying the public feature as displayed in the below image.

We will have multiple resources to deploy:

VPC
2 Public Subnets
Internet Gateway
Route Table
Application Load Balancer
2 EC2 instances

You can check out the source code for this part here

Terraform Resources

Under the terraform folder in the GitHub repository, you will notice couple of files:

vpc.tf -> creates the vpc, public subnets, internet gateway, security group, route table
lb.tf -> creates the application load balancer, the listener, and the target group
ec2.tf -> creates the compute instances
main.tf -> declares the providers to use (only the aws provider for now)
variables.tf -> declares the variables used in the different resources

Creating the infrastructure

Our current infrastructure will consist of a vpc resource named main that is declared with a cidr block of "10.0.0.0/16".

resource "aws_vpc" "main" {
  cidr_block = var.main_cidr_block

  enable_dns_hostnames = true
  enable_dns_support   = true
  tags = {
    Name = "main"
  }
}

We will have 2 public subnets in different availability zones (to achieve a highly available architecture)

# we are looping over the number of subnets we have and creating public subnets accordingly
resource "aws_subnet" "public_subnets" {
  count                   = length(var.public_cidr_blocks)
  vpc_id                  = aws_vpc.main.id
  cidr_block              = var.public_cidr_blocks[count.index]
  availability_zone       = data.aws_availability_zones.available.names[count.index]
  map_public_ip_on_launch = true

  tags = {
    Name = "public_subnet_${count.index + 1}"
  }
}

We need need to create a security group that allows HTTP traffic in and out of instances

resource "aws_security_group" "main_sg" {
  name        = "allow_connection"
  description = "Allow HTTP"
  vpc_id      = aws_vpc.main.id

  ingress {
    description      = "HTTP from anywhere"
    from_port        = 80
    to_port          = 80
    protocol         = "tcp"
    cidr_blocks      = ["0.0.0.0/0"]
    ipv6_cidr_blocks = ["::/0"]
  }

  egress {
    from_port        = 0
    to_port          = 0
    protocol         = "-1"
    cidr_blocks      = ["0.0.0.0/0"]
    ipv6_cidr_blocks = ["::/0"]
  }

  tags = {
    Name = "allow_http"
  }
}

Since our VPC will need to connect to the internet, we will need to create an Internet Gateway and attache it to our freshly created VPC as follows

resource "aws_internet_gateway" "gw" {
  vpc_id = aws_vpc.main.id

  tags = {
    Name = "main"
  }
}

We will also create a route table and attach our public subnets to it, so we will have a route from these subnets to the internet

resource "aws_route_table" "public_route" {
  vpc_id = aws_vpc.main.id

  route {
    cidr_block = "0.0.0.0/0"
    gateway_id = aws_internet_gateway.gw.id
  }

  tags = {
    Name = "public_route"
  }
}

# we are creating two associations one for each subnet
resource "aws_route_table_association" "public_route_association" {
  count          = length(var.public_cidr_blocks)
  subnet_id      = aws_subnet.public_subnets[count.index].id
  route_table_id = aws_route_table.public_route.id
}

Creating the Application Load Balancer

For this part you can refer to the lb.tf file. This file will create an application load balancer named "front-end-lb"

# you can see here that we are referring to the security group and subnets that we have created earlier
resource "aws_lb" "front_end" {
  name               = "front-end-lb"
  internal           = false
  load_balancer_type = "application"
  security_groups    = [aws_security_group.main_sg.id]
  subnets            = aws_subnet.public_subnets.*.id

  enable_deletion_protection = false
}

The rest of the file, create, a load balancer rule, a target group on port 80, and a target group attachement, that attaches the instance we will create to the load balancer target group

resource "aws_lb_listener" "front_end" {
  load_balancer_arn = aws_lb.front_end.arn
  port              = "80"
  protocol          = "HTTP"

  default_action {
    type             = "forward"
    target_group_arn = aws_lb_target_group.front_end.arn
  }
}

resource "aws_lb_target_group" "front_end" {
  name     = "front-end-lb-tg"
  port     = 80
  protocol = "HTTP"
  vpc_id   = aws_vpc.main.id
}

resource "aws_lb_target_group_attachment" "front_end" {
  count            = length(aws_subnet.public_subnets)
  target_group_arn = aws_lb_target_group.front_end.arn
  target_id        = aws_instance.front_end[count.index].id
  port             = 80
}

Creating the Compute instances

The last part here is the EC2 instances that will be provisioned when terraform runs the ec2.tf file. This will create 2 instances in the public subnets, and will have the security group that allows http traffic attached to them

resource "aws_instance" "front_end" {
  count                       = length(aws_subnet.public_subnets)
  ami                         = data.aws_ami.amazon_linux_2.id
  instance_type               = "t2.nano"
  associate_public_ip_address = true
  subnet_id                   = aws_subnet.public_subnets[count.index].id

  vpc_security_group_ids = [
    aws_security_group.main_sg.id,
  ]

  user_data = <<-EOF
    #!/bin/bash
    sudo su
    yum update -y
    yum install -y httpd.x86_64
    systemctl start httpd.service
    systemctl enable httpd.service
    echo “Hello World from $(hostname -f)” > /var/www/html/index.html
        EOF

  tags = {
    Name = "HelloWorld_${count.index + 1}"
  }
}

Deploying the infrastructure + application

Please make sure to have terraform installed, and have AWS Credentials configured locally.

Navigate to the terraform folder in your terminal and run:

terraform init

This will initialise the backend, and install the aws plugin and prepare terraform.

You should see the following output:

Initializing the backend...

Initializing provider plugins...
- Finding hashicorp/aws versions matching "~> 4.5.0"...
- Installing hashicorp/aws v4.5.0...
- Installed hashicorp/aws v4.5.0 (signed by HashiCorp)

Terraform has created a lock file .terraform.lock.hcl to record the provider
selections it made above. Include this file in your version control repository
so that Terraform can guarantee to make the same selections by default when
you run "terraform init" in the future.

Terraform has been successfully initialized!

You may now begin working with Terraform. Try running "terraform plan" to see
any changes that are required for your infrastructure. All Terraform commands
should now work.

If you ever set or change modules or backend configuration for Terraform,
rerun this command to reinitialize your working directory. If you forget, other
commands will detect it and remind you to do so if necessary.

Now you can run a terraform speculative plan to have an overall view of what will be created.

We will skip this part and directly run

terraform apply

You will be prompted to approve the changes. Type yes

It will take a couple of minutes to have everything ready. If all goes well terraform will exit without an error and you will see something like the following

.........

Apply complete! Resources: 15 added, 0 changed, 0 destroyed.

Outputs:

lb_dns_url = "front-end-lb-*********.us-east-1.elb.amazonaws.com"

Finally run terraform output to print the outputs that are declared in outputs.tf You should see the following

lb_dns_url = "front-end-lb-1873116014.us-east-1.elb.amazonaws.com"

Pasting the url in the browser, you should see something like this

“Hello World from ip-10-0-1-68.ec2.internal”

When we refresh the page, we should hit another instance, and see the hostname of the second EC2 instance (if not do a hard refresh).

Destroying the infrastructure

Keeping in mind that some of the services will incur some charges, don't forget to clean up the environment, you can do so by running terraform apply -destroy -auto-approve

Summary

In this post, we created the infrastructure + public part of our application. We created a main VPC, with 2 Public Subnets, an Internet Gateway, a Load Balancer, and 2 Compute Instances.
We saw how to provision and destroy our application using terraform.

In the next blog, we will be deploying private part of the infrastructure, along with some refactoring for our terraform code (example: using modules). Stay tuned, and I hope you have enjoyed Part 1.

Feel free to comment and leave your thoughts 🙏🏻!

Serverless Server Side Rendering with Angular on AWS Lambda@Edge

eelayoubi — Mon, 14 Dec 2020 12:47:59 +0000

In this article we will look at how we can enable server side rendering on a Angular application and make it run serverless on 'AWS Lambda@Edge'.
How do we go from running a non server side rendered static Angular application on AWS S3 to enabling SSR and deploying it to Lambda@Edge, S3 whilst utilising CloudFront in front of it?

Lambda@Edge to the rescue

I was recently interested in seeing how to server side render an Angular app with no server. As using Lambda@Edge.

Lambda@Edge is an extension of AWS Lambda, a compute service that lets you execute functions that customize the content that CloudFront delivers (more info).

Lambd@Edge can be executed in 4 ways:

Viewer Request
Origin Request (we will be using this for SSR 🤓)
Origin Response
Viewer Response

In this example, I am using:

Angular 11
Express js for SSR
AWS S3 for storing the application build
AWS Cloudfront as the CDN
and of course the famous Lambda@Edge

This post already assumes the following:

having an aws account
having aws cli configure
having serverless framework installed
Already familiar with Angular SSR

Here is the Github repo
And the application is deployed here

Introducing the sample application

The application is pretty simple, as we have 2 modules:

SearchModule
AnimalModule (lazy loaded)

When you navigate to the application, you are presented with an input field, where you can type a name (ex: Oliver, leo ...), or an animal (ex: dog, cat). You will be presented with a list of the findings. You can click on an anima to go see the details in the animal component.

As simple as that. Just to demonstrate the SSR on Lambda@Edge.

You can clone the repo to check it out

Enabling SSR on the application

Okay ... Off to the SSR part. The first thing to do is to run the following command:

ng add @nguniversal/express-engine

Which will generate couple of files (more on this here).

To run the default ssr application, just type:

yarn build:ssr && yarn serve:ssr and navigate to http://localhost:4000

You will notice that angular generated a file called 'server.ts'. This is the express web server. If you are familiar with lambda, you would know that there are no servers. As you don't think about it as a server ... You just give a code, and Lambda runs it ...

To keep the Angular SSR generated files intact, I made a copy of the following files:

server.ts -> serverless.ts
tsconfig.server.json -> tsconfig.serverless.json

In the serverless.ts I got rid of the 'listen' part (no server ... no listener 🤷🏻‍♂️).

The server.ts file uses ngExpressEngine to bootstrap the application. However, I replaced that in serverless.ts with 'renderModule' that comes from '@angular/platform-server' (more flexibility ...)

In tsconfig.serverless.json, on line 12, instead of including server.ts in the 'files' property, we are including our own serverless.ts.

In the angular.json file I added the following part:



"serverless": {
          "builder": "@angular-devkit/build-angular:server",
          "options": {
            "outputPath": "dist/angular-lambda-ssr/serverless",
            "main": "serverless.ts",
            "tsConfig": "tsconfig.serverless.json"
          },
          "configurations": {
            "production": {
              "outputHashing": "media",
              "fileReplacements": [
                {
                  "replace": "src/environments/environment.ts",
                  "with": "src/environments/environment.prod.ts"
                }
              ],
              "sourceMap": false,
              "optimization": true
            }
          }
        }

Then in the package.json I added the following property:

"build:sls": "ng build --prod && ng run angular-lambda-ssr:serverless:production"

As you can see in the 'options' property we are pointing to our customized main and tsconfig. So when running the yarn build:sls, these config will be used to generate the dist/angular-lambda-ssr/serverless

Creating the Lambda function to execute SSR

I added a new file called 'lambda.js. This is the file that contains the Lambda function, that will be executed on every request from CloudFront To the Origin (Origin Request)

I'm using the serverless-http package that is a fork of the original repo. The main repo maps Api Gateway requests, I added the Lambda@Edge support that can be viewed in this PR

Anyway, as you can see on line 8, we are passing the app (which is express app) to the serverless function, and it returns a function that accepts the Incoming event and a context.
On line 18 some magic will happen, basically mapping the request and passing it to the app instance which will return the response (the ssr response).
Then on line 19 we are just minifying the body, since there is a 1MB limit regarding the Lambda@Edge origin-request.
Finally on line 27 we are returning the response to the user.

Keep in mind that we are only doing SSR to requests to the index.html or to any request that doesn't have an extension.

If the request contains an extension, it means you are requesting a file... so we pass the request to S3 to serve it.

Deploying to AWS

You will notice in the repo 2 files:

serverless-distribution.yml
serverless.yml

We will first deploy the serverless-distribution.yml:

This will deploy the following resources:

Cloudfront Identity (used by S3 and Cloudfront to ensure that objects in 3 are only accessible via Cloudfront)
Cloudfront Distribution
S3 bucket that will store the application build
A Bucket Policy that Allows the CloudFront Identity to Get the S3 objects.

To deploy this stack, on line 58 change the bucket name to something unique for you, since S3 names are global ... Then just run the following command:

serverless deploy --config serverless-distribution.yml

This may take a few minutes. When the deployment is done, we need to get the cloudfront endpoint. You can do that by going to the console or by running:
aws cloudformation describe-stacks --stack-name angular-lambda-ssr-distribution-dev
The endpoint will have the following format:
d1234244112324.cloudfront.net

Now we need to add the cloudfront endpoint to the search.service.ts:

On line 15, replace "/assets/data/animals.json" with "https://cloudfrontendpointhere/assets/data/animals.json"

Now that we have that done, we need to build the app with our serverless.ts (in case already done, we need to build it again since we changed the endpoint to fetch the data), so run:

yarn build:sls

That will generate the dist folder that contains the angular app that we need to sync to S3 (since S3 will serve the static content, as the js, css ..)

After the dist is generated, go to the browser folder in the dist:

cd dist/angular-lambda-ssr/browser

Then run the following command to copy the files to S3:

aws s3 sync . s3://replacewithyourbucketname

Be sure to replace the placeholder with your S3 bucket Name.

Once this is done, we need to deploy the lambda function, which is in serverless.yml, simply run:

serverless deploy

This will deploy the following resources:

The Lambda Function
The Lambda execution role

Once the stack is created, we need to deploy Lambda@Edge to the Cloudfront behaviour we just created, so copy and paste this link in a browser tab (make sure you are logged in to aws console)
https://console.aws.amazon.com/lambda/home?region=us-east-1#/functions/angular-lambda-ssr-dev-ssr-origin-req/versions/$LATEST?tab=configuration

⚠️ Make sure the $LATEST version is selected

1- Click on 'Actions'
2- Click on 'Deploy to lambda@Edge'
3- Choose the distribution we created
3- Choose the Default behaviour (there is only one for the our distribution)
4- For Cloudfront Event, choose 'Origin Request'
5- Leave the include Body unticked
6- Tick the Acknowledge box
7- Click Deploy

It will take a couple of minutes to deploy this function to all the cloudfront edge locations.

Testing

You can navigate to the cloudfront endpoint again, and access the application, you should see that the SSR is working as expected.

You can see that the animal/3 request was served from express server

And the main js is served from S3 (it is cached on Cloudfront this time)

Cleanup

To return the AWS account to its previous state, it would be a good idea to delete our created resources.

Note that in term of spending, this will not be expensive, if you have an AWS Free Tier, you won't be charged, unless you go above the limits (lambda pricing, cloudfront pricing)

First we need to empty the S3 bucket, since if we delete the Cloudformation stack with a non empty bucket, the stack will fail.
So run the following command:

aws s3 rm s3://replacewithyourbucketname --recursive

Now we are ready to delete the serverless-distribution stack, run the following command:

serverless remove --config serverless-distribution.yml

We must wait for a while to be able to delete the serverless.yml stack, if you try to delete it now you will run into an error, as the lambda function is deployed on Cloudfront.

After a while, run the following:

serverless remove

Some Gotchas

We could have combined the two stacks (serverless-distribution & serverless) in one file. However, deleting the stack will fail, as it will delete all resource except the lambda function, since as explained we need to wait until the Replicas are deleted, which might take some time (more info)
We could have more complicated logic in the Lambda function to render specific pages, for specific browsers ... I tried to keep it simple in this example
Be aware that Lambda@Edge origin-request has some limits:
Size of a response that is generated by a Lambda function, including headers and body : 1MB
Function timeout: 30 seconds
more info
We can test the Lambda function locally, thanks to serverless framework, we can invoke our lambda. To do so, run the following command:
serverless invoke local --function ssr-origin-req --path event.json
You will see the result returned contains the app ssr rendered.
The event.json file contains an origin-request cloudfront request, in other words, the event the Lambda function expects in the parameter. more info

Conclusion

In this post we saw how we can leverage Lambda@Edge to server side render our angular application.

We have a simple angular app
We enabled SSR with some customisation
We Created the Lambda Function that will be executed on every request to Origin (to S3 in our case)
We deployed the serverless-distribution stack
we deployed the Lambda stack and associated the Lambda to the Cloudfront Behaviour
We tested that everything is working as expected

I hope you found this article beneficial. Thank you for reading ... 🤓

Decoupling an Angular app using AWS IOT

eelayoubi — Tue, 25 Aug 2020 20:08:21 +0000

Introduction

In this blog, I will walk you through how we can use AWS IOT thing to decouple the frontend application from the backend.

Basically, the frontend talks to an API Gateway through a rest endpoint. We have two methods one to get all animals in the database. And another method to insert an animal.

This is a configuration walkthrough blog, meaning the frontend app is very minimalistic.
The frontend consists of a simple Angular 10 application.
To checkout the full code, here is the GitHub repo

Architecture

As you can see, the backend consists of:

an API Gateway with a rest endpoint with two methods
A DynamoDB table with Streams enabled on it
An AlertIOTFunction that gets trigged on the STREAMS change
An IOT topic, that is used by the AlertIOTFunction to publish a message to.

So on a high level, we can imagine a system where a customer does an action, in this case, adds an animal to the database. This insert, triggers a stream that calls a lambda, which can trigger a process for a payment, or a confirmation or something that can take some time ⏳.

In our case, this process only takes the newly added animal, and publishes it to an IOT topic. And we can see it in the client's console and act on it if needed (which is most likely to happen 🙄 )

Code Examples

Frontend

For the frontend everything is in the aws-examples inside the github repo. To run it you can follow the README.

To subscribe to the IOT topic, we are using an AWS library called aws-iot-device-sdk. (we could use the MQTT.js directly if we want.)

To make it work with the frontend application, I have added the following in the package.json:

"browser": {
   "fs": false,
   "tls": false,
   "path": false
},

Without this piece, running the app will result in build errors: ERROR in ./node_modules/aws-iot-device-sdk/common/lib/tls-reader.js Module not found: Error: Can't resolve 'fs' in '/Users/.../aws-examples/aws-examples/node_modules/aws-iot-device-sdk/common/lib'

Plus, we have to add the following piece in the polyfill.ts:

(window as any)['global'] = window;
global.Buffer = global.Buffer || require('buffer').Buffer;

import * as process from 'process';
window['process'] = process;

without it the browser will complain that index.js:43 Uncaught ReferenceError: global is not defined

The code is pretty straightforward. In the app.component.ts
in the constructor we are connecting to the IOT Topic.

ℹ️ As you know everything that needs access to an AWS service needs credentials. This is why we are using Cognito. We are using it to generate temporary credentials so the application can subscribe to the IOT topic.

// 1
AWS.config.credentials = new AWS.CognitoIdentityCredentials({
    IdentityPoolId: this.AWSConfiguration.poolId
})

const clientId = 'animals-' + (Math.floor((Math.random() * 100000) + 1)); // Generating a clientID for every browser

// 2
this.mqttClient = new AWSIoTData.device({
    region: AWS.config.region,
    host: this.AWSConfiguration.host,
    clientId: clientId,
    protocol: 'wss',
    maximumReconnectTimeMs: 8000,
    debug: false,
    secretKey: '', // need to be send as an empty string, otherwise it will throw an error
    accessKeyId: '' // need to be send as an empty string, otherwise it will throw an error
});

On '1', the IdentityPoolId comes from the backend, where we deploy a template with some Cognito resources, it is explained below 🤓.

On '2', we are trying to connect to the IOT endpoint (explained in the README)

Moving to the ngOnInit, we can see the following:

this.mqttClient.on('connect', () => { // 1
    console.log('mqttClient connected')
    this.mqttClient.subscribe('animals-realtime')
});

this.mqttClient.on('error', (err) => { // 2
    console.log('mqttClient error:', err);
    this.getCreds();
});

this.mqttClient.on('message', (topic, payload) => { // 3
    const msg = JSON.parse(payload.toString())
    console.log('IoT msg: ', topic, msg)
});

this.http.get(`${this.api}get-animals` // 4
)
    .subscribe((data) => {
        console.log('data: ', data)
    });

On '1', we are listening to the connect event, if it is established correctly we are subscribing the the IOT topic created in AWS.

On '2', in case of an error we are calling the getCreds method. It is interesting to know, that the first time we run the app, connecting to the IOT topic will throw an error, because the credentials are not passed to the mqttClient, so in the error event we call the getCreds method to set the credentials correctly.

On '3', we are listening to the messaged that are published to the IOT topic, here we are just console logging it to keep things simple.

On '4', we are just making a request to API Gateway endpoint to get the animals in DynamoDB.

Moving to the getCreds method:

const cognitoIdentity = new AWS.CognitoIdentity(); // 1
(AWS.config.credentials as any).get((err, data) => {
    if (!err) {
        console.log('retrieved identity: ' + (AWS.config.credentials as any).identityId)
        var params = {
            IdentityId: (AWS.config.credentials as any).identityId as any
        }
        // 2
        cognitoIdentity.getCredentialsForIdentity(params, (err, data) => {
            if (!err) {
                // 3
                this.mqttClient.updateWebSocketCredentials(data.Credentials.AccessKeyId,
                    data.Credentials.SecretKey,
                    data.Credentials.SessionToken,
                    data.Credentials.Expiration
                )
            }
        })
    } else {
        console.log('Error retrieving identity:' + err)
    }
})

On '1' we are getting a Cognito Identity instance.
On '2' we are getting the credentials coming from Cognito
On '3' we are updating the mqttClient with the retrieved credentials.

To test this, we have a simple button, when we click it, it will call insertAnimal method that will simply post an animal to the database:

insertAnimal() {
    this.http.post(`${this.api}add-animal`, {
        "name": "cat",
        "age": 1
        // other fields ...
    }
    )
        .subscribe((data) => {
            console.log('data: ', data)
        });
}

After a couple of seconds we will receive a console in the console logs printing: IoT msg: animals-realtime ... 🎉

demo

Backend

The backend code is in /backend/iot
We have the resources defined in the template.yml. We deploy the backend using AWS SAM

To know how to deploy it, please follow the instructions in the project's README.

On a high level, in the template.yml you will find multiple resources:

AnimalsRealtime the AWS IOT thing
InsertAnimalFunction, a Lambda function that gets called when calling the api endpoint with /add-animal
GetAnimalsFunction, a Lambda function that gets called when calling the api endpoint with /get-animals
AlertIOTFunction, a Lambda function that gets trigger by a DynamoDB Stream
AnimalsAPI, an API Gateway
AnimalsTable, the DynamoDB database to store the items
UserPool & UserIdentity, to give access to the frontend to subscribe to the IOT topic

Conclusion

To sum things up, there are many ways to decouple the frontend from the asynchronous/long-term backend processes. One of these approaches could be leveraging the IOT publish/subscribe methodology. Where a client execute an event, and subscribes to a topic. And when the backend finishes processing the needed tasks, it can publish results/notification to the topic.

In our case it was a simple action, returning the new added animal to the frontend. It can be more complicated than that, such as handling payment, approvals ...

I hope you have found this article useful. Please feel free to leave your remarks/questions in comments 🙏