Fixes #1 #2 #3 #4 #5 #6 #7 #8 #9 #10 #11 #12

README.md

@@ -1,6 +1,6 @@
 # Service Mesh deployment demo
 
-This project aims to demonstrate how to deploy a microservices architecture on AWS ECS, leveraging on AWS App Mesh for East/West integration between those services and on AWS API Gateway for North/South integration. 
+This project aims to demonstrate how to deploy a microservices architecture on AWS ECS, leveraging AWS App Mesh for East/West integration between those services and on AWS API Gateway for North/South integration. 
 
 Before diving into that, let's recap the concepts mentioned above:  
 
@@ -12,14 +12,14 @@ This project uses a simple application, composed by a Frontend Web UI written in
 
 ![Application Architecture](./static/application-architecture.png) 
 
-Each backend services returns a 'Hello World' message, informing its IP address and Availability Zone within AWS Cloud. The frontend UI makes repetitive and infinite requests to those backend services, writing down their responses and plotting on a map the path each request took:
+Each backend services returns a 'Hello World' message informing its IP address and its Availability Zone (AZ). The frontend UI keeps making requests to the backend services, writing down their responses and plotting on a map the path each request took.
 
 ![Frontend UI](./static/a-b-c.svg) 
 
-On the diagram above, the request arrived at the frontend UI on the availability zone A, and then a request was made to the nodejs backend on the zone B, and to the crystal backend on the zone C. 
+On the diagram above, a request arrived at the frontend UI on AZ A, and then, a request was sent to the NodeJS backend on AZ B, and another request was sent to the crystal backend on AZ C.
 
 
-Their source code can be obtained here: 
+Their source code is available at: 
 - [nodejs](https://github.com/brentley/ecsdemo-nodejs)
 - [crystal](https://github.com/brentley/ecsdemo-crystal)
 - [frontend](https://github.com/brentley/ecsdemo-frontend)
@@ -29,9 +29,9 @@ The architecture of this deployment uses the following AWS Services:
 
 1. [AWS CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/GettingStarted.html) : Used to deploy this whole architecture using the '*infrastructure as code*' paradigm.
 1. [Amazon VPC](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-getting-started.html) : Used to define an isolated and secure network perimeter for the application. 
-1. [Amazon ECS](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/getting-started-ecs-ec2.html) : All the components of this application were encapsulated into containers. ECS is a container orchestration that aims to provide scalability and resiliency to a container-based architecture. 
+1. [Amazon ECS](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/getting-started-ecs-ec2.html) : All the components of this application were encapsulated into containers. ECS is a container orchestration service that aims to provide scalability and resiliency to a container-based architecture. 
 1. [Application Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/application-load-balancer-getting-started.html) : In order to provide internet-facing, easy access, to the frontend UI, an application load balancer was added to the solution.
-1. [Network Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/network-load-balancer-getting-started.html) : Used by API Gateway as its entry point into the VPC, and also load balancing the requests among the difference instances of each backend service. 
+1. [Network Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/network-load-balancer-getting-started.html) : Used by API Gateway as its entry point into the VPC, and also load balancing the requests among the different instances of each backend service. 
 1. [AWS Cloud Map](https://docs.aws.amazon.com/cloud-map/latest/dg/setting-up-cloud-map.html) : Provides *service discovery* capabilities to the application. Since all these components were deployed using an auto-scaling topology using ephemeral containers, it is important to have a mechanism to allow each service to discover the location of other services. 
 1. [AWS App Mesh](https://docs.aws.amazon.com/app-mesh/latest/userguide/appmesh-getting-started.html) : Creates a service mesh, allowing the microservices to talk to each other in a secure, reliable and scalable way, providing East/West integration capabilities within the application.
 1. [Amazon API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/getting-started.html) : Encapsulates access to the backend services, adding a layer of control to the application, that way allowing North/South integration capabilities to the application.
@@ -43,29 +43,29 @@ The architecture of this deployment uses the following AWS Services:
 
 As mentioned earlier, this application will be deployed onto a ECS cluster, using a service mesh to encapsulate it. In the next diagram, notice that there are 2 different paths used to reach the backend services, colored with different colors.
 
--	The blue path illustrates the East/West scenario: The frontend UI is part of the service mesh, and it communicates with the backend services directly within the mesh, relying on the Cloud Map service discovery to figure out the ip address where those services are running. 
+-	The blue path illustrates the East/West scenario. The frontend UI is part of the service mesh, and it communicates with the backend services directly within the mesh, relying on the Cloud Map service discovery to figure out the services IP addresses. 
 
--	The red path illustrates the North/South scenario. The fronted UI is deployed onto a separated VPC on the same AWS account, but it could be running on another AWS account or even on-premises. 
+-	The red path illustrates the North/South scenario. The frontend UI is deployed onto a separated VPC on the same AWS account, but it could be running on another AWS account or even on-premises. 
 
 	![alt](./static/architecture.png)
 
 
-You can reach the frontend app of these scenarios by accessing its related application load balancer URL on your web browser.
+The frontend app of these scenarios can be accessed using their related load balancer URL on a web browser.
 
 ## Communication
 
 There are a few concepts hidden on the previous diagram that needs to be explored on each scenario.
 
 
-### Blue scenario:
+### Blue scenario
 
 - When the request arrives at the service mesh from the ALB, it reaches the ***Virtual Node*** endpoint declared for the frontend UI. A ***Virtual Node*** is an abstraction of a deployment or physical server where your service/application is running. In this case, we are only using one ***Virtual Node*** per service. It represents its deployment on ECS.  
 
 - When the frontend UI makes a request to a backend service, it uses its ***Virtual Service*** name. Since containers are ephemeral, the only way that the frontend service can figure out where the backend service is running, is by relying on a 'Service Discovery' component.    
    
-Every time a new task is started at the ECS cluster, the ECS service registers this task on AWS Cloud Map, and a DNS entry is created on Route 53 for this task. The ***Virtual Service*** is this name being used to register the task.
+Every time a new task is started at the ECS cluster, the ECS service registers this task on AWS Cloud Map, and a DNS entry is created on Route 53 for this task. The ***Virtual Service*** is this name used to register the task.
 
-- Instead of reaching directly the ***Virtual Node*** (can be done), the frontend UI is talking to the ***Virtual Router*** component. This router has the ability to abstract the connectivity to several distinct ***Virtual Nodes***, adding intelligence to the routing logic. For instance, if you want to setup a blue/green deployment of one of the backend services, you could add the routing rules on this component.  
+- Instead of directly reaching the ***Virtual Node*** (which can be done), the frontend UI is talking to the ***Virtual Router*** component. ***The Virtual Router*** abstracts the connectivity to several distinct ***Virtual Nodes***, adding intelligence to the routing logic. For instance, if you want to setup a blue/green deployment of one of the backend services, you could add the routing rules on this component.  
 
 	![alt](./static/dataflow-mesh.png)
 
@@ -135,6 +135,6 @@ This is a master template that you can use to deploy the whole solution on your
 
 ### Getting Started
 
-Click <a href="https://console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacks/quickcreate?templateURL=https://servicemesh-demo-templates.s3-sa-east-1.amazonaws.com/stack.yaml&stackName=servicemesh-demo" target="_blank">here</a> to deploy this stack on your AWS Account using CloudFormation and play with it. After the stack finishes deploying (it might take up to 20 minutes), navigate to its 'Outputs' tab to get the URLs for the frontend UI on both Red and Blue scenarios.  
+Click [here](https://console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacks/quickcreate?templateURL=https://servicemesh-demo-templates.s3-sa-east-1.amazonaws.com/stack.yaml&stackName=servicemesh-demo) to deploy this stack on your AWS Account using CloudFormation and play with it. After the stack finishes deploying (it might take up to 20 minutes), navigate to its 'Outputs' tab to get the URLs for the frontend UI on both Red and Blue scenarios.  
 
 If you want to extend or make modifications on this demo, the template sources are included in this github repository, inside the [stacks](./stacks) folder.