Add dev guides section to docs

fluxcd · Feb 28, 2020 · e4da4a3 · e4da4a3
1 parent 2837d44
commit e4da4a3
Show file tree

Hide file tree

Showing 5 changed files with 82 additions and 24 deletions.
diff --git a/docs/gitbook/README.md b/docs/gitbook/README.md
@@ -4,13 +4,20 @@ description: Flagger is a progressive delivery Kubernetes operator
 
 # Introduction
 
-[Flagger](https://github.com/weaveworks/flagger) is a **Kubernetes** operator that automates the promotion of canary deployments using **Istio**, **Linkerd**, **App Mesh**, **NGINX**, **Contour** or **Gloo** 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.
+[Flagger](https://github.com/weaveworks/flagger) is a **Kubernetes** operator that automates the promotion of
+canary deployments using **Istio**, **Linkerd**, **App Mesh**, **NGINX**, **Contour** or **Gloo** 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.
 
-Flagger implements a control loop that gradually shifts traffic to the canary while measuring key performance indicators like HTTP requests success rate, requests average duration and pods health. Based on analysis of the **KPIs** a canary is promoted or aborted, and the analysis result is published to **Slack** or **MS Teams**.
+Flagger implements a control loop that gradually shifts traffic to the canary while measuring key performance indicators
+like HTTP requests success rate, requests average duration and pods health.
+Based on analysis of the **KPIs** a canary is promoted or aborted, and the analysis result is published to **Slack** or **MS Teams**.
 
 ![Flagger overview diagram](https://raw.githubusercontent.com/weaveworks/flagger/master/docs/diagrams/flagger-canary-overview.png)
 
-Flagger can be configured with Kubernetes custom resources and is compatible with any CI/CD solutions made for Kubernetes. Since Flagger is declarative and reacts to Kubernetes events, it can be used in **GitOps** pipelines together with Flux CD or JenkinsX.
+Flagger can be configured with Kubernetes custom resources and is compatible with any CI/CD solutions made for Kubernetes.
+Since Flagger is declarative and reacts to Kubernetes events,
+it can be used in **GitOps** pipelines together with Flux CD or JenkinsX.
 
 This project is sponsored by [Weaveworks](https://www.weave.works/)
 
diff --git a/docs/gitbook/SUMMARY.md b/docs/gitbook/SUMMARY.md
@@ -3,7 +3,6 @@
 * [Introduction](README.md)
 * [How it works](how-it-works.md)
 * [FAQ](faq.md)
-* [Development guide](dev-guide.md)
 
 ## Install
 
@@ -35,3 +34,7 @@
 * [Canaries with Helm charts and GitOps](tutorials/canary-helm-gitops.md)
 * [Zero downtime deployments](tutorials/zero-downtime-deployments.md)
 
+## Dev
+
+* [Development Guide](dev/dev-guide.md)
+* [Release Guide](dev/release-guide.md)
diff --git a/docs/gitbook/dev-guide.md → docs/gitbook/dev/dev-guide.md b/docs/gitbook/dev-guide.md → docs/gitbook/dev/dev-guide.md
@@ -1,4 +1,4 @@
-# Flagger Development Guide
+# Development Guide
 
 This document describes how to build, test and run Flagger from source.
 
@@ -177,18 +177,3 @@ chose one that matches your changes from this [list](https://github.com/weavewor
 
 When you open a pull request on Flagger repo, the unit and integration tests will be run in CI.
 
-### Release
-
-To release a new Flagger version (e.g. `2.0.0`) follow these steps:
-* create a branch `git checkout -b prep-2.0.0`
-* set the version in code and manifests `TAG=2.0.0 make version-set`
-* commit changes and merge PR
-* checkout master `git checkout master && git pull`
-* tag master `make release`
-
-After the tag has been pushed to GitHub, the CI release pipeline does the following:
-* creates a GitHub release
-* pushes the Flagger binary and change log to GitHub release
-* pushes the Flagger container image to Docker Hub
-* pushes the Helm chart to github-pages branch
-* GitHub pages publishes the new chart version on the Helm repository
diff --git a/docs/gitbook/dev/release-guide.md b/docs/gitbook/dev/release-guide.md
@@ -0,0 +1,34 @@
+# Flagger Release Guide
+
+This document describes how to release Flagger.
+
+### Release
+
+To release a new Flagger version (e.g. `2.0.0`) follow these steps:
+* create a branch `git checkout -b prep-2.0.0`
+* set the version in code and manifests `TAG=2.0.0 make version-set`
+* commit changes and merge PR
+* checkout master `git checkout master && git pull`
+* tag master `make release`
+
+### CI
+
+After the tag has been pushed to GitHub, the CI release pipeline does the following:
+* creates a GitHub release
+* pushes the Flagger binary and change log to GitHub release
+* pushes the Flagger container image to Docker Hub
+* pushes the Helm chart to github-pages branch
+* GitHub pages publishes the new chart version on the Helm repository
+
+### Docs
+
+The documentation [website](https://docs.flagger.app) is built from the `docs` branch.
+
+After a Flagger release, publish the docs with:
+* `git checkout master && git pull`
+* `git checkout docs`
+* `git rebase master`
+* `git push origin docs`
+
+
+
diff --git a/docs/gitbook/how-it-works.md b/docs/gitbook/how-it-works.md
@@ -5,9 +5,12 @@ a horizontal pod autoscaler (HPA) and creates a series of objects
 (Kubernetes deployments, ClusterIP services, virtual service, traffic split or ingress)
 to drive the canary analysis and promotion.
 
-### Canary Custom Resource
+### Canary custom resource
 
-For a deployment named _podinfo_, a canary can be defined using Flagger's custom resource:
+The canary custom resource defines the release process of an application running on Kubernetes
+and is portable across clusters, service meshes and ingress providers.
+
+For a deployment named _podinfo_, a canary release with progressive traffic shifting can be defined as:
 
 ```yaml
 apiVersion: flagger.app/v1alpha3
@@ -40,6 +43,11 @@ spec:
           cmd: "hey -z 1m -q 10 -c 2 http://podinfo-canary.test:9898/"
 ```
 
+When you deploy a new version of an app, Flagger gradually shifts traffic to the canary,
+and at the same time, measures the requests success rate as well as the average response duration.
+You can extend the canary analysis with custom metrics, acceptance and load testing
+to harden the validation process of your app release process.
+
 ### Canary target
 
 A canary resource can target a Kubernetes Deployment or DaemonSet.
@@ -139,6 +147,28 @@ This ensures that traffic to `podinfo.test:9898` will be routed to the latest st
 The `podinfo-canary.test:9898` address is available only during the 
 canary analysis and can be used for conformance testing or load testing.
 
+Besides the port mapping, the service specification can contain URI match and rewrite rules,
+timeout and retry polices:
+
+```yaml
+spec:
+  service:
+    port: 9898
+    match:
+      - uri:
+          prefix: /
+    rewrite:
+      uri: /
+    retries:
+      attempts: 3
+      perTryTimeout: 1s
+    timeout: 5s
+```
+
+When using **Istio** as the mesh provider, you can also specify
+HTTP header operations, CORS and traffic policies, Istio gateways and hosts.
+The Istio routing configuration can be found [here](faq.md#istio-routing).
+
 ### Canary status
 
 You can use kubectl to get the current status of canary deployments cluster wide: 
@@ -207,7 +237,7 @@ kubectl wait canary/podinfo --for=condition=promoted --timeout=5m
 kubectl get canary/podinfo | grep Succeeded
 ```
 
-### Canary Analysis
+### Canary analysis
 
 The canary analysis defines:
 * the type of [deployment strategy](usage/deployment-strategies.md)
@@ -250,4 +280,3 @@ Spec:
 The canary analysis runs periodically until it reaches the maximum traffic weight or the number of iterations.
 On each run, Flagger calls the webhooks, checks the metrics and if the failed checks threshold is reached, stops the
 analysis and rolls back the canary. If alerting is configured, Flagger will post the analysis result using the alert providers.
-