Merge pull request #68 from nckturner/logos

Add logo

README.md

@@ -1,10 +1,14 @@
+<p align="center">
+    <img src="docs/product-icon_AWS_App_Mesh_icon_squid_ink.svg" alt="App Mesh Logo" width="200" />
+</p>
+
 ## AWS App Mesh Controller For K8s
 
-AWS App Mesh Controller For K8s is a controller to help manage AppMesh resources for a Kubernetes cluster.  The controller watches custom resources for changes and reflects those changes into the App Mesh API. It is accompanied by the deployment of three custom resource definitions ([CRDs](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/)): meshes, virtualnodes, and virtualservices.  These map to App Mesh API objects which the controller manages for you. 
+AWS App Mesh Controller For K8s is a controller to help manage [App Mesh](https://aws.amazon.com/app-mesh/) resources for a Kubernetes cluster.  The controller watches custom resources for changes and reflects those changes into the [App Mesh API](https://docs.aws.amazon.com/app-mesh/latest/APIReference/Welcome.html). It is accompanied by the deployment of three custom resource definitions ([CRDs](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/)): meshes, virtualnodes, and virtualservices.  These map to App Mesh API objects which the controller manages for you.
 
 ## Getting started
 
-Check out the [example](docs/example.md) application, and read the [design](docs/design.md).
+Check out the [example](docs/example.md) application, and read [design and usage](docs/design.md).
 
 To begin using it in your cluster, follow the [install instructions](docs/install.md).
 
@@ -55,7 +59,7 @@ First, create a Mesh resource, which will trigger the controller to create a Mes
               prefix: /
             action:
               weightedTargets:
-                - virtualNodeName: 
+                - virtualNodeName:
                   weight: 1
 
 
@@ -73,4 +77,4 @@ Contributions welcome!  Please read our [guidelines](CONTRIBUTING.md) and [Code
 
 ## License
 
-This library is licensed under the Apache 2.0 License. 
+This library is licensed under the Apache 2.0 License.

docs/design.md

@@ -1,3 +1,5 @@
+# Design and Usage
+
 ## Background
 
 App Mesh is an AWS service that provides an envoy based service mesh in which an envoy proxy (https://github.com/envoyproxy/envoy) is deployed alongside a user's applications, and facilitates communication between them, whether they are deployed in EKS, ECS, EC2, or any combination thereof.
@@ -8,7 +10,7 @@ In AWS App Mesh, the envoy proxies receive their configuration from the App Mesh
 
 ### Mesh
 
-A Mesh is a collection of App Mesh resources, and should include any resources for services that should communicate with one another, whether they run on EC2, ECS, or EKS.  
+A Mesh is a collection of App Mesh resources, and should include any resources for services that should communicate with one another, whether they run on EC2, ECS, or EKS.
 
 ### Virtual Service
 
@@ -20,28 +22,29 @@ A virtual router encapsulates the routing logic for a virtual service.  The virt
 
 ### Virtual Node
 
-A virtual node represents a node in the mesh when viewed as a graph, where each node in the graph is an application instance or collection of instances, where the instance might be a client and/or a server, and each edge in the graph is a communication pathway between them.  Each envoy proxy is a member of a single virtual node, which must be defined on startup.  Multiple envoys can be (and usually are) members of the same virtual node.  This determines what set of configuration the envoy proxy receives.  Virtual node definitions include backends (the services that the  virtual node wants to talk to), listeners (the ports on which it listens), and service discovery (how other services should find its endpoints).  
+A virtual node represents a node in the mesh when viewed as a graph, where each node in the graph is an application instance or collection of instances, where the instance might be a client and/or a server, and each edge in the graph is a communication pathway between them.  Each envoy proxy is a member of a single virtual node, which must be defined on startup.  Multiple envoys can be (and usually are) members of the same virtual node.  This determines what set of configuration the envoy proxy receives.  Virtual node definitions include backends (the services that the virtual node wants to talk to), listeners (the ports on which it listens), and service discovery (how other services should find its endpoints).
 
 ### Route
 
 A route is a set of rules that determines how HTTP traffic, bound for any of a set of virtual services which are managed by the route's containing virtual router, is directed to any of the virtual nodes that contain the service's endpoints.
 
 ## Design
 
-The primary task of the controller is to watch for creation of and modification to three Custom Resources: `Mesh`, `VirtualNode` and `VirtualService`. First, the Mesh Resource will provide some initial bootstrap configuration and its creation will trigger the creation of the Mesh via the App Mesh API. 
+The primary task of the controller is to watch for creation of and modification to three Custom Resources: `Mesh`, `VirtualNode` and `VirtualService`. First, the Mesh Resource will provide some initial bootstrap configuration and its creation will trigger the creation of the Mesh via the App Mesh API.
 
-When you want to add an application to their service mesh, create a VirtualNode Custom Resource, and the controller will create a corresponding Virtual Node via the App Mesh API.  The Virtual Node contains listener, backend and service discovery configuration for a set of envoys.  
+When you want to add an application to their service mesh, create a VirtualNode Custom Resource, and the controller will create a corresponding Virtual Node via the App Mesh API.  The Virtual Node contains listener, backend and service discovery configuration for a set of envoys.
 
 Next (though order is not enforced), you can create a VirtualService custom resource, which contains route configuration, allowing requests from one application in the mesh to be routed to a number of virtual nodes that make up a service.  In App Mesh, this results in the creation of a virtual service, virtual router, and one or more routes.
 
 It is highly recommended, though not required, to use the controller together with aws-app-mesh-inject, a webhook which performs envoy sidecar injection, to reduce the amount of manual configuration that you have to perform. The webhook will inject the sidecar into any namespace that is labelled with `appmesh.k8s.aws/sidecarInjectorWebhook=enabled`. See the [aws-app-mesh-inject](https://github.com/aws/aws-app-mesh-inject) repository for more details.
 
-Each virtual node currently supports DNS service discovery, although more types will be supported in the future. When DNS service discovery is being used, then the provided hostname must resolve. The easiest way to configure that is to create a [service](https://kubernetes.io/docs/concepts/services-networking/service/) that corresponds to the virtual node.  
+Each virtual node supports two types of service discovery, DNS and Cloud Map. When DNS service discovery is being used, then the provided hostname must resolve. The easiest way to configure that is to create a [service](https://kubernetes.io/docs/concepts/services-networking/service/) that corresponds to the virtual node.
 
 ## Virtual node naming convention
-To support the use case of using the same application as virtual node across namespaces, the controller creates the virtual node name in App Mesh backend by appending the name of the `VirtualNode` custom resource with the namespace. The naming format is "VirtualNodeName-Namespace" 
 
-For example, in the VirtualNode definition below, 
+To support the use case of using the same application as virtual node across namespaces, the controller creates the virtual node name in App Mesh backend by appending the name of the `VirtualNode` custom resource with the namespace. The naming format is "VirtualNodeName-Namespace"
+
+For example, in the VirtualNode definition below,
 ```
 kind: VirtualNode
 metadata:
@@ -51,9 +54,9 @@ metadata:
 ```
 the virtual node name created in App Mesh backend will be "colorteller-black-appmesh-demo".
 
-However, if the VirtualNode name in the custom resource contains `.`, i.e. `foo.bar`, the controller will assume namespace is `bar` by kubernetes convention. It will replace all `.` with `-` when creating the App Mesh virtual node because `.` isn't a valid character in App Mesh name.  
+However, if the VirtualNode name in the custom resource contains `.`, i.e. `foo.bar`, the controller will assume namespace is `bar` by kubernetes convention. It will replace all `.` with `-` when creating the App Mesh virtual node because `.` isn't a valid character in App Mesh name.
 
-For example, in the VirtualNode definition below, 
+For example, in the VirtualNode definition below,
 ```
 kind: VirtualNode
 metadata:
@@ -62,9 +65,9 @@ metadata:
 ```
 the virtual node name created in App Mesh backend will be "colorteller-black-appmesh-demo".
 
-Similarly, any references to VirtualNode name in other custom resources follow the same naming convention. 
+Similarly, any references to VirtualNode name in other custom resources follow the same naming convention.
 
-For example, in the example below, 
+For example, in the example below,
 
 ```
 kind: VirtualService
@@ -83,6 +86,39 @@ spec:
         - virtualNodeName: colorteller-black.appmesh-demo
           weight: 3
 ```
-the corresponding virtual node names in the App Mesh backend are, `colorteller-appmesh-demo`, `colorteller-blue-appmesh-demo`, and `colorteller-black-appmesh-demo` respectively. 
+the corresponding virtual node names in the App Mesh backend are, `colorteller-appmesh-demo`, `colorteller-blue-appmesh-demo`, and `colorteller-black-appmesh-demo` respectively.
+
+Check out the [example](docs/example.md) application for more details.
+
+## Cloud Map Service Discovery
+
+Cloud Map service discovery can be used in place of DNS. See this [App Mesh road map item](https://github.com/aws/aws-app-mesh-roadmap/issues/47).  In order to use it, you must specify the service discovery type as "cloudMap" in your virtual node definition.  For example,
+
+```
+apiVersion: appmesh.k8s.aws/v1beta1
+kind: VirtualNode
+metadata:
+  name: colorgateway
+  namespace: appmesh-demo
+spec:
+  meshName: color-mesh
+  listeners:
+    - portMapping:
+        port: 9080
+        protocol: http
+  serviceDiscovery:
+    cloudMap:
+      namespaceName: color-mesh-dns
+      serviceName: colorteller-red
+  backends:
+    - virtualService:
+        virtualServiceName: colorteller.appmesh-demo
+    - virtualService:
+        virtualServiceName: tcpecho.appmesh-demo
+  logging:
+    accessLog:
+      file:
+        path: /dev/stdout
+```
 
-Check out the [example](docs/example.md) application for more details. 
+The App Mesh controller will look for a Cloud Map namespace and service corresponding to the configuration in your virtual node.  The controller expects a namespace to preexist, but it will create a Cloud Map service if it needs to.  The controller watches for pod creates, and registers the endpoints (using [RegisterInstance](https://docs.aws.amazon.com/cloud-map/latest/api/API_RegisterInstance.html)) with the Cloud Map API.  If a pod belongs to a virtual node that uses Cloud Map service discovery, then that pod will be registered accordingly.