From c56850fdb5325f0bf385f59bd4a715151bf295c2 Mon Sep 17 00:00:00 2001 From: stefanprodan Date: Thu, 27 Feb 2020 10:37:48 +0200 Subject: [PATCH] Add dev guides section to docs --- docs/gitbook/README.md | 13 +++++++--- docs/gitbook/SUMMARY.md | 5 +++- docs/gitbook/{ => dev}/dev-guide.md | 17 +------------ docs/gitbook/dev/release-guide.md | 34 ++++++++++++++++++++++++++ docs/gitbook/how-it-works.md | 37 +++++++++++++++++++++++++---- 5 files changed, 82 insertions(+), 24 deletions(-) rename docs/gitbook/{ => dev}/dev-guide.md (85%) create mode 100644 docs/gitbook/dev/release-guide.md diff --git a/docs/gitbook/README.md b/docs/gitbook/README.md index 1aaf6b91c..5d8e60df6 100644 --- 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 index 6c50a1b8d..d51ea045a 100644 --- 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) \ No newline at end of file diff --git a/docs/gitbook/dev-guide.md b/docs/gitbook/dev/dev-guide.md similarity index 85% rename from docs/gitbook/dev-guide.md rename to docs/gitbook/dev/dev-guide.md index c082df0aa..43a004f7a 100644 --- a/docs/gitbook/dev-guide.md +++ b/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 new file mode 100644 index 000000000..2140f60a7 --- /dev/null +++ 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 index 4cdda8e09..9defb689d 100644 --- 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. -