From 9bf52f96681a3f6feabb62ac569f485e106f8d9f Mon Sep 17 00:00:00 2001
From: Stefan Prodan <stefan.prodan@gmail.com>
Date: Mon, 24 Sep 2018 19:58:18 +0300
Subject: [PATCH] Add intro

---
 README.md | 55 ++++++++++++++++++++++++++++---------------------------
 1 file changed, 28 insertions(+), 27 deletions(-)

diff --git a/README.md b/README.md
index aee900ed..8d770163 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,30 @@
 # steerer
 
-Istio progressive rollout gated by Prometheus HTTP success rate metric
+Steerer is a Kubernetes operator that automates the promotion of canary deployments
+using Istio routing for traffic shifting and Prometheus metrics for canary analysis.
+
+Gated rollout stages:
+
+* scan for deployments marked for rollout 
+* check Istio virtual service routes are mapped to primary and canary ClusterIP services
+* check primary and canary deployments status
+    * halt rollout if a rolling update is underway
+    * halt rollout if pods are unhealthy
+* increase canary traffic weight percentage by 10%
+* check canary HTTP success rate
+    * halt rollout if percentage is under the specified threshold
+* increase canary traffic wight by 10% till it reaches 100% 
+    * halt rollout while canary success rate is under the threshold
+    * halt rollout if the primary or canary deployment becomes unhealthy 
+    * halt rollout while canary deployment is being scaled up/down by HPA
+* promote canary to primary
+    * copy canary deployment spec template over primary
+* wait for primary rolling update to finish
+    * halt rollout if pods are unhealthy
+* route all traffic to primary
+* scale to zero the canary deployment
+* mark rollout as finished
+* wait for the canary deployment to be updated (revision bump) and start over
 
 ### Usage
 
@@ -13,10 +37,10 @@ kubectl apply -f ./artifacts/steerer
 Create a test namespace:
 
 ```bash
-kubectl apply -f ./artifacts/namespace/
+kubectl apply -f ./artifacts/namespaces/
 ```
 
-Create GA and canary deployments, services, hpa and Istio virtual service:
+Create primary and canary deployments, services, hpa and Istio virtual service:
 
 ```bash
 kubectl apply -f ./artifacts/workloads/
@@ -30,7 +54,7 @@ kubectl apply -f ./artifacts/rollouts/
 
 Rollout output:
 
-```bash
+```
 kubectl -n test describe rollout/podinfo
 
 Events:
@@ -60,29 +84,6 @@ Events:
   Normal   Synced  5s    steerer  Promotion complete! Scaling down podinfo-canary.test
 ```
 
-Rollout flow:
-
-* scan for deployments marked for rollout 
-* check Istio virtual service routes are mapped to primary and canary ClusterIP services
-* check primary and canary deployments status
-    * halt rollout if a rolling update is underway
-    * halt rollout if pods are unhealthy
-* increase canary traffic weight percentage by 10%
-* check canary HTTP success rate
-    * halt rollout if percentage is under the specified threshold
-* increase canary traffic wight by 10% till it reaches 100% 
-    * halt rollout while canary success rate is under the threshold
-    * halt rollout if the primary or canary deployment becomes unhealthy 
-    * halt rollout while canary deployment is being scaled up/down by HPA
-* promote canary to primary
-    * copy canary deployment spec template over primary
-* wait for primary rolling update to finish
-    * halt rollout if pods are unhealthy
-* route all traffic to primary
-* scale to zero the canary deployment
-* mark rollout as finished
-* wait for the canary deployment to be updated (revision bump) and start over
-
 HTTP success rate query:
 
 ```sql