Readme & FAQ updates

FAQ.md

@@ -0,0 +1,24 @@
+## App Mesh Preview FAQs
+
+1. **Why should I use App Mesh?**<br/>
+App Mesh makes it easy to get visibility and control over the communications between your microservices without writing new code or running additional AWS infrastructure. Using App Mesh, you can standardize how microservices communicate, implement rules for communications between microservices, and capture metrics, logs, and traces directly into AWS services and third-party tools of your choice.<br/>
+1. **How does App Mesh work?**<br/>
+App Mesh sets up and manages a service mesh for your microservices. To do this, App Mesh runs the open source Envoy proxy alongside each microservice container and configures the proxy to handle all communications into and out of each container. <br/>
+1. **What can I do with App Mesh now when it is preview?** <br/>
+App Mesh makes it easier to debug and identify the root cause of communication issues between your services. App Mesh collects logs and metrics including latencies, error rates, and connections per second, which can be exported to Amazon CloudWatch or Prometheus using a statsd collector. App Mesh enables you to connect and test new versions of your microservices before rolling it out to all users. App Mesh APIs provide traffic routing controls to enable canary style deployments. You can now route traffic based on HTTP path or weights to specific service versions. App Mesh now works with Amazon Elastic Container Services (ECS) and Amazon Elastic Container Service for Kubernetes (EKS).<br/>
+1. **What can I do with App Mesh when it is generally available?**<br/>
+You can use App Mesh to send metrics, logs and traces to services of your choice. You can insert tracing to visualize a service map with details of API calls between services. You can configure traffic policies like health checks, retries and circuit breaks for the clients that connect to your services. You can also perform traffic routing on several other protocols, and based on HTTP headers and query parameters.<br/>
+1. **How do I get started with using App Mesh APIs?**<br/>
+You can use App Mesh APIs to create the mesh and virtual nodes to represent your services. You then need to create virtual routers to configure traffic routes between these services. You then setup endpoints (statsd or Prometheus) to export metrics and logs from the mesh proxy and configure these endpoints in the Envoy bootstrap configuration - see detailed guide here (link). Then, you add App Mesh images into ECS task definition or EKS pod specification along with the environment variables required to virtual nodes. When these services get deployed, Envoys connect to App Mesh to get all the configuration required to handle all inbound and outbound task traffic according to the specified traffic routes.<br/>
+1. **Which version of Envoy do you use?**<br/>
+Today, App Mesh distributes a build of version 1.8.0 with an extensions for SigV4 that to ensure Envoy is authenticated propery with AWS authentication systems.We plan to upstream this change to Envoy soon.<br/>
+1. **How do your nodes authenticate so that a malicious service on my cluster doesn't connect itself to the mesh?** <br/>
+We have added Sigv4 based Authentication for Envoy proxies that connect to the App Mesh service via standard AWS authentication. We plan to upstream this change to Envoy soon.<br/>
+1. **Are the service limits during the preview?**<br/>
+You can create 1 mesh per account with 10 virtual nodes (10 versioned services or 10 deployments) and 10 virtual routers per mesh and 1 route in each virtual router.<br/>
+1. **Is there a performance impact from having Envoy in the data path?**<br/>
+Envoy is built for high performance. Using App Mesh should incur the same overhead as using Envoy without App Mesh.<br/>
+1. **What does App Mesh cost?**<br/>
+There is no additional charge for using AWS App Mesh. You pay only for the AWS resources (i.e. EC2 instances or requested Fargate CPU and memory) consumed by the App Mesh proxy that runs alongside your containers.<br/>
+1. **How do I start using App Mesh?**<br/>
+App Mesh is available today as a pubic preview. You can start using App Mesh from the AWS CLI or SDK. Learn more at aws.amazon.com/appmesh/getting-started<br/>

README.md

@@ -1,7 +1,58 @@
-## AWS App Mesh
+# AWS App Mesh
 
-AWS App Mesh is a service mesh that you can use with your microservices to manage service to service communication.
 
-## License Summary
+## Introduction
 
-This sample code is made available under a modified MIT license. See the LICENSE file.
+App Mesh makes it easy to run microservices by providing consistent visibility and network traffic controls for every microservice in an application. App Mesh separates the logic needed for monitoring and controlling communications into a proxy that runs next to every microservice. App Mesh removes the need to coordinate across teams or update application code to change how monitoring data is collected or traffic is routed. This allows you to quickly pinpoint the exact location of errors and automatically re-route network traffic when there are failures or when code changes need to be deployed.
+
+You can use App Mesh with AWS Fargate, Amazon ECS, Amazon EKS, and Kubernetes on EC2 to better run containerized microservices at scale. App Mesh uses [Envoy](https://www.envoyproxy.io/), an open source proxy, making it compatible with a wide range of AWS partner and open source tools for monitoring microservices.
+
+Learn more at https://aws.amazon.com/app-mesh
+
+### Why use  App Mesh?
+
+1. Streamline operations by offloading communication management logic from application code and libraries into configurable infrastructure.
+2. Reduce troubleshooting time required by having end-to-end visibility into service-level logs, metrics and traces across your application.
+3. Easily roll out of new code by configuring routes to new application versions.
+4. Ensure high-availability with custom routing rules that help ensure every service is highly available during deployments, after failures, and as your application scales.
+5. Manage all service to service traffic using one set of APIs regardless of how the services are implemented.
+
+### What makes AWS App Mesh unique?
+
+App Mesh is built in direct response to our customers needs implementing a 'service mesh' for their applications. Our customers asked us to: 
+
+* Make it easy to manage microservices deployed across accounts, clusters, container orchestration tools, and compute services with simple and consistent abstractions.
+* Minimize the cognitive and operational overhead in running a microservices application and handling its monitoring and traffic control. 
+* Remove the need to build or operate a control plane for service mesh.
+* Use open source software to allow extension to new tools and different use cases.
+
+In order to best meet the needs of our customers, we have invested into building a service that includes a control plane and API that follows the AWS best practices. Specifically, App Mesh: 
+
+* Is an AWS managed service that works across container services with a design that allows us to add support for other computer services in the future.
+* Works with open source Envoy proxy, and over time support most of its capabilities
+* Is designed to pluggable and can support bringing your own Envoy and Istio Mixer in the future.
+* Implemented as a multi-tenant control plane to be scalable, robust, cost-effective, and efficient.
+* Built to work independently of any particular container orchestration system. Today, App Mesh works with both Kubernetes and Amazon ECS.
+
+## Availability
+
+### App Mesh is in Preview
+
+Today, AWS App Mesh is available in preview. During the preview we will add new features, improve the user and operational experience, and incorporate the feedback you give us. We will actively share how you can use App Mesh, what you can use it for, and provide example applications to help you get started. We have a big vision and aggressive roadmap to support all your use cases and we want your input to tell us what makes sense and what we may have missed. We expect App Mesh to be generally available in late Q1 2019.
+
+Today, you can use AWS App Mesh with services running on Amazon ECS (with awsvpc networking mode) or Amazon EKS. You can:
+
+- connect applications using API, 
+- Bootstrap Envoy and connect to XDS endpoint provided by App Mesh.
+- Configure routes
+
+### Roadmap
+
+Here is what we are working on between preview and GA [GA Roadmap](https://github.com/awslabs/aws-app-mesh/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3A%22pre-GA%20Roadmap%22) and [post-GA Roadmap](https://github.com/awslabs/aws-app-mesh/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3A%22post-GA%20Roadmap%22)
+
+Here are some [FAQs about Preview](FAQ.md)
+
+### Questions?
+
+- About Features/Use cases: (https://github.com/awslabs/aws-app-mesh/issues)**About Usage clarifications/ - Issues: (https://github.com/awslabs/aws-app-mesh/issues)
+- Other discussion: [Get invited to #containers on AWS Developers [Slack Channel](awsdevelopers.slack.com)