From 29dbae373d65af5cf6c375c200c7ebb174115a16 Mon Sep 17 00:00:00 2001 From: Daniel Holbach Date: Fri, 18 Jan 2019 14:49:58 +0530 Subject: [PATCH 1/4] add tutorial which discusses automation, annotations, locks closes: #1309 Signed-off-by: Daniel Holbach --- README.md | 1 + site/annotations-tutorial.md | 146 +++++++++++++++++++++++++++++++++++ site/get-started.md | 7 +- 3 files changed, 151 insertions(+), 3 deletions(-) create mode 100644 site/annotations-tutorial.md diff --git a/README.md b/README.md index b896e16de..1b34666a7 100644 --- a/README.md +++ b/README.md @@ -82,6 +82,7 @@ Get started by browsing through the documentation below: - Get Started with Flux - [Standalone Flux](/site/get-started.md) - [Flux using Helm](/site/helm-get-started.md) + - [Automation: annotations and locks](/site/annotations-tutorial.md) - Operating Flux - [Using fluxctl to control Flux](/site/fluxctl.md) - [Helm Operator](/site/helm-operator.md) diff --git a/site/annotations-tutorial.md b/site/annotations-tutorial.md new file mode 100644 index 000000000..4b81f82f0 --- /dev/null +++ b/site/annotations-tutorial.md @@ -0,0 +1,146 @@ +# Driving Weave Flux - automations, locks and annotations + +In this tutorial we want to get a better feel for what we can do with Weave +Flux. We won't spend too much time with getting it up and running, so let's +get that out of the way first. + +## Setup + +Get the source code of Weave Flux: + +```sh +git clone https://github.com/weaveworks/flux +cd flux +``` + +To get a deployment up and running, it's easiest if you head to [our example +deployment](https://github.com/weaveworks/flux-get-started) we set up. Please +head to its site on Github and click on the "Fork" button. + +In the next step, let's change the Git URL of Flux to point to our fork: + +```sh +EDITOR deploy/flux-deployment.yaml +``` + +And update the following line + +```yaml + --git-url=git@github.com:weaveworks/flux-get-started +``` + +to point to your fork, e.g. if your Github Login is `baloothebear`, the line +above should be + +```yaml + --git-url=git@github.com:baloothebear/flux-get-started +``` + +Save the file. For our simple case, that's all the configuration we need. Now +it's time to deploy Flux. Simply run + +```sh +kubectl apply -f deploy +``` + +The first step is done. Flux is now and up running (you can confirm by +running `kubectl get pods --all-namespaces`). + +In the second step we will use fluxctl to talk to Flux in the cluster and +interact with the deployments. First, please [install fluxctl](https://github.com/weaveworks/flux/blob/master/site/fluxctl.md#installing-fluxctl). +(It enables you to drive all of Weave Flux, so have a look at the output of +`fluxctl -h` to get a better idea.) + +To enable Weave Flux to sync your config, you need to add the deployment key +to your fork. + +Get your Flux deployment key by running + +```sh +fluxctl identity +``` + +Copy/paste the key and add it to +`https://github.com/YOUR-USER-ID/flux-get-started/settings/keys/new` and +enable write access for it. + +Wait for sync to happen or run + +```sh +fluxctl sync +``` + +## Driving Weave Flux + +After syncing, Weave Flux will find out which workloads there are, which +images are available and what needs doing. To find out which workloads are +managed by Weave Flux, run + +```sh +fluxctl list-workloads -a +``` + +Notice that `podinfo` is on `v1.3.2` and in state `automated`. + +To check which images are avaible for podinfo run + +```sh +fluxctl list-images -c demo:deployment/podinfo +``` + +Now let's change the policy for `podinfo` to target `1.4.*` releases: + +```sh +fluxctl policy -c demo:deployment/podinfo --tag-all='1.4.*' +``` + +If you now go back to `https://github.com/YOUR-USER-ID/flux-get-started` in +your browser, you will notice that Weave Flux has made a commit on your +behalf. The policy change is now in Git, which is great for transparency and +for defining expected state. + +If you have a closer look at the last change which was committed, you'll see +that the image filtering pattern has been changed. (Our docs explain how to +use semver, glob, regex filtering.) + +Again, wait for the sync to happen or run + +```sh +fluxctl sync +``` + +To check which image is current, run + +```sh +fluxctl list-images -c demo:deployment/podinfo +``` + +In our case this is `1.4.2` (it could be a later image too). Let's say an +engineer found that `1.4.2` was faulty and we have to go back to `1.4.1`. +That's easy. + +Rollback to `1.4.1`: + +```sh +fluxctl release -c demo:deployment/podinfo -i stefanprodan/podinfo:1.4.1 +``` + +Lock to `1.4.1` with a message describing why: + +```sh +fluxctl lock -c demo:deployment/podinfo -m "1.4.2 does not work for us" +``` + +And that's it. At the end of this tutorial, you have automated, locked and +annotated deployments with Weave Flux. + +Another tip, if you should get stuck anywhere: check what Flux is doing. You +can do that by simply running + +```sh +kubectl logs -n default deploy/flux -f +``` + +If you should have any questions, find us on Slack in the [#flux +channel](https://weave-community.slack.com/messages/flux/), get +an invite to it [here](https://slack.weave.works/). \ No newline at end of file diff --git a/site/get-started.md b/site/get-started.md index 15c223704..9ec9faec5 100644 --- a/site/get-started.md +++ b/site/get-started.md @@ -141,6 +141,7 @@ As you can see, the actual steps to set up Flux, get our app deployed, give Flux access to it and see modifications land are very straight-forward and are a quite natural work-flow. -As a next step, you might want to dive deeper into [how to control -Flux](./fluxctl.md) or check out [more sophisticated -setups](./standalone-setup.md). +As a next step, you might want to dive deeper into [how to +control Flux](./fluxctl.md), check out [more sophisticated +setups](./standalone-setup.md) or go through our hands-on +tutorial about driving Flux, e.g. [automations, annotations and locks](annotations-tutorial.md). \ No newline at end of file From 2bd2daea8c98eaa39398d03eb2064673bcf94cb3 Mon Sep 17 00:00:00 2001 From: Daniel Holbach Date: Fri, 18 Jan 2019 17:10:57 +0530 Subject: [PATCH 2/4] refer to tutorial in helm-get-started too Signed-off-by: Daniel Holbach --- site/annotations-tutorial.md | 60 +++++++++++++++++++++++++++++++++--- site/helm-get-started.md | 5 +-- 2 files changed, 58 insertions(+), 7 deletions(-) diff --git a/site/annotations-tutorial.md b/site/annotations-tutorial.md index 4b81f82f0..08dc77398 100644 --- a/site/annotations-tutorial.md +++ b/site/annotations-tutorial.md @@ -4,6 +4,11 @@ In this tutorial we want to get a better feel for what we can do with Weave Flux. We won't spend too much time with getting it up and running, so let's get that out of the way first. +In our example we are going to use the `flux-get-started` example deployment. +So as your first step, please head to [our example +deployment](https://github.com/weaveworks/flux-get-started) and click on the +"Fork" button. + ## Setup Get the source code of Weave Flux: @@ -13,11 +18,7 @@ git clone https://github.com/weaveworks/flux cd flux ``` -To get a deployment up and running, it's easiest if you head to [our example -deployment](https://github.com/weaveworks/flux-get-started) we set up. Please -head to its site on Github and click on the "Fork" button. - -In the next step, let's change the Git URL of Flux to point to our fork: +In the next step, let's change the Git URL of Flux to point to our fork: ```sh EDITOR deploy/flux-deployment.yaml @@ -43,6 +44,55 @@ it's time to deploy Flux. Simply run kubectl apply -f deploy ``` +### Alternative: Using Helm for the setup + +If you have never used Helm, you first need to + +- Download/install Helm +- Set up Tiller. First create a service account and a cluster role binding + for Tiller: + + ```sh + 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: + + ```sh + helm init --skip-refresh --upgrade --service-account tiller + ``` + +Now you can take care of the actual installation. First add the Flux +repository of Weaveworks: + +```sh +helm repo add weaveworks https://weaveworks.github.io/flux +``` + +Apply the Helm Release CRD: + +```sh +kubectl apply -f https://raw.githubusercontent.com/weaveworks/flux/master/deploy-helm/flux-helm-release-crd.yaml +``` + +Install Weave Flux and its Helm Operator by specifying your fork URL. Just +make sure you replace `YOURUSER` with your GitHub username in the command +below: + +```sh +helm upgrade -i flux \ +--set helmOperator.create=true \ +--set helmOperator.createCRD=false \ +--set git.url=git@github.com:YOURUSER/flux-get-started \ +--namespace default \ +weaveworks/flux +``` + +### Connecting to your git config + The first step is done. Flux is now and up running (you can confirm by running `kubectl get pods --all-namespaces`). diff --git a/site/helm-get-started.md b/site/helm-get-started.md index 2b2bf7927..d3208cc44 100644 --- a/site/helm-get-started.md +++ b/site/helm-get-started.md @@ -192,7 +192,8 @@ very straight-forward and are a quite natural workflow. # Next As a next step, you might want to dive deeper into [how to control -Flux](fluxctl.md). +Flux](fluxctl.md) or go through our hands-on tutorial about driving Flux, +e.g. [automations, annotations and locks](annotations-tutorial.md). For a more advanced Helm setup, take a look at the [gitops-helm -repository](https://github.com/stefanprodan/gitops-helm). +repository](https://github.com/stefanprodan/gitops-helm). \ No newline at end of file From 47398b3563f3594243658784d86c27ffd7d1458d Mon Sep 17 00:00:00 2001 From: Daniel Holbach Date: Mon, 21 Jan 2019 13:35:40 +0530 Subject: [PATCH 3/4] incorporate Stefan's feedback: show generated yaml diff --- site/annotations-tutorial.md | 75 +++++++++++++++++++++++++++++++++++- 1 file changed, 74 insertions(+), 1 deletion(-) diff --git a/site/annotations-tutorial.md b/site/annotations-tutorial.md index 08dc77398..1b2716fed 100644 --- a/site/annotations-tutorial.md +++ b/site/annotations-tutorial.md @@ -101,6 +101,10 @@ interact with the deployments. First, please [install fluxctl](https://github.co (It enables you to drive all of Weave Flux, so have a look at the output of `fluxctl -h` to get a better idea.) +> **Note:** Another option (without installing `fluxctl` is to take a look +at the resulting annotation changes and make the changes in Git. This is +GitOps after all. :-) + To enable Weave Flux to sync your config, you need to add the deployment key to your fork. @@ -144,14 +148,40 @@ Now let's change the policy for `podinfo` to target `1.4.*` releases: fluxctl policy -c demo:deployment/podinfo --tag-all='1.4.*' ``` +On the command-line you should see a message just like this one: + +```sh +CONTROLLER STATUS UPDATES +demo:deployment/podinfo success +Commit pushed: 4755a3b +``` + If you now go back to `https://github.com/YOUR-USER-ID/flux-get-started` in your browser, you will notice that Weave Flux has made a commit on your behalf. The policy change is now in Git, which is great for transparency and for defining expected state. +It should look a little something like this: + +```diff +--- a/workloads/podinfo-dep.yaml ++++ b/workloads/podinfo-dep.yaml +@@ -8,8 +8,8 @@ metadata: + app: podinfo + annotations: + flux.weave.works/automated: "true" +- flux.weave.works/tag.init: regexp:^3.* +- flux.weave.works/tag.podinfod: semver:~1.3 ++ flux.weave.works/tag.init: glob:1.4.* ++ flux.weave.works/tag.podinfod: glob:1.4.* + spec: + strategy: + rollingUpdate: +``` + If you have a closer look at the last change which was committed, you'll see that the image filtering pattern has been changed. (Our docs explain how to -use semver, glob, regex filtering.) +use `semver`, `glob`, `regex` filtering.) Again, wait for the sync to happen or run @@ -175,12 +205,55 @@ Rollback to `1.4.1`: fluxctl release -c demo:deployment/podinfo -i stefanprodan/podinfo:1.4.1 ``` +The response should be + +```sh +Submitting release ... +CONTROLLER STATUS UPDATES +demo:deployment/podinfo success podinfod: stefanprodan/podinfo:1.4.2 -> 1.4.1 +Commit pushed: 426d723 +Commit applied: 426d723 +``` + +and the diff for this is going to look like this: + +```diff +--- a/workloads/podinfo-dep.yaml ++++ b/workloads/podinfo-dep.yaml +@@ -33,7 +33,7 @@ spec: + - "1" + containers: + - name: podinfod +- image: stefanprodan/podinfo:1.3.2 ++ image: stefanprodan/podinfo:1.4.1 + imagePullPolicy: IfNotPresent + ports: + - containerPort: 9898 +``` + Lock to `1.4.1` with a message describing why: ```sh fluxctl lock -c demo:deployment/podinfo -m "1.4.2 does not work for us" ``` +The resulting diff should look like this + +```diff +--- a/workloads/podinfo-dep.yaml ++++ b/workloads/podinfo-dep.yaml +@@ -10,6 +10,7 @@ metadata: + app: podinfo + annotations: + flux.weave.works/automated: "true" + flux.weave.works/tag.init: glob:1.4.* + flux.weave.works/tag.podinfod: glob:1.4.* ++ flux.weave.works/locked: 'true' + spec: + strategy: + rollingUpdate: +``` + And that's it. At the end of this tutorial, you have automated, locked and annotated deployments with Weave Flux. From 196325e9ddd1cf4b7dd2742b1dd799b7bc82712b Mon Sep 17 00:00:00 2001 From: Daniel Holbach Date: Mon, 21 Jan 2019 16:58:40 +0530 Subject: [PATCH 4/4] add note about our (simple) use of the default namespace --- site/annotations-tutorial.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/site/annotations-tutorial.md b/site/annotations-tutorial.md index 1b2716fed..2ffe0b21f 100644 --- a/site/annotations-tutorial.md +++ b/site/annotations-tutorial.md @@ -91,6 +91,11 @@ helm upgrade -i flux \ weaveworks/flux ``` +> **Note:** In this tutorial we keep things simple, so we deploy Flux into +the `default` namespace. Normally you would pick a separate namespace for +it. `fluxctl` has the `k8s-fwd-ns` option for specifying the right +namespace. + ### Connecting to your git config The first step is done. Flux is now and up running (you can confirm by