Merge pull request #109 from weaveworks/appmesh-docs

Add EKS App Mesh install docs

CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to this project are documented in this file.
 
+## Unreleased 
+
+Adds support for AWS App Mesh EKS
+
+#### Features
+
+- AWS App Mesh integration [#107](https://github.com/weaveworks/flagger/pull/107)
+
+#### Fixes
+
+- Copy pod labels from canary to primary [#105](https://github.com/weaveworks/flagger/pull/105)
+
 ## 0.9.0 (2019-03-11)
 
 Allows A/B testing scenarios where instead of weighted routing, the traffic is split between the 

README.md

@@ -7,7 +7,7 @@
 [![release](https://img.shields.io/github/release/weaveworks/flagger/all.svg)](https://github.com/weaveworks/flagger/releases)
 
 Flagger is a Kubernetes operator that automates the promotion of canary deployments
-using Istio routing for traffic shifting and Prometheus metrics for canary analysis. 
+using Istio or App Mesh routing for traffic shifting and Prometheus metrics for canary analysis. 
 The canary analysis can be extended with webhooks for running acceptance tests, 
 load tests or any other custom validation.
 
@@ -24,6 +24,7 @@ Flagger documentation can be found at [docs.flagger.app](https://docs.flagger.ap
 * Install
     * [Flagger install on Kubernetes](https://docs.flagger.app/install/flagger-install-on-kubernetes)
     * [Flagger install on GKE](https://docs.flagger.app/install/flagger-install-on-google-cloud)
+    * [Flagger install on EKS App Mesh](https://docs.flagger.app/install/flagger-install-on-eks-appmesh)
 * How it works
     * [Canary custom resource](https://docs.flagger.app/how-it-works#canary-custom-resource)
     * [Routing](https://docs.flagger.app/how-it-works#istio-routing)
@@ -168,7 +169,7 @@ For more details on how the canary analysis and promotion works please [read the
 
 ### Roadmap
 
-* Integrate with other service mesh technologies like AWS AppMesh and Linkerd v2
+* Integrate with other service mesh technologies like Linkerd v2 or Consul Mesh
 * Add support for comparing the canary metrics to the primary ones and do the validation based on the derivation between the two
 
 ### Contributing

charts/flagger/Chart.yaml

@@ -16,4 +16,5 @@ maintainers:
 keywords:
 - canary
 - istio
+- appmesh
 - gitops

charts/flagger/values.yaml

@@ -5,12 +5,12 @@ image:
   tag: 0.9.0
   pullPolicy: IfNotPresent
 
-metricsServer: "http://prometheus.istio-system.svc.cluster.local:9090"
+metricsServer: "http://prometheus:9090"
 
 # accepted values are istio or appmesh (defaults to istio)
 meshProvider: ""
 
-# namespace that flagger will watch for Canary objects
+# single namespace restriction
 namespace: ""
 
 slack:

charts/loadtester/Chart.yaml

@@ -1,6 +1,6 @@
 apiVersion: v1
 name: loadtester
-version: 0.2.0
+version: 0.3.0
 appVersion: 0.2.0
 kubeVersion: ">=1.11.0-0"
 engine: gotpl
@@ -16,5 +16,6 @@ maintainers:
 keywords:
   - canary
   - istio
+  - appmesh
   - gitops
   - load testing

charts/loadtester/templates/virtual-node.yaml

@@ -0,0 +1,27 @@
+{{- if .Values.meshName }}
+apiVersion: appmesh.k8s.aws/v1alpha1
+kind: VirtualNode
+metadata:
+  name: {{ include "loadtester.fullname" . }}
+  labels:
+    app.kubernetes.io/name: {{ include "loadtester.name" . }}
+    helm.sh/chart: {{ include "loadtester.chart" . }}
+    app.kubernetes.io/instance: {{ .Release.Name }}
+    app.kubernetes.io/managed-by: {{ .Release.Service }}
+spec:
+  meshName: {{ .Values.meshName }}
+  listeners:
+    - portMapping:
+        port: 80
+        protocol: http
+  serviceDiscovery:
+    dns:
+      hostName: {{ include "loadtester.fullname" . }}.{{ .Release.Namespace }}
+  {{- if .Values.backends }}
+  backends:
+    {{- range .Values.backends }}
+    - virtualService:
+        virtualServiceName: {{ . }}
+    {{- end }}
+  {{- end }}
+{{- end }}

charts/loadtester/values.yaml

@@ -26,3 +26,9 @@ nodeSelector: {}
 tolerations: []
 
 affinity: {}
+
+# App Mesh virtual node settings
+meshName: ""
+#backends:
+#  - app1.namespace
+#  - app2.namespace

docs/gitbook/README.md

@@ -5,7 +5,7 @@ description: Flagger is an Istio progressive delivery Kubernetes operator
 # Introduction
 
 [Flagger](https://github.com/weaveworks/flagger) is a **Kubernetes** operator that automates the promotion of canary 
-deployments using **Istio** routing for traffic shifting and **Prometheus** metrics for canary analysis.
+deployments using **Istio** or **App Mesh** routing for traffic shifting and **Prometheus** metrics for canary analysis.
 The canary analysis can be extended with webhooks for running 
 system integration/acceptance tests, load tests, or any other custom validation.
 

docs/gitbook/SUMMARY.md

@@ -6,7 +6,8 @@
 ## Install
 
 * [Flagger Install on Kubernetes](install/flagger-install-on-kubernetes.md)
-* [Flagger Install on Google Cloud](install/flagger-install-on-google-cloud.md)
+* [Flagger Install on GKE Istio](install/flagger-install-on-google-cloud.md)
+* [Flagger Install on EKS App Mesh](install/flagger-install-on-eks-appmesh.md)
 
 ## Usage
 

docs/gitbook/install/flagger-install-on-eks-appmesh.md

@@ -0,0 +1,218 @@
+# Flagger install on AWS
+
+This guide walks you through setting up Flagger and AWS App Mesh on EKS.
+
+### App Mesh
+
+The App Mesh integration with EKS is made out of the following components:
+
+* Kubernetes custom resources
+    * `mesh.appmesh.k8s.aws` defines a logical boundary for network traffic between the services 
+    * `virtualnode.appmesh.k8s.aws` defines a logical pointer to a Kubernetes workload
+    * `virtualservice.appmesh.k8s.aws` defines the routing rules for a workload inside the mesh
+* CRD controller - keeps the custom resources in sync with the App Mesh control plane
+* Admission controller - injects the Envoy sidecar and assigns Kubernetes pods to App Mesh virtual nodes
+* Metrics server - Prometheus instance that collects and stores Envoy's metrics
+
+Prerequisites:
+
+* homebrew
+* openssl
+* kubectl
+* AWS CLI (default region us-west-2)
+
+### Create a Kubernetes cluster
+
+In order to create an EKS cluster you can use [eksctl](https://eksctl.io).
+Eksctl is an open source command-line utility made by Weaveworks in collaboration with Amazon, 
+it's written in Go and is based on EKS CloudFormation templates.
+
+On MacOS you can install eksctl with Homebrew:
+
+```bash
+brew tap weaveworks/tap
+brew install weaveworks/tap/eksctl
+```
+
+Create an EKS cluster:
+
+```bash
+eksctl create cluster --name=appmesh \
+--region=us-west-2 \
+--appmesh-access
+```
+
+The above command will create a two nodes cluster with App Mesh
+[IAM policy](https://docs.aws.amazon.com/app-mesh/latest/userguide/MESH_IAM_user_policies.html)
+attached to the EKS node instance role.
+
+Verify the install with:
+
+```bash
+kubectl get nodes
+```
+
+### Install Helm
+
+Install the [Helm](https://docs.helm.sh/using_helm/#installing-helm) command-line tool:
+
+```text
+brew install kubernetes-helm
+```
+
+Create a service account and a cluster role binding for Tiller:
+
+```bash
+kubectl -n kube-system create sa tiller
+
+kubectl create clusterrolebinding tiller-cluster-rule \
+--clusterrole=cluster-admin \
+--serviceaccount=kube-system:tiller 
+```
+
+Deploy Tiller in the `kube-system` namespace:
+
+```bash
+helm init --service-account tiller
+```
+
+You should consider using SSL between Helm and Tiller, for more information on securing your Helm 
+installation see [docs.helm.sh](https://docs.helm.sh/using_helm/#securing-your-helm-installation).
+
+### Enable horizontal pod auto-scaling
+
+Install the Horizontal Pod Autoscaler (HPA) metrics provider:
+
+```bash
+helm upgrade -i metrics-server stable/metrics-server \
+--namespace kube-system
+```
+
+After a minute, the metrics API should report CPU and memory usage for pods.
+You can very the metrics API with:
+
+```bash
+kubectl -n kube-system top pods
+```
+
+### Install the App Mesh components
+
+Clone the config repo:
+
+```bash
+git clone https://github.com/stefanprodan/appmesh-eks
+cd appmesh-eks
+```
+
+Create the `appmesh-system` namespace:
+
+```bash
+kubectl apply -f /namespaces/appmesh-system.yaml
+```
+
+Deploy the App Mesh Kubernetes CRDs and controller:
+
+```bash
+kubectl apply -f ./operator/
+```
+
+Install the App Mesh sidecar injector in the `appmesh-system` namespace:
+
+```bash
+./injector/install.sh
+```
+
+The above script generates a certificate signed by Kubernetes CA,
+registers the App Mesh mutating webhook and deploys the injector.
+
+Deploy Prometheus in the `appmesh-system` namespace:
+
+```bash
+kubectl apply -f ./prometheus
+```
+
+Create a mesh called global in the `appmesh-system` namespace:
+
+```bash
+kubectl apply -f ./appmesh/global.yaml
+```
+
+Verify that the global mesh is active:
+
+```bash
+kubectl -n appmesh-system describe mesh
+
+Status:
+  Mesh Condition:
+    Status:                True
+    Type:                  Active
+```
+
+### Install Flagger and Grafana
+
+Add Flagger Helm repository:
+
+```bash
+helm repo add flagger https://flagger.app
+```
+
+Deploy Flagger in the _**appmesh-system**_ namespace:
+
+```bash
+helm upgrade -i flagger flagger/flagger \
+--namespace=appmesh-system \
+--set meshProvider=appmesh \
+--set metricsServer=http://prometheus.appmesh:9090
+```
+
+You can install Flagger in any namespace as long as it can talk to the Istio Prometheus service on port 9090.
+
+You can enable **Slack** notifications with:
+
+```bash
+helm upgrade -i flagger flagger/flagger \
+--namespace=appmesh-system \
+--set meshProvider=appmesh \
+--set metricsServer=http://prometheus.appmesh:9090 \
+--set slack.url=https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK \
+--set slack.channel=general \
+--set slack.user=flagger
+```
+
+Flagger comes with a Grafana dashboard made for monitoring the canary analysis.
+Deploy Grafana in the _**appmesh-system**_ namespace:
+
+```bash
+helm upgrade -i flagger-grafana flagger/grafana \
+--namespace=appmesh-system \
+--set url=http://prometheus.appmesh-system:9090 \
+--set user=admin \
+--set password=change-me
+```
+
+You can access Grafana using port forwarding:
+
+```bash
+kubectl -n appmesh-system port-forward svc/flagger-grafana 3000:3000
+```
+
+###  Install the load tester
+
+Flagger comes with an optional load testing service that generates traffic 
+during canary analysis when configured as a webhook.
+
+Create a test namespace with sidecar injector enabled:
+
+```bash
+kubectl apply -f ./namespaces/test.yaml
+```
+
+Deploy the load test runner with Helm:
+
+```bash
+helm upgrade -i flagger-loadtester flagger/loadtester \
+--namespace=test \
+--set meshName=global.appmesh-system \
+--set backends[0]=frontend.test \
+--set backends[1]=backend.test
+```